/ Empezar

Respuestas y errores

Formato unificado de respuestas, paginación, códigos HTTP, estados SUNAT y cabeceras de uso.

Formato de respuesta

Todas las respuestas usan la misma estructura: estado (exito o error), un mensaje legible y, según el caso, datos, errores o meta.

Respuesta200 OK

{
  "estado": "exito",
  "mensaje": "OK",
  "datos": {
    "id": 123
  }
}

Errores de validación

Cuando los datos no son válidos, la API responde 422 con el detalle por campo, en español.

Respuesta422 Unprocessable Entity

{
  "estado": "error",
  "mensaje": "Error de validación",
  "errores": {
    "cliente.num_doc": [
      "El campo cliente.num doc es obligatorio."
    ]
  }
}

Códigos HTTP

Código	Significado
200	Operación correcta.
201	Recurso creado.
202	Aceptado; la operación continúa en segundo plano.
401	Credenciales inválidas.
403	Tu plan no incluye la función, tu suscripción venció o la empresa está inactiva.
404	El recurso no existe.
409	Conflicto, por ejemplo serie duplicada o archivo aún no disponible.
422	Error de validación o rechazo por reglas de SUNAT.
429	Alcanzaste el cupo mensual de comprobantes de tu plan, o hiciste demasiadas peticiones por minuto.
500	Error interno.
502	SUNAT no está disponible.

Paginación

Los listados devuelven datos.datos con los registros y datos.paginacion con el detalle. Usa por_pagina (por defecto 15, máximo 100) y page para recorrer los resultados.

Respuesta200 OK

{
  "estado": "exito",
  "datos": {
    "datos": [
      "..."
    ],
    "paginacion": {
      "pagina_actual": 1,
      "ultima_pagina": 8,
      "por_pagina": 15,
      "total": 112
    }
  }
}

Estados SUNAT

Todo comprobante tiene un sunat_status que avanza mientras SUNAT lo procesa. Si SUNAT no responde, el comprobante sigue pendiente y se reintenta; una caída de SUNAT no se guarda como rechazo.

Estado	Significado
pendiente	Creado, aún no enviado o en cola.
enviado	En SUNAT, esperando respuesta.
aceptado	Aceptado por SUNAT. Ya tienes el CDR.
rechazado	Rechazado. Revisa `sunat_code` y `sunat_description`.
anulado	Dado de baja mediante comunicación de baja o resumen.
anulacion_en_proceso	Hay una baja en curso.

Cabeceras de uso

Las respuestas incluyen cabeceras para que sepas cuánto cupo mensual llevas consumido.

Cabecera	Contenido
X-Plan	Plan vigente de tu empresa.
X-Usage-Documents	Comprobantes usados / cupo del mes, por ejemplo `42/200`.
X-Usage-Warning	`approaching_limit` cuando te acercas al cupo.
X-Usage-Remaining	Comprobantes que te quedan en el mes (junto al aviso).