En esta página
Seguimiento de una operación GET
Consulta el resultado de una emisión: si sigue recibida, si el SRI la autorizó o la rechazó y cuál es su clave de acceso.
Cuando emites un comprobante, la API lo recibe y responde de inmediato con un
idOperacion, pero el resultado del SRI llega después.
Este endpoint te dice cómo está esa operación:
si el comprobante sigue recibido y sin resultado, si el SRI lo autorizó o lo
rechazó, si no se pudo emitir y por qué, y cuál es la
clave de acceso que le asignamos.
Puedes usarlo para seguir cada emisión hasta su estado final. Al terminar esta
página sabrás leer el campo estado, junto con codEstado, msgError y
errores, y qué hacer en cada caso: esperar, entregar el comprobante a tu cliente o corregirlo
y emitirlo de nuevo.
GET /v1/operaciones/{idOperacion}
X-Api-Key: <tu API Key>
Para agentes#
Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.
Pega este prompt en un agente de programación con acceso a la terminal:
Implementa en este proyecto el seguimiento de una operación de Ecuafact hasta un estado final. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/consulta-operacion.md antes de escribir código; no inventes campos. Reutiliza el SDK de Ecuafact que el proyecto ya use; si no usa ninguno, recomiéndame el SDK de su lenguaje o el CLI ecuafact, con una frase de motivo, y espera mi respuesta; HTTP directo solo si lo prefiero. Consulta GET /v1/operaciones/{idOperacion} con el idOperacion de la emisión (o usa urlEstado tal cual, que es una URL absoluta) y repite con espera creciente mientras el estado sea recibido (codEstado 1001 o 1002), con un tiempo máximo y sin saturar el límite de solicitudes; respeta Retry-After. Cualquier otro estado es final y se decide por estado y codEstado numérico: autorizado (2001) es el único con validez fiscal; en los demás casos lee errores como arreglo, explica la causa con el catálogo de la guía de errores y no reemitas ante 5001 ni 5007. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Prueba con una operación de pruebas que yo te indique o que emitas con un comprobante de prueba. Ejecuta el seguimiento e informa solo el estado final, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer.
Cuándo usarlo#
La emisión responde 202 Accepted con un idOperacion, y eso significa que el
comprobante fue recibido, no que esté autorizado. Puedes enterarte del
resultado de dos formas, y también combinarlas.
- Webhook, la forma que te recomendamos. Te avisamos con
document.authorized,document.rejectedodocument.faileden cuanto hay un resultado, así que no gastas solicitudes ni tienes que decidir cada cuánto preguntar. El detalle está en Webhooks. - Consulta, con este endpoint. Te sirve si aún no tienes un servidor público para recibir webhooks, durante las pruebas, como respaldo cuando un webhook no llegó o para mostrar el estado cuando un usuario lo pide.
Si emites muchos comprobantes, te recomendamos el webhook, porque consultar cada operación en bucle consume tu límite de solicitudes, que por defecto es de 200 por minuto y de 60 en un sandbox.
Antes de empezar#
- Una API Key de pruebas guardada en la variable de entorno
ECUAFACT_API_KEY. Si todavía no tienes una, crea un sandbox; cómo viaja la API Key se explica en Autenticación. - Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue Registra tu IP.
- El
idOperacionque recibiste en la respuesta 202 de una emisión. Debe ser de una emisión hecha con la misma API Key y en la misma URL, de pruebas o de producción.
Parámetros#
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
idOperacion (ruta) |
string (UUID) | Sí | El idOperacion de la respuesta 202 de la emisión, que también viene en urlEstado y en la cabecera Location. Debe tener formato UUID, por ejemplo 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f. |
X-Api-Key (cabecera) |
string | Sí | La misma API Key con la que emitiste. Una operación de otra integración responde 404. |
El campo urlEstado de la respuesta de emisión trae la URL completa del
seguimiento, por ejemplo
https://api-sandbox.mynexusapi.com/v1/operaciones/{idOperacion}, y la cabecera
Location trae el mismo valor. Puedes llamarla tal como viene, sin armar la
ruta por tu cuenta.
Ejemplo#
Importante
Ambiente de pruebas: sin validez fiscal.
Reemplaza el idOperacion de ejemplo por el que recibiste al emitir. Todos los
ejemplos imprimen el estado HTTP y el cuerpo de la respuesta.
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;
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 respuesta = await http.GetAsync("/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import os
import requests
r = requests.get(
"https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como operacion.mjs y ejecuta: node operacion.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f', {
headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
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);
echo $estado . ' ' . $cuerpo . PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
.uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.GET()
.build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
using var client = EcuafactClient.Create(new EcuafactClientOptions
{
BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});
Operation operacion = await client.GetOperacionAsync(Guid.Parse("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"));
Console.WriteLine($"{operacion.Estado} / {operacion.CodEstado} / {operacion.ClaveAcceso}");
import os
from ecuafact import EcuafactClient, EcuafactClientOptions
client = EcuafactClient(EcuafactClientOptions(
base_address="https://api-sandbox.mynexusapi.com/",
api_key=os.environ["ECUAFACT_API_KEY"],
))
operacion = client.get_operacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f")
print(operacion.estado, operacion.cod_estado, operacion.clave_acceso)
// Node.js 18 o superior. Guarda como operacion-sdk.mjs y ejecuta: node operacion-sdk.mjs
import { EcuafactClient } from '@ecuafact/sdk';
const client = new EcuafactClient({
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: process.env.ECUAFACT_API_KEY
});
const operacion = await client.getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
console.log(operacion.estado, operacion.codEstado, operacion.claveAcceso);
<?php
require 'vendor/autoload.php';
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
$client = new EcuafactClient(new EcuafactClientOptions(
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: getenv('ECUAFACT_API_KEY'),
));
$operacion = $client->getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
echo $operacion->estado . ' / ' . $operacion->codEstado . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.Operation;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
Operation operacion = client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
System.out.println(operacion.estado() + " / " + operacion.codEstado());
# Resultado esperado: el estado, el codEstado y la claveAcceso de la operación.
ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox
Respuesta#
La API responde 200 OK con la operación en el primer nivel del JSON. La forma
es la misma de la respuesta 202 Accepted de la emisión, con los valores
actuales. Este ejemplo corresponde a una factura ya autorizada:
{
"estado": "autorizado",
"codEstado": 2001,
"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": "0911202601179999999900110010010000001231234567810",
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": "2026-11-09T10:15:18-05:00"
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | Resultado de la operación. Sus valores están en Valores de estado. |
codEstado |
number | Código numérico de 4 dígitos que precisa el resultado. Su primer dígito coincide con el estado: 1 es recibido, 2 autorizado, 3 rechazado, 4 rechazo_configuracion, 5 error y 6 cancelado. Sus valores están en Códigos de resultado. |
msgError |
string | Descripción general y fija del código, en español. Solo viene cuando el comprobante no se autorizó; con recibido o autorizado el campo no aparece. Muéstralo o regístralo, pero decide con estado y codEstado. |
errores |
array de string | Detalle específico del resultado, por ejemplo el mensaje del SRI en un rechazo fiscal o la ruta del campo en un comprobante inválido. Viene siempre y es una lista vacía cuando no hay detalle. El texto es informativo, así que muéstralo o regístralo sin compararlo en tu código. |
idOperacion |
string (UUID) | El identificador que consultaste. |
urlEstado |
string | URL completa de este mismo seguimiento. |
ambiente |
number | 1 para pruebas y 2 para producción. Siempre coincide con la URL que llamas. |
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, por ejemplo 001-001-000000123. Si dejaste que te asignáramos el secuencial, aquí lo encuentras. |
referenciaExterna |
string o null |
La referenciaExterna que enviaste al emitir, o null si no la enviaste. |
claveAcceso |
string o null |
Clave de acceso de 49 dígitos que te asignamos. Vale null mientras el codEstado es 1001 y también cuando el comprobante no se llegó a emitir. Guárdala, porque la necesitas para descargar el RIDE y el XML. |
fhRecibido |
string | Fecha y hora en que recibimos la emisión, en ISO 8601 con la zona horaria de Ecuador, por ejemplo 2026-11-09T10:15:00-05:00. |
fhAutorizacion |
string o null |
Fecha y hora de autorización, en ISO 8601 con zona horaria. Puede ser null aunque el estado sea autorizado, porque la autorización no siempre trae fecha; por eso no la uses para decidir si el comprobante está autorizado. |
Mientras el comprobante no tiene resultado, el estado es recibido y el
codEstado vale 1001 si todavía no tiene clave de acceso o 1002 si ya la
tiene. Tu sistema debe aceptar los dos valores y tratar la claveAcceso como
opcional mientras el comprobante siga recibido:
{
"estado": "recibido",
"codEstado": 1002,
"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": "0911202601179999999900110010010000001231234567810",
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": null
}
Así se ve, en cambio, un comprobante que el SRI rechazó. El estado es
rechazado, el codEstado 3001 indica que el rechazo vino del SRI, msgError
trae la descripción fija del código y errores trae el mensaje del SRI:
{
"estado": "rechazado",
"codEstado": 3001,
"msgError": "El SRI rechazó el comprobante.",
"errores": [
"CLAVE ACCESO REGISTRADA"
],
"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": "0911202601179999999900110010010000001231234567810",
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": null
}
Valores de estado#
El campo estado tiene seis valores. Solo recibido es provisional; los demás
son finales y ya no cambian.
| Valor | Final | Significado |
|---|---|---|
recibido |
No | Recibimos el comprobante, pasó nuestras validaciones y todavía no tiene un resultado final. |
autorizado |
Sí | El SRI autorizó el comprobante. Es el único valor con validez fiscal. |
rechazado |
Sí | El comprobante no se autorizó por su contenido: lo rechazó el SRI o no cumplió una regla de la validación fiscal. codEstado dice cuál de los dos casos es. |
rechazo_configuracion |
Sí | No se pudo emitir porque falta o está mal una configuración del emisor, como la firma electrónica, la suscripción o el cupo. |
error |
Sí | No se pudo emitir por un fallo inesperado o porque algo impidió de forma definitiva que se autorice. |
cancelado |
Sí | La plataforma canceló el envío de forma automática. El comprobante no se emitió y no consumió cupo. |
No llames "autorizado" a un comprobante recibido, porque el 202 de la emisión
solo indica que se recibió. Para uso fiscal solo cuenta que el estado sea
autorizado.
Códigos de resultado#
El codEstado precisa el resultado dentro de cada estado. Mientras el
comprobante sigue recibido vale 1001 o 1002, y cuando el estado es final y
distinto de autorizado dice la causa. La acción para cada código está en
Qué hacer según el estado, y el catálogo completo,
en Errores.
codEstado |
Nombre | estado |
Significado |
|---|---|---|---|
| 1001 | comprobante_recibido |
recibido |
Recibimos el comprobante y todavía no tiene clave de acceso ni resultado. |
| 1002 | comprobante_enviado |
recibido |
El comprobante ya tiene claveAcceso y espera el resultado del SRI. |
| 2001 | comprobante_autorizado |
autorizado |
El SRI autorizó el comprobante. |
| 3001 | rechazo_sri |
rechazado |
El SRI rechazó el comprobante. errores trae el mensaje del SRI. |
| 3002 | comprobante_invalido |
rechazado |
La validación fiscal rechazó el contenido antes de enviarlo al SRI. errores trae el detalle por campo cuando existe. |
| 4001 | emisor_no_configurado |
rechazo_configuracion |
Al emisor le falta configuración para emitir ante el SRI. |
| 4002 | firma_no_valida |
rechazo_configuracion |
La firma electrónica del emisor está caducada o no es válida. |
| 4003 | suscripcion_inactiva |
rechazo_configuracion |
La suscripción del emisor no está activa. |
| 4004 | cupo_agotado |
rechazo_configuracion |
No quedan documentos en tus paquetes vigentes. |
| 5001 | error_interno |
error |
Tuvimos un fallo inesperado y el comprobante no se completó. |
| 5006 | entrega_no_posible |
error |
El comprobante no se pudo emitir y confirmamos que no se creó. |
| 5007 | resultado_no_confirmado |
error |
No pudimos confirmar si el comprobante llegó a crearse. |
| 6001 | operacion_cancelada |
cancelado |
La plataforma canceló el envío antes de emitirlo. |
Los nombres de la tabla te sirven para leer la documentación y coinciden con las
constantes de nuestros SDK, pero en el JSON solo viaja el número. Si recibes un
codEstado que tu sistema no reconoce, decide por su primer dígito, que siempre
coincide con el estado. Si es final, trátalo como un rechazo que debe revisar
una persona y conserva el idOperacion para soporte.
Qué hacer según el estado#
Una operación está en estado final cuando su estado es cualquier valor
distinto de recibido. Mientras sea recibido, sigue esperando.
estado |
codEstado |
Final | Qué hacer |
|---|---|---|---|
recibido |
1001 o 1002 | No | Espera el webhook o consulta más tarde, y no reenvíes la emisión. Con 1002 ya puedes guardar la claveAcceso, pero el comprobante todavía no está autorizado. |
autorizado |
2001 | Sí | Guarda la claveAcceso, descarga el RIDE y el XML y entrégalos a tu cliente. |
rechazado |
3001 | Sí | Es un rechazo fiscal y el cupo se consume. Corrige el comprobante según el mensaje del SRI que viene en errores y emítelo como un comprobante nuevo, con un secuencial nuevo (o sin secuencial, para que te asignemos el siguiente), una Idempotency-Key nueva y una referenciaExterna nueva. Si reutilizas el número rechazado, la API responde 409 con el codEstado 3004 (comprobante_duplicado). |
rechazado |
3002 | Sí | Corrige el dato que indica errores y reenvía el comprobante con claves nuevas. Puedes conservar el mismo número. |
rechazo_configuracion |
4001 | Sí | Revisa el RUC en Cuenta > Contribuyentes del Portal del Cliente: en el ambiente en que emitiste, la columna Pruebas o Producción debe mostrar Listo o En producción. Si muestra Configurando, espera a que termine; si ya está listo, escribe a soporte con el idOperacion. Después reenvía con el mismo número y claves nuevas. |
rechazo_configuracion |
4002 | Sí | En Cuenta > Contribuyentes del Portal del Cliente, pulsa Reemplazar firma en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en Cuenta > Certificados con Reemplazar certificado. Después reenvía con el mismo número y claves nuevas. |
rechazo_configuracion |
4003 | Sí | Regulariza la suscripción del emisor y reenvía con el mismo número y claves nuevas. |
rechazo_configuracion |
4004 | Sí | Compra un paquete de documentos y reenvía con el mismo número y claves nuevas. |
error |
5006 | Sí | El comprobante no se creó. Reenvíalo con el mismo número y claves nuevas. |
error |
5007 | Sí | No reemitas, porque el comprobante podría existir y lo duplicarías. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
error |
5001 | Sí | Escribe a soporte con el idOperacion antes de reemitir, para confirmar que el comprobante no existe. |
cancelado |
6001 | Sí | El comprobante no se emitió y no consumió cupo. Emítelo de nuevo con claves nuevas; puedes usar el mismo número. Con la misma Idempotency-Key recibirías otra vez esta operación cancelada. |
En esta tabla, "claves nuevas" significa una Idempotency-Key nueva y una
referenciaExterna nueva. Para conservar el número, envía el mismo estab,
ptoEmi y secuencial. Si dejaste que te asignáramos el secuencial, lo
encuentras en el numeroDocumento de esta misma respuesta o en el
listado de operaciones. Un reenvío
con el mismo número puede responder con el mismo idOperacion y no descuenta
otro documento de tu cupo.
Atención
No reemplaces la Idempotency-Key ni la referenciaExterna mientras la
operación siga en recibido. Emitir de nuevo con datos de idempotencia
distintos crea un segundo comprobante.
Un rechazo y una espera se manejan de forma distinta. Un rechazo
(rechazado o rechazo_configuracion) exige corregir el comprobante o la
configuración del emisor antes de emitir de nuevo. Una espera (recibido)
no requiere ninguna acción: consulta más tarde o espera el webhook.
Listado de operaciones por contribuyente#
Para reconciliar lo emitido en un período, usa el listado paginado por
contribuyente. No devuelve todo el historial de la cuenta: exige la
identificacion y limita el rango de fechas a 366 días. No consume cupo.
GET /v1/operaciones?identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50
X-Api-Key: <tu API Key>
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
identificacion (consulta) |
string | Sí | La identificación completa que devuelve GET /v1/contexto, la misma de infoTributaria.ruc. |
desde (consulta) |
string (yyyy-MM-dd) |
No | Fecha inicial, desde el 2000-01-01. Si no la envías, se usan los 30 días anteriores a hasta. |
hasta (consulta) |
string (yyyy-MM-dd) |
No | Fecha final. Si no la envías, se usa la fecha de hoy. Entre desde y hasta puede haber como máximo 366 días. |
tipoDocumento (consulta) |
string | No | 01, 03, 04, 05, 06 o 07. Sin él, devuelve todos los tipos. |
buscar (consulta) |
string | No | Texto libre de hasta 100 caracteres, sin caracteres de control, para filtrar por número, clave, contraparte o referencia. |
pagina (consulta) |
number | No | Página, de 1 a 10000. Por defecto 1. |
tamanoPagina (consulta) |
number | No | Filas por página, de 1 a 100. Por defecto 20. |
X-Api-Key (cabecera) |
string | Sí | Tu API Key. |
Los ejemplos listan las facturas de los primeros 10 días de noviembre de 2026 del contribuyente de pruebas.
curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones?identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50" \
-H "X-Api-Key: $ECUAFACT_API_KEY"
using System.Net.Http;
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);
string consulta = "identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50";
using HttpResponseMessage respuesta = await http.GetAsync("/v1/operaciones?" + consulta);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
// Node.js 18 o superior. Guarda como listado.mjs y ejecuta: node listado.mjs
const consulta = new URLSearchParams({
identificacion: '0123456789001',
desde: '2026-11-01',
hasta: '2026-11-10',
tipoDocumento: '01',
pagina: '1',
tamanoPagina: '50'
});
const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones?${consulta}`, {
headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
<?php
$consulta = http_build_query([
'identificacion' => '0123456789001',
'desde' => '2026-11-01',
'hasta' => '2026-11-10',
'tipoDocumento' => '01',
'pagina' => 1,
'tamanoPagina' => 50,
]);
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones?' . $consulta);
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);
echo $estado . ' ' . $cuerpo . PHP_EOL;
La respuesta es una página de comprobantes:
{
"comprobantes": [
{
"claveAcceso": "1011202601099215640600110010010000000025469774111",
"numeroDocumento": "001-001-000000002",
"tipoDocumento": "01",
"fechaEmision": "10/11/2026",
"identificacionContraparte": "0123456789",
"razonSocialContraparte": "CONTRIBUYENTE DE PRUEBAS",
"total": 1.00,
"estado": "recibido",
"codEstado": 1002,
"errores": [],
"fhAutorizacion": null
}
],
"pagina": 1,
"tamanoPagina": 50,
"hayMas": false
}
| Campo | Tipo | Descripción |
|---|---|---|
comprobantes |
array | Comprobantes de la página; vacío si no hay ninguno en el período. |
comprobantes[].claveAcceso |
string | Clave de acceso de 49 dígitos. |
comprobantes[].numeroDocumento |
string | Número con la forma estab-ptoEmi-secuencial. |
comprobantes[].tipoDocumento |
string | Tipo de comprobante: 01, 03, 04, 05, 06 o 07. |
comprobantes[].fechaEmision |
string | Fecha de emisión con formato dd/MM/yyyy. |
comprobantes[].identificacionContraparte |
string | Identificación del comprador, del proveedor o del destinatario. |
comprobantes[].razonSocialContraparte |
string | Razón social de la contraparte. |
comprobantes[].total |
number | Importe total del comprobante. |
comprobantes[].estado |
string | Mismo significado que en Valores de estado. |
comprobantes[].codEstado |
number | Mismo significado que en Códigos de resultado. |
comprobantes[].msgError |
string | Descripción fija del código. Solo viene cuando el comprobante no se autorizó. |
comprobantes[].errores |
array de string | Detalle del resultado; lista vacía cuando no hay detalle. |
comprobantes[].fhAutorizacion |
string o null |
Fecha y hora de autorización en ISO 8601; null si no está autorizado. |
pagina |
number | Página devuelta. |
tamanoPagina |
number | Filas por página usadas en la consulta. |
hayMas |
boolean | true si existe una página siguiente. |
Tu API Key debe tener el scope comprobantes:leer y acceso al contribuyente
consultado. Si no lo tiene, la API responde 403 con el codEstado 3011
(acceso_denegado); un filtro fuera de rango, por ejemplo un período mayor de
366 días, responde 400 con el codEstado 3012 (filtros_invalidos). Para un
volumen grande, recorre las páginas con hayMas en lugar de pedir todo en una
sola llamada. Los estados de este listado están en
Estados de este endpoint.
Listado desde el CLI#
El comando ecuafact operaciones listar hace esta misma consulta. Si no indicas
--identificacion, toma el contribuyente de GET /v1/contexto cuando hay uno
solo; si la integración tiene varios, se detiene y te pide --identificacion,
sin elegir uno en silencio. --json y --csv equivalen a --salida json y
--salida csv. La tabla muestra el número, el tipo, la fecha, el estado, el
codEstado, el total, la identificación de la contraparte y la clave de acceso;
en JSON recibes la
página completa, con pagina, tamanoPagina y hayMas.
# Resultado esperado: una fila por comprobante, con su estado y codEstado.
ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --tipo 01 --entorno sandbox
# La pagina completa en JSON, para guardarla o procesarla.
ecuafact operaciones listar --identificacion 0123456789001 --desde 2026-11-01 --hasta 2026-11-10 --json
# Un CSV para abrir en Excel.
ecuafact operaciones listar --identificacion 0123456789001 --desde 2026-11-01 --hasta 2026-11-10 --csv > emitidos.csv
Si la respuesta trae hayMas en true, repite el comando con --pagina una
unidad mayor. El comando te recuerda la página siguiente en el mensaje de
resumen.
Listado en Postman#
En la colección, abre 03 · Listado de operaciones > 03.1 Listar operaciones.
Usa las variables del environment baseUrl, apiKey e identificacion, y
ajusta desde y hasta al período que quieras conciliar. La petición trae
ejemplos de 200 con una página de comprobantes, de 403 con el codEstado
3011 y de 400 con el 3012.
Seguimiento con espera#
Si no usas webhooks, puedes consultar la operación cada pocos segundos hasta llegar a un estado final, siempre con un tope de tiempo. El resultado del SRI puede tardar varios minutos, y consultar más seguido que cada 5 segundos no lo acelera.
Este ejemplo consulta cada 10 segundos durante un máximo de 10 minutos. Si llega al tope sin un estado final, no es un error. Deja el comprobante como pendiente en tu sistema y vuelve a consultarlo más tarde, o espera el webhook.
# Requiere jq. Uso: ./seguir.sh 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f
ID="$1"
for intento in $(seq 1 60); do
CUERPO=$(curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/$ID" -H "X-Api-Key: $ECUAFACT_API_KEY")
ESTADO=$(echo "$CUERPO" | jq -r '.estado')
echo "Intento $intento: $ESTADO"
if [ "$ESTADO" != "recibido" ]; then echo "$CUERPO"; exit 0; fi
sleep 10
done
echo "Sin estado final tras 10 minutos: consulta mas tarde."
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);
string idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f";
DateTime limite = DateTime.UtcNow.AddMinutes(10);
while (DateTime.UtcNow < limite)
{
using HttpResponseMessage respuesta = await http.GetAsync($"/v1/operaciones/{idOperacion}");
string cuerpo = await respuesta.Content.ReadAsStringAsync();
if (!respuesta.IsSuccessStatusCode)
{
Console.WriteLine($"{(int)respuesta.StatusCode} {cuerpo}");
return;
}
using JsonDocument json = JsonDocument.Parse(cuerpo);
string estado = json.RootElement.GetProperty("estado").GetString()!;
Console.WriteLine(estado);
if (estado != "recibido")
{
Console.WriteLine(cuerpo);
return;
}
await Task.Delay(TimeSpan.FromSeconds(10));
}
Console.WriteLine("Sin estado final tras 10 minutos: consulta mas tarde.");
import os
import time
import requests
id_operacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"
url = f"https://api-sandbox.mynexusapi.com/v1/operaciones/{id_operacion}"
headers = {"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}
limite = time.monotonic() + 600
while time.monotonic() < limite:
r = requests.get(url, headers=headers, timeout=30)
if r.status_code != 200:
print(r.status_code, r.text)
break
operacion = r.json()
print(operacion["estado"], "/", operacion["codEstado"])
if operacion["estado"] != "recibido":
print(r.text)
break
time.sleep(10)
else:
print("Sin estado final tras 10 minutos: consulta mas tarde.")
// Node.js 18 o superior. Guarda como seguir.mjs y ejecuta: node seguir.mjs
const idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f';
const limite = Date.now() + 10 * 60 * 1000;
const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms));
let terminado = false;
while (!terminado && Date.now() < limite) {
const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones/${idOperacion}`, {
headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
if (res.status !== 200) {
console.log(res.status, await res.text());
break;
}
const operacion = await res.json();
console.log(operacion.estado, '/', operacion.codEstado);
terminado = operacion.estado !== 'recibido';
if (terminado) {
console.log(JSON.stringify(operacion));
} else {
await esperar(10000);
}
}
if (!terminado) {
console.log('Sin estado final: consulta mas tarde.');
}
<?php
$idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f';
$limite = time() + 600;
$terminado = false;
while (!$terminado && time() < $limite) {
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones/' . $idOperacion);
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);
if ($estado !== 200) {
echo $estado . ' ' . $cuerpo . PHP_EOL;
break;
}
$operacion = json_decode($cuerpo, true);
echo $operacion['estado'] . ' / ' . $operacion['codEstado'] . PHP_EOL;
$terminado = $operacion['estado'] !== 'recibido';
if ($terminado) {
echo $cuerpo . PHP_EOL;
} else {
sleep(10);
}
}
if (!$terminado) {
echo 'Sin estado final: consulta mas tarde.' . PHP_EOL;
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
// Dentro de: public static void main(String[] args) throws Exception
String idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f";
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
.uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/" + idOperacion))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.GET()
.build();
Pattern patronEstado = Pattern.compile("\"estado\"\\s*:\\s*\"([a-z_]+)\"");
long limite = System.currentTimeMillis() + 10 * 60 * 1000;
boolean terminado = false;
while (!terminado && System.currentTimeMillis() < limite) {
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
if (respuesta.statusCode() != 200) {
System.out.println(respuesta.statusCode() + " " + respuesta.body());
break;
}
Matcher estado = patronEstado.matcher(respuesta.body());
String valorEstado = estado.find() ? estado.group(1) : "";
System.out.println(valorEstado);
terminado = !valorEstado.isEmpty() && !valorEstado.equals("recibido");
if (terminado) {
System.out.println(respuesta.body());
} else {
Thread.sleep(10_000);
}
}
if (!terminado) {
System.out.println("Sin estado final: consulta mas tarde.");
}
Sabrás que funcionó si el bucle termina con el estado en autorizado y te
muestra la claveAcceso. En pruebas, eso ocurre cuando emitiste un comprobante válido.
Estados de este endpoint#
Cuando la consulta falla, el cuerpo trae la forma de error de toda la API, con
estado, codEstado, msgError y errores, que se explica en
Errores.
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La API encontró la operación. | Lee el estado y el codEstado como se explica en Qué hacer según el estado. |
3013 (no_encontrado) |
404 | No existe una operación con ese idOperacion para tu integración, porque el valor está mal copiado, pertenece a otra integración o se emitió en el otro ambiente. |
Revisa el idOperacion y confirma que llamas a la misma URL, de pruebas o de producción, donde emitiste. |
3013 (no_encontrado) |
404 | El idOperacion de la ruta no tiene formato UUID. |
Copia el idOperacion tal como vino en la respuesta 202. |
3009 (credenciales_invalidas) |
401 | Falta la API Key o es inválida. | Revisa la API Key, como se explica en Autenticación. |
3010 (ip_no_autorizada) |
403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en Cuenta > IP permitidas o llama sin proxies que oculten el origen. |
5005 (limite_solicitudes) |
429 | Superaste el límite de solicitudes. | Espera lo que indica Retry-After, consulta con menos frecuencia o usa webhooks. |
5002 (servicio_no_disponible) |
503 | El servicio no está disponible temporalmente. | Reintenta con una espera creciente. |
Para el listado de operaciones, los estados propios son estos, además de los de autenticación y límite de la tabla anterior:
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La API devuelve la página de comprobantes, que puede venir vacía. | Si hayMas es true, pide la página siguiente. |
3003 (solicitud_invalida) |
400 | Falta identificacion o una fecha no tiene el formato yyyy-MM-dd. |
Envía identificacion y fechas con formato 2026-11-01. |
3012 (filtros_invalidos) |
400 | Un filtro está fuera de rango: fecha anterior al 2000-01-01, hasta menor que desde, más de 366 días entre ambas, pagina fuera de 1 a 10000, tamanoPagina fuera de 1 a 100, buscar de más de 100 caracteres o tipoDocumento distinto de 01, 03, 04, 05, 06 o 07. |
Corrige el filtro que indica errores y repite la consulta. |
3002 (comprobante_invalido) |
422 | La identificacion no tiene entre 5 y 13 dígitos numéricos. |
Usa la identificacion que devuelve GET /v1/contexto. |
3011 (acceso_denegado) |
403 | La identificacion no es de un contribuyente habilitado para tu API Key en este ambiente, o no puede emitir el tipoDocumento que pediste. |
Revisa GET /v1/contexto y usa un contribuyente y un tipo habilitados. |
El catálogo completo está en Errores.
Siguientes pasos#
- Webhooks: recibe el resultado sin consultar en bucle.
- Descargar PDF: obtén el RIDE cuando el comprobante esté
autorizado. - Buenas prácticas: reintentos e idempotencia sin duplicar comprobantes.