Respuestas del API

Forma comun de las respuestas del API. Aqui ves como leer el cuerpo segun el endpoint, la correlacion y como se reportan los errores.

Forma de la respuesta#

Dependiendo del endpoint, la respuesta llega de una de estas dos formas:

Forma	Endpoints	Como se lee
Plana	Emision (`POST /v1/contribuyentes/{identificacion}/comprobantes`), cupo (`GET /v1/consumo`) y consultas al SRI (`GET /v1/consultas/...`)	Los datos estan en el primer nivel del JSON
Con `datos`	Contexto, listados, estado de operacion, perfil del emisor, reenvio de correo y catalogos	Los datos vienen en la clave `datos`

Cuando emites: la solicitud#

Al emitir, la API responde 202 Accepted con un objeto como este:

{
  "codigo": "200",
  "mensaje": "Operacion exitosa.",
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://staging-api.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "uid": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

Campo	Significado
`codigo`	`200` si es una emision nueva; `201` si es un reintento con la misma `Idempotency-Key`
`mensaje`	Descripcion del resultado
`idOperacion`	Identificador de seguimiento de la emision (guardalo)
`urlEstado`	Ruta para consultar el estado de esta operacion
`uid`	Identificador del documento (util para soporte)

202 significa que la solicitud fue recibida; todavia no es la autorizacion del SRI. El resultado final se obtiene consultando urlEstado o esperando el webhook.

Respuestas de error#

{ "codigo": "301", "mensaje": "Solicitud invalida.", "errores": ["Idempotency-Key: obligatoria."] }

El detalle de los codigos esta en Errores.

Correlacion#

Toda respuesta incluye la cabecera X-Correlation-Id. Guardala al reportar un incidente.

Las respuestas a /v1 incluyen ademas las cabeceras de limite (X-RateLimit-Limit, X-RateLimit-Remaining y, al superarlo, X-RateLimit-Reset y Retry-After); ve Limite de request.

Version del contrato#

Toda respuesta a /v1 trae la cabecera X-Api-Version con la version del contrato que respondio. Puedes fijar la version en la solicitud con la misma cabecera (opcional): si la omites, se usa la vigente. Una version inexistente o retirada responde 400 con codigo 306. Ve Versionado.