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

  1. Al crear el documento en tu sistema, genera la Idempotency-Key y la referenciaExterna y guárdalas en la misma fila, dentro de la misma transacción de base de datos.
  2. Envía la emisión con esos valores.
  3. 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.
  4. Al recibir el 202, guarda el idOperacion en 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 + secuencial para otro comprobante. Si ese número ya está autorizado o pendiente, la API responde 409 con el codEstado 3004.
  • Deja la numeración en nuestras manos. Si omites infoTributaria.secuencial o 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 codEstado 3005.
  • Solo campos del contrato. No agregues campos propios a la Estructura del comprobante, porque un campo desconocido se rechaza con un 422 y el codEstado 3002 (comprobante_invalido), con el campo indicado en errores. Para datos extra, usa infoAdicional.
  • 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-Key nueva. 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-Signature sobre 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-Key solo 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-Key y la referenciaExterna una vez por documento y las guardas antes del primer envío.
  • Reintentas con espera exponencial y jitter los timeouts, los 429 con el codEstado 5005 y los 500, 502, 503 y 504.
  • No reintentas automáticamente los 400, 401, 403, 409, 413, 422 ni los 429 con el codEstado 4004.
  • 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-Id en tus logs junto a cada respuesta.
  • Envías X-Additional-Info con 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#

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.