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

# SDK PHP

Biblioteca oficial para emitir comprobantes desde PHP 8.2 o superior, seguir su autorización, descargar el RIDE y verificar webhooks.

Si desarrollas en PHP, puedes integrarte con nuestros servicios de facturación
usando nuestro SDK para PHP. Lo instalas con Composer y, en lugar de armar cada
petición con cURL, llamas a métodos como `emitirEn` o `descargarRide`, que
reciben y devuelven clases tipadas. Puedes reintentar sin miedo a duplicar
comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos;
además envía tu API Key en cada llamada, te indica si llegaste al límite de
solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te
enviamos.

Esta guía sigue el orden de una integración. Primero instalas el paquete,
configuras el cliente, emites tu primera factura y sigues su resultado; después
recibes webhooks y manejas errores, y al final ajustas los reintentos, las
opciones por llamada y la conexión, y armas comprobantes con los constructores.
Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en
[SDKs](/v1/guias/sdk).

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan
> `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com`
> solo cuando emitas comprobantes reales.

## 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
Instala el SDK PHP 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, puedes instalarla 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/sdk-php.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con composer require ecuafact/sdk. 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. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere PHP 8.2 o superior con ext-curl. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado (numérico), usa urlEstado tal cual (URL absoluta) y lee errores como arreglo. Ejecuta el programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer.
```

## Paquete

| Dato | Valor |
|---|---|
| Paquete Composer | [`ecuafact/sdk`](https://packagist.org/packages/ecuafact/sdk) |
| Versión | `v1.0.1` |
| PHP | 8.2 o superior, con las extensiones `curl` y `json`. |
| Dependencias | No necesita otras dependencias fuera de las extensiones. Solo si usas tu propio cliente PSR-18 necesitas `psr/http-client` y `psr/http-factory`. |
| Repositorio | [github.com/Ecuanexus/ecuafact-sdk-php](https://github.com/Ecuanexus/ecuafact-sdk-php) |
| Cliente | Es síncrono y usa cURL, o tu cliente PSR-18 con `Psr18Transport`. |
| Espacio de nombres | `Ecuafact\Sdk` (cliente, opciones, excepciones, webhooks), `Ecuafact\Sdk\Contracts` (clases de datos), `Ecuafact\Sdk\Builders` (constructores). |

## Requisitos

- [ ] PHP 8.2 o superior, que compruebas con `php -v`, con la extensión `curl`
      habilitada (aparece en la lista de `php -m`) y
      [Composer](https://getcomposer.org/).
- [ ] Una API Key de pruebas guardada en la variable de entorno
      `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se
      explica en [Sandbox de pruebas](/v1/guias/sandbox).
- [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier
      IP. En producción, la IP desde la que ejecutas el código debe estar en
      **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el
      `codEstado` 3010 (`ip_no_autorizada`).
- [ ] Un [contribuyente](/v1/guias/glosario) con `puedeEmitir` en tu
      [contexto](/v1/guias/consulta-contexto). El sandbox crea uno con el
      establecimiento `001` y el punto de emisión `001`.

## Instalación

Crea una carpeta para la prueba e instala el paquete.

```bash
mkdir ecuafact-prueba && cd ecuafact-prueba
composer require ecuafact/sdk
```

Si prefieres fijar la versión exacta, usa `composer require ecuafact/sdk:1.0.1`.

Composer crea `vendor/autoload.php`, que incluyes al inicio de cada script con
`require __DIR__ . '/vendor/autoload.php';`. Para verificar la instalación,
ejecuta este comando.

```bash
composer show ecuafact/sdk
```

La instalación funcionó si la salida muestra `versions : * v1.0.1`.

## Configuración

Crea el cliente **una vez** por proceso y reutilízalo, porque sirve para todos
los contribuyentes de tu API Key. Las opciones se pasan como argumentos con
nombre.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    identificacion: '0123456789001', // opcional: contribuyente por defecto
));
var_dump($client->options()); // la API Key aparece como ***
```

Si no pasas `apiKey`, o pasas `null` o el `false` que devuelve `getenv()` cuando
la variable no existe, el SDK lee la variable de entorno `ECUAFACT_API_KEY`; si
no pasas `baseAddress`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas
basta `new EcuafactClient(new EcuafactClientOptions())`.

Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción
aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y
`https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK
agrega la versión a cada ruta.

| Opción | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
| `baseAddress` | `?string` | `ECUAFACT_BASE_URL` | URL absoluta que debe usar `https`; el SDK rechaza `http` con `EcuafactConfigurationException`. Sin `/v1`, sin consulta (`?`), fragmento (`#`) ni usuario y contraseña. |
| `apiKey` | `?string` | `ECUAFACT_API_KEY` | Tu API Key; viaja en la cabecera `X-Api-Key`. No puede tener espacios al inicio o al final ni caracteres de control. Puedes leerla con `$options->apiKey`, que es de solo lectura, y no aparece en `var_dump`, `print_r`, `var_export`, `json_encode` ni en las trazas. |
| `identificacion` | `?string` | `null` | Contribuyente por defecto para `emitir` y `validar`. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). |
| `validarAntesDeEmitir` | `bool` | `false` | Si es `true`, `emitir` y `emitirEn` llaman antes a `/validar` y solo envían la emisión si la API la da por válida (2 peticiones por emisión). Se explica en [Validar antes de cada emisión](#validar-antes-de-cada-emision). |
| `timeout` | `float` | `30.0` | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta, en segundos, con fracciones. Debe ser mayor que 0 y solo se aplica con el transporte cURL. |
| `userAgent` | `string` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. Sin caracteres de control. |
| `retryTransientFailures` | `bool` | `true` | Reintenta fallos transitorios (ver [Reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. |
| `maxAttempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. |
| `transport` | `?TransportInterface` | `null` (cURL) | Transporte HTTP propio, por ejemplo `Transport\Psr18Transport` para usar tu cliente PSR-18 (ver [Conexión](#conexion-proxy-tls-y-psr-18)). |
| `respectRetryAfter` | `bool` | `true` | Espera lo que indique la cabecera `Retry-After` antes de reintentar, si es mayor que la espera calculada. |
| `maxRetryDelaySeconds` | `float` | `60.0` | Espera máxima entre reintentos, en segundos. Con `0` no hay tope. |
| `retryRateLimited` | `bool` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `maxRetryDelaySeconds`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. |
| `retryableStatusCodes` | `?int[]` | `null` = `[408, 425, 500, 502, 503, 504]` | Estados HTTP que se reintentan (enteros entre 100 y 599). El 429 no va aquí: lo controla `retryRateLimited`. Los valores por defecto están en `EcuafactClientOptions::DEFAULT_RETRYABLE_STATUS_CODES`. |
| `retryBaseDelaySeconds` | `float` | `0.2` | Espera base entre reintentos, en segundos. |
| `retryBackoff` | `RetryBackoff\|string` | `RetryBackoff::Linear` | `Linear`: base x intento (0.2, 0.4, 0.6 s). `Exponential`: base x 2^(intento-1) (0.2, 0.4, 0.8 s). Acepta también `'linear'` o `'exponential'`. |
| `retryJitterSeconds` | `float` | `0.05` | Variación aleatoria que se suma a cada espera, en segundos (ver [Reintentos](#idempotencia-y-reintentos)). |
| `totalTimeoutSeconds` | `?float` | `null` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas, en segundos. Al superarlo lanza `EcuafactTimeoutException`. Mayor que 0. |
| `connectTimeout` | `?float` | `null` | Tiempo máximo para abrir la conexión, en segundos. Mayor que 0. Solo con el transporte cURL. |
| `proxy` | `?string` | `null` | Proxy, por ejemplo `http://proxy.miempresa.local:8080`. Aparece como `***` en `var_dump`. Solo con el transporte cURL. |
| `caInfo` | `?string` | `null` | Ruta a un bundle de CA propio (CA corporativa). Solo con el transporte cURL. |
| `verifyPeer` | `bool` | `true` | Verificación del certificado TLS. Déjalo en `true` fuera de pruebas locales. Solo con el transporte cURL. |
| `curlOptions` | `array` | `[]` | Opciones `CURLOPT_*` adicionales. Solo con el transporte cURL. |
| `maxResponseBytes` | `?int` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un entero positivo lo aplica a todas las llamadas, incluidas las descargas; `null` o `0` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `$limite` y `$bytesLeidos`. |
| `additionalInfo` | `?string` | `null` | Valor de la cabecera `X-Additional-Info` en todas las solicitudes, por ejemplo `erp=MiERP/4.2; sucursal=quito`; no se guarda con el comprobante. Con `null` o `''` no se envía la cabecera. Sus reglas están en [Información adicional](#informacion-adicional). |

```php
new EcuafactClientOptions(maxResponseBytes: 64 * 1024 * 1024); // 64 MiB; null desactiva el tope
```

Las opciones se validan al crearlas. `EcuafactClientOptions` lanza
`EcuafactConfigurationException`, antes de hacer cualquier llamada, en
cualquiera de estos casos:

- Falta la API Key o la URL.
- La URL no es válida o termina en `/v1`.
- La API Key tiene espacios o caracteres de control.
- `timeout` no es mayor que 0, o `maxAttempts` es menor que 1.
- Un tiempo es negativo.
- `maxResponseBytes` es negativo.
- `retryBackoff` no es `linear` ni `exponential`.
- `additionalInfo` tiene caracteres fuera de ASCII imprimible, espacios al
  inicio o al final o más de 256 caracteres.

El mensaje de la excepción nunca incluye la API Key.

## Quickstart: de la API Key al RIDE

Este script hace el flujo completo en el ambiente de pruebas: lee tu
[contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado
del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el
[RIDE](/v1/guias/glosario), el PDF del comprobante.

### Paso 1. Guarda el comprobante

Guarda este JSON como `comprobante.json` junto al script. Es una factura a
consumidor final, con el tipo de identificación `07` y la identificación
`9999999999999`, que solo se admite en facturas de hasta 50.00. Factura 10.00
más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva
`secuencial`, porque te asignamos el
siguiente [secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El
script reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de
hoy.

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "001",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "07",
    "identificacionComprador": "9999999999999",
    "razonSocialComprador": "CONSUMIDOR FINAL",
    "totalSinImpuestos": 10.00,
    "totalDescuento": 0.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "baseImponible": 10.00,
        "valor": 1.50
      }
    ],
    "propina": 0.00,
    "importeTotal": 11.50,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 11.50
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "SERV-001",
      "descripcion": "Servicio de prueba",
      "cantidad": 1,
      "precioUnitario": 10.00,
      "descuento": 0.00,
      "precioTotalSinImpuesto": 10.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 10.00,
          "valor": 1.50
        }
      ]
    }
  ]
}
```

> [!NOTE]
> El JSON no lleva el tipo del comprobante: lo da la clase que lo recibe (`FacturaRequest` en este caso), como se explica en [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta).

`estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un
[punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el
establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01).

### Paso 2. Escribe el script

Guarda el código siguiente como `quickstart.php`. `Hydrator::hydrate` convierte el JSON en las
clases del SDK (`FacturaRequest`, `InfoFactura`, `DetalleCompraVenta`...); también
puedes construir esos objetos propiedad por propiedad o con los
[constructores](#constructores-de-comprobantes). `Hydrator` ignora las
propiedades del JSON que no existen en las clases del SDK. El SDK usa
la clase del comprobante para elegir la ruta.

El paso 4 usa `esperarResultado`, un método **opcional** que consulta la
operación cada 5 segundos hasta tener un resultado final o hasta 2 minutos. En
producción puedes usar en cambio el flujo asíncrono, en el que emites, guardas
el `idOperacion` y procesas el resultado cuando llega el
[webhook](/v1/guias/webhooks); así tu proceso no se queda esperando.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\EcuafactApiException;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\Support\Hydrator;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

try {
    // 1. Contexto: que contribuyentes puede usar tu API Key.
    $contexto = $client->getContexto();
    $emisor = null;
    foreach ($contexto->contribuyentes ?? [] as $contribuyente) {
        if ($contribuyente->puedeEmitir) {
            $emisor = $contribuyente;
            break;
        }
    }
    if ($emisor === null) {
        exit('Tu API Key no tiene un contribuyente habilitado para emitir.' . PHP_EOL);
    }
    echo "Emisor {$emisor->identificacion}" . PHP_EOL;

    // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador).
    /** @var FacturaRequest $comprobante */
    $comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));
    $comprobante->infoTributaria->ruc = $emisor->identificacion;
    $comprobante->info->fechaEmision = (new DateTimeImmutable('now', new DateTimeZone('America/Guayaquil')))->format('d/m/Y');

    // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key.
    $emision = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001');
    $idOperacion = $emision->admission->idOperacion;
    // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos.
    echo "estado {$emision->admission->estado} codEstado {$emision->admission->codEstado} idOperacion {$idOperacion}" . PHP_EOL;

    // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min).
    $operacion = $client->esperarResultado($idOperacion);
    echo "estado {$operacion->estado} codEstado {$operacion->codEstado}" . PHP_EOL;
    foreach ($operacion->errores ?? [] as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }

    // 5. RIDE: solo existe cuando el comprobante esta autorizado.
    if ($operacion->esAutorizado()) {
        $ride = $client->descargarRide($emisor->identificacion, $operacion->claveAcceso);
        file_put_contents('ride.pdf', $ride->contenido);
        echo "RIDE guardado en ride.pdf; claveAcceso {$operacion->claveAcceso}" . PHP_EOL;
    } elseif (!$operacion->esFinal()) {
        echo 'Aun sin resultado: consulta mas tarde o espera el webhook.' . PHP_EOL;
    }
} catch (EcuafactApiException $error) {
    echo "HTTP {$error->estadoHttp} codEstado {$error->codEstado}: {$error->msgError}" . PHP_EOL;
    foreach ($error->errores as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }
    echo "X-Correlation-Id: {$error->correlationId}" . PHP_EOL;
}
```

### Paso 3. Ejecuta y verifica

```bash
php quickstart.php
```

Deberías ver algo como esto; los identificadores cambian en cada ejecución:

```
Emisor 0123456789001
estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f
estado autorizado codEstado 2001
RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811
```

El programa funcionó si ves `estado autorizado` y el ejemplo guardó
el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir.

| Salida | Significado | Qué hacer |
|---|---|---|
| `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `claveAcceso` es `null`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. |
| `estado autorizado codEstado 2001` | El SRI autorizó el comprobante; `claveAcceso` trae la [clave de acceso](/v1/guias/glosario) de 49 dígitos. | Descarga el RIDE o el XML. |
| `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas que empiezan con `-` muestran el mensaje del SRI, que llega en `errores`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. |
| `estado rechazado codEstado 3002`, `rechazo_configuracion` o `error` | El comprobante no se emitió por su contenido, por la configuración del emisor o por un fallo. | Sigue la fila de su `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). |
| `estado cancelado codEstado 6001` | La plataforma canceló el envío; no se emitió y no consumió cupo. | Emite de nuevo con una **nueva** `Idempotency-Key`. |
| `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde o espera el [webhook](/v1/guias/webhooks). No emitas de nuevo. |
| `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. |
| `HTTP 403 codEstado 3011` | El contribuyente o el tipo de comprobante no está habilitado, o `ruc` no coincide con el contribuyente de la ruta. | Revisa `puedeEmitir` y `tiposComprobante` en el contexto. |
| `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal. Lee las líneas que empiezan con `-`. | Corrige el JSON; un 422 consume 1 documento como intento. |

> [!NOTE]
> Si ejecutas el script otro día con la misma `Idempotency-Key`, la fecha cambia
> el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una
> `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva.

## Tipo de comprobante y ruta

Así como la API tiene un endpoint por tipo de documento, el SDK tiene una clase de solicitud por tipo, y esa clase
elige la ruta de emisión y de validación. Pasas la clase a `emitir`, `emitirEn`, `validar` o `validarEn` y el SDK
llama al endpoint de su tipo; no hay campo de tipo en el cuerpo ni argumento de tipo en la llamada.

```php
$emision = $client->emitirEn($identificacion, $factura, 'FACTURA-2026-0001');      // $factura es un FacturaRequest
$validacion = $client->validarEn($identificacion, $notaCredito);                    // $notaCredito es un NotaCreditoRequest
```

Cada clase tiene solo las propiedades de su esquema del contrato, con los mismos nombres y tipos. En el docblock de
cada propiedad, `Obligatorio.` marca las que el contrato exige; el SDK no las valida, la API responde con un 422 y su
detalle. Las clases comunes se reutilizan en todos los tipos.

| Clase de solicitud | Cabecera | Líneas | Comunes |
|---|---|---|---|
| `FacturaRequest` | `InfoFactura` (incluye la exportación) | `DetalleCompraVenta` | `InfoTributaria`, `Pago`, `Impuesto`, `CampoAdicional` |
| `LiquidacionCompraRequest` | `InfoLiquidacionCompra` | `DetalleCompraVenta` | `InfoTributaria`, `Pago`, `Impuesto`, `CampoAdicional` |
| `NotaCreditoRequest` | `InfoNotaCredito` | `DetalleNotaCredito` | `InfoTributaria`, `Impuesto`, `CampoAdicional` |
| `NotaDebitoRequest` | `InfoNotaDebito` | `Motivo` | `InfoTributaria`, `Pago`, `Impuesto`, `CampoAdicional` |
| `GuiaRemisionRequest` | `InfoGuiaRemision` | `Destinatario` con `DetalleGuia` | `InfoTributaria`, `CampoAdicional` |
| `RetencionRequest` | `InfoComprobanteRetencion` | `DocsSustento` con `ImpuestoDocSustento` y `RetencionLinea` | `InfoTributaria`, `Pago`, `CampoAdicional` |

Todas implementan `SolicitudComprobante`, que expone `tipoComprobante()` (un `TipoComprobante`), útil si guardas
solicitudes de varios tipos en una misma lista. `EcuafactTipoComprobanteException` solo se lanza cuando el filtro
`tipoDocumento` de `listarOperaciones` no es uno de los seis tipos.

| Código | Documento | Ruta de emisión | Ruta de validación |
|---|---|---|---|
| `01` | Factura | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST .../facturas/validar` |
| `03` | Liquidación de compra | `POST .../liquidaciones-compra` | `POST .../liquidaciones-compra/validar` |
| `04` | Nota de crédito | `POST .../notas-credito` | `POST .../notas-credito/validar` |
| `05` | Nota de débito | `POST .../notas-debito` | `POST .../notas-debito/validar` |
| `06` | Guía de remisión | `POST .../guias-remision` | `POST .../guias-remision/validar` |
| `07` | Comprobante de retención | `POST .../retenciones` | `POST .../retenciones/validar` |

`emitir`, `emitirEn`, `validar` y `validarEn` eligen la ruta por ti y no cambian
su firma. Las rutas de seguimiento, consulta, descarga y correo no cambian.

## Validar sin emitir

Las reglas de negocio de los comprobantes (campos requeridos, formatos de
`estab`, `ptoEmi` y `secuencial`, catálogos, topes, coherencia aritmética) viven
solo en la API. El SDK no las revisa: `validar` siempre llama a `/validar`, y
`emitir` envía el comprobante directo y lanza `EcuafactValidationException` con
el 422 de la API. Así, cuando la API cambia una regla no tienes que actualizar el SDK.

Antes de emitir puedes comprobar que un comprobante cumple las reglas de la
emisión con `validar`, o con `validarEn` si indicas la identificación del
contribuyente. La validación usa la ruta del tipo y le
agrega `/validar`; por ejemplo, una nota de crédito (`04`) se valida en
`POST .../notas-credito/validar`. La validación no emite nada ni consume cupo, y
no necesita `Idempotency-Key`; el SDK no la envía. El detalle de qué se valida
está en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir).

El método devuelve un `ValidacionResultado` con `valido`, `codEstado`, `msgError`,
`errores`, `advertencias` y `correlationId`. Cuando el comprobante cumple las reglas, la API
responde 200, `valido` es `true`, `codEstado` y `msgError` son `null` y `errores`
llega vacío. `advertencias` trae los avisos que la API devuelve junto al resultado
(por ejemplo, que ignora la firma de un XML que la trae); un aviso no impide emitir. Cuando el comprobante no cumple una regla, la API responde 422 con
el `codEstado` 3002 (`comprobante_invalido`) y el SDK no lanza una excepción: recibes `valido`
en `false` y los problemas en `errores`, para que los corrijas antes de emitir.

```php
$validacion = $client->validarEn($emisor->identificacion, $comprobante);
if ($validacion->valido) {
    $emision = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001');
} else {
    foreach ($validacion->errores as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }
}
```

Cualquier otra respuesta de error lanza la misma excepción que en la emisión.
Por ejemplo, si el contribuyente o el tipo de comprobante no están habilitados
para tu API Key, recibes `EcuafactAuthException` con el `codEstado` 3011 (`acceso_denegado`). Como validar
no tiene efectos, el SDK repite la llamada ante fallos de red o errores
temporales del servidor igual que en una consulta. Un comprobante válido todavía
puede fallar al emitirse por cupo o porque ya lo emitiste.

### Validar antes de cada emisión

Si quieres que cada emisión pase primero por `/validar`, activa
`validarAntesDeEmitir: true` en `EcuafactClientOptions`, o `validarAntes: true`
en `RequestOptions` para una sola llamada (la opción de la llamada reemplaza a la
del cliente). Con la opción activa, `emitir` y `emitirEn` llaman primero a
`/validar`:

- Si `valido` es `false` o hay `errores`, lanzan `EcuafactValidationException`
  (HTTP 422, `codEstado` 3002) con esos `errores`, y la emisión no se envía.
- Si es válido, envían la emisión y las `advertencias` quedan en
  `EmisionResultado::$advertencias`. Una advertencia no bloquea.

Por defecto es `false`, porque duplica las peticiones: sin la opción, una emisión
hace 1 petición; con ella, 2.

```php
$client = new EcuafactClient(new EcuafactClientOptions(
    apiKey: getenv('ECUAFACT_API_KEY'),
    validarAntesDeEmitir: true,
));
$resultado = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001');
foreach ($resultado->advertencias as $aviso) {
    echo "Aviso: {$aviso}" . PHP_EOL;
}
```

## Seguimiento del resultado

La emisión responde `202 Accepted` en cuanto la API recibe el comprobante, y el
resultado del SRI llega después. Puedes conocerlo de tres formas.

| Forma | Método | Cuándo usarla |
|---|---|---|
| Esperar en tu proceso | `esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0, $opciones = null)` | La usas en scripts, pruebas y procesos que pueden esperar unos segundos. |
| Consultar una vez | `getOperacion($idOperacion, $opciones = null)` (alias: `consultarOperacion`) | La usas en tareas programadas que revisan operaciones pendientes, o para mostrar el estado cuando un usuario lo pide. |
| Recibirlo | [Webhooks](#webhooks) | En producción, te avisamos sin que consultes. |

`esperarResultado` consulta `GET /v1/operaciones/{idOperacion}` cada `$intervalo`
segundos hasta que `esFinal()` sea `true` o hasta que pasen `$maximo` segundos, y
devuelve la **última** operación leída, así que revisa `esFinal()` antes de
decidir. Los tiempos se expresan en segundos (`float`), y un valor negativo
lanza `EcuafactSdkException`.
Cada consulta cuenta para tu límite de solicitudes por minuto. `$opciones` se
aplica a cada consulta.

`getOperacion`, `consultarOperacion` y `esperarResultado` exigen que
`$idOperacion` sea un UUID; si no lo es, lanzan `EcuafactSdkException` sin llamar
a la API.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

// Consulta cada 3 segundos, hasta 1 minuto.
$operacion = $client->esperarResultado('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f', 3.0, 60.0);

if ($operacion->esAutorizado()) {
    echo "Autorizado: {$operacion->claveAcceso}" . PHP_EOL;
} elseif ($operacion->esFinal()) {
    echo "Final sin autorizacion: estado {$operacion->estado}, codEstado {$operacion->codEstado}: {$operacion->msgError}" . PHP_EOL;
    foreach ($operacion->errores ?? [] as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }
} else {
    echo "Aun sin resultado ({$operacion->estado}); vuelve a consultar con getOperacion mas tarde." . PHP_EOL;
}
```

Reemplaza el `idOperacion` del ejemplo por el que recibiste al emitir.

`Operation` tiene estas propiedades, y todas pueden ser `null`:

| Propiedad | Tipo | Descripción |
|---|---|---|
| `estado` | `?string` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. |
| `codEstado` | `?int` | Código numérico del resultado; su primer dígito es el `estado`. En `recibido` es 1001, sin clave de acceso, o 1002, con `claveAcceso`; en `autorizado`, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (`rechazo_sri`) o 4002 (`firma_no_valida`). Compáralo con las constantes de `CodEstado`. |
| `msgError` | `?string` | Descripción general y fija del código; `null` con `recibido` y `autorizado`. |
| `errores` | `?array` | Lista de textos con el detalle del resultado; en un rechazo del SRI trae su mensaje. La API la envía siempre, vacía si no hay detalle. |
| `idOperacion` | `?string` | UUID de la operación. |
| `urlEstado` | `?string` | URL completa del seguimiento. |
| `ambiente` | `?int` | `1` = pruebas, `2` = producción. |
| `tipoDocumento` | `?string` | Tipo de comprobante (`01` a `07`). |
| `numeroDocumento` | `?string` | Número del comprobante, por ejemplo `001-001-000000123`. |
| `referenciaExterna` | `?string` | La `referenciaExterna` que enviaste al emitir. |
| `claveAcceso` | `?string` | Clave de acceso de 49 dígitos; es `null` con el `codEstado` 1001. |
| `fhRecibido` | `?string` | Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). |
| `fhAutorizacion` | `?string` | Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con `estado`. |

Como todos los modelos de respuesta, `Operation` tiene además la propiedad
`extra` (`array`), que guarda los campos que la API devuelve y el modelo no declara,
con su nombre como clave y los objetos JSON como arreglos asociativos. Está
vacía (`[]`) cuando no hay campos nuevos y no se envía a la API si serializas el
modelo.

El significado de cada `estado` y de cada `codEstado` está en
[Seguimiento de una operación](/v1/guias/consulta-operacion#que-hacer-segun-el-estado).

## Estados tipados

`Operation`, `Admission` y `Comprobante` conservan las propiedades de la API
(`estado`, `codEstado`, `tipoDocumento`) y agregan métodos que devuelven enums
de PHP. Un valor que el SDK no conoce no rompe tu código, porque se lee como
`Desconocido`, o como `null` en `tipoComprobante()`, y el texto original sigue
en la propiedad.

| Método | Enum | Casos |
|---|---|---|
| `$operacion->estadoOperacion()`, `$comprobante->estadoOperacion()` | `Contracts\EstadoOperacion` | `Recibido`, `Autorizado`, `Rechazado`, `RechazoConfiguracion`, `Error`, `Cancelado`, `Desconocido` |
| `$operacion->tipoComprobante()`, `$comprobante->tipoComprobante()` | `?Contracts\TipoComprobante` | `Factura` (`01`), `LiquidacionCompra` (`03`), `NotaCredito` (`04`), `NotaDebito` (`05`), `GuiaRemision` (`06`), `Retencion` (`07`); `null` si el código no se conoce |
| `$operacion->esFinal()` | `bool` | `true` si `estado` es cualquier valor distinto de `recibido`. |
| `$operacion->esAutorizado()` | `bool` | `true` si `estado` es `autorizado`. |
| `$evento->eventType` | `Contracts\TipoEventoWebhook` | `DocumentoAutorizado`, `DocumentoRechazado`, `DocumentoFallido`, `OperacionRequiereAtencion`, `Desconocido` |

Los valores de `codEstado` están como constantes `int` en
`Contracts\CodEstado`, con el nombre de cada código del
[catálogo](/v1/guias/errores#catalogo-de-codestado) en mayúsculas, por ejemplo
`CodEstado::RECHAZO_SRI` (3001), `CodEstado::COMPROBANTE_INVALIDO` (3002) o
`CodEstado::LIMITE_SOLICITUDES` (5005). `CodEstado::estado($codigo)` devuelve el
`EstadoOperacion` que corresponde al primer dígito, incluso para un código que
tu versión del SDK todavía no conoce, y `CodEstado::nombre($codigo)` devuelve
su nombre.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\CodEstado;
use Ecuafact\Sdk\Contracts\EstadoOperacion;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$operacion = $client->getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
echo match (true) {
    $operacion->estadoOperacion() === EstadoOperacion::Autorizado => 'Descarga el RIDE',
    $operacion->estadoOperacion() === EstadoOperacion::Recibido => 'Consulta mas tarde',
    $operacion->codEstado === CodEstado::RECHAZO_SRI => 'Corrige y emite un comprobante nuevo: ' . implode(' | ', $operacion->errores ?? []),
    $operacion->estadoOperacion() === EstadoOperacion::Rechazado => "Corrige segun codEstado {$operacion->codEstado}: {$operacion->msgError}",
    $operacion->estadoOperacion() === EstadoOperacion::Cancelado => 'Emite de nuevo con nueva Idempotency-Key',
    default => 'Consulta mas tarde',
} . PHP_EOL;
```

## Webhooks

Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y,
antes de procesar cada entrega, comprobar que te la enviamos nosotros. El SDK te
ayuda a recibir webhooks: verifica la firma y te entrega el evento tipado, pero
no administra los destinos. Los destinos (la URL a la que enviamos cada evento,
sus eventos suscritos y su secreto) los administras desde el Portal del Cliente
(**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP
o con la API REST, como se explica en
[Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api).

`WebhookEvent::construir` verifica la cabecera `Ecuafact-Signature`
(`t=<epoch>,v1=<hmac>`) contra el cuerpo **crudo** y, si es válida, devuelve el
evento tipado. Si la firma no coincide, está fuera de la tolerancia (300 s por
defecto, `WebhookSignature::DEFAULT_TOLERANCE_SECONDS`) o el cuerpo no es un
objeto JSON, lanza `EcuafactWebhookException`.

| Método | Devuelve | Lanza |
|---|---|---|
| `WebhookEvent::construir($secretos, $cabecera, $cuerpo, $toleranceSeconds = 300, $now = null)` | `WebhookEvent` | `EcuafactWebhookException` |
| `WebhookSignature::construirEvento(...)` | Lo mismo que `construir`, con los mismos argumentos. | `EcuafactWebhookException` |
| `WebhookSignature::verify($secretos, $cabecera, $cuerpo, $now = null, $toleranceSeconds = 300)` | `bool` | Nunca. |
| `WebhookSignature::sign($secreto, $unixSeconds, $cuerpo)` | La cabecera `t=...,v1=...` | Nunca. Útil para probar tu endpoint en local. |

`$secretos` acepta un secreto (`string`) o un arreglo de secretos, y la entrega
es válida si coincide con cualquiera; así puedes rotar el secreto sin rechazar
entregas. Agrega el nuevo, publica tu aplicación y quita el anterior cuando las
entregas lleguen firmadas con el nuevo, como se explica en
[Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). Pasa
siempre un `string` o un arreglo, porque `getenv()` devuelve `false` si la
variable no existe y `false` no es un argumento válido.

El ejemplo siguiente usa PHP sin framework. Guarda tu secreto en
`ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en
`ECUAFACT_WEBHOOK_SECRET_ANTERIOR`.

```php
<?php
// Guarda como webhook.php y ejecuta: php -S localhost:3000 webhook.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\TipoEventoWebhook;
use Ecuafact\Sdk\EcuafactWebhookException;
use Ecuafact\Sdk\WebhookEvent;

$secretos = array_values(array_filter([
    getenv('ECUAFACT_WEBHOOK_SECRET') ?: null,
    getenv('ECUAFACT_WEBHOOK_SECRET_ANTERIOR') ?: null,
]));
$cuerpoCrudo = file_get_contents('php://input'); // Cuerpo crudo, sin parsear.
$cabecera = $_SERVER['HTTP_ECUAFACT_SIGNATURE'] ?? '';

try {
    $evento = WebhookEvent::construir($secretos, $cabecera, $cuerpoCrudo);
} catch (EcuafactWebhookException) {
    http_response_code(401);
    exit;
}

// Deduplica por eventTypeRaw + resourceId. Solo para el ejemplo: marca en disco;
// en produccion usa una tabla con clave unica.
$marca = sys_get_temp_dir() . '/ecuafact-' . hash('sha256', $evento->eventTypeRaw . '|' . $evento->resourceId);
if (file_exists($marca)) {
    http_response_code(200); // Duplicado: ya procesado.
    exit;
}
touch($marca);

match ($evento->eventType) {
    TipoEventoWebhook::DocumentoAutorizado => error_log("Autorizado {$evento->idOperacion} {$evento->claveAcceso}"),
    TipoEventoWebhook::DocumentoRechazado => error_log("Rechazo fiscal {$evento->idOperacion}: codEstado {$evento->codEstado} " . implode(' | ', $evento->errores)),
    TipoEventoWebhook::DocumentoFallido => error_log("No emitido {$evento->idOperacion}: estado {$evento->estado}, codEstado {$evento->codEstado}"),
    default => error_log("Evento {$evento->eventTypeRaw} prueba=" . var_export($evento->probe, true)),
};
http_response_code(200);
```

Para probarlo en local, firma un cuerpo con `WebhookSignature::sign` y envíalo
con cURL.

```php
<?php
// Guarda como firmar.php y ejecuta: php firmar.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\WebhookSignature;

$cuerpo = '{"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';
file_put_contents('evento.json', $cuerpo);
echo WebhookSignature::sign(getenv('ECUAFACT_WEBHOOK_SECRET'), time(), $cuerpo) . PHP_EOL;
```

```bash
FIRMA=$(php firmar.php)
curl -s -i -X POST "http://localhost:3000/" \
  -H "Ecuafact-Signature: $FIRMA" \
  -H "Content-Type: application/json" \
  --data-binary @evento.json
# HTTP/1.1 200 OK (con un secreto distinto responde 401)
```

`WebhookEvent` tiene estas propiedades:

| Propiedad | Tipo | Descripción |
|---|---|---|
| `eventType` | `TipoEventoWebhook` | Tipo tipado; `Desconocido` si el SDK no conoce el valor. |
| `eventTypeRaw` | `string` | Valor original de `eventType` (por ejemplo `document.authorized`). |
| `resourceId` | `?string` | En los eventos `document.*`, el `idOperacion`; en el evento de prueba, el identificador del destino. |
| `occurredAtUtc` | `?\DateTimeImmutable` | Momento del evento, en UTC. |
| `idOperacion`, `claveAcceso`, `tipoDocumento` | `?string` | Datos de la operación; `tipoDocumento` viene cuando el evento lo trae. |
| `estado` | `?string` | El mismo `estado` del seguimiento: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`. |
| `codEstado` | `?int` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Decide con `estado` y `codEstado`, no solo con el tipo del evento. |
| `msgError` | `?string` | Descripción fija del código; `null` cuando no hay error. |
| `errores` | `string[]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacío si no hay detalle. |
| `fhAutorizacion` | `?string` | Momento de la autorización del SRI, cuando existe. |
| `ruc` | `?string` | RUC del documento; en el evento de prueba, el RUC al que se limita el destino. `null` si no viene. |
| `probe` | `bool` | `true` en el evento de prueba del portal. |
| `cuerpo` | `array` | El cuerpo completo decodificado. |

> [!WARNING]
> Verifica la firma sobre el cuerpo crudo (`php://input`). En Laravel usa
> `$request->getContent()`; no uses `$request->all()` ni vuelvas a codificar el
> JSON.

### Standard Webhooks

Cada entrega trae además las cabeceras del estándar
[Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks) (`webhook-id`,
`webhook-timestamp` y `webhook-signature`), firmadas con el mismo secreto. Con el
SDK puedes verificar cualquiera de las dos firmas, sin decidir cuál llegó.

| Método | Qué hace |
|---|---|
| `WebhookEvent::construirDesdeCabeceras($secretos, $cabeceras, $cuerpo, $toleranceSeconds = 300, $now = null)` | Devuelve el `WebhookEvent` si `Ecuafact-Signature` o Standard Webhooks es válida; si no, lanza `EcuafactWebhookException`. |
| `WebhookSignature::construirEventoDesdeCabeceras(...)` | Lo mismo que el anterior, con los mismos argumentos. |
| `WebhookSignature::verificarCabeceras($secretos, $cabeceras, $cuerpo, $now = null, $toleranceSeconds = 300)` | Devuelve `bool` con la misma regla y nunca lanza una excepción. |
| `WebhookSignature::verificarStandardWebhooks($secretos, $webhookId, $webhookTimestamp, $webhookSignature, $cuerpo, $now = null, $toleranceSeconds = 300)` | Devuelve `bool`. Verifica solo la firma de Standard Webhooks. |
| `WebhookSignature::firmarStandardWebhooks($secreto, $webhookId, $unixSeconds, $cuerpo)` | Devuelve el valor de `webhook-signature` (`v1,<base64>`). Sirve para pruebas automatizadas. |

`$cabeceras` es un arreglo asociativo cuyos nombres no distinguen mayúsculas, así
que sirven `getallheaders()`, las cabeceras de una petición PSR-7 o `$_SERVER`.
El secreto puede llevar o no el prefijo `whsec_`, y también aceptas un arreglo de
secretos para la rotación. Con `construirDesdeCabeceras` verificas
`Ecuafact-Signature` si viene y, si no viene o no es válida, Standard Webhooks.

```php
try {
    $evento = WebhookEvent::construirDesdeCabeceras($secretos, getallheaders(), $cuerpoCrudo);
} catch (EcuafactWebhookException) {
    http_response_code(401);
    exit;
}
```

Los eventos y su contenido están en [Webhooks](/v1/guias/webhooks), y el
algoritmo de la firma, en [Verificación de firma](/v1/guias/webhooks-firma).

## Errores

Todas las excepciones del SDK heredan de `EcuafactSdkException`, que extiende
`\RuntimeException`, y las que vienen de una respuesta de la API heredan además
de `EcuafactApiException`. Captura primero las específicas y al final las
generales. Todas están en el espacio de nombres `Ecuafact\Sdk`.

| Excepción | Hereda de | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL, la URL no es válida o termina en `/v1`, la API Key tiene espacios o caracteres de control, o una opción del cliente o de `RequestOptions` es inválida. | Corrige la configuración. No llama a la API. |
| `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API tras agotar los intentos. Trae `curlErrno` cuando el error viene de cURL, `idempotencyKey` y `correlationId`. | Reintenta más tarde con la misma `idempotencyKey`. |
| `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `timeout` en el último intento o el tope total de la llamada. Trae `idempotencyKey` y `correlationId`. | Si emitías, consulta antes el seguimiento o reintenta con la misma `idempotencyKey`. |
| `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo que no es un objeto JSON. | Responde 401 y no proceses el evento. |
| `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `codEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. |
| `EcuafactValidationException` | `EcuafactApiException` | HTTP 400, 413, 415, 422 o 501: solicitud rechazada, con el `codEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3006 (`cuerpo_excedido`), 3007 (`version_no_soportada`), 3008 (`no_implementado`) o 3012 (`filtros_invalidos`). | Corrige según `errores`. Un 422 con el `codEstado` 3002 no consume cupo, porque el comprobante no llegó a emitirse. |
| `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `codEstado` 3013 (`no_encontrado`), o con `codEstado` en 0 si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `idOperacion`, la `claveAcceso` o el ambiente (URL). |
| `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `codEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `codEstado` en la tabla de códigos de abajo. |
| `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `codEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `retryAfter` segundos y reintenta con la misma `idempotencyKey`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste `retryRateLimited`. |
| `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`): cupo agotado. | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes. |
| `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `codEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Si `esReintentable` es `true`, reintenta más tarde con la misma `idempotencyKey`. |
| `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API que no corresponda a las filas anteriores (por ejemplo, un 418). | Revisa `codEstado`, `msgError` y `errores`. |
| `EcuafactInvalidResponseException` | `EcuafactSdkException` | La API respondió con un estado 2xx, pero el cuerpo está vacío o no es JSON válido. Trae `status`, `idempotencyKey` y `correlationId`. | No se reintenta. Si emitías, repite la emisión con la misma `idempotencyKey`, como se explica en [Idempotencia y reintentos](#idempotencia-y-reintentos), o consulta el resultado; no emitas de nuevo con otra clave. Si persiste, contacta a soporte con el `correlationId`. |
| `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El filtro `tipoDocumento` de `listarOperaciones` no es un tipo válido. | Usa el código (`01`, `03`, `04`, `05`, `06`, `07`) o su nombre. No llama a la API. |
| `EcuafactResponseTooLargeException` | `EcuafactSdkException` | El cuerpo de la respuesta supera el tope `maxResponseBytes`. Trae `$limite` y `$bytesLeidos`. | Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. |
| `EcuafactSdkException` | `\RuntimeException` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, importe con formato inválido, falta el contribuyente por defecto, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, argumento obligatorio vacío. | Corrige la llamada. |

| Propiedad de `EcuafactApiException` | Tipo | Descripción |
|---|---|---|
| `codEstado` | `int` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de `CodEstado`. Es 0 si la respuesta no trae cuerpo de error. |
| `estado` | `?string` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`. |
| `msgError` | `?string` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. |
| `estadoHttp` | `int` | Estado HTTP. |
| `errores` | `string[]` | Detalle específico del error, como la ruta del campo que falla en un 3002. Vacío cuando no hay detalle. |
| `correlationId` | `?string` | Cabecera `X-Correlation-Id` (la de la API o la que enviaste en `RequestOptions`). Inclúyelo al pedir soporte. |
| `idempotencyKey` | `?string` | Clave usada en la emisión; reutilízala al reintentar. `null` en llamadas sin idempotencia. |
| `retryAfter` | `?int` | Segundos indicados por la cabecera `Retry-After`; `null` si no llegó. |
| `esReintentable` | `bool` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `codEstado` 5005. El 429 con 4004 (cupo agotado) no es reintentable. |

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\EcuafactApiException;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\EcuafactConnectionException;
use Ecuafact\Sdk\EcuafactQuotaException;
use Ecuafact\Sdk\EcuafactRateLimitException;
use Ecuafact\Sdk\EcuafactTimeoutException;
use Ecuafact\Sdk\EcuafactValidationException;
use Ecuafact\Sdk\Support\Hydrator;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));
$comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));

try {
    $r = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
    echo $r->admission->estado . ' ' . $r->admission->idOperacion . PHP_EOL;
} catch (EcuafactValidationException $error) {
    // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual.
    foreach ($error->errores as $detalle) {
        echo $detalle . PHP_EOL;
    }
} catch (EcuafactQuotaException $error) {
    echo 'Cupo agotado: compra un paquete. No reintentes.' . PHP_EOL;
} catch (EcuafactRateLimitException $error) {
    echo 'Limite de solicitudes: espera ' . ($error->retryAfter ?? 1) . " s y reintenta con {$error->idempotencyKey}" . PHP_EOL;
} catch (EcuafactApiException $error) {
    echo "{$error->estadoHttp} codEstado {$error->codEstado} {$error->msgError} reintentable=" . var_export($error->esReintentable, true)
        . " correlation={$error->correlationId}" . PHP_EOL;
} catch (EcuafactConnectionException | EcuafactTimeoutException $error) {
    // Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key.
    echo $error->getMessage() . " clave={$error->idempotencyKey}" . PHP_EOL;
}
```

Estos son los códigos que verás con más frecuencia. El catálogo completo, con
el nombre de cada código, está en
[Errores](/v1/guias/errores#catalogo-de-codestado), y las constantes de `CodEstado`
llevan ese mismo nombre, escrito con la convención del lenguaje.

| `codEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|---|
| 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. |
| 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el `correlationId`. |
| 3011 | `acceso_denegado` | 403 | Contribuyente, tipo de comprobante no habilitado, o `ruc` distinto del contribuyente de la ruta. | Revisa `getContexto()` (`puedeEmitir`, `tiposComprobante`). |
| 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `retryAfter` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo. |
| 3003 | `solicitud_invalida` | 400 | JSON mal formado, cabecera inválida o parámetro de ruta con tipo inválido. | Corrige según `errores`. |
| 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `errores`; consume 1 documento como intento. |
| 3012 | `filtros_invalidos` | 400 | Un filtro de una consulta está fuera de rango. | Ajusta los filtros a los [límites](/v1/guias/limites). |
| 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión o 1 MiB en otros `POST`/`PUT`. | Reduce el cuerpo. |
| 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes; si querías otro comprobante, omite `secuencial` para que se asigne el siguiente. |
| 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` o `referenciaExterna` con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. |
| 4004 | `cupo_agotado` | 429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa `getConsumo()`; compra un paquete. |
| 3013 | `no_encontrado` | 404 | Operación, comprobante o RIDE no encontrado. | Verifica el id, la clave y el ambiente; el RIDE existe solo si está autorizado. |
| 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. |

## Idempotencia y reintentos

La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada
se repite, por ejemplo después de un timeout o de una caída de la red.

- Si no la pasas, o pasas `''`, el SDK genera una de 32 caracteres
  hexadecimales, la usa en todos sus reintentos y te la devuelve en
  `$resultado->idempotencyKey` o, si falla, en `$error->idempotencyKey`.
- Te recomendamos pasar un valor estable por intención, como tu número interno
  de factura, o un UUID v4 que guardes junto al documento.
- El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a
  128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple,
  lanza `EcuafactSdkException` sin llamar a la API.

> [!WARNING]
> Si reintentas una emisión desde tu aplicación, reutiliza la misma
> `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la
> emisión.

Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción
(`EcuafactInvalidResponseException`) conserva la `Idempotency-Key` en
`idempotencyKey` y el `X-Correlation-Id` en `correlationId`; repite la emisión
con esa misma clave y no se duplica el comprobante.

| Situación | Se reintenta | Detalle |
|---|---|---|
| HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `retryableStatusCodes`. Solo en `GET` y en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva). |
| HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `retryRateLimited: false` | Espera lo que indica `Retry-After` y reintenta. Con `retryRateLimited: false` lanza `EcuafactRateLimitException` con `retryAfter`, y decides tú cuándo reintentar. |
| HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. |
| Error de red o timeout de un intento | Sí | Se reintenta en las mismas condiciones; al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. |
| Descarga de RIDE/XML | Sí | Se reintenta ante un estado HTTP transitorio o un error de red. |
| Validación sin emitir (`validar`, `validarEn`) | Sí | Se reintenta como una consulta ante un estado HTTP transitorio o un error de red. No lleva `Idempotency-Key` porque no emite nada. |
| `actualizarPerfil`, `actualizarLogo` | No | No llevan `Idempotency-Key`, así que un reintento automático podría repetir el efecto. |
| Cualquier otro 4xx | No | Se lanza la excepción de inmediato. |

Entre intentos, el SDK espera según estas reglas, donde `n` es el número del
intento que falló:

- `Linear`: `retryBaseDelaySeconds` x `n`, más un margen aleatorio de hasta
  `retryJitterSeconds` x `n`. Con los valores por defecto, espera 0.2 s y 0.4 s,
  más hasta 0.05 s y 0.1 s.
- `Exponential`: `retryBaseDelaySeconds` x 2^(`n`-1), más un margen aleatorio
  de hasta `retryJitterSeconds`.

Si la respuesta trae un `Retry-After` mayor y `respectRetryAfter` es `true`,
espera ese tiempo. Si `maxRetryDelaySeconds` es mayor que 0, la espera nunca
lo supera. Si la siguiente espera no cabe en el tope total de la llamada, el SDK no
reintenta y lanza el último error.

## Opciones por llamada

Puedes cambiar el tiempo máximo, el tope total, la correlación, la cabecera
`X-Additional-Info` o los reintentos de una sola llamada sin tocar la
configuración del cliente.

Todos los métodos del cliente y de la vista `EcuafactContribuyente` que llaman
a la API aceptan como último argumento `?RequestOptions $opciones`, incluido
`esperarResultado`. Lo que no indiques usa la configuración del cliente.

| Argumento de `RequestOptions` | Valor por defecto | Qué hace |
|---|---|---|
| `timeout` | `null` (usa el del cliente) | Tiempo máximo de cada intento, en segundos. Mayor que 0. Se aplica con el transporte cURL o con uno que implemente `TimeoutOverrideTransportInterface`; con un transporte PSR-18 se ignora y lo controla tu cliente HTTP. |
| `totalTimeout` | `null` (usa `totalTimeoutSeconds`) | Tope de la llamada, incluidos reintentos y esperas, en segundos. Al superarlo lanza `EcuafactTimeoutException`. Mayor que 0. |
| `correlationId` | `null` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres `A-Z a-z 0-9 . _ -`. |
| `reintentos` | `true` | `false` desactiva los reintentos solo en esta llamada. |
| `validarAntes` | `null` (usa el del cliente) | Solo en `emitir` y `emitirEn`: `true` llama a `/validar` antes de emitir y `false` no lo llama, sea cual sea `validarAntesDeEmitir`. |
| `additionalInfo` | `null` (usa el del cliente) | Valor de la cabecera `X-Additional-Info` en esta llamada; reemplaza al `additionalInfo` del cliente. Sigue la misma validación que en el cliente, descrita en [Información adicional](#informacion-adicional). Con `null` usa el del cliente, y con `''` no envía la cabecera en esta llamada. |

PHP no tiene cancelación cooperativa, así que acota la llamada con `timeout` o
`totalTimeout`.

La API devuelve la correlación que enviaste. La encuentras en
`EmisionResultado::$correlationId`, en `EcuafactApiException::$correlationId` y
en `$correlationId` de `EcuafactConnectionException` y
`EcuafactTimeoutException`.

```php
<?php
// Guarda como opciones.php y ejecuta: php opciones.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: 'erp=MiERP/4.2; sucursal=quito', // X-Additional-Info en todas las solicitudes
));

// Un solo intento, correlacion propia y X-Additional-Info distinta para esta consulta.
$contexto = $client->getContexto(new RequestOptions(
    reintentos: false,
    correlationId: 'pedido-2026-0457',
    additionalInfo: 'erp=MiERP/4.2; sucursal=quito; caja=3',
));
echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL;

// Mas tiempo para una descarga grande, con tope total de 2 minutos.
$ride = $client->descargarRide(
    '0123456789001',
    '0710202601012345678900110010010000001231234567811',
    new RequestOptions(timeout: 60.0, totalTimeout: 120.0),
);
file_put_contents('ride.pdf', $ride->contenido);
```

Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu
emisor. Un `correlationId` con espacios o de más de 64 caracteres, un
`additionalInfo` inválido o un tiempo menor o igual a 0 lanzan
`EcuafactConfigurationException` al crear `RequestOptions`, sin llamar a la API.

## Información adicional

Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP
o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas
soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu
solicitud y no cambia su respuesta.
Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en
[Límites](/v1/guias/limites#cabeceras).

| Dónde | Qué hace |
|---|---|
| `EcuafactClientOptions` argumento `additionalInfo` | Se envía en todas las solicitudes del cliente, incluidas las de `esperarResultado` y la vista `EcuafactContribuyente` (`$client->para(...)`). Con `null` o `''` no se envía. |
| `RequestOptions` argumento `additionalInfo` | Reemplaza el valor del cliente solo en esa llamada. Con `null` usa el del cliente, y con `''` no envía la cabecera en esa llamada. |

El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas:

- Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea.
- Sin espacios al inicio ni al final.
- Máximo 256 caracteres (`EcuafactClientOptions::ADDITIONAL_INFO_MAX`).

Si no cumple, el constructor lanza `EcuafactConfigurationException` sin llamar
a la API. El valor aparece como `***` en `var_dump` y no se incluye en las
excepciones. No pongas en él la API Key ni datos personales.

```php
<?php
// Guarda como info_adicional.php y ejecuta: php info_adicional.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: 'erp=MiERP/4.2; sucursal=001',
));

// Todas las solicitudes llevan X-Additional-Info: erp=MiERP/4.2; sucursal=001
$contexto = $client->getContexto();

// Solo esta llamada lleva otro valor.
$consumo = $client->getConsumo(new RequestOptions(
    additionalInfo: 'erp=MiERP/4.2; sucursal=002; lote=2026-10-08',
));
echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL;
```

| Error | Por qué pasa | Qué hacer |
|---|---|---|
| `EcuafactConfigurationException` al crear `EcuafactClientOptions` | `additionalInfo` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. |
| `EcuafactConfigurationException` al crear `RequestOptions` | El mismo problema en `additionalInfo` de la llamada. No se llamó a la API. | Corrige el valor de esa llamada. |

## Conexión: proxy, TLS y PSR-18

Si necesitas salir por un proxy, confiar en una CA propia o ajustar el tiempo de
conexión, puedes configurarlo con las opciones del cliente. Por defecto el SDK
usa cURL.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RetryBackoff;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    retryRateLimited: true,
    retryBaseDelaySeconds: 0.5,
    retryBackoff: RetryBackoff::Exponential,
    totalTimeoutSeconds: 60.0,
    connectTimeout: 5.0,
    proxy: 'http://proxy.miempresa.local:8080',
    caInfo: '/etc/ssl/certs/ca-miempresa.pem',
));
echo count($client->getContexto()->contribuyentes ?? []) . PHP_EOL;
```

Si tu aplicación ya usa un cliente PSR-18, como Guzzle o Symfony HttpClient,
pásalo con `Transport\Psr18Transport`, que necesita el cliente y las fábricas
PSR-17 de peticiones y de flujos. Con este transporte no se aplican `timeout`,
`connectTimeout`, `proxy`, `caInfo`, `verifyPeer` ni `curlOptions`, así que
configúralos en tu cliente. Los reintentos, `totalTimeoutSeconds` (que se
comprueba antes de cada intento), la idempotencia, `additionalInfo` y las
excepciones funcionan igual.

Cuando tu cliente PSR-18 falla, el SDK decide entre `EcuafactTimeoutException` y
`EcuafactConnectionException` por el tipo de la excepción. Con Guzzle mira el
`errno` de cURL que trae `getHandlerContext()`, donde 28 es un timeout y
cualquier otro valor es un error de conexión; con Symfony HttpClient busca una
`TimeoutExceptionInterface` en la cadena de excepciones. Solo si la excepción no trae esa información, el SDK revisa si
el mensaje dice `timeout` o `timed out`. Una `RequestExceptionInterface`, que
indica que la petición no se pudo armar, sin esa información es siempre
`EcuafactConnectionException`. La excepción original queda en `getPrevious()`.

El ejemplo siguiente usa Guzzle, que instalas con
`composer require guzzlehttp/guzzle`.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\Transport\Psr18Transport;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$guzzle = new Client([
    'timeout' => 30,
    'connect_timeout' => 5,
    'proxy' => 'http://proxy.miempresa.local:8080',
]);
$fabrica = new HttpFactory(); // Fabrica PSR-17 de peticiones y de flujos.

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    transport: new Psr18Transport($guzzle, $fabrica, $fabrica),
));
echo count($client->getContexto()->contribuyentes ?? []) . PHP_EOL;
```

## Constructores de comprobantes

Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en
lugar de escribir el JSON.

Los constructores son opcionales y están en `Ecuafact\Sdk\Builders`. Solo
ensamblan la solicitud de su tipo (`FacturaRequest`, `NotaCreditoRequest`...) con los valores que les das: no calculan
totales, impuestos ni redondeos, y no completan valores por defecto. Tú
calculas los importes y la API los calcula y valida igual que si armaras el JSON
a mano.

```php
<?php
// Guarda como constructor.php y ejecuta: php constructor.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Builders\ComprobanteBuilder;
use Ecuafact\Sdk\Builders\Tarifa;
use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\Contracts\Impuesto;
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'),
));

// Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor.
$factura = ComprobanteBuilder::factura('0123456789001', '001', '001')
    ->referencias('MiERP', 'FACTURA-2026-0002')
    ->fechaEmision(new DateTimeImmutable('now', new DateTimeZone('America/Guayaquil')))
    ->comprador('07', '9999999999999', 'CONSUMIDOR FINAL')
    ->moneda('DOLAR')
    ->linea('SERV-001', 'Servicio de prueba', 1, '10.00', 0, Tarifa::iva('4', 15))
    ->totalSinImpuestos('10.00')
    ->totalDescuento('0.00')
    ->propina('0.00')
    ->importeTotal('11.50')
    ->pago('01', '11.50')
    // Los importes de la linea y de totalConImpuestos los das tu: el SDK no los calcula.
    ->configurar(function (FacturaRequest $c): void {
        $c->detalles[0]->precioTotalSinImpuesto = '10.00';
        $c->detalles[0]->impuestos[0]->baseImponible = '10.00';
        $c->detalles[0]->impuestos[0]->valor = '1.50';
        $fila = new Impuesto();
        $fila->codigo = '2';
        $fila->codigoPorcentaje = '4';
        $fila->tarifa = '15';
        $fila->baseImponible = '10.00';
        $fila->valor = '1.50';
        $c->info->totalConImpuestos = [$fila];
    });

$comprobante = $factura->construir();
echo 'importeTotal ' . $comprobante->info->importeTotal . PHP_EOL; // 11.50

$r = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0002',
    new RequestOptions(correlationId: 'pedido-2026-0458'));
echo $r->admission->estado . ' ' . $r->admission->idOperacion . ' ' . $r->correlationId . PHP_EOL;
```

Deberías ver `importeTotal 11.50` y luego
`recibido <idOperacion> pedido-2026-0458`. Si ejecutas el script otro día con la
misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`); en ese caso usa una
`Idempotency-Key` y una `referenciaExterna` nuevas.

Las seis fábricas reciben `($ruc, $estab, $ptoEmi)`.

| Tipo | Fábrica | Métodos propios |
|---|---|---|
| Factura (`01`) | `ComprobanteBuilder::factura(...)` | `fechaEmision`, `comprador`, `linea`, `detalle`, `totalSinImpuestos`, `totalDescuento`, `propina`, `moneda`, `pago`, `importeTotal`, `guiaRemision` |
| Liquidación de compra (`03`) | `ComprobanteBuilder::liquidacionCompra(...)` | `fechaEmision`, `proveedor`, `linea`, `detalle`, `totalSinImpuestos`, `totalDescuento`, `moneda`, `pago`, `importeTotal` |
| Nota de crédito (`04`) | `ComprobanteBuilder::notaCredito(...)` | `fechaEmision`, `comprador`, `documentoModificado`, `motivo`, `linea`, `detalle`, `totalSinImpuestos`, `moneda`, `totalDocumentoSustento`, `valorModificacion` |
| Nota de débito (`05`) | `ComprobanteBuilder::notaDebito(...)` | `fechaEmision`, `comprador`, `documentoModificado`, `motivo($razon, $valor)`, `iva`, `totalSinImpuestos`, `moneda`, `pago`, `valorTotal` |
| Guía de remisión (`06`) | `ComprobanteBuilder::guiaRemision(...)` | `transportista`, `traslado`, `destinatario`, `linea` |
| Retención (`07`) | `ComprobanteBuilder::retencion(...)` | `fechaEmision`, `sujetoRetenido`, `periodo`, `docSustento`, `impuestoSustento`, `lineaRetencion`, `pago` |

Estas son las firmas de los métodos más usados:

| Método | Firma |
|---|---|
| `linea` (01, 03, 04) | `linea($codigo, $descripcion, $cantidad, $precioUnitario, $descuento, Tarifa $iva, ?Tarifa $ice = null, ?string $codigoAuxiliar = null, ?array $detallesAdicionales = null)`. `$descuento` es un importe en dólares, no un porcentaje, y `$detallesAdicionales` admite hasta 3 pares `nombre => valor`. |
| `comprador` | `comprador($tipoIdentificacion, $identificacion, $razonSocial, ?string $direccion = null)`. `proveedor` (03) tiene la misma firma. |
| `pago` | `pago($formaPago, $total = null, ?int $plazo = null, ?string $unidadTiempo = null)` |
| `documentoModificado` (04, 05) | `documentoModificado($codDocModificado, $numDocModificado, $fechaEmisionDocSustento)`. El número tiene la forma `ddd-ddd-ddddddddd`. |
| `linea` (06) | `linea($codigoInterno, $descripcion, $cantidad, ?string $codigoAdicional = null)`; agrega el producto al destinatario de la guía. |
| `destinatario` (06) | `destinatario($identificacion, $razonSocial, $direccion, $motivoTraslado, ?string $codEstabDestino = null, ?string $ruta = null, ?string $docAduaneroUnico = null)`. El constructor arma un solo destinatario, así que llamarlo otra vez reemplaza sus datos y conserva las líneas. Para varios destinatarios, usa `configurar`. |
| `docSustento` (07) | `docSustento($codSustento, $codDocSustento, $numDocSustento, $fechaEmisionDocSustento, $fechaRegistroContable, $totalSinImpuestos = null, $importeTotal = null, ?string $numAutDocSustento = null, ?string $pagoLocExt = null)`. `$pagoLocExt` no tiene valor por defecto: se envía solo si lo indicas. |
| `impuestoSustento` (07) | `impuestoSustento($codImpuesto, $codigoPorcentaje, $baseImponible, $tarifa, $valorImpuesto = null)`; `$valorImpuesto` se envía solo si lo indicas. |
| `lineaRetencion` (07) | `lineaRetencion($codigo, $codigoRetencion, $baseImponible, $porcentajeRetener, $valorRetenido = null)`; `$valorRetenido` se envía solo si lo indicas. |

Todos los constructores tienen además `referencias($origen, $externa)`, `secuencial`,
`dirEstablecimiento`, `correo`, `telefono`, `infoAdicional($nombre, $valor)`,
`configurar(fn (FacturaRequest $c) => ...)` (con la clase de su tipo; asigna cualquier campo del
contrato) y `construir()`.
`fechaEmision` acepta un texto `dd/MM/yyyy` o un `DateTimeInterface`; la guía de
remisión no lo tiene y usa `traslado($dirPartida, $fechaInicio, $fechaFin)`. El
ICE de una línea va en el séptimo argumento:
`linea(..., Tarifa::iva('4', 15), Tarifa::ice('3011', 10))`. Los importes aceptan
`int`, `float` o texto decimal como `'10.00'`, que es la forma exacta.

**Lo que asignas se envía tal cual.** Todo valor que asignes (subtotal de
línea, impuestos, bases, totales, propina, moneda, pagos) se envía exactamente
como lo diste, y lo que no asignes no se envía: el constructor no completa
totales, impuestos, `propina`, `moneda`, `pagoLocExt` ni el `total` de un pago.
Los importes que das como texto decimal (`'10.00'`) conservan su precisión sin
pérdida. Como `construir()` devuelve una copia, puedes seguir usando el
constructor.

| Elemento | Detalle |
|---|---|
| Tarifa de una línea | `Tarifa::iva($codigoPorcentaje, $tarifa)` o `Tarifa::ice($codigoPorcentaje, $tarifa)` con el `codigoPorcentaje` del [catálogo](/v1/guias/catalogos) y la `tarifa` en porcentaje (`15`, no `0.15`). El SDK envía la pareja tal como la defines. |
| Importes | `int`, `float` o texto decimal. Un texto como `'10,50'` lanza `EcuafactSdkException` porque no se puede enviar sin perder precisión. |
| Validación | Los constructores no validan reglas de negocio ni calculan: solo ayudan a armar el cuerpo. Valida con `$client->validar()` o emite y lee el 422 de la API, que es la única que calcula y decide. |

## Métodos

Esta es la referencia de todos los métodos del cliente. Todos son síncronos y
aceptan como último argumento `?RequestOptions $opciones`, que se explica en
[Opciones por llamada](#opciones-por-llamada). La identificación que reciben es
siempre el valor `identificacion` del contexto, y las clases de datos están en
`Ecuafact\Sdk\Contracts`.

| Método | Endpoint | Devuelve |
|---|---|---|
| `getContexto()` | `GET /v1/contexto` | `Contexto` (ver [Contexto y consumo](#contexto-y-consumo)) |
| `emitir($comprobante, $idempotencyKey = null)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` |
| `emitirEn($identificacion, $comprobante, $idempotencyKey = null)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` |
| `validar($comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` (revisa `valido`) |
| `validarEn($identificacion, $comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` (ver [Validar sin emitir](#validar-sin-emitir)) |
| `getOperacion($idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `$idOperacion` debe ser un UUID. |
| `consultarOperacion($idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) |
| `esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Opcional; tiempos en segundos. |
| `descargarRide($identificacion, $claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) |
| `descargarXml($identificacion, $claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) |
| `getConsumo()` | `GET /v1/consumo` | `QuotaBucket` (ver [Contexto y consumo](#contexto-y-consumo)) |
| `listarOperaciones($identificacion, $desde, $hasta, $tipoDocumento, $buscar, $pagina, $tamanoPagina)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de operaciones](#listado-de-operaciones)) |
| `obtenerSalud()` | `GET /salud` | `bool`: `true` si el servicio responde. No envía API Key. Ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos). |
| `obtenerEstadoServicio()` | `GET /estado` | `EstadoServicio` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía API Key. |
| `listarCatalogos()` | `GET /v1/catalogos` | `Catalogos` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)) |
| `obtenerCatalogo($nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)) |
| `getPerfil($identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` |
| `actualizarPerfil($identificacion, PerfilEmisorUpdate $cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` |
| `actualizarLogo($identificacion, $contenido, $contentType, $nombreArchivo = 'logo')` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) |
| `consultarContribuyente($identificacion, $fusionar = true, $fuente = null)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` |
| `buscarContribuyentes($apellidos, $nombres = null, $clase = null, $max = null)` | `GET /v1/consultas/contribuyentes` | `BusquedaContribuyente[]` |
| `listarEstablecimientos($ruc, $filtro = null)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente` |
| `validarIdentificacion($numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `valido`) |
| `decodificarClaveAcceso($claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` |
| `para($identificacion)` | - (no llama a la API; no recibe `RequestOptions`) | `EcuafactContribuyente` |
| `options()` | - (no llama a la API) | `EcuafactClientOptions` |

En `emitir`, `emitirEn`, `validar` y `validarEn`, `{ruta del tipo}` es
la ruta de la tabla de [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta).
El cuerpo de esas cuatro llamadas es el de la clase del comprobante, sin ningún campo de tipo.

Ten en cuenta además estos detalles de los métodos y de sus tipos:

- `EmisionResultado` trae `admission`, `idempotencyKey` y `correlationId`
  (cabecera `X-Correlation-Id`). `admission` tiene los mismos campos que
  `Operation`, que se describen en
  [Seguimiento del resultado](#seguimiento-del-resultado). En una emisión
  aceptada, `estado` es `recibido` y `codEstado` es 1001 o 1002: con 1001,
  `claveAcceso` todavía es `null`, y con 1002 ya trae la clave de acceso. Tu
  código debe aceptar los dos valores. `urlEstado` es la URL completa del
  seguimiento.
- Si no configuras `identificacion` en las opciones, `emitir` y `validar`
  lanzan `EcuafactSdkException`. En ese caso
  usa los métodos `...En` o `para()`.
- `ArchivoComprobante` tiene `contenido` (`string` binario) y `contentType`. Las
  descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml).
- `PerfilEmisorUpdate` tiene `nombreComercial`, `direccionMatriz`, `correo`,
  `telefono`, `ciudad` y `provincia`, y las propiedades en `null` no se envían.
  El detalle está en [Perfil del emisor](/v1/guias/perfil-emisor).

## Importes exactos

En PHP un `float` es binario, y por eso `0.1 + 0.2` da `0.30000000000000004`.
Los campos de importe, cantidad, precio y tarifa de la solicitud son
`float|string|null`, y cada tipo se envía de una forma distinta.

- Un **texto** decimal con punto, como `'11.50'`, se envía como número JSON
  literal (`11.50`), sin pasar por `float`. Es la forma exacta.
- Un **float** se envía con 15 dígitos significativos, así que `0.1 + 0.2`
  viaja como `0.3`.
- Un texto con otro formato, como `'10,50'` o `'1e3'`, se rechaza con
  `EcuafactSdkException` antes de llamar a la API.
- Las propiedades en `null` no se envían.

`Pago::$plazo` también acepta `float|string`. Calcula con `bcmath`, si la
tienes, o en centavos enteros, y asigna el resultado como texto.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\Support\Hydrator;

/** @var FacturaRequest $comprobante */
$comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));

// Calcula en centavos enteros y asigna el resultado como texto con 2 decimales.
$baseCentavos = 1000;                                     // 10.00
$ivaCentavos = intdiv($baseCentavos * 15 + 50, 100);      // 150 = 1.50
$comprobante->info->totalSinImpuestos = number_format($baseCentavos / 100, 2, '.', '');               // '10.00'
$comprobante->info->importeTotal = number_format(($baseCentavos + $ivaCentavos) / 100, 2, '.', '');   // '11.50'

echo $comprobante->info->importeTotal . PHP_EOL; // 11.50
```

Si tu código lee esas propiedades con un tipo `float` estricto, conviértelas con
`(float)`. En las respuestas, `Comprobante::$total` se lee como `float`. Las reglas de cálculo de cada comprobante están en
[Factura](/v1/guias/emision-01).

## Varios contribuyentes

Si no configuras `identificacion` en las opciones, usa los métodos `...En` o una
vista por contribuyente. La vista repite la identificación por ti en cada
método.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$matriz = $client->para('0123456789001');

$perfil = $matriz->getPerfil();
echo "{$perfil->razonSocial} ({$perfil->identificacion})" . PHP_EOL;
```

La vista `EcuafactContribuyente` tiene estos métodos, y todos aceptan
`RequestOptions` al final. Además, `identificacion()` devuelve la
identificación fija de la vista.

| Método | Equivale a |
|---|---|
| `emitir($comprobante, $idempotencyKey = null)` | `$client->emitirEn($identificacion, $comprobante, $idempotencyKey)` |
| `validar($comprobante)` | `$client->validarEn($identificacion, $comprobante)` |
| `descargarRide($claveAcceso)` | `$client->descargarRide($identificacion, $claveAcceso)` |
| `descargarXml($claveAcceso)` | `$client->descargarXml($identificacion, $claveAcceso)` |
| `getPerfil()` | `$client->getPerfil($identificacion)` |
| `actualizarPerfil($cambios)` | `$client->actualizarPerfil($identificacion, $cambios)` |
| `actualizarLogo($contenido, $contentType, $nombreArchivo = 'logo')` | `$client->actualizarLogo($identificacion, ...)` |
| `esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0)` | `$client->esperarResultado(...)` |
| `getConsumo()` | `$client->getConsumo()` (el cupo es de la API Key, no del contribuyente) |

## Logo del perfil

Con `actualizarLogo` puedes subir el logo que aparece en el RIDE de tu contribuyente sin
armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. La API acepta PNG o JPEG de hasta 512 KB;
`$contenido` son los bytes del archivo y `$contentType` es `image/png` o
`image/jpeg`. Un contenido vacío o un `contentType` con caracteres inválidos
lanza `EcuafactSdkException` sin llamar a la API. La subida no se reintenta
automáticamente.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$perfil = $client->actualizarLogo('0123456789001', file_get_contents('logo.png'), 'image/png', 'logo.png');
echo "Logo actualizado para {$perfil->razonSocial}: {$perfil->logo}" . PHP_EOL;
```

Las reglas del archivo y los errores posibles están en
[Perfil del emisor](/v1/guias/perfil-emisor).

## Contexto y consumo

Antes de emitir puedes preguntar con qué contribuyentes puedes trabajar y
cuántos documentos te quedan. `getContexto()` lee el
[contexto](/v1/guias/consulta-contexto) de tu API Key y `getConsumo()` lee tu
[cupo](/v1/guias/consumo). Ninguna de las dos consume cupo.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$contexto = $client->getContexto();
foreach ($contexto->contribuyentes ?? [] as $c) {
    echo $c->identificacion . ' ' . var_export($c->puedeEmitir, true) . ' ' . implode(',', $c->tiposComprobante ?? []) . PHP_EOL;
}

$cupo = $client->getConsumo();
echo "Disponibles {$cupo->disponibles} de {$cupo->limiteDocumentos}; vigente hasta {$cupo->vigenteHasta}" . PHP_EOL;
```

`getContexto()` devuelve un `Contexto`. La `identificacion` de cada
contribuyente es la completa que devuelve el contexto, y es la que va en las
rutas y en `infoTributaria.ruc`. Todas las propiedades pueden ser `null`.

| Propiedad | Tipo | Descripción |
|---|---|---|
| `idCliente` | `?string` | Identificador de tu integración. |
| `nombre` | `?string` | Nombre de tu integración. |
| `contribuyentes` | `?Contribuyente[]` | Contribuyentes habilitados para tu API Key en el ambiente de la URL. |
| `Contribuyente::$identificacion` | `?string` | Identificación completa del contribuyente; úsala en las rutas. |
| `Contribuyente::$puedeEmitir` | `?bool` | `true` si tu API Key puede emitir para este contribuyente. |
| `Contribuyente::$puedeRecibir` | `?bool` | `true` si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. |
| `Contribuyente::$tiposComprobante` | `?string[]` | Códigos de los tipos de comprobante habilitados (`01`, `03`, `04`, `05`, `06`, `07`). |
| `Contribuyente::$marcaBlanca` | `?bool` | `true` si el contribuyente es un emisor de marca blanca: sus comprobantes no tienen RIDE, y el XML se descarga igual. |

`getConsumo()` devuelve un `QuotaBucket`. Cada comprobante que el SRI autoriza
o rechaza consume un documento de tu cupo, y uno cancelado no lo consume.

| Propiedad | Tipo | Descripción |
|---|---|---|
| `limiteDocumentos` | `?int` | Documentos contratados en total: la suma de tus paquetes vigentes. |
| `reservados` | `?int` | Documentos de emisiones recibidas que aún no tienen resultado final. |
| `consumidos` | `?int` | Documentos descontados por emisiones con resultado final. |
| `disponibles` | `?int` | Documentos que aún puedes emitir con tus paquetes vigentes. |
| `vigenteHasta` | `?string` | Fecha y hora (ISO 8601, UTC) en que vence el próximo paquete con saldo. |
| `limiteExtra`, `reservadosExtra`, `consumidosExtra`, `disponiblesExtra` | `?int` | Se mantienen por compatibilidad y valen 0: todo el saldo está en las cuatro propiedades anteriores. |

El significado de cada valor, con un ejemplo numérico, está en
[Consumo y cuotas](/v1/guias/consumo#respuesta).

## Listado de operaciones

`listarOperaciones` devuelve una página de los comprobantes de un contribuyente
(`GET /v1/operaciones`) y no consume cupo. La `identificacion` es obligatoria; los
demás filtros son opcionales: `desde` y `hasta` en formato `yyyy-MM-dd`,
`tipoDocumento` (el código o el nombre del tipo), `buscar` (número, clave de
acceso, contraparte o referencia), `pagina` desde 1 y `tamanoPagina` de 1 a 100.
Si un filtro no tiene el formato esperado, el SDK lanza `EcuafactSdkException`
sin llamar a la API.

```php
$pagina = 1;
do {
    $resultado = $client->listarOperaciones(
        identificacion: '0123456789001',
        desde: '2026-11-01',
        hasta: '2026-11-30',
        pagina: $pagina,
        tamanoPagina: 50,
    );
    foreach ($resultado->comprobantes as $fila) {
        echo $fila->numeroDocumento . ' ' . $fila->estado . ' ' . $fila->codEstado . ' ' . $fila->total . PHP_EOL;
    }
    $pagina++;
} while ($resultado->hayMas);
```

La respuesta es un `PaginaComprobantes` con `comprobantes`, `pagina`,
`tamanoPagina` y `hayMas`; mientras `hayMas` sea `true`, pide la página siguiente.
Cada fila es un `Comprobante` con `claveAcceso`, `numeroDocumento`,
`tipoDocumento`, `fechaEmision`, `identificacionContraparte`,
`razonSocialContraparte`, `total`, `estado`, `codEstado`, `msgError`, `errores` y
`fhAutorizacion`; `estadoOperacion()` y `tipoComprobante()` devuelven los valores
tipados. La vista `$client->para($identificacion)` ofrece el mismo método con la
identificación fija.

## Consultas SRI

Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$validacion = $client->validarIdentificacion('0123456789001');
$contribuyente = $client->consultarContribuyente('0123456789001');
$encontrados = $client->buscarContribuyentes('PEREZ LOPEZ', 'JUAN', 'PersonaNatural', 10);
$establecimientos = $client->listarEstablecimientos('0123456789001', 'SoloActivos');
$clave = $client->decodificarClaveAcceso('0710202601012345678900110010010000001231234567811');
echo var_export($validacion->valido, true) . ' ' . count($encontrados) . ' ' . $clave->rucEmisor . PHP_EOL;
```

Si un argumento obligatorio, como la identificación, los apellidos, el RUC, el
número o la clave de acceso, llega vacío, el SDK lanza `EcuafactSdkException`
sin llamar a la API. Los parámetros y las respuestas de cada consulta están en
[Contribuyente por identificación](/v1/guias/consulta-contribuyente),
[Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre),
[Establecimientos de un RUC](/v1/guias/consulta-establecimientos),
[Validar identificación](/v1/guias/consulta-identificacion) y
[Decodificar clave de acceso](/v1/guias/consulta-clave-acceso).

## Estado del servicio y catálogos

Puedes consultar el estado público del servicio y los catálogos del SRI sin
armar ninguna petición. `obtenerEstadoServicio()` lee el
[estado del servicio](/v1/guias/estado-del-servicio) y no envía API Key ni consume
cupo, así que sirve para comprobar la disponibilidad antes de configurar una
credencial o desde tus propias alertas. `listarCatalogos()` y
`obtenerCatalogo($nombre)` leen los [catálogos del SRI](/v1/guias/catalogos) con
la API Key del cliente. Los catálogos cambian pocas veces al año, así que puedes
guardar sus respuestas en caché por una hora.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\EcuafactNotFoundException;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$estado = $client->obtenerEstadoServicio();
echo $estado->estado . ' ' . ($estado->disponibilidad90Dias ?? 'sin datos') . PHP_EOL;
foreach ($estado->componentes ?? [] as $componente) {
    echo $componente->nombre . ' ' . $componente->estado . PHP_EOL;
}
foreach ($estado->incidentes ?? [] as $incidente) {
    echo $incidente->inicio . ' ' . $incidente->impacto . ' ' . $incidente->titulo . ' ' . ($incidente->fin ?? 'abierto') . PHP_EOL;
}

foreach ($client->listarCatalogos()->catalogos ?? [] as $resumen) {
    echo $resumen->nombre . ': ' . $resumen->descripcion . PHP_EOL;
}

try {
    $tarifas = $client->obtenerCatalogo('tarifas-iva');
    foreach ($tarifas->items ?? [] as $fila) {
        echo $fila->codigo . ' ' . $fila->descripcion . ' ' . ($fila->valor ?? '') . PHP_EOL;
    }
} catch (EcuafactNotFoundException) {
    echo 'Ese catálogo no existe' . PHP_EOL;
}
```

Si el catálogo `tarifas-iva` existe, el script imprime una línea por cada
código de IVA con su tarifa. Con una clave que no está en el índice, la API
responde 404 con el `codEstado` 3013 (`no_encontrado`) y el SDK lanza
`EcuafactNotFoundException`. Los demás errores siguen la jerarquía de
[Errores](#errores). Un `nombre` vacío lanza `EcuafactSdkException` sin llamar a
la API.

### Estado del servicio

`obtenerEstadoServicio()` devuelve un `EstadoServicio` con los mismos campos que
la [respuesta de la consulta](/v1/guias/estado-del-servicio#respuesta). Todas las
propiedades pueden ser `null`.

| Propiedad | Tipo | Descripción |
|---|---|---|
| `estado` | `?string` | Estado general: `operativo`, `degradado`, `caido` o `sin_datos`. |
| `medidoEn` | `?string` | Momento de la última medición (ISO 8601, UTC). `null` si todavía no hay mediciones. |
| `componentes` | `?ComponenteEstado[]` | Componentes monitoreados. |
| `disponibilidad90Dias` | `float\|string\|null` | Porcentaje de minutos sin caída en los últimos 90 días. `null` si aún no hay muestras. |
| `incidentes` | `?IncidentePublico[]` | Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo. |

| Propiedad de `ComponenteEstado` | Tipo | Descripción |
|---|---|---|
| `nombre` | `?string` | Nombre del componente. |
| `estado` | `?string` | `operativo`, `degradado`, `caido` o `sin_datos`. |

| Propiedad de `IncidentePublico` | Tipo | Descripción |
|---|---|---|
| `inicio` | `?string` | Inicio del incidente (ISO 8601, UTC). |
| `fin` | `?string` | Fin del incidente. `null` mientras sigue abierto. |
| `impacto` | `?string` | `degradado` o `caido`. |
| `titulo` | `?string` | Título breve. |
| `detalle` | `?string` | Qué significó para tus integraciones. `null` si no hay detalle. |

Qué hacer ante cada `estado` se explica en
[Valores de estado](/v1/guias/estado-del-servicio#valores-de-estado).

Para comprobar solo que el servicio responde, `obtenerSalud()` llama a
`GET /salud`, que no requiere API Key, y devuelve `true`; si la respuesta no es
2xx, lanza la excepción correspondiente.

### Catálogos

`listarCatalogos()` devuelve un `Catalogos` y `obtenerCatalogo($nombre)`, un
`CatalogoDetalle`. El `nombre` es la clave que devuelve el índice, como
`tarifas-iva`; las claves disponibles están en
[Catálogos disponibles](/v1/guias/catalogos#catalogos-disponibles).

| Propiedad de `Catalogos` | Tipo | Descripción |
|---|---|---|
| `catalogos` | `?CatalogoResumen[]` | Catálogos disponibles, en el orden de la ficha técnica del SRI. |

| Propiedad de `CatalogoResumen` | Tipo | Descripción |
|---|---|---|
| `nombre` | `?string` | Clave del catálogo; es el valor que recibe `obtenerCatalogo`. |
| `descripcion` | `?string` | Descripción breve de lo que contiene. |

| Propiedad de `CatalogoDetalle` | Tipo | Descripción |
|---|---|---|
| `nombre` | `?string` | Clave del catálogo. |
| `descripcion` | `?string` | Descripción breve del catálogo. |
| `fuente` | `?string` | Tabla o anexo de la ficha técnica del SRI de donde proviene. |
| `items` | `?CatalogoItem[]` | Filas del catálogo. |

| Propiedad de `CatalogoItem` | Tipo | Descripción |
|---|---|---|
| `codigo` | `?string` | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. |
| `descripcion` | `?string` | Descripción del código. |
| `valor` | `float\|string\|null` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. `null` si el catálogo no lo tiene. |
| `vigenteDesde` | `?string` | Primer día de vigencia (`yyyy-MM-dd`). `null` si la fila no está acotada por el inicio. |
| `vigenteHasta` | `?string` | Último día de vigencia (`yyyy-MM-dd`). `null` si sigue vigente. |
| `atributos` | `?array` | Atributos propios del catálogo. `null` si no hay. |

## Siguientes pasos

- [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`.
- [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle.
- [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo.

