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

# Primeros pasos

Emite tu primera factura en el ambiente de pruebas, sigue su autorización hasta el final y descarga su RIDE, paso a paso.

Esta guía te lleva desde la API Key hasta tu primer comprobante autorizado. En
seis pasos configuras tu credencial, consultas para qué contribuyentes puedes
emitir, envías una factura, sigues su autorización y descargas su RIDE, el PDF
que se entrega al cliente. Cada paso trae el ejemplo listo para copiar, la
respuesta que deberías ver y cómo comprobar que funcionó antes de seguir.

Puedes seguir cada ejemplo de tres formas, en pestañas: llamando a la API por
HTTP desde tu lenguaje, con nuestro [SDK oficial](/v1/guias/sdk) de ese lenguaje
o desde la terminal con nuestro [CLI de Ecuafact](/v1/guias/cli). Te
recomendamos elegir la que vas a usar en tu integración; el resultado es el
mismo.

Si nunca antes trabajaste con facturación electrónica, te recomendamos leer
primero la sección [Conceptos de la Introducción](/v1/guias/introduccion#conceptos).
En unos cinco minutos explica qué es el SRI, qué significa que un comprobante
esté autorizado y qué es la clave de acceso, tres ideas que esta guía usa todo
el tiempo.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Todo lo que emitas en esta guía va a
> `https://api-sandbox.mynexusapi.com`.

## Para agentes

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

```text
Integra la API de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, instálala con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/primeros-pasos.md antes de escribir código; no inventes campos. Primero detecta cómo se integra este proyecto. Si ya usa el SDK de Ecuafact, el CLI ecuafact o el MCP de Ecuafact, sigue con esa vía (las guías sdk-dotnet, sdk-node, sdk-python, sdk-java, sdk-php, cli y mcp traen su propio prompt). Si no usa ninguna, recomiéndame la que mejor encaje, con una frase de motivo, y espera mi respuesta: el SDK de Ecuafact en el lenguaje del proyecto, el CLI ecuafact para probar o automatizar desde la terminal, el MCP para operar mi cuenta desde un asistente, o HTTP directo con la guía de emisión. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Valida la factura con POST /v1/contribuyentes/{identificacion}/facturas/validar y, solo si valida, emítela con POST /v1/contribuyentes/{identificacion}/facturas, una Idempotency-Key estable y una referenciaExterna propia; no envíes infoTributaria.tipoDocumento en el cuerpo. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide por estado y codEstado, usa urlEstado tal cual y lee errores como arreglo. Ejecuta una validación y una emisión de prueba e informa solo el estado, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer.
```

## Antes de empezar

- [ ] Una API Key de pruebas. Si todavía no tienes una, crea tu sandbox como se
      explica en [Sandbox de pruebas](/v1/guias/sandbox); el alta tarda unos 10
      minutos.
- [ ] No necesitas registrar ninguna IP para el sandbox. Al pasar a producción,
      registra la IP de salida de tu servidor como se explica en
      [IP en sandbox y producción](/v1/guias/sandbox#ip-en-sandbox-y-produccion).
- [ ] Una terminal con cURL o el entorno de tu lenguaje: .NET 8 o superior,
      Python 3.10 o superior con `requests`, Node.js 18 o superior, PHP 8.2 o
      superior con la extensión `curl` o Java 17 o superior. Si prefieres el CLI, instálalo con
      las instrucciones de [CLI de Ecuafact](/v1/guias/cli#instalacion).
- [ ] Un editor de texto para guardar el archivo `comprobante.json` del paso 3.

## Paso 0. Configura la variable `ECUAFACT_API_KEY`

Todos los ejemplos leen la API Key de la variable de entorno `ECUAFACT_API_KEY`.
Así no la escribes dentro del código ni la subes por error a tu repositorio.

En Windows PowerShell (vale para la ventana actual):

```powershell
$env:ECUAFACT_API_KEY = "pega_aqui_tu_api_key"
```

Para que quede guardada en las ventanas nuevas, ejecuta también
`setx ECUAFACT_API_KEY "pega_aqui_tu_api_key"` y abre otra terminal.

En macOS o Linux (bash o zsh):

```bash
export ECUAFACT_API_KEY="pega_aqui_tu_api_key"
```

Los ejemplos cURL usan sintaxis bash (`$ECUAFACT_API_KEY` y `\` al final de
línea). En Windows ejecútalos desde Git Bash o WSL, o usa los ejemplos de tu
lenguaje.

**Cómo sabes que funcionó:** en PowerShell, `echo $env:ECUAFACT_API_KEY`; en
bash, `echo $ECUAFACT_API_KEY`. Debe imprimir tu API Key, no una línea vacía.

> [!WARNING]
> La API Key da acceso a emitir en nombre de tus contribuyentes. No la pegues en
> código de navegador, capturas de pantalla ni repositorios. Si se filtra, rótala
> en el Portal del Cliente (**Cuenta > API Keys**).

## Paso 1. Obtén tu API Key de pruebas

Si ya tienes una API Key de pruebas, salta al paso 2.

1. Abre `https://portal.mynexusapi.com/sandbox`.
2. Completa tus nombres, apellidos, correo y celular, confirma el celular con
   el código que llega por WhatsApp y crea tu clave con el enlace que llega a
   tu correo. El detalle está en [Sandbox de pruebas](/v1/guias/sandbox).
3. Ingresa al Portal del Cliente, abre **Pruebas** y pulsa **Generar** en "API
   Key de pruebas" (si ya tenías una, el botón es **Rotar**). Copia la API Key,
   que se muestra una sola vez, en la variable del paso 0.
4. Agrega tu RUC y tu certificado en **Contribuyentes > Agregar RUC**. El
   detalle está en [Sandbox de pruebas](/v1/guias/sandbox#agrega-tu-ruc-y-tu-certificado).

**Resultado esperado:** la pantalla "Tu cuenta está creada" al terminar el
alta y, dentro del portal, tu API Key de pruebas copiada desde **Pruebas**.

**Cómo sabes que funcionó:** la consulta del paso 2 responde 200. Si responde
401, revisa la [tabla de errores](#si-algo-falla).

## Paso 2. Consulta tu contexto

`GET /v1/contexto` devuelve los [contribuyentes](/v1/guias/glosario) para los que
tu API Key puede emitir. Lo necesitas porque el valor `identificacion` de esta
respuesta es el que va en la ruta de emisión y, como
[RUC](/v1/guias/glosario) del emisor, dentro del comprobante.

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

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

using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/contexto",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=30,
)
print(r.status_code, r.text)
```

```javascript
// Node.js 18 o superior. Guarda como contexto.mjs y ejecuta: node contexto.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
```

```php
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contexto');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
```

```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"))
    .GET()
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
```

```csharp-sdk
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

// client: cliente EcuafactClient - ver SDK .NET
Contexto contexto = await client.GetContextoAsync();
Console.WriteLine(contexto.Contribuyentes![0].Identificacion);
```

```python-sdk
from ecuafact import EcuafactClient

# client: cliente EcuafactClient - ver SDK Python
contexto = client.get_contexto()
print(contexto.contribuyentes[0].identificacion)
```

```javascript-sdk
import { EcuafactClient } from "@ecuafact/sdk";

// client: cliente EcuafactClient - ver SDK Node.js
const contexto = await client.getContexto();
console.log(contexto.contribuyentes[0].identificacion);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: cliente EcuafactClient - ver SDK PHP
$contexto = $client->getContexto();
echo $contexto->contribuyentes[0]->identificacion;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.contracts.Contexto;

// client: cliente EcuafactClient - ver SDK Java
Contexto contexto = client.getContexto();
System.out.println(contexto.contribuyentes().get(0).identificacion());
```

```bash-cli
# Una sola vez: guarda tu API Key en el CLI para el entorno de pruebas.
ecuafact login --entorno sandbox

# Muestra tu integración y sus contribuyentes, en tabla.
ecuafact cuenta --entorno sandbox
```

**Resultado esperado** (`200 OK`; tus valores serán los de tu sandbox):

```json
{
  "idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345",
  "nombre": "Integracion de ejemplo",
  "contribuyentes": [
    {
      "identificacion": "0123456789001",
      "puedeEmitir": true,
      "puedeRecibir": true,
      "tiposComprobante": [
        "01",
        "03",
        "04",
        "05",
        "06",
        "07"
      ]
    }
  ]
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `idCliente` | string (UUID) | Identificador de tu integración. |
| `nombre` | string | Nombre de tu integración. |
| `contribuyentes` | array | Contribuyentes habilitados para tu API Key en este ambiente. Vacío si no tienes ninguno. |
| `contribuyentes[].identificacion` | string | Identificación completa del contribuyente: su RUC de 13 dígitos o la identificación con la que está registrado. Va en la ruta `/v1/contribuyentes/{identificacion}/...` y en `infoTributaria.ruc`. |
| `contribuyentes[].puedeEmitir` | boolean | `true` si puedes emitir para este contribuyente. |
| `contribuyentes[].puedeRecibir` | boolean | Indica si el contribuyente tiene habilitada la recepción. No afecta la emisión. |
| `contribuyentes[].tiposComprobante` | array de string | Códigos de comprobante habilitados: `01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión, `07` comprobante de retención. |

**Cómo sabes que funcionó:** el código HTTP es `200`, ves al menos un
contribuyente con `puedeEmitir: true` y `tiposComprobante` incluye `"01"`.
Anota su `identificacion`: es la que usas en la ruta y en `infoTributaria.ruc`.

En esta guía usamos la identificación de los
[datos de prueba](/v1/guias/datos-de-prueba), `0123456789001`, en la ruta y en
`infoTributaria.ruc`. Si tu sandbox tiene otro RUC, reemplázalo por tu valor en
los pasos 3 a 5.

## Paso 3. Emite la factura

### Prepara el archivo `comprobante.json`

Guarda este JSON como `comprobante.json` en la carpeta desde la que ejecutarás
los ejemplos. Antes de guardarlo, cambia:

- `infoTributaria.ruc`: tu `identificacion` del paso 2.
- `estab` y `ptoEmi`: el [establecimiento y punto de emisión](/v1/guias/glosario)
  que registraste en el alta del sandbox (por defecto `001` y `001`).
- `info.fechaEmision`: la fecha de hoy en formato `dd/MM/yyyy`.

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "001",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "10/11/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE EJEMPLO",
    "direccionComprador": "DIRECCION DE PRUEBAS",
    "totalSinImpuestos": 100.00,
    "totalDescuento": 0.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 100.00,
        "valor": 15.00
      }
    ],
    "propina": 0.00,
    "importeTotal": 115.00,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 115.00
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "SERV-001",
      "descripcion": "Servicio de ejemplo",
      "cantidad": 2,
      "precioUnitario": 50.00,
      "descuento": 0.00,
      "precioTotalSinImpuesto": 100.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 100.00,
          "valor": 15.00
        }
      ]
    }
  ]
}
```

El tipo de comprobante lo fija la ruta, así que el cuerpo no lleva
`infoTributaria.tipoDocumento`. `POST /v1/contribuyentes/{identificacion}/facturas`
emite una factura (`01`). Si necesitas otro tipo, usa su ruta:
`.../liquidaciones-compra` (`03`), `.../notas-credito` (`04`),
`.../notas-debito` (`05`), `.../guias-remision` (`06`) o `.../retenciones`
(`07`). Para revisar el cuerpo sin emitir, usa la misma ruta con `/validar`:
para la factura, `POST /v1/contribuyentes/{identificacion}/facturas/validar`.

Cómo cuadran los totales (si no cuadran, la API responde `422`):

| Cálculo | Valor |
|---|---|
| `precioTotalSinImpuesto` = `cantidad` x `precioUnitario` - `descuento` = 2 x 50.00 - 0.00 | 100.00 |
| IVA de la línea (`codigo` `2`, `codigoPorcentaje` `4` = 15 %) = 100.00 x 15 % | 15.00 |
| `totalSinImpuestos` = suma de `precioTotalSinImpuesto` | 100.00 |
| `importeTotal` = `totalSinImpuestos` + IVA + `propina` = 100.00 + 15.00 + 0.00 | 115.00 |
| Suma de `pagos[].total` (debe ser igual a `importeTotal`) | 115.00 |

| Campo | Para qué sirve |
|---|---|
| `origenReferencia` | Nombre de tu sistema (hasta 64 caracteres). Obligatorio. |
| `referenciaExterna` | Tu identificador interno del documento (hasta 128 caracteres), por ejemplo tu número de factura. Obligatorio. |
| `infoTributaria.secuencial` | No aparece en el ejemplo a propósito: nosotros asignamos el siguiente número. Ver [El secuencial](#el-secuencial). |
| `info.tipoIdentificacionComprador` | `05` cédula, `04` RUC, `06` pasaporte, `07` consumidor final, `08` identificación del exterior. |
| `info.propina` y `info.moneda` | Obligatorios en factura: `propina` puede ser `0.00`; `moneda` es `DOLAR`. |
| `info.pagos[].formaPago` | `01` es "sin utilización del sistema financiero" (efectivo). El catálogo completo está en [Catálogos](/v1/guias/catalogos). |

No envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`:
nosotros los asignamos y, si los envías, la API responde `422` con el `codEstado` 3002 (`comprobante_invalido`). Los
campos de cada tipo de comprobante están en [Factura](/v1/guias/emision-01).

### El secuencial

El [secuencial](/v1/guias/glosario) es el número consecutivo de 9 dígitos del
comprobante dentro de su serie (`estab` + `ptoEmi` + tipo de comprobante +
ambiente). Tienes dos opciones, válidas en pruebas y en producción:

| Opción | Qué envías | Qué pasa |
|---|---|---|
| Automático (recomendado para empezar) | Omites `secuencial`, o envías `"000000000"` | Asignamos el siguiente número libre de la serie. Lo ves dentro de la `claveAcceso` del paso 4. |
| Explícito | Un número de 1 a 999999999, solo dígitos, máximo 9 (por ejemplo `"000000124"` o `"124"`) | Se usa ese número. Si ya existe un comprobante autorizado o pendiente con ese número en la serie, la API responde `409` con el `codEstado` 3004 (`comprobante_duplicado`). |

Usa el explícito solo si tu sistema ya lleva su propia numeración. No mezcles las
dos opciones en la misma serie sin control: el automático continúa desde el
número más alto usado.

### Envía el comprobante

La cabecera `Idempotency-Key` es obligatoria. Identifica la intención de emitir
este documento: si tu programa reintenta por un corte de red, envía la misma
clave y la API devuelve la misma operación en lugar de crear un duplicado. Usa un
valor estable, como tu número interno de factura (`FACTURA-2026-0001`) o un UUID
v4 guardado junto al documento. Se admiten letras, dígitos y `- _ . : /`, hasta
128 caracteres.

```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} (paso 4)
```

```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
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado} / codEstado: {resultado.Admission.CodEstado}");
```

```python-sdk
from ecuafact import EcuafactClient

# client: cliente EcuafactClient - ver SDK Python
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado} / codEstado: {resultado.admission.cod_estado}")
```

```javascript-sdk
import { EcuafactClient } from "@ecuafact/sdk";

// client: cliente EcuafactClient - ver SDK Node.js
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado} / codEstado: ${resultado.admission.codEstado}`);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: cliente EcuafactClient - ver SDK PHP
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado
    . ' / codEstado: ' . $resultado->admission->codEstado;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EmisionResultado;

// client: cliente EcuafactClient - ver SDK Java
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()
    + " / codEstado: " + resultado.admission().codEstado());
```

```bash-cli
# Envía el comprobante y muestra el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox
```

**Resultado esperado:** HTTP `202 Accepted` con este cuerpo:

```json
{
  "estado": "recibido",
  "codEstado": 1001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "01",
  "numeroDocumento": "001-001-000000123",
  "referenciaExterna": "FACTURA-2026-0001",
  "claveAcceso": null,
  "fhRecibido": "2026-11-09T10:15:00-05:00",
  "fhAutorizacion": null
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. Todavía no es una autorización del SRI. |
| `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu código debe aceptar los dos valores. |
| `errores` | array de string | Viene siempre; aquí es una lista vacía. |
| `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario). Guárdalo, porque lo necesitas en el paso 4. |
| `urlEstado` | string | URL completa del seguimiento. Puedes llamarla tal como viene en el paso 4. |
| `ambiente` | number | `1` pruebas, `2` producción. |
| `tipoDocumento` | string | Tipo de comprobante (`01` factura). |
| `numeroDocumento` | string | Número de la factura con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos. |
| `referenciaExterna` | string | La `referenciaExterna` que enviaste. |
| `claveAcceso` | string o `null` | `null` con el `codEstado` 1001; con el 1002 ya trae la clave de 49 dígitos. En cualquier caso la ves en el paso 4. |
| `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |
| `fhAutorizacion` | `null` | La autorización todavía no existe. |

La respuesta trae además dos cabeceras: `Location`, con la misma URL de
`urlEstado`, y `X-Correlation-Id`, el identificador de la petición, que te
conviene incluir si escribes a soporte.

Usa el código HTTP para saber si la petición tuvo éxito. Cuando falla, el
cuerpo trae además un número en `codEstado`, por ejemplo 3003
(`solicitud_invalida`) en un HTTP `400`, que es el valor con el que programas tu
lógica. El catálogo completo está en
[Errores](/v1/guias/errores#catalogo-de-codestado).

**Cómo sabes que funcionó:** la API responde 202 con `estado` en `recibido`, el
`codEstado` 1001 o 1002 y un `idOperacion`. Un 202 significa que el comprobante quedó **recibido**, no
autorizado: el SRI todavía no respondió, así que sigue con el paso 4.

> [!NOTE]
> Si repites el envío con la misma `Idempotency-Key` y el mismo archivo, recibes
> un `202` con el mismo `idOperacion` y el estado actual de la operación. Es lo
> esperado y no se emite otra factura. Para emitir otra factura usa otra `Idempotency-Key` y otra
> `referenciaExterna`.

## Paso 4. Sigue la operación hasta la autorización

La emisión es asíncrona: nos encargamos de que el comprobante llegue al SRI y
de obtener su respuesta. Eso tarda desde unos segundos hasta varios minutos, y
puedes enterarte del resultado de dos formas:

- **Seguimiento por consulta** (lo que haces en esta guía): consulta
  `GET /v1/operaciones/{idOperacion}` cada 10 segundos, con un tope de 5 minutos
  (30 consultas). No consultes más seguido: cada consulta cuenta para tu
  [límite de solicitudes](/v1/guias/limite-de-request) (60 por minuto en un
  sandbox; 200 por minuto por defecto en otras integraciones).
- **Webhook** (recomendado en producción): registras una URL en el Portal del
  Cliente (**Integración > Eventos**) y te enviamos
  `document.authorized`, `document.rejected` o `document.failed` cuando hay
  resultado. Cómo probarlo en este quickstart: [Alternativa: recibe el resultado por webhook](#alternativa-recibe-el-resultado-por-webhook).

El bucle se detiene cuando hay un resultado final, es decir, cuando `estado`
deja de ser `recibido`.
Reemplaza el `idOperacion` por el que recibiste en el paso 3.

```bash
ID_OPERACION="3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"   # el idOperacion del paso 3
for intento in $(seq 1 30); do
  respuesta=$(curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/$ID_OPERACION" \
    -H "X-Api-Key: $ECUAFACT_API_KEY")
  echo "$respuesta"
  case "$respuesta" in
    *'"estado":"recibido"'*) ;;   # sin resultado final: sigue esperando
    *) break ;;                   # resultado final o error: revisa "Si algo falla"
  esac
  sleep 10
done
```

```csharp
using System.Net.Http;
using System.Text.Json;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

string idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el idOperacion del paso 3
for (int intento = 1; intento <= 30; intento++)
{
    using HttpResponseMessage respuesta = await http.GetAsync($"/v1/operaciones/{idOperacion}");
    string cuerpo = await respuesta.Content.ReadAsStringAsync();
    Console.WriteLine($"{(int)respuesta.StatusCode} {cuerpo}");
    if (!respuesta.IsSuccessStatusCode)
    {
        break;
    }
    using JsonDocument json = JsonDocument.Parse(cuerpo);
    string estado = json.RootElement.GetProperty("estado").GetString()!;
    if (estado != "recibido")
    {
        break;
    }
    await Task.Delay(TimeSpan.FromSeconds(10));
}
```

```python
import os
import time
import requests

id_operacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"  # el idOperacion del paso 3
for intento in range(30):
    r = requests.get(
        f"https://api-sandbox.mynexusapi.com/v1/operaciones/{id_operacion}",
        headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
        timeout=30,
    )
    print(r.status_code, r.text)
    if r.status_code != 200:
        break
    if r.json()["estado"] != "recibido":
        break
    time.sleep(10)
```

```javascript
// Node.js 18 o superior. Guarda como seguimiento.mjs y ejecuta: node seguimiento.mjs
const idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'; // el idOperacion del paso 3
const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms));

for (let intento = 1; intento <= 30; intento++) {
  const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones/${idOperacion}`, {
    headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
  });
  const cuerpo = await res.text();
  console.log(res.status, cuerpo);
  if (res.status !== 200) break;
  const { estado } = JSON.parse(cuerpo);
  if (estado !== 'recibido') break;
  await esperar(10000);
}
```

```php
<?php
$idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'; // el idOperacion del paso 3
for ($intento = 1; $intento <= 30; $intento++) {
    $ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones/' . $idOperacion);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
    ]);
    $cuerpo = curl_exec($ch);
    $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    echo $estado . ' ' . $cuerpo . PHP_EOL;
    if ($estado !== 200) {
        break;
    }
    $operacion = json_decode($cuerpo, true);
    if ($operacion['estado'] !== 'recibido') {
        break;
    }
    sleep(10);
}
```

```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
String idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el idOperacion del paso 3
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/" + idOperacion))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
for (int intento = 1; intento <= 30; intento++) {
    HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
    String cuerpo = respuesta.body();
    System.out.println(respuesta.statusCode() + " " + cuerpo);
    if (respuesta.statusCode() != 200) {
        break;
    }
    // Busqueda de texto simple para no depender de una libreria JSON.
    boolean terminado = !cuerpo.contains("\"estado\":\"recibido\"");
    if (terminado) {
        break;
    }
    Thread.sleep(10_000);
}
```

```csharp-sdk
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

// client: cliente EcuafactClient - ver SDK .NET
Operation operacion = await client.GetOperacionAsync(idOperacion);
Console.WriteLine($"{operacion.Estado} / {operacion.CodEstado}");
```

```python-sdk
from ecuafact import EcuafactClient

# client: cliente EcuafactClient - ver SDK Python
operacion = client.get_operacion(id_operacion)
print(operacion.estado, operacion.cod_estado)
```

```javascript-sdk
import { EcuafactClient } from "@ecuafact/sdk";

// client: cliente EcuafactClient - ver SDK Node.js
const operacion = await client.getOperacion(idOperacion);
console.log(operacion.estado, operacion.codEstado);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: cliente EcuafactClient - ver SDK PHP
$operacion = $client->getOperacion($idOperacion);
echo $operacion->estado . ' ' . $operacion->codEstado;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.contracts.Operation;

// client: cliente EcuafactClient - ver SDK Java
Operation operacion = client.getOperacion(idOperacion);
System.out.println(operacion.estado() + " " + operacion.codEstado());
```

```bash-cli
# Consulta una vez el estado de la operación.
ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox

# O emite y espera el resultado del SRI en un solo comando (hasta 180 segundos).
ecuafact emitir comprobante.json --esperar --entorno sandbox
```

**Resultado esperado:** las primeras consultas muestran `estado` `recibido`,
con el `codEstado` 1001 o, cuando la factura ya tiene clave de acceso, 1002, y
sin `msgError`. La última (`200 OK`) se ve así:

```json
{
  "estado": "autorizado",
  "codEstado": 2001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "01",
  "numeroDocumento": "001-001-000000123",
  "referenciaExterna": "FACTURA-2026-0001",
  "claveAcceso": "0710202601012345678900110010010000001231234567811",
  "fhRecibido": "2026-11-09T10:15:00-05:00",
  "fhAutorizacion": "2026-11-09T10:15:18-05:00"
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | `recibido` mientras no hay resultado final; después, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Significado y qué hacer en [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). |
| `codEstado` | number | Código de 4 dígitos que precisa el resultado; su primer dígito coincide con el `estado`. 2001 es autorizado, y cuando el comprobante no se autorizó dice la causa, por ejemplo 3001 en un rechazo del SRI. Los valores están en [Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion). |
| `msgError` | string | Descripción general del código. Solo aparece cuando el comprobante no se autorizó. |
| `errores` | array de string | Detalle del resultado; en un rechazo del SRI trae su mensaje. Viene siempre y aquí es una lista vacía. |
| `idOperacion` | string (UUID) | La operación que consultaste. |
| `urlEstado` | string | URL completa de este seguimiento. |
| `ambiente` | number | `1` pruebas, `2` producción. |
| `tipoDocumento` | string | Tipo de comprobante (`01` factura). |
| `numeroDocumento` | string o `null` | Número de la factura, `estab-ptoEmi-secuencial`. |
| `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste. |
| `claveAcceso` | string o `null` | [Clave de acceso](/v1/guias/glosario) de 49 dígitos que asignamos nosotros. Es `null` mientras el `codEstado` es 1001. La necesitas en el paso 5. |
| `fhRecibido` | string | Cuándo recibimos la emisión, en ISO 8601 con zona horaria. |
| `fhAutorizacion` | string o `null` | Fecha de autorización. Puede ser `null` aun con `autorizado`, porque algunas autorizaciones no traen fecha. |

**Cómo sabes que funcionó:** `estado` es `autorizado`, el `codEstado` es 2001 y
`claveAcceso` tiene 49 dígitos. Copia la `claveAcceso` para el paso 5. El
secuencial que se asignó aparece en `numeroDocumento` (`001-001-000000123` en el
ejemplo).

Si el bucle termina con otro resultado:

| Resultado | Qué significa | Qué hacer |
|---|---|---|
| `estado` = `rechazado` y `codEstado` = 3001 (`rechazo_sri`) | El SRI rechazó el comprobante; `errores` trae su mensaje. | Corrige el dato y emite de nuevo con una nueva `Idempotency-Key` y una nueva `referenciaExterna`, sin `secuencial` para que se asigne el siguiente número. Reusar el número rechazado responde `409` con el `codEstado` 3004 (`comprobante_duplicado`). Ver [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). |
| `estado` = `rechazado` y `codEstado` = 3002 (`comprobante_invalido`) | El comprobante no pasó la validación fiscal antes de llegar al SRI; `errores` dice qué corregir. | Corrige y reenvía con nueva `Idempotency-Key` y nueva `referenciaExterna`. Si quieres conservar el número, envía en `infoTributaria.secuencial` el mismo secuencial, que ves en el `numeroDocumento` de la respuesta. La respuesta puede traer el mismo `idOperacion`. |
| `estado` = `rechazo_configuracion` | Falta o está mal una configuración del emisor, como su firma electrónica; el `codEstado`, de 4001 a 4004, dice cuál. | Corrige la configuración en el Portal del Cliente y reenvía con nueva `Idempotency-Key` y nueva `referenciaExterna`. Ver [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). |
| `estado` = `error` | No se pudo emitir; el `codEstado` dice si puedes reenviar. | Sigue la fila de su `codEstado` en [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). Con 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`) no reemitas y escribe a soporte con el `idOperacion`. |
| `estado` = `cancelado` | La plataforma canceló el envío antes de emitirlo. | Reenvía con nueva `Idempotency-Key` y nueva `referenciaExterna`. Si repites la misma `referenciaExterna` con el mismo cuerpo, la API te devuelve la operación cancelada y no emite nada. |
| Pasaron 5 minutos y `estado` sigue en `recibido` | El SRI todavía no da un resultado final. No es un error. | No reemitas, porque emitir de nuevo puede duplicar el comprobante. Consulta más tarde o espera el webhook, como se explica en [Webhooks](/v1/guias/webhooks#que-hacer-ante-cada-evento). |

### Alternativa: recibe el resultado por webhook

En lugar del bucle, o además de él, puedes recibir el resultado en tu servidor.
Te lo recomendamos para producción: te avisamos cuando hay resultado y no gastas
solicitudes en consultas.

Prerequisitos adicionales:

- [ ] Una URL pública `https://` (puerto 443) que llegue a tu equipo o servidor.
      En tu equipo de desarrollo puedes exponer un puerto local con un túnel como
      ngrok o cloudflared ([Probar en local](/v1/guias/webhooks#probar-en-local)).
- [ ] Un receptor que verifique la firma. Copia el de tu lenguaje (.NET, Python,
      Node.js, PHP o Java) de [Implementación en tu servidor](/v1/guias/webhooks#implementacion-en-tu-servidor)
      y ejecútalo en el puerto 3000.

Pasos:

1. Entra al Portal del Cliente (`https://portal.mynexusapi.com`)
   y abre **Integración > Eventos**.
2. Pulsa **Nuevo destino**, escribe tu URL (por ejemplo
   `https://tu-subdominio.ngrok-free.app/webhooks/ecuafact`), deja marcados los
   tres eventos y pulsa **Crear**.
3. Copia el **secreto** que muestra el portal (se muestra una sola vez) en la
   variable `ECUAFACT_WEBHOOK_SECRET` de tu receptor y reinícialo.
4. Pulsa **Probar**. En **Entregas** debe aparecer el evento de prueba con estado
   **Entregado** y `HTTP` `200`.
5. Emite otra factura como en el paso 3, con otra `Idempotency-Key` y otra
   `referenciaExterna` (por ejemplo `FACTURA-2026-0002` en ambas).

**Resultado esperado:** cuando el SRI autoriza, tu receptor recibe un `POST` con
la cabecera `Ecuafact-Signature` y este cuerpo:

```json
{
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "estado": "autorizado",
  "codEstado": 2001,
  "errores": [],
  "tipoDocumento": "01",
  "claveAcceso": "0710202601012345678900110010010000001231234567811",
  "eventType": "document.authorized",
  "resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "occurredAtUtc": "2026-11-09T15:15:18.1234567Z"
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `idOperacion` | string (UUID) | La operación que recibiste en el `202` de la emisión. |
| `estado` | string | El mismo estado del seguimiento: `autorizado` en `document.authorized`; `rechazado`, `rechazo_configuracion` o `error` en los demás eventos, que además traen `msgError`. |
| `codEstado` | number | El mismo `codEstado` del seguimiento, por ejemplo 2001 en `document.authorized`. |
| `errores` | array de string | El detalle del resultado, como en el seguimiento. Viene siempre. |
| `tipoDocumento` | string | Tipo de comprobante (`01` factura), cuando se conoce. |
| `claveAcceso` | string | Clave de acceso de 49 dígitos. Úsala en el paso 5. En `document.failed` puede faltar. |
| `eventType` | string | `document.authorized`, `document.rejected` o `document.failed`. |
| `resourceId` | string (UUID) | En estos eventos, igual a `idOperacion`. Úsalo con `eventType` para descartar duplicados. |
| `occurredAtUtc` | string | Momento del evento en UTC (ISO 8601). |

**Cómo sabes que funcionó:** tu receptor imprime `Autorizado` con el
`idOperacion` y la `claveAcceso`, y en **Entregas** la entrega figura como
**Entregado**. Con esa `claveAcceso` sigue al paso 5. Los demás eventos y qué
hacer con cada uno están en [Webhooks](/v1/guias/webhooks#eventos).

## Paso 5. Descarga el RIDE y el XML

Con la `claveAcceso` del paso 4 descarga el RIDE (PDF) y el XML del comprobante
autorizado:

```
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml
```

`{identificacion}` es el mismo valor de la ruta de emisión, la `identificacion`
del paso 2. Reemplaza la `claveAcceso` del ejemplo por la tuya.

```bash
curl -s -o ride.pdf -w "HTTP %{http_code}\n" \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

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

string claveAcceso = "0710202601012345678900110010010000001231234567811"; // la claveAcceso del paso 4
using HttpResponseMessage respuesta = await http.GetAsync(
    $"/v1/contribuyentes/0123456789001/comprobantes/{claveAcceso}/ride");
Console.WriteLine($"{(int)respuesta.StatusCode} {respuesta.Content.Headers.ContentType}");
if (respuesta.IsSuccessStatusCode)
{
    await File.WriteAllBytesAsync("ride.pdf", await respuesta.Content.ReadAsByteArrayAsync());
}
else
{
    Console.WriteLine(await respuesta.Content.ReadAsStringAsync());
}
```

```python
import os
import requests

clave_acceso = "0710202601012345678900110010010000001231234567811"  # la claveAcceso del paso 4
r = requests.get(
    f"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/{clave_acceso}/ride",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=30,
)
print(r.status_code, r.headers.get("Content-Type"))
if r.status_code == 200:
    with open("ride.pdf", "wb") as archivo:
        archivo.write(r.content)
else:
    print(r.text)
```

```javascript
// Node.js 18 o superior. Guarda como ride.mjs y ejecuta: node ride.mjs
import { writeFile } from 'node:fs/promises';

const claveAcceso = '0710202601012345678900110010010000001231234567811'; // la claveAcceso del paso 4
const res = await fetch(
  `https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/${claveAcceso}/ride`,
  { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } });
console.log(res.status, res.headers.get('content-type'));
if (res.ok) {
  await writeFile('ride.pdf', Buffer.from(await res.arrayBuffer()));
} else {
  console.log(await res.text());
}
```

```php
<?php
$claveAcceso = '0710202601012345678900110010010000001231234567811'; // la claveAcceso del paso 4
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/' . $claveAcceso . '/ride');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . PHP_EOL;
if ($estado === 200) {
    file_put_contents('ride.pdf', $cuerpo);
} else {
    echo $cuerpo . PHP_EOL;
}
```

```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
String claveAcceso = "0710202601012345678900110010010000001231234567811"; // la claveAcceso del paso 4
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/" + claveAcceso + "/ride"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
HttpResponse<byte[]> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray());
System.out.println(respuesta.statusCode());
if (respuesta.statusCode() == 200) {
    Files.write(Path.of("ride.pdf"), respuesta.body());
} else {
    System.out.println(new String(respuesta.body()));
}
```

```csharp-sdk
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

// client: cliente EcuafactClient - ver SDK .NET
ArchivoComprobante ride = await client.DescargarRideAsync("0123456789001", claveAcceso);
await File.WriteAllBytesAsync("ride.pdf", ride.Contenido);
```

```python-sdk
from ecuafact import EcuafactClient

# client: cliente EcuafactClient - ver SDK Python
archivo = client.descargar_ride("0123456789001", clave_acceso)
with open("ride.pdf", "wb") as destino:
    destino.write(archivo.contenido)
```

```javascript-sdk
import { writeFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";

// client: cliente EcuafactClient - ver SDK Node.js
const archivo = await client.descargarRide("0123456789001", claveAcceso);
await writeFile("ride.pdf", archivo.contenido);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: cliente EcuafactClient - ver SDK PHP
$archivo = $client->descargarRide('0123456789001', $claveAcceso);
file_put_contents('ride.pdf', $archivo->contenido);
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import java.nio.file.Files;
import java.nio.file.Path;

// client: cliente EcuafactClient - ver SDK Java
ArchivoComprobante archivo = client.descargarRide("0123456789001", claveAcceso);
Files.write(Path.of("ride.pdf"), archivo.contenido());
```

```bash-cli
# Descarga el RIDE y el XML en la carpeta actual.
ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride,xml --entorno sandbox
```

Para el XML cambia `/ride` por `/xml` en la ruta (en los SDK: `DescargarXmlAsync`,
`descargar_xml`, `descargarXml`). Este ejemplo guarda el archivo como
`factura.xml` e imprime las cabeceras para que veas `Content-Type`:

```bash
curl -s -o factura.xml -D - \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

**Resultado esperado:**

| Descarga | HTTP | `Content-Type` | Contenido |
|---|---|---|---|
| RIDE | `200 OK` | `application/pdf` | El PDF del comprobante. |
| XML | `200 OK` | `application/xml` | El XML del comprobante, con nombre sugerido `{claveAcceso}.xml` (cabecera `Content-Disposition`). |
| XML pendiente | `404 Not Found` | `application/json` | Si falta la autorización o el archivo, recibes el `codEstado` 3013 (`no_encontrado`). Reintenta la descarga en unos minutos, sin volver a emitir. |

**Cómo sabes que funcionó:** el RIDE que descargaste (los ejemplos HTTP y SDK lo
guardan como `ride.pdf`) se abre en tu visor de PDF y muestra la clave de acceso
y el número de autorización. Con eso completaste la guía.

Detalle de cada descarga: [Descargar PDF](/v1/guias/consulta-ride) y
[Descargar XML](/v1/guias/consulta-xml).

## Si algo falla

Cuando una petición falla, la API responde con un código HTTP de error y un
cuerpo con `estado`, `codEstado`, `msgError` y `errores`. En la emisión, esos
mismos campos llegan dentro de la forma completa de la respuesta 202, con
`idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en
`null`, porque no se creó ninguna operación:

```json
{
  "estado": "rechazado",
  "codEstado": 3003,
  "msgError": "La solicitud no es válida.",
  "errores": [
    "Idempotency-Key: La cabecera Idempotency-Key es obligatoria y debe ser ASCII estable (maximo 128 caracteres)."
  ],
  "idOperacion": null,
  "urlEstado": null,
  "ambiente": 1,
  "tipoDocumento": "01",
  "numeroDocumento": null,
  "referenciaExterna": "FACTURA-2026-0001",
  "claveAcceso": null,
  "fhRecibido": null,
  "fhAutorizacion": null
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | Estado que corresponde al código. Su valor coincide con el primer dígito de `codEstado`: 3 es `rechazado`, 4 `rechazo_configuracion` y 5 `error`. |
| `codEstado` | number | Código estable de la API, de 4 dígitos. Programa contra este valor. No es el código HTTP. |
| `msgError` | string | Descripción fija y breve del código. Puedes mostrarla, pero no decidas con ella. |
| `errores` | array de string | Viene siempre. En 3002 (`comprobante_invalido`) trae hasta 20 mensajes, uno por problema, con la ruta del campo (por ejemplo `$.infoTributaria.ruc: Campo obligatorio.`). En 3003 (`solicitud_invalida`) trae el detalle de los parámetros o del cuerpo que no se pudo leer; puede ser más de uno. Corrige todos los que puedas y reenvía. En el resto de errores es una lista vacía (`[]`). |

Los errores más probables en este quickstart:

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 3009 (`credenciales_invalidas`) | 401 | Falta la cabecera `X-Api-Key` o la API Key es incorrecta, está revocada o es de otro ambiente. | Corrige: revisa que `ECUAFACT_API_KEY` tenga la API Key completa (paso 0). Si la revocaste, crea otra. |
| 3010 (`ip_no_autorizada`) | 403 | En producción, la API Key es correcta pero **tu IP de salida no está registrada** para esa API Key. En sandbox no ocurre por IP. | Registra tu IP en **Cuenta > IP permitidas** del Portal del Cliente ([cómo](/v1/guias/sandbox#si-tu-ip-cambia)). |
| 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta no está habilitado para tu API Key o el tipo de comprobante no está habilitado. | Corrige: usa en la ruta y en `infoTributaria.ruc` la `identificacion` del paso 2. |
| 3003 (`solicitud_invalida`) | 400 | Falta `Idempotency-Key` o tiene caracteres no admitidos, el JSON está mal formado, o la `claveAcceso` de la descarga no es válida. | Corrige: agrega la cabecera; valida el JSON (comas, comillas); copia la `claveAcceso` completa. |
| 3002 (`comprobante_invalido`) | 422 | El comprobante tiene un campo faltante o mal formado, totales que no cuadran, un `infoTributaria.ruc` distinto de la identificación de la ruta, o un campo que no se envía (`claveAcceso`, `ambiente`, `version`). `errores` dice cuál. | Corrige el campo indicado en `errores` y reenvía con la misma `Idempotency-Key`. Un `422` descuenta un documento de tu cupo como intento, así que valida antes con `/validar`, que no lo descuenta. |
| 3004 (`comprobante_duplicado`) | 409 | Ya existe un comprobante autorizado o pendiente con el mismo `estab`, `ptoEmi` y `secuencial`. | Corrige: omite `secuencial` para que se asigne el siguiente, o usa otro número. |
| 3005 (`conflicto_idempotencia`) | 409 | Usaste una `Idempotency-Key` que ya se usó con un cuerpo distinto, o una `referenciaExterna` (con el mismo `origenReferencia`) que ya pertenece a otro comprobante. | Corrige: para un comprobante nuevo usa una `Idempotency-Key` y una `referenciaExterna` nuevas; para reintentar, envía exactamente el mismo cuerpo. |
| 3013 (`no_encontrado`) | 404 | Descarga del RIDE o XML: el comprobante no existe o aún no está disponible. | Reintenta cuando el `estado` de la operación sea `autorizado`; revisa la `claveAcceso` y la `identificacion` de la ruta. |
| 5005 (`limite_solicitudes`) | 429 | Superaste tu límite de solicitudes por minuto (60 en un sandbox), por ejemplo con un bucle de seguimiento sin espera. | Reintenta después de los segundos de la cabecera `Retry-After` y agrega la espera de 10 segundos. |

El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida): qué hacer ante cada `estado` y cada `codEstado`.
- [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar en bucle.
- [Datos de prueba](/v1/guias/datos-de-prueba): provoca cada caso (duplicado, idempotencia, rechazo) antes de ir a producción.
- [Comprobantes electrónicos](/v1/guias/emision): estructura de los seis tipos de comprobante.
