En esta página
Respuestas del API
Las respuestas de la API llegan como JSON plano o como archivo, y siempre traen cabeceras que te conviene leer.
Antes de leer un campo de una respuesta necesitas saber dónde está. Las respuestas JSON traen sus campos en el primer nivel, sin ninguna clave que los envuelva, y las descargas traen el archivo binario. Así puedes leer cualquier respuesta de la misma manera, sin importar el endpoint.
Aquí ves las dos formas del cuerpo, la respuesta de la emisión, la forma de los errores, las cabeceras que acompañan a cada respuesta y el formato de los valores. Al terminar sabrás leer cualquier respuesta de la API sin adivinar.
Formas del cuerpo#
Antes de leer una respuesta, ubica su endpoint en esta tabla.
| Forma | Endpoints | Cómo se lee |
|---|---|---|
| JSON plano | Todos los endpoints que responden JSON: emisión, seguimiento, contexto, cupo, perfil del emisor, consultas al SRI y errores | Los campos están en el primer nivel del JSON. |
| Archivo | RIDE (GET .../comprobantes/{claveAcceso}/ride) y XML (GET .../comprobantes/{claveAcceso}/xml) |
El cuerpo es el archivo binario, no JSON. |
Este es un ejemplo completo de respuesta JSON, la de GET /v1/consumo:
{
"limiteDocumentos": 1500,
"reservados": 5,
"consumidos": 990,
"disponibles": 505,
"vigenteHasta": "2027-01-01T00:00:00Z",
"limiteExtra": 500,
"reservadosExtra": 0,
"consumidosExtra": 0,
"disponiblesExtra": 500
}
| Campo | Tipo | Descripción |
|---|---|---|
| Campos del recurso | varios | Están en el primer nivel. El detalle está en Consumo y cuotas. |
Lee una respuesta en tu código#
El ejemplo consulta tu cupo y el seguimiento de una operación, e imprime un
campo de cada una. Reemplaza el idOperacion por uno que te haya devuelto una
emisión.
Importante
Ambiente de pruebas: sin validez fiscal.
curl -s "https://api-sandbox.mynexusapi.com/v1/consumo" \
-H "X-Api-Key: $ECUAFACT_API_KEY"
curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" \
-H "X-Api-Key: $ECUAFACT_API_KEY"
using System.Net.Http;
using System.Text.Json;
string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
using HttpResponseMessage consumo = await http.GetAsync("/v1/consumo");
using JsonDocument cupo = JsonDocument.Parse(await consumo.Content.ReadAsStringAsync());
Console.WriteLine($"{(int)consumo.StatusCode} disponibles: {cupo.RootElement.GetProperty("disponibles").GetInt32()}");
using HttpResponseMessage operacion = await http.GetAsync("/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
using JsonDocument seguimiento = JsonDocument.Parse(await operacion.Content.ReadAsStringAsync());
Console.WriteLine($"{(int)operacion.StatusCode} estado: {seguimiento.RootElement.GetProperty("estado").GetString()}");
import os
import requests
base = "https://api-sandbox.mynexusapi.com"
headers = {"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}
consumo = requests.get(f"{base}/v1/consumo", headers=headers, timeout=30)
print(consumo.status_code, "disponibles:", consumo.json()["disponibles"])
operacion = requests.get(f"{base}/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", headers=headers, timeout=30)
print(operacion.status_code, "estado:", operacion.json()["estado"])
// Node.js 18 o superior. Guarda como respuestas.mjs y ejecuta: node respuestas.mjs
const base = 'https://api-sandbox.mynexusapi.com';
const headers = { 'X-Api-Key': process.env.ECUAFACT_API_KEY };
const consumo = await fetch(`${base}/v1/consumo`, { headers });
const cupo = await consumo.json();
console.log(consumo.status, 'disponibles:', cupo.disponibles);
const operacion = await fetch(`${base}/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f`, { headers });
const seguimiento = await operacion.json();
console.log(operacion.status, 'estado:', seguimiento.estado);
<?php
function consultar(string $ruta): array
{
$ch = curl_init('https://api-sandbox.mynexusapi.com' . $ruta);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return [$estado, json_decode($cuerpo, true)];
}
[$estado, $cupo] = consultar('/v1/consumo');
echo $estado . ' disponibles: ' . $cupo['disponibles'] . PHP_EOL;
[$estado, $seguimiento] = consultar('/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
echo $estado . ' estado: ' . $seguimiento['estado'] . PHP_EOL;
# Resultado esperado: tus documentos disponibles y el estado de la operación.
ecuafact consumo --entorno sandbox --campos disponibles
ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox --campos estado
Resultado esperado. Los ejemplos HTTP imprimen 200 disponibles: ... y
200 estado: .... Si la operación no existe en tu integración, la segunda
llamada responde 404 con el codEstado 3013 (no_encontrado), como se explica en
Respuestas de error.
Respuesta de la emisión#
La emisión responde 202 Accepted con este cuerpo, que tiene la misma forma
del seguimiento:
{
"estado": "recibido",
"codEstado": 1001,
"errores": [],
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"ambiente": 1,
"tipoDocumento": "01",
"numeroDocumento": "001-001-000000123",
"referenciaExterna": "FAC-ERP-4581",
"claveAcceso": null,
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": null
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | recibido en el 202: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. |
codEstado |
number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores. |
errores |
array de string | Lista vacía cuando el comprobante se recibió sin novedades. |
idOperacion |
string (UUID) | Identificador de la operación. Guárdalo, porque con él consultas el resultado del SRI. |
urlEstado |
string | URL completa del seguimiento, por ejemplo https://api-sandbox.mynexusapi.com/v1/operaciones/{idOperacion}. Puedes llamarla tal como viene. |
ambiente |
number | 1 para pruebas y 2 para producción. |
tipoDocumento |
string | Tipo de comprobante: 01, 03, 04, 05, 06 o 07. |
numeroDocumento |
string o null |
Número del comprobante con la forma estab-ptoEmi-secuencial, incluido el secuencial que te asignamos si no lo enviaste. |
referenciaExterna |
string o null |
La referenciaExterna que enviaste. |
claveAcceso |
string o null |
Clave de acceso de 49 dígitos. Es null con el codEstado 1001; en ese caso la obtienes después en el seguimiento o en el webhook. |
fhRecibido |
string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |
fhAutorizacion |
string o null |
Fecha y hora de autorización; en el 202 es null. |
El campo msgError no aparece porque la emisión no tiene error. Si reintentas
con la misma Idempotency-Key y el mismo cuerpo, o con la misma
referenciaExterna y el mismo cuerpo, la API responde con la misma forma y el
mismo idOperacion, con el estado actual de esa operación, y no crea otro
comprobante. El resultado actual también lo ves en el
seguimiento.
Nota
El 202 significa que la solicitud fue recibida; la autorización del SRI llega después por seguimiento o por webhook.
Respuestas de error#
Todos los errores tienen la misma forma plana, con un codEstado numérico de
4 dígitos cuyo primer dígito coincide con el estado:
{
"estado": "rechazado",
"codEstado": 3013,
"msgError": "Recurso no encontrado.",
"errores": []
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | Estado que corresponde al código: rechazado (3xxx), rechazo_configuracion (4xxx) o error (5xxx). |
codEstado |
number | Código estable del catálogo. Programa tus decisiones con este valor y el estado HTTP. |
msgError |
string | Descripción general y fija del código. |
errores |
array de string | Detalle específico, por ejemplo la ruta del campo en un error de validación. Viene siempre y es una lista vacía cuando no hay detalle. |
Un rechazo de la emisión, por ejemplo un 422 de validación, trae estos mismos
cuatro campos dentro de la forma completa de la respuesta de emisión, con
idOperacion, urlEstado, numeroDocumento, claveAcceso y las fechas en
null, porque no se creó ninguna operación. Qué significa cada código y si se
reintenta se explica en Errores.
Cabeceras de respuesta#
Además del cuerpo, cada respuesta trae cabeceras con información útil para tu integración:
| Cabecera | Cuándo aparece | Qué contiene | Para qué te sirve |
|---|---|---|---|
X-Correlation-Id |
En toda respuesta. | El identificador de la petición. Si enviaste tu propio X-Correlation-Id (de 1 a 64 caracteres A-Z, a-z, 0-9, ., _, -), la API usa y devuelve ese mismo valor. |
Regístralo en tus logs, porque es el dato que te pedimos en soporte. |
X-Api-Version |
En toda respuesta de /v1. |
La versión del contrato que respondió (2026-11-16). |
Te permite detectar cambios de versión, como se explica en Versionado. |
Location |
En el 202 de la emisión. | La URL completa del seguimiento, el mismo valor que urlEstado. |
Úsala para consultar el estado. |
Content-Type |
En toda respuesta con cuerpo. | application/json en JSON, application/pdf en el RIDE y application/xml en el XML. |
Te dice cómo leer el cuerpo. |
Content-Disposition |
En la descarga del XML. | attachment con el nombre de archivo sugerido {claveAcceso}.xml. |
Úsala para guardar el archivo con su nombre. |
X-RateLimit-Limit |
En las respuestas autenticadas, cuando tu API Key tiene límite. | Las solicitudes permitidas por minuto. | Te dice tu límite; más detalle en Límite de request. |
X-RateLimit-Remaining |
Junto con X-RateLimit-Limit. |
Las solicitudes que te quedan en el minuto. | Te permite frenar antes de recibir un 429. |
X-RateLimit-Reset |
En el 429 con el codEstado 5005 (limite_solicitudes). |
El fin de la ventana, en segundos Unix. | Te dice cuándo vuelves a tener solicitudes. |
Retry-After |
En los 429 y 503. | Los segundos de espera antes de reintentar. | Úsala para programar el reintento. |
Cache-Control |
En toda respuesta de /v1. |
no-store, salvo en GET /v1/catalogos y GET /v1/catalogos/{nombre}, que traen private, max-age=3600. |
Con no-store, las respuestas no se guardan en cachés intermedias; tampoco las guardes tú sin control. Los catálogos sí puedes guardarlos hasta una hora, como se explica en Consultar los catálogos por API. |
Así se ven las cabeceras de una emisión:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f
X-Correlation-Id: 0HN7A2B3C4D5E:00000001
X-Api-Version: 2026-11-16
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
Cache-Control: no-store
Formatos de los valores#
Los valores de las respuestas siguen estos formatos:
| Tipo de dato | Formato | Ejemplo |
|---|---|---|
Identificadores (idOperacion, idCliente) |
UUID en texto. | "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" |
Códigos e identificaciones (tipoDocumento, identificacion, claveAcceso) |
Texto, aunque solo tengan dígitos, para conservar los ceros a la izquierda. | "01", "0123456789" |
Códigos de resultado y de error (codEstado) |
Número entero de 4 dígitos. El primer dígito coincide con el estado. |
3002 |
Estados (estado) |
Texto en minúsculas con guion bajo. | "recibido", "rechazo_configuracion" |
| Importes | Número JSON con punto decimal. | 112.5 |
Fechas del comprobante (fechaEmision del listado de operaciones) |
Texto con el formato dd/MM/yyyy. |
"15/09/2026" |
Fechas y horas de las respuestas (fhRecibido, fhAutorizacion, vigenteHasta) |
Texto ISO 8601 (yyyy-MM-ddTHH:mm:ss). Algunos campos agregan la zona horaria al final (Z o -05:00), así que usa un parser ISO 8601 que acepte las dos formas. |
"2026-09-15T14:32:10" |
| Campos opcionales sin valor | null. La excepción es msgError, que no aparece cuando no hay error. |
"fhAutorizacion": null |
Siguientes pasos#
- Errores: qué hacer ante cada
codEstado. - Seguimiento de una operación: los campos del estado de una emisión.
- Webhooks: recibe el resultado sin consultar.
- Versionado: cómo cambia el contrato y qué significa
X-Api-Version. - Estado del servicio: consulta sin API Key si la API está operativa cuando recibes errores 5xx.