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

Prompt para agentes

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.rejected o document.failed en 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 idOperacion que 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.
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.