Paginación y formato de respuesta

Para desarrolladores

Toda respuesta exitosa de la API tiene una de tres formas: un recurso único, una colección paginada o ninguna (status 204). Esta página muestra cada forma, los códigos de estado y cómo recorrer una colección página a página. Los errores (4xx/5xx) usan otro formato, descrito en Respuestas de error.

Forma de la respuesta

Caso	Forma del body
Recurso único	objeto directo: los campos del recurso están en el nivel superior, no dentro de data
Colección	{ "data": [ ... ], "pagination": { ... } }
Sin body	ninguno (status 204)

Recurso único

GET /v1/senders/42

{
  "id": 42,
  "name": "Atención al cliente",
  "email_address": "[email protected]",
  "domain_id": 7,
  "created_at": "2026-05-08T14:24:10Z",
  "updated_at": "2026-05-08T14:24:10Z"
}

Colección

GET /v1/senders?page=1&page_size=20

{
  "data": [
    { "id": 42, "name": "Atención al cliente", "...": "..." },
    { "id": 43, "name": "Facturación", "...": "..." }
  ],
  "pagination": { "page": 1, "page_size": 20, "has_more": true, "total_items": 57, "total_pages": 3 }
}

Status codes

El código depende de la operación y de si la respuesta trae body:

HTTP	Cuándo	Body	Header extra
200 OK	Lectura, o actualización/acción que devuelve un resultado	el recurso o resultado	—
201 Created	POST/PUT que crea un recurso nuevo con su propia URL	el recurso creado	Location: /v1/<coleccion>/{id}
204 No Content	Éxito sin body (DELETE; PUT/PATCH que no devuelven la entidad)	ninguno (sin body ni Content-Length)	—

201 solo se usa cuando se crea un recurso con su propia URL. Una acción como /send, que no crea nada, responde 200.

Paginación

Query params en endpoints de colección:

Param	Default	Rango
page	1	≥ 1
page_size	20	1–100

Bloque pagination de la respuesta:

Campo	Significado
page	Página actual; la primera es la 1.
page_size	Tamaño de página efectivo.
has_more	Si existe una página siguiente.
total_items	Total de elementos que coinciden con el filtro (no solo la página). Puede ser null.
total_pages	Total de páginas según el page_size usado. Vale 0 si no hay elementos y puede ser null.

Para avanzar de página, lea has_more: está en toda respuesta de colección. Los dos totales son opcionales. Algunos listados los informan y otros los dejan en null cuando el conteo exacto sería costoso. Si su integración muestra "página X de Y", debe tolerar ese null.

Headers

Header	Presencia	Significado
X-Request-Id	Toda respuesta (éxito y error)	Identificador único del request. Indíquelo a soporte al reportar un problema. Usted puede enviarlo como UUID. Si no es un UUID válido, la API lo descarta y genera uno propio. No se incluye en el body.
X-Trace-Id	No siempre presente	ID de traza distribuida; útil junto con X-Request-Id al reportar un problema a soporte.
Location	Solo 201	URI del recurso recién creado.

Fechas

Las fechas se devuelven en RFC 3339, en UTC y con sufijo Z (p. ej. 2026-05-08T14:24:10Z).