Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.