En esta página
Primeros pasos
Emite tu primera factura en el ambiente de pruebas, sigue su autorización hasta el final y descarga su RIDE, paso a paso.
Esta guía te lleva desde la API Key hasta tu primer comprobante autorizado. En seis pasos configuras tu credencial, consultas para qué contribuyentes puedes emitir, envías una factura, sigues su autorización y descargas su RIDE, el PDF que se entrega al cliente. Cada paso trae el ejemplo listo para copiar, la respuesta que deberías ver y cómo comprobar que funcionó antes de seguir.
Puedes seguir cada ejemplo de tres formas, en pestañas: llamando a la API por HTTP desde tu lenguaje, con nuestro SDK oficial de ese lenguaje o desde la terminal con nuestro CLI de Ecuafact. Te recomendamos elegir la que vas a usar en tu integración; el resultado es el mismo.
Si nunca antes trabajaste con facturación electrónica, te recomendamos leer primero la sección Conceptos de la Introducción. En unos cinco minutos explica qué es el SRI, qué significa que un comprobante esté autorizado y qué es la clave de acceso, tres ideas que esta guía usa todo el tiempo.
Importante
Ambiente de pruebas: sin validez fiscal. Todo lo que emitas en esta guía va a
https://api-sandbox.mynexusapi.com.
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:
Integra la API de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, instálala 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/primeros-pasos.md antes de escribir código; no inventes campos. Primero detecta cómo se integra este proyecto. Si ya usa el SDK de Ecuafact, el CLI ecuafact o el MCP de Ecuafact, sigue con esa vía (las guías sdk-dotnet, sdk-node, sdk-python, sdk-java, sdk-php, cli y mcp traen su propio prompt). Si no usa ninguna, recomiéndame la que mejor encaje, con una frase de motivo, y espera mi respuesta: el SDK de Ecuafact en el lenguaje del proyecto, el CLI ecuafact para probar o automatizar desde la terminal, el MCP para operar mi cuenta desde un asistente, o HTTP directo con la guía de emisión. 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. Valida la factura con POST /v1/contribuyentes/{identificacion}/facturas/validar y, solo si valida, emítela con POST /v1/contribuyentes/{identificacion}/facturas, una Idempotency-Key estable y una referenciaExterna propia; no envíes infoTributaria.tipoDocumento en el cuerpo. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide por estado y codEstado, usa urlEstado tal cual y lee errores como arreglo. Ejecuta una validación y una emisión de prueba e informa solo el estado, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer.
Antes de empezar#
- Una API Key de pruebas. Si todavía no tienes una, crea tu sandbox como se explica en Sandbox de pruebas; el alta tarda unos 10 minutos.
- No necesitas registrar ninguna IP para el sandbox. Al pasar a producción, registra la IP de salida de tu servidor como se explica en IP en sandbox y producción.
- Una terminal con cURL o el entorno de tu lenguaje: .NET 8 o superior,
Python 3.10 o superior con
requests, Node.js 18 o superior, PHP 8.2 o superior con la extensióncurlo Java 17 o superior. Si prefieres el CLI, instálalo con las instrucciones de CLI de Ecuafact. - Un editor de texto para guardar el archivo
comprobante.jsondel paso 3.
Paso 0. Configura la variable ECUAFACT_API_KEY#
Todos los ejemplos leen la API Key de la variable de entorno ECUAFACT_API_KEY.
Así no la escribes dentro del código ni la subes por error a tu repositorio.
En Windows PowerShell (vale para la ventana actual):
$env:ECUAFACT_API_KEY = "pega_aqui_tu_api_key"
Para que quede guardada en las ventanas nuevas, ejecuta también
setx ECUAFACT_API_KEY "pega_aqui_tu_api_key" y abre otra terminal.
En macOS o Linux (bash o zsh):
export ECUAFACT_API_KEY="pega_aqui_tu_api_key"
Los ejemplos cURL usan sintaxis bash ($ECUAFACT_API_KEY y \ al final de
línea). En Windows ejecútalos desde Git Bash o WSL, o usa los ejemplos de tu
lenguaje.
Cómo sabes que funcionó: en PowerShell, echo $env:ECUAFACT_API_KEY; en
bash, echo $ECUAFACT_API_KEY. Debe imprimir tu API Key, no una línea vacía.
Atención
La API Key da acceso a emitir en nombre de tus contribuyentes. No la pegues en código de navegador, capturas de pantalla ni repositorios. Si se filtra, rótala en el Portal del Cliente (Cuenta > API Keys).
Paso 1. Obtén tu API Key de pruebas#
Si ya tienes una API Key de pruebas, salta al paso 2.
- Abre
https://portal.mynexusapi.com/sandbox. - Completa tus nombres, apellidos, correo y celular, confirma el celular con el código que llega por WhatsApp y crea tu clave con el enlace que llega a tu correo. El detalle está en Sandbox de pruebas.
- Ingresa al Portal del Cliente, abre Pruebas y pulsa Generar en "API Key de pruebas" (si ya tenías una, el botón es Rotar). Copia la API Key, que se muestra una sola vez, en la variable del paso 0.
- Agrega tu RUC y tu certificado en Contribuyentes > Agregar RUC. El detalle está en Sandbox de pruebas.
Resultado esperado: la pantalla "Tu cuenta está creada" al terminar el alta y, dentro del portal, tu API Key de pruebas copiada desde Pruebas.
Cómo sabes que funcionó: la consulta del paso 2 responde 200. Si responde 401, revisa la tabla de errores.
Paso 2. Consulta tu contexto#
GET /v1/contexto devuelve los contribuyentes para los que
tu API Key puede emitir. Lo necesitas porque el valor identificacion de esta
respuesta es el que va en la ruta de emisión y, como
RUC del emisor, dentro del comprobante.
curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \
-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/contexto");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import os
import requests
r = requests.get(
"https://api-sandbox.mynexusapi.com/v1/contexto",
headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como contexto.mjs y ejecuta: node contexto.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', {
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/contexto');
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/contexto"))
.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;
// client: cliente EcuafactClient - ver SDK .NET
Contexto contexto = await client.GetContextoAsync();
Console.WriteLine(contexto.Contribuyentes![0].Identificacion);
from ecuafact import EcuafactClient
# client: cliente EcuafactClient - ver SDK Python
contexto = client.get_contexto()
print(contexto.contribuyentes[0].identificacion)
import { EcuafactClient } from "@ecuafact/sdk";
// client: cliente EcuafactClient - ver SDK Node.js
const contexto = await client.getContexto();
console.log(contexto.contribuyentes[0].identificacion);
<?php
use Ecuafact\Sdk\EcuafactClient;
// $client: cliente EcuafactClient - ver SDK PHP
$contexto = $client->getContexto();
echo $contexto->contribuyentes[0]->identificacion;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.contracts.Contexto;
// client: cliente EcuafactClient - ver SDK Java
Contexto contexto = client.getContexto();
System.out.println(contexto.contribuyentes().get(0).identificacion());
# Una sola vez: guarda tu API Key en el CLI para el entorno de pruebas.
ecuafact login --entorno sandbox
# Muestra tu integración y sus contribuyentes, en tabla.
ecuafact cuenta --entorno sandbox
Resultado esperado (200 OK; tus valores serán los de tu sandbox):
{
"idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345",
"nombre": "Integracion de ejemplo",
"contribuyentes": [
{
"identificacion": "0123456789001",
"puedeEmitir": true,
"puedeRecibir": true,
"tiposComprobante": [
"01",
"03",
"04",
"05",
"06",
"07"
]
}
]
}
| Campo | Tipo | Descripción |
|---|---|---|
idCliente |
string (UUID) | Identificador de tu integración. |
nombre |
string | Nombre de tu integración. |
contribuyentes |
array | Contribuyentes habilitados para tu API Key en este ambiente. Vacío si no tienes ninguno. |
contribuyentes[].identificacion |
string | Identificación completa del contribuyente: su RUC de 13 dígitos o la identificación con la que está registrado. Va en la ruta /v1/contribuyentes/{identificacion}/... y en infoTributaria.ruc. |
contribuyentes[].puedeEmitir |
boolean | true si puedes emitir para este contribuyente. |
contribuyentes[].puedeRecibir |
boolean | Indica si el contribuyente tiene habilitada la recepción. No afecta la emisión. |
contribuyentes[].tiposComprobante |
array de string | Códigos de comprobante habilitados: 01 factura, 03 liquidación de compra, 04 nota de crédito, 05 nota de débito, 06 guía de remisión, 07 comprobante de retención. |
Cómo sabes que funcionó: el código HTTP es 200, ves al menos un
contribuyente con puedeEmitir: true y tiposComprobante incluye "01".
Anota su identificacion: es la que usas en la ruta y en infoTributaria.ruc.
En esta guía usamos la identificación de los
datos de prueba, 0123456789001, en la ruta y en
infoTributaria.ruc. Si tu sandbox tiene otro RUC, reemplázalo por tu valor en
los pasos 3 a 5.
Paso 3. Emite la factura#
Prepara el archivo comprobante.json#
Guarda este JSON como comprobante.json en la carpeta desde la que ejecutarás
los ejemplos. Antes de guardarlo, cambia:
infoTributaria.ruc: tuidentificaciondel paso 2.estabyptoEmi: el establecimiento y punto de emisión que registraste en el alta del sandbox (por defecto001y001).info.fechaEmision: la fecha de hoy en formatodd/MM/yyyy.
{
"origenReferencia": "MiERP",
"referenciaExterna": "FACTURA-2026-0001",
"infoTributaria": {
"ruc": "0123456789001",
"estab": "001",
"ptoEmi": "001"
},
"info": {
"fechaEmision": "10/11/2026",
"tipoIdentificacionComprador": "05",
"identificacionComprador": "0123456789",
"razonSocialComprador": "CONTRIBUYENTE DE EJEMPLO",
"direccionComprador": "DIRECCION DE PRUEBAS",
"totalSinImpuestos": 100.00,
"totalDescuento": 0.00,
"totalConImpuestos": [
{
"codigo": "2",
"codigoPorcentaje": "4",
"tarifa": 15,
"baseImponible": 100.00,
"valor": 15.00
}
],
"propina": 0.00,
"importeTotal": 115.00,
"moneda": "DOLAR",
"pagos": [
{
"formaPago": "01",
"total": 115.00
}
]
},
"detalles": [
{
"codigoPrincipal": "SERV-001",
"descripcion": "Servicio de ejemplo",
"cantidad": 2,
"precioUnitario": 50.00,
"descuento": 0.00,
"precioTotalSinImpuesto": 100.00,
"impuestos": [
{
"codigo": "2",
"codigoPorcentaje": "4",
"tarifa": 15,
"baseImponible": 100.00,
"valor": 15.00
}
]
}
]
}
El tipo de comprobante lo fija la ruta, así que el cuerpo no lleva
infoTributaria.tipoDocumento. POST /v1/contribuyentes/{identificacion}/facturas
emite una factura (01). Si necesitas otro tipo, usa su ruta:
.../liquidaciones-compra (03), .../notas-credito (04),
.../notas-debito (05), .../guias-remision (06) o .../retenciones
(07). Para revisar el cuerpo sin emitir, usa la misma ruta con /validar:
para la factura, POST /v1/contribuyentes/{identificacion}/facturas/validar.
Cómo cuadran los totales (si no cuadran, la API responde 422):
| Cálculo | Valor |
|---|---|
precioTotalSinImpuesto = cantidad x precioUnitario - descuento = 2 x 50.00 - 0.00 |
100.00 |
IVA de la línea (codigo 2, codigoPorcentaje 4 = 15 %) = 100.00 x 15 % |
15.00 |
totalSinImpuestos = suma de precioTotalSinImpuesto |
100.00 |
importeTotal = totalSinImpuestos + IVA + propina = 100.00 + 15.00 + 0.00 |
115.00 |
Suma de pagos[].total (debe ser igual a importeTotal) |
115.00 |
| Campo | Para qué sirve |
|---|---|
origenReferencia |
Nombre de tu sistema (hasta 64 caracteres). Obligatorio. |
referenciaExterna |
Tu identificador interno del documento (hasta 128 caracteres), por ejemplo tu número de factura. Obligatorio. |
infoTributaria.secuencial |
No aparece en el ejemplo a propósito: nosotros asignamos el siguiente número. Ver El secuencial. |
info.tipoIdentificacionComprador |
05 cédula, 04 RUC, 06 pasaporte, 07 consumidor final, 08 identificación del exterior. |
info.propina y info.moneda |
Obligatorios en factura: propina puede ser 0.00; moneda es DOLAR. |
info.pagos[].formaPago |
01 es "sin utilización del sistema financiero" (efectivo). El catálogo completo está en Catálogos. |
No envíes claveAcceso, ambiente, tipoEmision, version ni formato:
nosotros los asignamos y, si los envías, la API responde 422 con el codEstado 3002 (comprobante_invalido). Los
campos de cada tipo de comprobante están en Factura.
El secuencial#
El secuencial es el número consecutivo de 9 dígitos del
comprobante dentro de su serie (estab + ptoEmi + tipo de comprobante +
ambiente). Tienes dos opciones, válidas en pruebas y en producción:
| Opción | Qué envías | Qué pasa |
|---|---|---|
| Automático (recomendado para empezar) | Omites secuencial, o envías "000000000" |
Asignamos el siguiente número libre de la serie. Lo ves dentro de la claveAcceso del paso 4. |
| Explícito | Un número de 1 a 999999999, solo dígitos, máximo 9 (por ejemplo "000000124" o "124") |
Se usa ese número. Si ya existe un comprobante autorizado o pendiente con ese número en la serie, la API responde 409 con el codEstado 3004 (comprobante_duplicado). |
Usa el explícito solo si tu sistema ya lleva su propia numeración. No mezcles las dos opciones en la misma serie sin control: el automático continúa desde el número más alto usado.
Envía el comprobante#
La cabecera Idempotency-Key es obligatoria. Identifica la intención de emitir
este documento: si tu programa reintenta por un corte de red, envía la misma
clave y la API devuelve la misma operación en lugar de crear un duplicado. Usa un
valor estable, como tu número interno de factura (FACTURA-2026-0001) o un UUID
v4 guardado junto al documento. Se admiten letras, dígitos y - _ . : /, hasta
128 caracteres.
curl -s -X POST \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \
-H "X-Api-Key: $ECUAFACT_API_KEY" \
-H "Idempotency-Key: FACTURA-2026-0001" \
-H "Content-Type: application/json" \
-d @comprobante.json
# 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} (paso 4)
using System.Net.Http;
using System.Text;
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 var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas");
peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001");
peticion.Content = new StringContent(
await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");
using HttpResponseMessage respuesta = await http.SendAsync(peticion);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import json
import os
import requests
with open("comprobante.json", encoding="utf-8") as archivo:
cuerpo = json.load(archivo)
r = requests.post(
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas",
headers={
"X-Api-Key": os.environ["ECUAFACT_API_KEY"],
"Idempotency-Key": "FACTURA-2026-0001",
},
json=cuerpo,
timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs
import { readFile } from 'node:fs/promises';
const res = await fetch(
'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas',
{
method: 'POST',
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'Idempotency-Key': 'FACTURA-2026-0001',
'Content-Type': 'application/json'
},
body: await readFile('comprobante.json', 'utf8')
});
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
'Idempotency-Key: FACTURA-2026-0001',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
]);
$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;
import java.nio.file.Files;
import java.nio.file.Path;
// 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/contribuyentes/0123456789001/facturas"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.header("Idempotency-Key", "FACTURA-2026-0001")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json"))))
.build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
using Ecuafact.Sdk;
// client: cliente EcuafactClient - ver SDK .NET
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado} / codEstado: {resultado.Admission.CodEstado}");
from ecuafact import EcuafactClient
# client: cliente EcuafactClient - ver SDK Python
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado} / codEstado: {resultado.admission.cod_estado}")
import { EcuafactClient } from "@ecuafact/sdk";
// client: cliente EcuafactClient - ver SDK Node.js
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado} / codEstado: ${resultado.admission.codEstado}`);
<?php
use Ecuafact\Sdk\EcuafactClient;
// $client: cliente EcuafactClient - ver SDK PHP
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado
. ' / codEstado: ' . $resultado->admission->codEstado;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EmisionResultado;
// client: cliente EcuafactClient - ver SDK Java
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()
+ " / codEstado: " + resultado.admission().codEstado());
# Envía el comprobante y muestra el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox
Resultado esperado: HTTP 202 Accepted con este cuerpo:
{
"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": "FACTURA-2026-0001",
"claveAcceso": null,
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": null
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | recibido: el comprobante pasó nuestras validaciones y lo aceptamos. Todavía no es una autorización del SRI. |
codEstado |
number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu código debe aceptar los dos valores. |
errores |
array de string | Viene siempre; aquí es una lista vacía. |
idOperacion |
string (UUID) | Identificador de la operación. Guárdalo, porque lo necesitas en el paso 4. |
urlEstado |
string | URL completa del seguimiento. Puedes llamarla tal como viene en el paso 4. |
ambiente |
number | 1 pruebas, 2 producción. |
tipoDocumento |
string | Tipo de comprobante (01 factura). |
numeroDocumento |
string | Número de la factura con la forma estab-ptoEmi-secuencial, incluido el secuencial que te asignamos. |
referenciaExterna |
string | La referenciaExterna que enviaste. |
claveAcceso |
string o null |
null con el codEstado 1001; con el 1002 ya trae la clave de 49 dígitos. En cualquier caso la ves en el paso 4. |
fhRecibido |
string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |
fhAutorizacion |
null |
La autorización todavía no existe. |
La respuesta trae además dos cabeceras: Location, con la misma URL de
urlEstado, y X-Correlation-Id, el identificador de la petición, que te
conviene incluir si escribes a soporte.
Usa el código HTTP para saber si la petición tuvo éxito. Cuando falla, el
cuerpo trae además un número en codEstado, por ejemplo 3003
(solicitud_invalida) en un HTTP 400, que es el valor con el que programas tu
lógica. El catálogo completo está en
Errores.
Cómo sabes que funcionó: la API responde 202 con estado en recibido, el
codEstado 1001 o 1002 y un idOperacion. Un 202 significa que el comprobante quedó recibido, no
autorizado: el SRI todavía no respondió, así que sigue con el paso 4.
Nota
Si repites el envío con la misma Idempotency-Key y el mismo archivo, recibes
un 202 con el mismo idOperacion y el estado actual de la operación. Es lo
esperado y no se emite otra factura. Para emitir otra factura usa otra Idempotency-Key y otra
referenciaExterna.
Paso 4. Sigue la operación hasta la autorización#
La emisión es asíncrona: nos encargamos de que el comprobante llegue al SRI y de obtener su respuesta. Eso tarda desde unos segundos hasta varios minutos, y puedes enterarte del resultado de dos formas:
- Seguimiento por consulta (lo que haces en esta guía): consulta
GET /v1/operaciones/{idOperacion}cada 10 segundos, con un tope de 5 minutos (30 consultas). No consultes más seguido: cada consulta cuenta para tu límite de solicitudes (60 por minuto en un sandbox; 200 por minuto por defecto en otras integraciones). - Webhook (recomendado en producción): registras una URL en el Portal del
Cliente (Integración > Eventos) y te enviamos
document.authorized,document.rejectedodocument.failedcuando hay resultado. Cómo probarlo en este quickstart: Alternativa: recibe el resultado por webhook.
El bucle se detiene cuando hay un resultado final, es decir, cuando estado
deja de ser recibido.
Reemplaza el idOperacion por el que recibiste en el paso 3.
ID_OPERACION="3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" # el idOperacion del paso 3
for intento in $(seq 1 30); do
respuesta=$(curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/$ID_OPERACION" \
-H "X-Api-Key: $ECUAFACT_API_KEY")
echo "$respuesta"
case "$respuesta" in
*'"estado":"recibido"'*) ;; # sin resultado final: sigue esperando
*) break ;; # resultado final o error: revisa "Si algo falla"
esac
sleep 10
done
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"; // el idOperacion del paso 3
for (int intento = 1; intento <= 30; intento++)
{
using HttpResponseMessage respuesta = await http.GetAsync($"/v1/operaciones/{idOperacion}");
string cuerpo = await respuesta.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)respuesta.StatusCode} {cuerpo}");
if (!respuesta.IsSuccessStatusCode)
{
break;
}
using JsonDocument json = JsonDocument.Parse(cuerpo);
string estado = json.RootElement.GetProperty("estado").GetString()!;
if (estado != "recibido")
{
break;
}
await Task.Delay(TimeSpan.FromSeconds(10));
}
import os
import time
import requests
id_operacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" # el idOperacion del paso 3
for intento in range(30):
r = requests.get(
f"https://api-sandbox.mynexusapi.com/v1/operaciones/{id_operacion}",
headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
timeout=30,
)
print(r.status_code, r.text)
if r.status_code != 200:
break
if r.json()["estado"] != "recibido":
break
time.sleep(10)
// Node.js 18 o superior. Guarda como seguimiento.mjs y ejecuta: node seguimiento.mjs
const idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'; // el idOperacion del paso 3
const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms));
for (let intento = 1; intento <= 30; intento++) {
const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones/${idOperacion}`, {
headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
const cuerpo = await res.text();
console.log(res.status, cuerpo);
if (res.status !== 200) break;
const { estado } = JSON.parse(cuerpo);
if (estado !== 'recibido') break;
await esperar(10000);
}
<?php
$idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'; // el idOperacion del paso 3
for ($intento = 1; $intento <= 30; $intento++) {
$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);
echo $estado . ' ' . $cuerpo . PHP_EOL;
if ($estado !== 200) {
break;
}
$operacion = json_decode($cuerpo, true);
if ($operacion['estado'] !== 'recibido') {
break;
}
sleep(10);
}
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
String idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el idOperacion del paso 3
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();
for (int intento = 1; intento <= 30; intento++) {
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
String cuerpo = respuesta.body();
System.out.println(respuesta.statusCode() + " " + cuerpo);
if (respuesta.statusCode() != 200) {
break;
}
// Busqueda de texto simple para no depender de una libreria JSON.
boolean terminado = !cuerpo.contains("\"estado\":\"recibido\"");
if (terminado) {
break;
}
Thread.sleep(10_000);
}
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
// client: cliente EcuafactClient - ver SDK .NET
Operation operacion = await client.GetOperacionAsync(idOperacion);
Console.WriteLine($"{operacion.Estado} / {operacion.CodEstado}");
from ecuafact import EcuafactClient
# client: cliente EcuafactClient - ver SDK Python
operacion = client.get_operacion(id_operacion)
print(operacion.estado, operacion.cod_estado)
import { EcuafactClient } from "@ecuafact/sdk";
// client: cliente EcuafactClient - ver SDK Node.js
const operacion = await client.getOperacion(idOperacion);
console.log(operacion.estado, operacion.codEstado);
<?php
use Ecuafact\Sdk\EcuafactClient;
// $client: cliente EcuafactClient - ver SDK PHP
$operacion = $client->getOperacion($idOperacion);
echo $operacion->estado . ' ' . $operacion->codEstado;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.contracts.Operation;
// client: cliente EcuafactClient - ver SDK Java
Operation operacion = client.getOperacion(idOperacion);
System.out.println(operacion.estado() + " " + operacion.codEstado());
# Consulta una vez el estado de la operación.
ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox
# O emite y espera el resultado del SRI en un solo comando (hasta 180 segundos).
ecuafact emitir comprobante.json --esperar --entorno sandbox
Resultado esperado: las primeras consultas muestran estado recibido,
con el codEstado 1001 o, cuando la factura ya tiene clave de acceso, 1002, y
sin msgError. La última (200 OK) se ve así:
{
"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": "FACTURA-2026-0001",
"claveAcceso": "0710202601012345678900110010010000001231234567811",
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": "2026-11-09T10:15:18-05:00"
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | recibido mientras no hay resultado final; después, autorizado, rechazado, rechazo_configuracion, error o cancelado. Significado y qué hacer en Ciclo de vida. |
codEstado |
number | Código de 4 dígitos que precisa el resultado; su primer dígito coincide con el estado. 2001 es autorizado, y cuando el comprobante no se autorizó dice la causa, por ejemplo 3001 en un rechazo del SRI. Los valores están en Errores. |
msgError |
string | Descripción general del código. Solo aparece cuando el comprobante no se autorizó. |
errores |
array de string | Detalle del resultado; en un rechazo del SRI trae su mensaje. Viene siempre y aquí es una lista vacía. |
idOperacion |
string (UUID) | La operación que consultaste. |
urlEstado |
string | URL completa de este seguimiento. |
ambiente |
number | 1 pruebas, 2 producción. |
tipoDocumento |
string | Tipo de comprobante (01 factura). |
numeroDocumento |
string o null |
Número de la factura, estab-ptoEmi-secuencial. |
referenciaExterna |
string o null |
La referenciaExterna que enviaste. |
claveAcceso |
string o null |
Clave de acceso de 49 dígitos que asignamos nosotros. Es null mientras el codEstado es 1001. La necesitas en el paso 5. |
fhRecibido |
string | Cuándo recibimos la emisión, en ISO 8601 con zona horaria. |
fhAutorizacion |
string o null |
Fecha de autorización. Puede ser null aun con autorizado, porque algunas autorizaciones no traen fecha. |
Cómo sabes que funcionó: estado es autorizado, el codEstado es 2001 y
claveAcceso tiene 49 dígitos. Copia la claveAcceso para el paso 5. El
secuencial que se asignó aparece en numeroDocumento (001-001-000000123 en el
ejemplo).
Si el bucle termina con otro resultado:
| Resultado | Qué significa | Qué hacer |
|---|---|---|
estado = rechazado y codEstado = 3001 (rechazo_sri) |
El SRI rechazó el comprobante; errores trae su mensaje. |
Corrige el dato y emite de nuevo con una nueva Idempotency-Key y una nueva referenciaExterna, sin secuencial para que se asigne el siguiente número. Reusar el número rechazado responde 409 con el codEstado 3004 (comprobante_duplicado). Ver Ciclo de vida. |
estado = rechazado y codEstado = 3002 (comprobante_invalido) |
El comprobante no pasó la validación fiscal antes de llegar al SRI; errores dice qué corregir. |
Corrige y reenvía con nueva Idempotency-Key y nueva referenciaExterna. Si quieres conservar el número, envía en infoTributaria.secuencial el mismo secuencial, que ves en el numeroDocumento de la respuesta. La respuesta puede traer el mismo idOperacion. |
estado = rechazo_configuracion |
Falta o está mal una configuración del emisor, como su firma electrónica; el codEstado, de 4001 a 4004, dice cuál. |
Corrige la configuración en el Portal del Cliente y reenvía con nueva Idempotency-Key y nueva referenciaExterna. Ver Ciclo de vida. |
estado = error |
No se pudo emitir; el codEstado dice si puedes reenviar. |
Sigue la fila de su codEstado en Ciclo de vida. Con 5007 (resultado_no_confirmado) o 5001 (error_interno) no reemitas y escribe a soporte con el idOperacion. |
estado = cancelado |
La plataforma canceló el envío antes de emitirlo. | Reenvía con nueva Idempotency-Key y nueva referenciaExterna. Si repites la misma referenciaExterna con el mismo cuerpo, la API te devuelve la operación cancelada y no emite nada. |
Pasaron 5 minutos y estado sigue en recibido |
El SRI todavía no da un resultado final. No es un error. | No reemitas, porque emitir de nuevo puede duplicar el comprobante. Consulta más tarde o espera el webhook, como se explica en Webhooks. |
Alternativa: recibe el resultado por webhook#
En lugar del bucle, o además de él, puedes recibir el resultado en tu servidor. Te lo recomendamos para producción: te avisamos cuando hay resultado y no gastas solicitudes en consultas.
Prerequisitos adicionales:
- Una URL pública
https://(puerto 443) que llegue a tu equipo o servidor. En tu equipo de desarrollo puedes exponer un puerto local con un túnel como ngrok o cloudflared (Probar en local). - Un receptor que verifique la firma. Copia el de tu lenguaje (.NET, Python, Node.js, PHP o Java) de Implementación en tu servidor y ejecútalo en el puerto 3000.
Pasos:
- Entra al Portal del Cliente (
https://portal.mynexusapi.com) y abre Integración > Eventos. - Pulsa Nuevo destino, escribe tu URL (por ejemplo
https://tu-subdominio.ngrok-free.app/webhooks/ecuafact), deja marcados los tres eventos y pulsa Crear. - Copia el secreto que muestra el portal (se muestra una sola vez) en la
variable
ECUAFACT_WEBHOOK_SECRETde tu receptor y reinícialo. - Pulsa Probar. En Entregas debe aparecer el evento de prueba con estado
Entregado y
HTTP200. - Emite otra factura como en el paso 3, con otra
Idempotency-Keyy otrareferenciaExterna(por ejemploFACTURA-2026-0002en ambas).
Resultado esperado: cuando el SRI autoriza, tu receptor recibe un POST con
la cabecera Ecuafact-Signature y este cuerpo:
{
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"estado": "autorizado",
"codEstado": 2001,
"errores": [],
"tipoDocumento": "01",
"claveAcceso": "0710202601012345678900110010010000001231234567811",
"eventType": "document.authorized",
"resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"occurredAtUtc": "2026-11-09T15:15:18.1234567Z"
}
| Campo | Tipo | Descripción |
|---|---|---|
idOperacion |
string (UUID) | La operación que recibiste en el 202 de la emisión. |
estado |
string | El mismo estado del seguimiento: autorizado en document.authorized; rechazado, rechazo_configuracion o error en los demás eventos, que además traen msgError. |
codEstado |
number | El mismo codEstado del seguimiento, por ejemplo 2001 en document.authorized. |
errores |
array de string | El detalle del resultado, como en el seguimiento. Viene siempre. |
tipoDocumento |
string | Tipo de comprobante (01 factura), cuando se conoce. |
claveAcceso |
string | Clave de acceso de 49 dígitos. Úsala en el paso 5. En document.failed puede faltar. |
eventType |
string | document.authorized, document.rejected o document.failed. |
resourceId |
string (UUID) | En estos eventos, igual a idOperacion. Úsalo con eventType para descartar duplicados. |
occurredAtUtc |
string | Momento del evento en UTC (ISO 8601). |
Cómo sabes que funcionó: tu receptor imprime Autorizado con el
idOperacion y la claveAcceso, y en Entregas la entrega figura como
Entregado. Con esa claveAcceso sigue al paso 5. Los demás eventos y qué
hacer con cada uno están en Webhooks.
Paso 5. Descarga el RIDE y el XML#
Con la claveAcceso del paso 4 descarga el RIDE (PDF) y el XML del comprobante
autorizado:
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml
{identificacion} es el mismo valor de la ruta de emisión, la identificacion
del paso 2. Reemplaza la claveAcceso del ejemplo por la tuya.
curl -s -o ride.pdf -w "HTTP %{http_code}\n" \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride" \
-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 claveAcceso = "0710202601012345678900110010010000001231234567811"; // la claveAcceso del paso 4
using HttpResponseMessage respuesta = await http.GetAsync(
$"/v1/contribuyentes/0123456789001/comprobantes/{claveAcceso}/ride");
Console.WriteLine($"{(int)respuesta.StatusCode} {respuesta.Content.Headers.ContentType}");
if (respuesta.IsSuccessStatusCode)
{
await File.WriteAllBytesAsync("ride.pdf", await respuesta.Content.ReadAsByteArrayAsync());
}
else
{
Console.WriteLine(await respuesta.Content.ReadAsStringAsync());
}
import os
import requests
clave_acceso = "0710202601012345678900110010010000001231234567811" # la claveAcceso del paso 4
r = requests.get(
f"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/{clave_acceso}/ride",
headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
timeout=30,
)
print(r.status_code, r.headers.get("Content-Type"))
if r.status_code == 200:
with open("ride.pdf", "wb") as archivo:
archivo.write(r.content)
else:
print(r.text)
// Node.js 18 o superior. Guarda como ride.mjs y ejecuta: node ride.mjs
import { writeFile } from 'node:fs/promises';
const claveAcceso = '0710202601012345678900110010010000001231234567811'; // la claveAcceso del paso 4
const res = await fetch(
`https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/${claveAcceso}/ride`,
{ headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } });
console.log(res.status, res.headers.get('content-type'));
if (res.ok) {
await writeFile('ride.pdf', Buffer.from(await res.arrayBuffer()));
} else {
console.log(await res.text());
}
<?php
$claveAcceso = '0710202601012345678900110010010000001231234567811'; // la claveAcceso del paso 4
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/' . $claveAcceso . '/ride');
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 . PHP_EOL;
if ($estado === 200) {
file_put_contents('ride.pdf', $cuerpo);
} else {
echo $cuerpo . PHP_EOL;
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
// Dentro de: public static void main(String[] args) throws Exception
String claveAcceso = "0710202601012345678900110010010000001231234567811"; // la claveAcceso del paso 4
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
.uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/" + claveAcceso + "/ride"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.GET()
.build();
HttpResponse<byte[]> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray());
System.out.println(respuesta.statusCode());
if (respuesta.statusCode() == 200) {
Files.write(Path.of("ride.pdf"), respuesta.body());
} else {
System.out.println(new String(respuesta.body()));
}
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
// client: cliente EcuafactClient - ver SDK .NET
ArchivoComprobante ride = await client.DescargarRideAsync("0123456789001", claveAcceso);
await File.WriteAllBytesAsync("ride.pdf", ride.Contenido);
from ecuafact import EcuafactClient
# client: cliente EcuafactClient - ver SDK Python
archivo = client.descargar_ride("0123456789001", clave_acceso)
with open("ride.pdf", "wb") as destino:
destino.write(archivo.contenido)
import { writeFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";
// client: cliente EcuafactClient - ver SDK Node.js
const archivo = await client.descargarRide("0123456789001", claveAcceso);
await writeFile("ride.pdf", archivo.contenido);
<?php
use Ecuafact\Sdk\EcuafactClient;
// $client: cliente EcuafactClient - ver SDK PHP
$archivo = $client->descargarRide('0123456789001', $claveAcceso);
file_put_contents('ride.pdf', $archivo->contenido);
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import java.nio.file.Files;
import java.nio.file.Path;
// client: cliente EcuafactClient - ver SDK Java
ArchivoComprobante archivo = client.descargarRide("0123456789001", claveAcceso);
Files.write(Path.of("ride.pdf"), archivo.contenido());
# Descarga el RIDE y el XML en la carpeta actual.
ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride,xml --entorno sandbox
Para el XML cambia /ride por /xml en la ruta (en los SDK: DescargarXmlAsync,
descargar_xml, descargarXml). Este ejemplo guarda el archivo como
factura.xml e imprime las cabeceras para que veas Content-Type:
curl -s -o factura.xml -D - \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml" \
-H "X-Api-Key: $ECUAFACT_API_KEY"
Resultado esperado:
| Descarga | HTTP | Content-Type |
Contenido |
|---|---|---|---|
| RIDE | 200 OK |
application/pdf |
El PDF del comprobante. |
| XML | 200 OK |
application/xml |
El XML del comprobante, con nombre sugerido {claveAcceso}.xml (cabecera Content-Disposition). |
| XML pendiente | 404 Not Found |
application/json |
Si falta la autorización o el archivo, recibes el codEstado 3013 (no_encontrado). Reintenta la descarga en unos minutos, sin volver a emitir. |
Cómo sabes que funcionó: el RIDE que descargaste (los ejemplos HTTP y SDK lo
guardan como ride.pdf) se abre en tu visor de PDF y muestra la clave de acceso
y el número de autorización. Con eso completaste la guía.
Detalle de cada descarga: Descargar PDF y Descargar XML.
Si algo falla#
Cuando una petición falla, la API responde con un código HTTP de error y un
cuerpo con estado, codEstado, msgError y errores. En la emisión, esos
mismos campos llegan dentro de la forma completa de la respuesta 202, con
idOperacion, urlEstado, numeroDocumento, claveAcceso y las fechas en
null, porque no se creó ninguna operación:
{
"estado": "rechazado",
"codEstado": 3003,
"msgError": "La solicitud no es válida.",
"errores": [
"Idempotency-Key: La cabecera Idempotency-Key es obligatoria y debe ser ASCII estable (maximo 128 caracteres)."
],
"idOperacion": null,
"urlEstado": null,
"ambiente": 1,
"tipoDocumento": "01",
"numeroDocumento": null,
"referenciaExterna": "FACTURA-2026-0001",
"claveAcceso": null,
"fhRecibido": null,
"fhAutorizacion": null
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | Estado que corresponde al código. Su valor coincide con el primer dígito de codEstado: 3 es rechazado, 4 rechazo_configuracion y 5 error. |
codEstado |
number | Código estable de la API, de 4 dígitos. Programa contra este valor. No es el código HTTP. |
msgError |
string | Descripción fija y breve del código. Puedes mostrarla, pero no decidas con ella. |
errores |
array de string | Viene siempre. En 3002 (comprobante_invalido) trae hasta 20 mensajes, uno por problema, con la ruta del campo (por ejemplo $.infoTributaria.ruc: Campo obligatorio.). En 3003 (solicitud_invalida) trae el detalle de los parámetros o del cuerpo que no se pudo leer; puede ser más de uno. Corrige todos los que puedas y reenvía. En el resto de errores es una lista vacía ([]). |
Los errores más probables en este quickstart:
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
3009 (credenciales_invalidas) |
401 | Falta la cabecera X-Api-Key o la API Key es incorrecta, está revocada o es de otro ambiente. |
Corrige: revisa que ECUAFACT_API_KEY tenga la API Key completa (paso 0). Si la revocaste, crea otra. |
3010 (ip_no_autorizada) |
403 | En producción, la API Key es correcta pero tu IP de salida no está registrada para esa API Key. En sandbox no ocurre por IP. | Registra tu IP en Cuenta > IP permitidas del Portal del Cliente (cómo). |
3011 (acceso_denegado) |
403 | El contribuyente de la ruta no está habilitado para tu API Key o el tipo de comprobante no está habilitado. | Corrige: usa en la ruta y en infoTributaria.ruc la identificacion del paso 2. |
3003 (solicitud_invalida) |
400 | Falta Idempotency-Key o tiene caracteres no admitidos, el JSON está mal formado, o la claveAcceso de la descarga no es válida. |
Corrige: agrega la cabecera; valida el JSON (comas, comillas); copia la claveAcceso completa. |
3002 (comprobante_invalido) |
422 | El comprobante tiene un campo faltante o mal formado, totales que no cuadran, un infoTributaria.ruc distinto de la identificación de la ruta, o un campo que no se envía (claveAcceso, ambiente, version). errores dice cuál. |
Corrige el campo indicado en errores y reenvía con la misma Idempotency-Key. Un 422 descuenta un documento de tu cupo como intento, así que valida antes con /validar, que no lo descuenta. |
3004 (comprobante_duplicado) |
409 | Ya existe un comprobante autorizado o pendiente con el mismo estab, ptoEmi y secuencial. |
Corrige: omite secuencial para que se asigne el siguiente, o usa otro número. |
3005 (conflicto_idempotencia) |
409 | Usaste una Idempotency-Key que ya se usó con un cuerpo distinto, o una referenciaExterna (con el mismo origenReferencia) que ya pertenece a otro comprobante. |
Corrige: para un comprobante nuevo usa una Idempotency-Key y una referenciaExterna nuevas; para reintentar, envía exactamente el mismo cuerpo. |
3013 (no_encontrado) |
404 | Descarga del RIDE o XML: el comprobante no existe o aún no está disponible. | Reintenta cuando el estado de la operación sea autorizado; revisa la claveAcceso y la identificacion de la ruta. |
5005 (limite_solicitudes) |
429 | Superaste tu límite de solicitudes por minuto (60 en un sandbox), por ejemplo con un bucle de seguimiento sin espera. | Reintenta después de los segundos de la cabecera Retry-After y agrega la espera de 10 segundos. |
El catálogo completo está en Errores.
Siguientes pasos#
- Ciclo de vida del comprobante: qué hacer ante cada
estadoy cadacodEstado. - Webhooks: recibe el resultado sin consultar en bucle.
- Datos de prueba: provoca cada caso (duplicado, idempotencia, rechazo) antes de ir a producción.
- Comprobantes electrónicos: estructura de los seis tipos de comprobante.