En esta página
Buenas prácticas
Las prácticas que hacen estable una integración en producción, desde la idempotencia y los reintentos hasta el cupo y la seguridad.
Una integración que funciona en pruebas puede fallar en producción por motivos que no tienen que ver con el comprobante: un timeout, un corte de red, un proceso que se reinicia a mitad de un envío o un lote que supera el límite de solicitudes. Aquí te recomendamos las prácticas que evitan esos problemas, con código listo para copiar en cada caso.
Te sugerimos leerla antes de pasar a producción y volver a ella cuando diseñes los reintentos, la emisión en lote o el seguimiento. Al final tienes una lista de verificación con todo lo que te conviene tener resuelto.
Conceptos#
- Idempotencia. Repetir la misma petición produce el mismo efecto que
hacerla una vez. En la emisión la consigues con la cabecera
Idempotency-Key: si tu proceso reenvía un comprobante porque no supo si llegó, la API reconoce la intención y no crea un segundo comprobante. Más detalle en Idempotencia. - Reintento con espera exponencial y jitter. Ante un fallo temporal esperas cada vez más entre intentos (1, 2, 4, 8 segundos...) y agregas un componente aleatorio, el jitter, para que muchos clientes no reintenten al mismo tiempo.
- Asincronía. La emisión responde
202 Acceptedcuando recibe el comprobante, y la autorización del SRI llega después. El recorrido completo está en Ciclo de vida del comprobante.
Idempotencia#
Reglas de la Idempotency-Key#
La cabecera Idempotency-Key identifica la intención de emitir un comprobante
concreto. Estas son sus reglas:
| Regla | Valor |
|---|---|
| Obligatoria | Sí, en la ruta de emisión del tipo, por ejemplo POST /v1/contribuyentes/{identificacion}/facturas para una factura. Si falta, la API responde 400 con el codEstado 3003 (solicitud_invalida). |
| Longitud | De 1 a 128 caracteres. |
| Caracteres | Letras ASCII sin tildes (A-Z, a-z), dígitos (0-9) y - _ . : /. |
| Alcance | Tu integración (todas tus API Key) y el ambiente. La misma clave en pruebas y en producción son intenciones distintas. |
| Retención | 7 días desde que se usó por primera vez. |
Qué responde la API#
La respuesta depende de si la clave y el cuerpo ya se habían usado:
| Envías | Respuesta | Qué significa |
|---|---|---|
| Clave nueva | 202 con estado en recibido y un idOperacion nuevo. |
La API recibió una emisión nueva. |
| Misma clave y mismo cuerpo admitido | Un 202 con el mismo idOperacion y el estado actual de la operación. |
La API reconoce el reintento y no crea otro comprobante. |
| Misma clave y mismo cuerpo rechazado con 422 | El mismo 422 de validación, sin otro consumo. | Corrige el documento antes de usar una nueva clave. |
| Misma clave y otro cuerpo | 409 con el codEstado 3005 (conflicto_idempotencia). |
Hay un conflicto, porque esa clave ya pertenece a otra intención. |
Otra clave, misma referenciaExterna (con el mismo origenReferencia) y mismo cuerpo |
Un 202 con el mismo idOperacion y el estado actual de la operación. |
La referencia también identifica la intención. |
Otra clave, misma referenciaExterna y otro cuerpo |
409 si la operación sigue pendiente o fue autorizada. Tras un rechazo terminal admite la corrección con 202. | La corrección de un comprobante rechazado consume un documento. |
"Mismo cuerpo" significa el mismo contenido del comprobante. Si en el reintento cambias un importe, una fecha o el orden de los detalles, la API lo trata como otro cuerpo.
Cómo generar y guardar la clave#
Elige una de estas dos formas y aplícala siempre igual:
| Forma | Ejemplo | Cuándo conviene |
|---|---|---|
| Derivada de tu documento interno | FACTURA-2026-0001 (tu número interno de factura) |
Cuando tu sistema ya tiene un identificador único y estable por documento. |
| UUID v4 generado una vez | 5b0c6f6e-3c2a-4d7e-9a51-7f2f0d6b2c11 |
Cuando no tienes un identificador estable o puede repetirse entre sistemas. |
Lo importante es guardar la clave antes del primer envío, para poder reutilizarla en cualquier reintento:
- Al crear el documento en tu sistema, genera la
Idempotency-Keyy lareferenciaExternay guárdalas en la misma fila, dentro de la misma transacción de base de datos. - Envía la emisión con esos valores.
- Si no recibes respuesta porque hubo un timeout, un corte de red o tu proceso se reinició, lee los valores guardados y reenvía el mismo cuerpo con la misma clave.
- Al recibir el 202, guarda el
idOperacionen la misma fila.
Atención
No generes una Idempotency-Key nueva en cada intento. Si el primer envío
llegó y reintentas con otra clave y otra referenciaExterna, puedes emitir dos
comprobantes con validez fiscal.
Ejemplo#
Guarda el JSON de Factura como comprobante.json. El
tipo de comprobante lo fija la ruta de emisión, así que este ejemplo emite una
factura en /v1/contribuyentes/{identificacion}/facturas.
Importante
Ambiente de pruebas: sin validez fiscal.
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}
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. comprobante: tu Estructura del comprobante.
// Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado.
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
string clave = resultado.IdempotencyKey; // guardala para reintentos de tu aplicacion
# client: cliente EcuafactClient - ver SDK Python. comprobante: tu Estructura del comprobante.
# Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado.
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
clave = resultado.idempotency_key # guardala para reintentos de tu aplicacion
// client: cliente EcuafactClient - ver SDK Node.js. comprobante: tu Estructura del comprobante.
// Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado.
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
const clave = resultado.idempotencyKey; // guardala para reintentos de tu aplicacion
<?php
// $client: cliente EcuafactClient - ver SDK PHP. $comprobante: tu Estructura del comprobante.
// Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado.
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
$clave = $resultado->idempotencyKey; // guardala para reintentos de tu aplicacion
import com.ecuafact.sdk.EmisionResultado;
// client: cliente EcuafactClient - ver SDK Java. comprobante: tu Estructura del comprobante.
// Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado.
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
String clave = resultado.idempotencyKey(); // guardala para reintentos de tu aplicacion
# Resultado esperado: el idOperacion de la emisión. Si repites el comando con el
# mismo archivo, la API reconoce el reintento y no emite un segundo comprobante.
ecuafact emitir comprobante.json --entorno sandbox
Resultado esperado. La primera vez recibes un 202 con estado en
recibido y un idOperacion. Si ejecutas el mismo ejemplo otra vez sin
cambiar comprobante.json, recibes un 202 con el mismo idOperacion y el
estado actual de la operación, y así compruebas que tu reintento no duplica el comprobante.
Errores y reintentos#
No todos los errores se reintentan. Los fallos temporales se repiten con el mismo cuerpo y la misma clave; los demás se corrigen antes de volver a enviar.
| Situación | Reintentar | Cómo |
|---|---|---|
| Timeout o corte de red (no recibiste respuesta) | Sí | Reenvía el mismo cuerpo con la misma Idempotency-Key, con espera exponencial. |
500 con el codEstado 5001 (error_interno), 502 con 5003 (error_dependencia), 503 con 5002 (servicio_no_disponible) o 504 con 5004 (tiempo_agotado) |
Sí | Reenvía el mismo cuerpo con la misma Idempotency-Key, con espera exponencial. En un 503, respeta Retry-After. |
429 con el codEstado 5005 (limite_solicitudes) |
Sí | Espera al menos lo que indica Retry-After y repite la misma petición. |
429 con el codEstado 4004 (cupo_agotado) |
No | El cupo se agotó; amplíalo como se explica en Consumo y cuotas. |
| 400, 401, 403, 404, 413, 415 o 422 | No | Corrige la causa, porque repetir la petición igual da el mismo error. |
409 con el codEstado 3004 (comprobante_duplicado) |
No | El número ya existe; busca el comprobante existente. |
409 con el codEstado 3005 (conflicto_idempotencia) |
No | Reenvía el cuerpo original, o usa una clave nueva si es otra emisión. |
Decide siempre con el estado HTTP y el codEstado del cuerpo, nunca con el texto
de msgError. El detalle de cada código está en el
catálogo de codEstado.
Reintentos con espera exponencial#
Para los errores que sí se reintentan, este es el algoritmo recomendado:
| Parámetro | Valor sugerido |
|---|---|
| Intentos máximos | 5: el primero más 4 reintentos. |
Espera antes del reintento n |
Aleatoria entre 0 y min(60, 2^n) segundos (jitter completo). |
Si la respuesta trae Retry-After |
Espera el mayor valor entre Retry-After y la espera calculada. |
| Timeout por intento | 30 segundos. |
| Al agotar los intentos | Deja la emisión pendiente en tu sistema con su Idempotency-Key y reinténtala más tarde, por ejemplo en un proceso programado. |
Si usas nuestros SDK oficiales, no necesitas programar estos reintentos: ya
reintentan, con la misma Idempotency-Key, los errores de red y las respuestas
408, 425, 500, 502, 503 y 504. Por defecto
hacen 3 intentos en total y respetan Retry-After. Un 429 con el codEstado
5005 también lo reintentan por defecto, después de esperar Retry-After, y un
429 con el codEstado 4004 no lo reintentan nunca; el detalle está en la guía de cada SDK.
Los ejemplos siguientes son para integraciones HTTP directas. Para ejecutarlos,
guarda el JSON de Factura como comprobante.json.
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Text.Json;
string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient
{
BaseAddress = new Uri("https://api-sandbox.mynexusapi.com"),
Timeout = TimeSpan.FromSeconds(30)
};
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
string cuerpo = await File.ReadAllTextAsync("comprobante.json");
const string idempotencyKey = "FACTURA-2026-0001"; // guardada con tu documento ANTES del primer intento
int[] reintentables = { 429, 500, 502, 503, 504 };
const int maxIntentos = 5;
for (int intento = 1; intento <= maxIntentos; intento++)
{
TimeSpan retryAfter = TimeSpan.Zero;
try
{
using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas");
peticion.Headers.Add("Idempotency-Key", idempotencyKey);
peticion.Content = new StringContent(cuerpo, Encoding.UTF8, "application/json");
using HttpResponseMessage respuesta = await http.SendAsync(peticion);
int estado = (int)respuesta.StatusCode;
string texto = await respuesta.Content.ReadAsStringAsync();
int codEstado = 0;
try { codEstado = JsonDocument.Parse(texto).RootElement.GetProperty("codEstado").GetInt32(); }
catch (Exception) { }
// 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si.
if (!reintentables.Contains(estado) || codEstado == 4004)
{
Console.WriteLine($"Respuesta definitiva: {estado} {texto}");
return;
}
retryAfter = respuesta.Headers.RetryAfter?.Delta ?? TimeSpan.Zero;
Console.WriteLine($"Intento {intento}: HTTP {estado}");
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
Console.WriteLine($"Intento {intento}: sin respuesta ({ex.GetType().Name})");
}
if (intento == maxIntentos)
{
break;
}
double tope = Math.Min(60, Math.Pow(2, intento));
TimeSpan calculada = TimeSpan.FromSeconds(Random.Shared.NextDouble() * tope);
await Task.Delay(retryAfter > calculada ? retryAfter : calculada);
}
Console.WriteLine("Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.");
import json
import os
import random
import time
import requests
URL = "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas"
IDEMPOTENCY_KEY = "FACTURA-2026-0001" # guardada con tu documento ANTES del primer intento
REINTENTABLES = {429, 500, 502, 503, 504}
MAX_INTENTOS = 5
with open("comprobante.json", encoding="utf-8") as archivo:
cuerpo = json.load(archivo)
definitiva = False
for intento in range(1, MAX_INTENTOS + 1):
retry_after = 0.0
try:
r = requests.post(
URL,
headers={
"X-Api-Key": os.environ["ECUAFACT_API_KEY"],
"Idempotency-Key": IDEMPOTENCY_KEY,
},
json=cuerpo,
timeout=30,
)
try:
cod_estado = r.json().get("codEstado", 0)
except ValueError:
cod_estado = 0
# 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si.
if r.status_code not in REINTENTABLES or cod_estado == 4004:
print("Respuesta definitiva:", r.status_code, r.text)
definitiva = True
break
retry_after = float(r.headers.get("Retry-After", "0"))
print(f"Intento {intento}: HTTP {r.status_code}")
except (requests.ConnectionError, requests.Timeout) as error:
print(f"Intento {intento}: sin respuesta ({type(error).__name__})")
if intento < MAX_INTENTOS:
tope = min(60, 2 ** intento)
time.sleep(max(retry_after, random.uniform(0, tope)))
if not definitiva:
print("Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.")
// Node.js 18 o superior. Guarda como reintentos.mjs y ejecuta: node reintentos.mjs
import { readFile } from 'node:fs/promises';
const URL = 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas';
const IDEMPOTENCY_KEY = 'FACTURA-2026-0001'; // guardada con tu documento ANTES del primer intento
const REINTENTABLES = new Set([429, 500, 502, 503, 504]);
const MAX_INTENTOS = 5;
const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms));
const cuerpo = await readFile('comprobante.json', 'utf8');
let definitiva = false;
for (let intento = 1; intento <= MAX_INTENTOS && !definitiva; intento++) {
let retryAfter = 0;
try {
const res = await fetch(URL, {
method: 'POST',
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'Idempotency-Key': IDEMPOTENCY_KEY,
'Content-Type': 'application/json'
},
body: cuerpo,
signal: AbortSignal.timeout(30000)
});
const texto = await res.text();
let codEstado = 0;
try { codEstado = JSON.parse(texto).codEstado ?? 0; } catch { }
// 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si.
if (!REINTENTABLES.has(res.status) || codEstado === 4004) {
console.log('Respuesta definitiva:', res.status, texto);
definitiva = true;
break;
}
retryAfter = Number(res.headers.get('Retry-After') ?? 0);
console.log(`Intento ${intento}: HTTP ${res.status}`);
} catch (error) {
console.log(`Intento ${intento}: sin respuesta (${error.name})`);
}
if (intento < MAX_INTENTOS) {
const tope = Math.min(60, 2 ** intento);
await esperar(Math.max(retryAfter, Math.random() * tope) * 1000);
}
}
if (!definitiva) {
console.log('Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.');
}
<?php
$url = 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas';
$idempotencyKey = 'FACTURA-2026-0001'; // guardada con tu documento ANTES del primer intento
$reintentables = [429, 500, 502, 503, 504];
$maxIntentos = 5;
$cuerpo = file_get_contents('comprobante.json');
$definitiva = false;
for ($intento = 1; $intento <= $maxIntentos; $intento++) {
$retryAfter = 0;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
'Idempotency-Key: ' . $idempotencyKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $cuerpo,
CURLOPT_HEADERFUNCTION => function ($ch, $linea) use (&$retryAfter) {
if (stripos($linea, 'Retry-After:') === 0) {
$retryAfter = (int) trim(substr($linea, 12));
}
return strlen($linea);
},
]);
$respuesta = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($respuesta === false || $estado === 0) {
echo "Intento $intento: sin respuesta" . PHP_EOL;
} else {
$json = json_decode($respuesta, true);
$codEstado = is_array($json) ? (int) ($json['codEstado'] ?? 0) : 0;
// 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si.
if (!in_array($estado, $reintentables, true) || $codEstado === 4004) {
echo "Respuesta definitiva: $estado $respuesta" . PHP_EOL;
$definitiva = true;
break;
}
echo "Intento $intento: HTTP $estado" . PHP_EOL;
}
if ($intento < $maxIntentos) {
$tope = min(60, 2 ** $intento);
$calculada = mt_rand() / mt_getrandmax() * $tope;
usleep((int) (max($retryAfter, $calculada) * 1000000));
}
}
if (!$definitiva) {
echo 'Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.' . PHP_EOL;
}
Atención
Reintenta siempre con la misma Idempotency-Key y el mismo cuerpo. Un
reintento con una clave nueva después de un timeout puede crear un segundo
comprobante.
Emisión en lote y concurrencia#
Cuando emites muchos comprobantes, a la vez o en poco tiempo, ten en cuenta estas pautas:
- Un número por comprobante. No reutilices el mismo
estab+ptoEmi+secuencialpara otro comprobante. Si ese número ya está autorizado o pendiente, la API responde 409 con elcodEstado3004. - Deja la numeración en nuestras manos. Si omites
infoTributaria.secuencialo lo envías en ceros, asignamos el siguiente número de la serie y evitas choques entre procesos paralelos. Más detalle en Secuencial. - Concurrencia moderada. Puedes emitir en paralelo con la misma API Key. Empieza con 5 a 10 peticiones simultáneas y respeta el límite de tu integración, que es de 200 por minuto por defecto y de 60 en un sandbox, como se explica en Límite de request.
- No reescribas en los reintentos. Conserva las fechas, los importes y el
orden de los detalles tal como los enviaste la primera vez. Si cambian, la API
lo trata como otro cuerpo y responde 409 con el
codEstado3005. - Solo campos del contrato. No agregues campos propios a la Estructura del
comprobante, porque un campo desconocido se rechaza con un 422 y el
codEstado3002 (comprobante_invalido), con el campo indicado enerrores. Para datos extra, usainfoAdicional. - Corrige después de confirmar un rechazo terminal. Conserva el número y la
referencia del comprobante rechazado; envía el contenido corregido con una
Idempotency-Keynueva. La corrección consume un documento. Si reenvías el mismo contenido, conserva la clave original: recibirás la operación y su estado actual sin una nueva emisión. No reenvíes operaciones pendientes ni autorizadas. Ante un resultado no confirmado, consulta la operación y contacta a soporte antes de intentar otra emisión.
Seguimiento del estado#
La emisión responde 202 cuando el comprobante queda recibido, no
autorizado, así que no esperes el resultado fiscal en esa misma respuesta. Te
recomendamos usar los webhooks como fuente principal y
GET /v1/operaciones/{idOperacion} como respaldo.
Si consultas, espacia las consultas, por ejemplo a los 10 segundos, a los 30, al
minuto, a los 2 minutos y luego cada 5 minutos. Sigue consultando mientras el
estado sea recibido y detente con cualquier otro valor, porque todos los
demás son finales. Para fines fiscales solo cuenta un estado en
autorizado; el detalle está en
Seguimiento de una operación.
Webhooks#
Si recibes el resultado por webhook, te recomendamos estas pautas en tu endpoint:
- Verifica la firma
Ecuafact-Signaturesobre el cuerpo crudo antes de interpretar el evento, como se explica en Verificación de firma. - Guarda el evento, responde rápido con un 2xx y procésalo en segundo plano. Un
timeout, un 408, un 429 o un 5xx provocan un reintento; un 3xx u otro 4xx
dejan la entrega rechazada, sin reintentos. Ante un fallo temporal tuyo,
responde 503 con
Retry-After. - Trata los eventos como idempotentes, porque el mismo evento puede llegar más de una vez. Deduplica antes de actuar.
- Ten un respaldo: si no recibes el webhook en un tiempo razonable, consulta la operación.
Cupo#
El cupo se mueve de forma distinta en cada etapa de una emisión:
| Momento | Efecto en el cupo |
|---|---|
Validación con /validar |
No consume documentos. |
| Emisión nueva admitida | Aparta una unidad al recibirla; se consume cuando la operación llega a un resultado final (autorizada o rechazada) y se libera si queda cancelado. |
| Nuevo intento rechazado por formato o validación (422) | Consume una unidad; reutilizar la misma clave y cuerpo no vuelve a consumir. |
| Reintento del mismo contenido | No consume otra unidad. |
| Corrección de contenido tras un rechazo terminal | Consume una unidad. |
| RUC no autorizado o emisor sin firma configurada | No consume documentos. |
Antes de un lote grande, consulta GET /v1/consumo y
verifica que disponibles alcance. Sin cupo, la emisión responde 429 con el
codEstado 4004; en ese caso no reintentes en bucle y amplía tu cupo primero.
Además, valida bien tus comprobantes en pruebas, porque en producción cada
rechazo del SRI gasta un documento.
Formatos#
Los valores del comprobante siguen estos formatos:
- Los importes son números JSON con punto decimal y sin comillas:
112.50, no"112,50". - Las fechas del comprobante son texto con el formato
dd/MM/yyyy, y el periodo fiscal,MM/yyyy. - Los códigos y las identificaciones son texto y conservan los ceros a la
izquierda (
"01","0123456789"). - La codificación es UTF-8.
Identifica tus solicitudes#
Puedes enviar dos cabeceras opcionales para ubicar una solicitud en tus logs y para que podamos encontrarla cuando nos pides soporte. Las reglas completas están en Límites.
| Cabecera | Para qué | Qué haces |
|---|---|---|
X-Correlation-Id |
Identifica la solicitud. La API lo devuelve en toda respuesta y, si envías uno válido (de 1 a 64 caracteres A-Z a-z 0-9 . _ -), lo reutiliza. |
Envía el identificador de tu proceso, por ejemplo el número de pedido, y guarda el que vuelve en la respuesta junto a tu documento. |
X-Additional-Info |
Es un texto tuyo con el que podemos encontrar tu llamada cuando nos pides soporte, aunque no tengas el X-Correlation-Id. No se guarda con el comprobante ni se devuelve en la respuesta. |
Envía el nombre y la versión de tu sistema y datos operativos, por ejemplo MiERP/4.2 sucursal=norte lote=42. |
X-Additional-Info tiene tres reglas:
- Envía una sola cabecera por solicitud.
- Usa solo ASCII imprimible, sin tildes,
ñni saltos de línea, y como máximo 256 caracteres. Si no cumple, no podremos usarla para ubicar tu solicitud, pero la API tampoco la rechaza. - No incluyas datos personales (correos, cédulas, nombres) ni secretos (API Key, contraseñas).
Importante
Ambiente de pruebas: sin validez fiscal.
curl -s -i "https://api-sandbox.mynexusapi.com/v1/contexto" \
-H "X-Api-Key: $ECUAFACT_API_KEY" \
-H "X-Correlation-Id: pedido-2026-0457" \
-H "X-Additional-Info: MiERP/4.2 sucursal=norte lote=42"
# -i muestra las cabeceras: la respuesta trae X-Correlation-Id: pedido-2026-0457
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);
// En todas las solicitudes de este HttpClient.
http.DefaultRequestHeaders.Add("X-Additional-Info", "MiERP/4.2 sucursal=norte lote=42");
using var peticion = new HttpRequestMessage(HttpMethod.Get, "/v1/contexto");
peticion.Headers.Add("X-Correlation-Id", "pedido-2026-0457");
using HttpResponseMessage respuesta = await http.SendAsync(peticion);
string correlacion = respuesta.Headers.TryGetValues("X-Correlation-Id", out IEnumerable<string>? valores)
? valores.First()
: "";
Console.WriteLine($"{(int)respuesta.StatusCode} X-Correlation-Id: {correlacion}");
import os
import requests
r = requests.get(
"https://api-sandbox.mynexusapi.com/v1/contexto",
headers={
"X-Api-Key": os.environ["ECUAFACT_API_KEY"],
"X-Correlation-Id": "pedido-2026-0457",
"X-Additional-Info": "MiERP/4.2 sucursal=norte lote=42",
},
timeout=30,
)
print(r.status_code, "X-Correlation-Id:", r.headers.get("X-Correlation-Id", ""))
// Node.js 18 o superior. Guarda como identificar.mjs y ejecuta: node identificar.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', {
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'X-Correlation-Id': 'pedido-2026-0457',
'X-Additional-Info': 'MiERP/4.2 sucursal=norte lote=42'
}
});
console.log(res.status, 'X-Correlation-Id:', res.headers.get('X-Correlation-Id') ?? '');
<?php
$correlacion = '';
$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'),
'X-Correlation-Id: pedido-2026-0457',
'X-Additional-Info: MiERP/4.2 sucursal=norte lote=42',
],
CURLOPT_HEADERFUNCTION => function ($ch, string $linea) use (&$correlacion): int {
if (stripos($linea, 'X-Correlation-Id:') === 0) {
$correlacion = trim(substr($linea, strlen('X-Correlation-Id:')));
}
return strlen($linea);
},
]);
curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' X-Correlation-Id: ' . $correlacion . 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"))
.header("X-Correlation-Id", "pedido-2026-0457")
.header("X-Additional-Info", "MiERP/4.2 sucursal=norte lote=42")
.GET()
.build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " X-Correlation-Id: "
+ respuesta.headers().firstValue("X-Correlation-Id").orElse(""));
Con los SDK, configura X-Additional-Info una vez en el cliente y cambia la
correlación o el texto en una sola llamada con las opciones por llamada. Ver
SDKs.
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
AdditionalInfo = "MiERP/4.2 sucursal=norte"
});
Contexto contexto = await client.GetContextoAsync(opciones: new RequestOptions
{
CorrelationId = "pedido-2026-0457",
AdditionalInfo = "MiERP/4.2 sucursal=norte lote=42"
});
Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}");
import os
from ecuafact import EcuafactClient, EcuafactClientOptions, RequestOptions
with EcuafactClient(EcuafactClientOptions(
base_address="https://api-sandbox.mynexusapi.com/",
api_key=os.environ["ECUAFACT_API_KEY"],
additional_info="MiERP/4.2 sucursal=norte",
)) as client:
contexto = client.get_contexto(opciones=RequestOptions(
correlation_id="pedido-2026-0457",
additional_info="MiERP/4.2 sucursal=norte lote=42",
))
print(f"Contribuyentes: {len(contexto.contribuyentes or [])}")
import { EcuafactClient } from "@ecuafact/sdk";
const client = new EcuafactClient({
baseAddress: "https://api-sandbox.mynexusapi.com/",
apiKey: process.env.ECUAFACT_API_KEY,
additionalInfo: "MiERP/4.2 sucursal=norte"
});
const contexto = await client.getContexto({
correlationId: "pedido-2026-0457",
additionalInfo: "MiERP/4.2 sucursal=norte lote=42"
});
console.log(`Contribuyentes: ${contexto.contribuyentes.length}`);
<?php
require __DIR__ . '/vendor/autoload.php';
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RequestOptions;
$client = new EcuafactClient(new EcuafactClientOptions(
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: getenv('ECUAFACT_API_KEY'),
additionalInfo: 'MiERP/4.2 sucursal=norte',
));
$contexto = $client->getContexto(new RequestOptions(
correlationId: 'pedido-2026-0457',
additionalInfo: 'MiERP/4.2 sucursal=norte lote=42',
));
echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.Contexto;
// 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"))
.additionalInfo("MiERP/4.2 sucursal=norte"));
Contexto contexto = client.getContexto(RequestOptions.create()
.correlationId("pedido-2026-0457")
.additionalInfo("MiERP/4.2 sucursal=norte lote=42"));
System.out.println("Contribuyentes: " + contexto.contribuyentes().size());
Resultado esperado. La API responde 200 y la respuesta trae la cabecera
X-Correlation-Id: pedido-2026-0457. X-Additional-Info no cambia la
respuesta; cuando pidas soporte, incluye el valor que enviaste, como se explica
en Cómo pedir soporte.
Seguridad#
La API Key permite emitir comprobantes a nombre de tus contribuyentes, así que protégela como cualquier otro secreto de producción:
- Envía
X-Api-Keysolo desde tu backend, nunca desde el navegador ni desde una app móvil. Cómo guardarla se explica en Autenticación. - Registra solo las IP de salida que de verdad llaman a la API.
- Usa una API Key por sistema y rótala si alguien con acceso deja el equipo.
- No escribas la API Key ni el secreto del webhook en los logs.
Checklist antes de producción#
Antes de pasar a producción, comprueba que tu integración cumple cada punto:
- Generas la
Idempotency-Keyy lareferenciaExternauna vez por documento y las guardas antes del primer envío. - Reintentas con espera exponencial y jitter los timeouts, los 429 con el
codEstado5005 y los 500, 502, 503 y 504. - No reintentas automáticamente los 400, 401, 403, 409, 413, 422 ni los 429 con el
codEstado4004. - Cada emisión lleva un número de comprobante único, o usas el secuencial automático.
- Tu webhook verifica la firma, responde rápido y deduplica los eventos.
- Registras el
X-Correlation-Iden tus logs junto a cada respuesta. - Envías
X-Additional-Infocon el nombre y la versión de tu sistema en cada solicitud, sin datos personales ni secretos, como se explica en Identifica tus solicitudes. - Vigilas el saldo de tu cupo en
/v1/consumo. - La API Key de producción está en un gestor de secretos y las IP de producción están registradas.
Siguientes pasos#
- Errores: qué significa cada código y si se reintenta.
- Webhooks: recibe el resultado de tus emisiones sin consultar.
- Límite de request: cuántas solicitudes por minuto puedes hacer.
- Consumo y cuotas: consulta tu cupo antes de un lote.