Saltar a contenido

Formato de respuestas

La API utiliza dos formatos de respuesta principales: objetos individuales y listas paginadas.

Objeto individual

Las respuestas de un recurso individual devuelven el objeto directamente, sin envelope:

{
  "declaracionId": 5001,
  "evaluacionId": 10,
  "estado": "NoPresentada",
  "estadoCodigo": 1,
  "ultimaPuntuacion": 72.5
}

Sin envelope

Los objetos individuales se devuelven directamente como JSON, sin un campo data ni metadatos adicionales. La respuesta es el objeto en sí.

Lista paginada

Los endpoints de listado devuelven un envelope con metadatos de paginación:

{
  "data": [
    {
      "evaluacionId": 10,
      "evaluacion": "Evaluacion ITCanarias 2024",
      "declaracionId": 5001,
      "estado": "NoPresentada"
    }
  ],
  "total": 142,
  "page": 0,
  "size": 20,
  "totalPages": 8
}

Campos del envelope de paginación

Campo Tipo Descripción
data array Registros de la página actual
total int Total de registros sin paginar
page int Página actual (base 0)
size int Registros por página solicitados
totalPages int Total de páginas disponibles

Parámetros de paginación

Los endpoints paginados aceptan estos parámetros en el query string:

Parámetro Tipo Default Rango Descripción
page int 0 0 - N Página a obtener (base 0)
size int 20 1 - 100 Registros por página

Ejemplo: 

GET /apientidades/v1/evaluaciones?page=0&size=10
GET /apientidades/v1/incidencias?page=2&size=50

Ejemplo de navegación de páginas

import requests

BASE_URL = "https://apientidades-pro.transparenciacanarias.org/apientidades/v1"
headers = {"Authorization": f"Bearer {token}"}

# Obtener la primera página
page = 0
size = 20
all_items = []

while True:
    response = requests.get(
        f"{BASE_URL}/evaluaciones",
        headers=headers,
        params={"page": page, "size": size}
    )
    data = response.json()

    all_items.extend(data["data"])

    if page >= data["totalPages"] - 1:
        break  # No hay más páginas

    page += 1

print(f"Total obtenido: {len(all_items)} registros")

var allItems = new List<EvaluacionResumen>();
int page = 0;
int size = 20;
int totalPages;

do
{
    var response = await client.GetAsync(
        $"{baseUrl}/evaluaciones?page={page}&size={size}");
    var result = JsonConvert.DeserializeObject<PaginatedResponse<EvaluacionResumen>>(
        await response.Content.ReadAsStringAsync());

    allItems.AddRange(result.Data);
    totalPages = result.TotalPages;
    page++;
}
while (page < totalPages);

Console.WriteLine($"Total: {allItems.Count} registros");

Listas no paginadas

Algunos endpoints devuelven arrays directos (sin paginación):

  • GET /usuarios — Array de usuarios
  • GET /documentos/declaracion/{id} — Array de documentos
  • GET /webhooks — Array de webhooks
  • GET /declaraciones/{id}/pa — Árbol de PA
  • GET /declaraciones/{id}/cuestionarios — Array de cuestionarios
[
  { "id": 1, "nombre": "..." },
  { "id": 2, "nombre": "..." }
]

Mensajes de confirmación

Las operaciones de escritura devuelven un objeto de confirmación:

{
  "message": "Obligación actualizada correctamente."
}

{
  "message": "5 respuestas actualizadas.",
  "count": 5
}

{
  "id": 201,
  "message": "Incidencia creada correctamente."
}

Respuestas binarias

Los endpoints de descarga de PDF devuelven ficheros binarios:

Content-Type: application/pdf
Content-Disposition: attachment; filename="Borrador_5001.pdf"

No parsear como JSON

Las respuestas de descarga (borrador, documentos, informes) son ficheros binarios, no JSON. Trate la respuesta como bytes y guárdela en un fichero.