<!-- source_url: https://docs.mynexusapi.com/v1/guias/buenas-practicas | last_updated: 2026-11-19 -->

# 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](/v1/guias/glosario#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](/v1/guias/ciclo-de-vida).

## 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.

> [!WARNING]
> 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](/v1/guias/emision-01) 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`.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

```bash
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}
```

```csharp
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()}");
```

```python
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)
```

```javascript
// 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
<?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;
```

```java
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());
```

```csharp-sdk
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
```

```python-sdk
# 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
```

```javascript-sdk
// 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-sdk
<?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
```

```java-sdk
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
```

```bash-cli
# 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](/v1/guias/consumo). |
| 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`](/v1/guias/errores#catalogo-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](/v1/guias/sdk).

Los ejemplos siguientes son para integraciones HTTP directas. Para ejecutarlos,
guarda el JSON de [Factura](/v1/guias/emision-01) como `comprobante.json`.

```csharp
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.");
```

```python
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.")
```

```javascript
// 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
<?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;
}
```

> [!WARNING]
> 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](/v1/guias/glosario#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](/v1/guias/limite-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](/v1/guias/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](/v1/guias/consulta-operacion).

## 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](/v1/guias/webhooks-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](/v1/guias/glosario#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`](/v1/guias/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](/v1/guias/limites#cabeceras).

| 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).

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

```bash
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
```

```csharp
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}");
```

```python
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", ""))
```

```javascript
// 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
<?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;
```

```java
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](/v1/guias/sdk#informacion-adicional).

```csharp-sdk
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}");
```

```python-sdk
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 [])}")
```

```javascript-sdk
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-sdk
<?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;
```

```java-sdk
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](/v1/guias/errores#como-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](/v1/guias/autenticacion#guarda-la-api-key).
- 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](#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](/v1/guias/errores): qué significa cada código y si se reintenta.
- [Webhooks](/v1/guias/webhooks): recibe el resultado de tus emisiones sin consultar.
- [Límite de request](/v1/guias/limite-de-request): cuántas solicitudes por minuto puedes hacer.
- [Consumo y cuotas](/v1/guias/consumo): consulta tu cupo antes de un lote.
