Estructura de respuestas | API de facturación electrónica

La API tiene tres formas estables de respuesta: éxito JSON, error JSON y descarga binaria. Todas las demás respuestas caen en una de estas tres categorías.

1. Éxito en JSON

El cuerpo siempre va envuelto en un objeto con la clave data.

json

{
  "data": {
    "id": 17,
    "businessName": "Mi Empresa S.A.",
    "ruc": "0105678901001",
    "created_at": "2026-05-22T13:22:01Z"
  }
}

Para colecciones (GET /customers, GET /documents…), data puede ser un arreglo o un objeto paginado, según el endpoint. Cada página de endpoint detalla la forma exacta.

2. Error en JSON (Problem Details, RFC 7807)

Los errores de validación y de negocio se devuelven con Content-Type: application/problem+json, siguiendo el estándar RFC 7807:

json

{
  "type": "https://docs.facturator.dev/errors/validation",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "El campo customer_id es obligatorio.",
  "instance": "urn:uuid:7c2b...c12",
  "errors": [
    { "field": "customer_id", "message": "El campo customer_id es obligatorio." }
  ]
}

Campos del objeto Problem

Campo	Significado
`type`	URI que identifica la clase del problema. `about:blank` si no hay una URI específica.
`title`	Resumen corto y legible del problema.
`status`	Código HTTP, repetido aquí para conveniencia del cliente.
`detail`	Explicación específica de esta ocurrencia del error.
`instance`	URI o identificador único de esta ocurrencia (útil para soporte).
`errors`	Lista de errores de campo (`{ field, message }`) cuando aplica.

Los errores de autenticación, plan, IP y rate limit usan un payload más simple con un único campo error (y a veces message):

json

{ "error": "API Key is missing" }

3. Descarga binaria

Para GET /documents/{id}/download el cuerpo NO es JSON. La respuesta incluye:

Content-Type apropiado (application/pdf o application/xml).
Content-Disposition con el nombre sugerido del archivo.

Campos comunes en respuestas de entidades

Campo	Tipo	Descripción
`id`	int	Identificador único.
`created_at` / `updated_at`	string	Marcas de tiempo ISO-8601.
`deleted_at`	string / null	Presente solo en recursos con soft-delete.