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

# SDK Java

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

Si desarrollas en Java, puedes integrarte con nuestros servicios de facturación
usando nuestro SDK para Java. En lugar de armar cada petición HTTP, llamas a
métodos como `emitirEn` o `descargarRide`, que reciben y devuelven objetos
tipados, en versión síncrona o con `CompletableFuture`. 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.

La guía sigue el orden de una integración. Primero instalas el paquete,
configuras el cliente, emites tu primera factura y haces el seguimiento hasta el
resultado del SRI; 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. La referencia completa está en
[Métodos](#metodos). 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 Java 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-java.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 la dependencia com.ecuafact:sdk:1.0.1 en Maven o Gradle. 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 Java 17 o superior. 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 |
|---|---|
| Coordenadas Maven | `com.ecuafact:sdk` |
| Versión | `1.0.1` |
| Java | 17 o superior |
| Dependencias | Jackson Databind `2.18.2`. Es una dependencia transitiva, así que no necesitas declararla. |
| Cliente | Síncrono, sobre `java.net.http.HttpClient`, con variantes `*Async` que devuelven `CompletableFuture`. Seguro para uso concurrente. |

## Requisitos

- [ ] El JDK 17 o superior, que compruebas con `java -version`, y Maven o
      Gradle.
- [ ] 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`).

## Instalación

El paquete se publica en
[Maven Central](https://central.sonatype.com/artifact/com.ecuafact/sdk), así que
Maven y Gradle lo resuelven sin configurar repositorios adicionales.

Con Maven, agrega la dependencia a tu `pom.xml`:

```xml
<dependency>
  <groupId>com.ecuafact</groupId>
  <artifactId>sdk</artifactId>
  <version>1.0.1</version>
</dependency>
```

Con Gradle y el Kotlin DSL, agrégala en `build.gradle.kts`:

```kotlin
dependencies {
    implementation("com.ecuafact:sdk:1.0.1")
}
```

Para comprobar la instalación, ejecuta `mvn dependency:tree` o
`gradle dependencies`. Debe aparecer `com.ecuafact:sdk:jar:1.0.1` con
`jackson-databind` debajo.

## Configuración

Crea el cliente **una vez** y reutilízalo, porque sirve para todos los
[contribuyentes](/v1/guias/glosario) de tu API Key. Las opciones se encadenan
sobre `EcuafactClientOptions.create(baseAddress, apiKey)`.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import java.time.Duration;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .identificacion("0123456789001")          // opcional: contribuyente por defecto
        .timeout(Duration.ofSeconds(60)));     // opcional
System.out.println(client);                    // la API Key aparece como ***
```

Si pasas `null` como `apiKey`, el SDK lee la variable de entorno `ECUAFACT_API_KEY`, y si pasas `null` como
`baseAddress`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta
`new EcuafactClient()` o `EcuafactClientOptions.fromEnvironment()`. Los nombres
están en las constantes `EcuafactClientOptions.ENV_API_KEY` y
`EcuafactClientOptions.ENV_BASE_URL`.

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` | Primer argumento de `create`. URL `https` absoluta, sin usuario, sin consulta, sin fragmento y sin `/v1`. El SDK rechaza `http`. |
| `apiKey` | `String` | `ECUAFACT_API_KEY` | Segundo argumento de `create`. Tu API Key; viaja en la cabecera `X-Api-Key`. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en `toString()`. |
| `identificacion` | `String` | `null` | Contribuyente por defecto para `emitir` y `validar` sin identificación. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). |
| `validarAntesDeEmitir(boolean)` | `boolean` | `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` | `Duration` | `PT30S` (30 s) | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta. Mayor que cero. Por llamada lo cambias con `RequestOptions.timeout(Duration)`. |
| `maxResponseBytes` | `Long` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un valor positivo lo aplica a todas las llamadas, incluidas las descargas; `null` o `0` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `limite()` y `bytesLeidos()`. |
| `userAgent` | `String` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. No puede estar vacío ni tener caracteres de control. |
| `additionalInfo` | `String` | `null` | Texto tuyo que viaja en la cabecera `X-Additional-Info` en cada solicitud a la API. Si es `null` o vacío, no se envía. Admite solo ASCII imprimible (0x20 a 0x7E), sin espacios al inicio o al final y hasta 256 caracteres; el detalle está en [Información adicional](#informacion-adicional). |
| `retryTransientFailures` | `boolean` | `true` | Reintenta fallos transitorios (ver [Idempotencia y reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. |
| `maxAttempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. |
| `respectRetryAfter` | `boolean` | `true` | Espera lo que indique la cabecera `Retry-After` antes de reintentar. |
| `maxRetryDelay` | `Duration` | `PT60S` (60 s) | Espera máxima entre reintentos. Con `Duration.ZERO` no hay tope. |
| `retryRateLimited` | `boolean` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `maxRetryDelay`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. Un 429 sin el `codEstado` 5005 tampoco se reintenta. |
| `retryableStatusCodes` | `Set<Integer>` | `408`, `425`, `500`, `502`, `503`, `504` | Estados HTTP que se reintentan (valores de 100 a 599). El 429 no va aquí: lo controla `retryRateLimited`. Los valores por defecto están en `EcuafactClientOptions.DEFAULT_RETRYABLE_STATUS_CODES`. |
| `retryBaseDelay` | `Duration` | `PT0.2S` (200 ms) | Espera base entre reintentos. No negativa. |
| `retryBackoff` | `RetryBackoff` | `RetryBackoff.LINEAR` | `LINEAR`: base x intento (200, 400, 600 ms). `EXPONENTIAL`: base x 2^(intento-1) (200, 400, 800 ms). |
| `retryJitter` | `Duration` | `PT0.05S` (50 ms) | Variación aleatoria máxima que se suma a cada espera (en `LINEAR`, multiplicada por el número de intento). No negativa. |
| `totalTimeout` | `Duration` | `null` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas. Ver [Idempotencia y reintentos](#idempotencia-y-reintentos). |
| `httpClient` | `HttpClient` | `null` | Tu propio `java.net.http.HttpClient`. Si lo pasas, `proxy`, `sslContext`, `executor` y `connectTimeout` se ignoran: configúralos en ese cliente. |
| `proxy` | `ProxySelector` | `null` | Proxy, por ejemplo `ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080))`. |
| `sslContext` | `SSLContext` | `null` (el del JDK) | Contexto TLS propio: CA corporativa o certificado de cliente. |
| `executor` | `Executor` | `null` | Executor del `HttpClient` y de las esperas entre reintentos. Sin valor, el JDK usa el suyo y las esperas usan `ForkJoinPool.commonPool()`. |
| `connectTimeout` | `Duration` | `PT10S` (10 s) | Tiempo máximo para abrir la conexión. Mayor que cero. |

```java
EcuafactClientOptions.create(baseAddress, apiKey).maxResponseBytes(64L * 1024 * 1024); // null desactiva el tope
```

Cada método de opción valida su valor y lanza
`EcuafactConfigurationException` si no es válido, por ejemplo con
`maxAttempts(0)`, con un tiempo negativo o con un `additionalInfo` con tildes.
Al crear el cliente se validan además la URL y la API Key. Si faltan, si la URL
no es una URL `https`, si trae usuario, consulta o fragmento, o si termina en `/v1`, o si la API Key tiene
espacios, el constructor lanza la misma excepción antes de hacer cualquier
llamada. El mensaje nunca incluye la API Key ni el valor de `additionalInfo`.

## Quickstart: de la API Key al RIDE

Este programa 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` en la carpeta desde la que ejecutas el
programa, que es la raíz de tu proyecto Maven. 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 la
plataforma asigna el siguiente
[secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El programa
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 cuerpo no lleva `infoTributaria.tipoDocumento`: el tipo lo da la clase que usas, en este caso `FacturaRequest`, como se explica en [Ruta de emisión por tipo de comprobante](#ruta-de-emision-por-tipo-de-comprobante).

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

Guarda el código siguiente como `src/main/java/Quickstart.java` en un proyecto
Maven que tenga la dependencia de [Instalación](#instalacion). Los modelos del SDK son `record`
inmutables, por eso el programa ajusta el JSON con Jackson antes de convertirlo
en `FacturaRequest`. El `ObjectMapper` usa `USE_BIG_DECIMAL_FOR_FLOATS`
para que los importes no pasen por `double`.

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). Ese flujo evita que tu proceso se quede
esperando.

```java
import com.ecuafact.sdk.EcuafactApiException;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import com.ecuafact.sdk.contracts.Contexto;
import com.ecuafact.sdk.contracts.Contribuyente;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.ecuafact.sdk.contracts.Operation;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;

public class Quickstart {
    public static void main(String[] args) throws Exception {
        EcuafactClient client = new EcuafactClient(
            EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
        ObjectMapper mapper = new ObjectMapper().enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS);
        try {
            // 1. Contexto: que contribuyentes puede usar tu API Key.
            Contexto contexto = client.getContexto();
            Contribuyente emisor = contexto.contribuyentes().stream()
                .filter(Contribuyente::puedeEmitir).findFirst().orElseThrow();
            System.out.println("Emisor " + emisor.identificacion());

            // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador).
            ObjectNode json = (ObjectNode) mapper.readTree(Files.readString(Path.of("comprobante.json")));
            ((ObjectNode) json.get("infoTributaria")).put("ruc", emisor.identificacion());
            ((ObjectNode) json.get("info")).put("fechaEmision",
                LocalDate.now(ZoneOffset.ofHours(-5)).format(DateTimeFormatter.ofPattern("dd/MM/yyyy")));
            FacturaRequest comprobante = mapper.treeToValue(json, FacturaRequest.class);

            // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key.
            EmisionResultado emision = client.emitirEn(emisor.identificacion(), comprobante, "FACTURA-2026-0001");
            String idOperacion = emision.admission().idOperacion();
            // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos.
            System.out.println("estado " + emision.admission().estado() + " codEstado " + emision.admission().codEstado()
                + " idOperacion " + idOperacion);

            // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min).
            Operation operacion = client.esperarResultado(idOperacion);
            System.out.println("estado " + operacion.estado() + " codEstado " + operacion.codEstado());
            operacion.errores().forEach(detalle -> System.out.println(" - " + detalle));

            // 5. RIDE: solo existe cuando el comprobante esta autorizado.
            if (operacion.esAutorizado()) {
                ArchivoComprobante ride = client.descargarRide(emisor.identificacion(), operacion.claveAcceso());
                Files.write(Path.of("ride.pdf"), ride.contenido());
                System.out.println("RIDE guardado en ride.pdf; claveAcceso " + operacion.claveAcceso());
            } else if (!operacion.esFinal()) {
                System.out.println("Aun sin resultado: consulta mas tarde o espera el webhook.");
            }
        } catch (EcuafactApiException error) {
            System.out.println("HTTP " + error.estadoHttp() + " codEstado " + error.codEstado() + ": " + error.msgError());
            error.errores().forEach(detalle -> System.out.println(" - " + detalle));
            System.out.println("X-Correlation-Id: " + error.correlationId());
        }
    }
}
```

### Paso 3. Ejecuta y verifica

Con Maven, ejecuta la clase con el plugin `exec`; también puedes ejecutarla desde
tu IDE.

```bash
mvn -q compile exec:java -Dexec.mainClass=Quickstart
```

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) real 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`, `rechazo_configuracion`, `error` o `cancelado` con otro `codEstado` | La operación terminó sin autorización. | Sigue la fila de su `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). |
| `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). |
| `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. |
| `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 programa 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.

`EmisionResultado` es un `record` con estos métodos:

| Método | Tipo | Descripción |
|---|---|---|
| `admission()` | `Admission` | La respuesta de la emisión, con los mismos campos que `Operation`, que se describen en [Seguimiento y resultado](#seguimiento-y-resultado). En una emisión aceptada, `estado()` es `recibido`: aceptamos el comprobante, que todavía no está autorizado. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde igual. |
| `admission().codEstado()` | `Integer` | 1001 si todavía no hay clave de acceso, con `claveAcceso()` en `null`, o 1002 si ya la trae. Tu código debe aceptar los dos valores. |
| `admission().idOperacion()` | `String` | UUID de la operación. Guárdalo: lo necesitas para el seguimiento. |
| `admission().urlEstado()` | `String` | URL completa del seguimiento de esta operación. |
| `idempotencyKey()` | `String` | La `Idempotency-Key` usada (la tuya o la que generó el SDK). |
| `correlationId()` | `String` | Cabecera `X-Correlation-Id` de la respuesta. |

## Ruta de emisión por tipo de comprobante

Cada tipo de comprobante tiene su propia clase de solicitud, igual que tiene su propio endpoint en la API. El SDK
elige la ruta por la clase del objeto que pasas a `emitir`, `emitirEn`, `validar` y `validarEn`, así que no
indicas el tipo en ningún otro lugar y el cuerpo de la solicitud no incluye `tipoDocumento`. Las seis clases están en
`com.ecuafact.sdk.contracts` y comparten la interfaz `SolicitudComprobante`, que solo agrupa los seis tipos para que el
compilador rechace cualquier otro objeto.

| Código | Comprobante | Clase | Cabecera y líneas | Ruta de emisión |
|---|---|---|---|---|
| `01` | Factura | `FacturaRequest` | `InfoFactura`, `DetalleCompraVenta` | `POST /v1/contribuyentes/{identificacion}/facturas` |
| `03` | Liquidación de compra | `LiquidacionCompraRequest` | `InfoLiquidacionCompra`, `DetalleCompraVenta` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` |
| `04` | Nota de crédito | `NotaCreditoRequest` | `InfoNotaCredito`, `DetalleNotaCredito` | `POST /v1/contribuyentes/{identificacion}/notas-credito` |
| `05` | Nota de débito | `NotaDebitoRequest` | `InfoNotaDebito`, `Motivo` | `POST /v1/contribuyentes/{identificacion}/notas-debito` |
| `06` | Guía de remisión | `GuiaRemisionRequest` | `InfoGuiaRemision`, `Destinatario`, `DetalleGuia` | `POST /v1/contribuyentes/{identificacion}/guias-remision` |
| `07` | Comprobante de retención | `RetencionRequest` | `InfoComprobanteRetencion`, `DocsSustento`, `RetencionLinea`, `ImpuestoDocSustento` | `POST /v1/contribuyentes/{identificacion}/retenciones` |

```java
FacturaRequest factura = ...;
EmisionResultado emision = client.emitirEn(identificacion, factura, "FACTURA-2026-0001"); // POST .../facturas
ValidacionResultado validacion = client.validarEn(identificacion, factura);                 // POST .../facturas/validar
```

Todas las clases comparten `InfoTributaria`, `Impuesto`, `Pago` y `CampoAdicional`. Cada clase tiene exactamente las
propiedades de su esquema en el contrato, con los mismos nombres, tipos y nulabilidad; los campos que el contrato
marca como obligatorios se listan en el Javadoc de cada clase. La validación usa la misma ruta del tipo con
`/validar` al final.

## 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 está bien armado con
`validarEn(identificacion, comprobante)`, o con `validar(comprobante)` si
configuraste la identificación por defecto. El método recibe el mismo
request que usarías para emitir, elige la ruta con
la clase del comprobante y agrega `/validar`, y aplica las mismas reglas,
pero no emite nada, no consume cupo y no necesita `Idempotency-Key`. Te sirve
sobre todo cuando generas comprobantes de forma automática: validas el lote,
corriges lo que falle y emites después solo lo que pasó.

```java
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.ValidacionResultado;

// Dentro de: public static void main(String[] args) throws Exception
ValidacionResultado validacion = client.validarEn("0123456789001", comprobante);
if (validacion.valido()) {
    EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
    System.out.println("Emitido: " + resultado.admission().idOperacion());
} else {
    System.out.println("Comprobante con errores (codEstado " + validacion.codEstado() + "):");
    validacion.errores().forEach(error -> System.out.println("- " + error));
}
```

Cuando el comprobante cumple todas las reglas, `valido()` es `true`. Cuando no
las cumple, la API responde lo mismo que respondería al emitirlo, un 422 con el
`codEstado` 3002 (`comprobante_invalido`), y el SDK no lanza una excepción: te devuelve `valido()` en `false`,
con el código y el problema en `errores()`, para que decidas qué hacer con ese
comprobante. Cualquier otro error lanza la misma excepción que en el resto de
llamadas, descrita en [Errores](#errores); por ejemplo, si el contribuyente, su
RUC 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 un fallo transitorio igual que hace con las consultas.

Un resultado válido significa que la emisión no tendrá errores de validación con
ese mismo contenido, pero al emitir todavía pueden aparecer otras respuestas,
como el cupo agotado o un comprobante duplicado. El detalle de las reglas está en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir) de la guía de emisión.

### Validar antes de cada emisión

Si quieres que cada emisión pase primero por `/validar`, activa
`EcuafactClientOptions.validarAntesDeEmitir(true)`, o
`RequestOptions.create().validarAntes(true)` para una sola llamada (la opción de
la llamada reemplaza a la del cliente). Con la opción activa, `emitir` y
`emitirEn` (y sus variantes asíncronas) 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.

```java
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .validarAntesDeEmitir(true));
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
resultado.advertencias().forEach(aviso -> System.out.println("Aviso: " + aviso));
```

`ValidacionResultado` es un `record` con estos métodos:

| Método | Tipo | Descripción |
|---|---|---|
| `valido()` | `boolean` | `true` si el comprobante cumple todas las reglas de la emisión. |
| `codEstado()` | `Integer` | `null` si es válido, o 3002 (`CodEstado.COMPROBANTE_INVALIDO`) si no lo es. |
| `msgError()` | `String` | Descripción general del código; `null` si es válido. |
| `errores()` | `List<String>` | Vacía si es válido; si no, el problema encontrado con la ruta del campo, por ejemplo `$.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa.` |
| `advertencias()` | `List<String>` | Avisos que la API devuelve junto al resultado (por ejemplo, que ignora la firma de un XML que la trae); vacía si no hay. Un aviso no impide emitir. |

## Seguimiento y resultado

Después de emitir tienes un `idOperacion`, y con él consultas la operación
hasta que el SRI responde. Puedes hacerlo de tres formas.

| Forma | Cuándo usarla |
|---|---|
| `getOperacion(idOperacion)` (o su alias `consultarOperacion`) | Haces una consulta puntual, por ejemplo desde un proceso programado que revisa las operaciones pendientes. |
| `esperarResultado(idOperacion)` / `esperarResultado(idOperacion, intervalo, maximo)` | Necesitas el resultado en el mismo proceso, como en scripts, pruebas o procesos por lotes. Por defecto consulta cada 5 s durante 120 s como máximo. |
| [Webhooks](#webhooks) | En producción, recibes el resultado sin consultar en bucle. |

`esperarResultado` se detiene en cuanto `esFinal()` es `true` o al agotar
`maximo`, y devuelve la **última** lectura, así que revisa `esFinal()` antes de
usarla.
`intervalo` debe ser mayor que cero y `maximo` no puede ser negativo; si no,
lanza `EcuafactSdkException`. Si interrumpes el hilo durante la espera, también
lanza `EcuafactSdkException`. `getOperacion`, `consultarOperacion` y
`esperarResultado` exigen que `idOperacion` sea un UUID, con o sin guiones; si
no lo es, lanzan `EcuafactSdkException` sin llamar a la API.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.EstadoOperacion;
import com.ecuafact.sdk.contracts.Operation;
import java.time.Duration;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

// Consulta cada 10 s durante 5 minutos como maximo.
Operation operacion = client.esperarResultado(
    "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", Duration.ofSeconds(10), Duration.ofMinutes(5));

String accion = switch (operacion.estadoOperacion()) {
    case AUTORIZADO -> "Descarga el RIDE con la claveAcceso " + operacion.claveAcceso();
    case RECIBIDO, DESCONOCIDO -> "Aun sin resultado: consulta mas tarde o espera el webhook";
    default -> "Terminada sin autorizacion: codEstado " + operacion.codEstado() + " " + operacion.msgError()
        + " " + String.join(" | ", operacion.errores());
};
System.out.println(accion);
```

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

`Operation` es un `record` con los campos de
[Seguimiento de una operación](/v1/guias/consulta-operacion).

| Método | Tipo | Descripción |
|---|---|---|
| `estado()` | `String` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. |
| `codEstado()` | `Integer` | 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()` | `List<String>` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Nunca es `null` y está vacía si no hay detalle. |
| `idOperacion()` | `String` | El identificador que consultaste. |
| `urlEstado()` | `String` | URL completa del seguimiento. |
| `ambiente()` | `Integer` | `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()`. |

### Estados tipados

`Operation`, `Admission` y `Comprobante` conservan los campos de la API (`estado()`,
`codEstado()`, `tipoDocumento()`) y agregan métodos tipados. Un valor nuevo
de la API no rompe tu código, porque el estado se lee como `DESCONOCIDO` y el
tipo de comprobante como `null`, mientras el texto original sigue en el campo
`String`.

| Método | Tipo | Valores |
|---|---|---|
| `Operation.estadoOperacion()`, `Comprobante.estadoOperacion()` | `EstadoOperacion` | `RECIBIDO`, `AUTORIZADO`, `RECHAZADO`, `RECHAZO_CONFIGURACION`, `ERROR`, `CANCELADO`, `DESCONOCIDO` |
| `Operation.tipoComprobante()`, `Comprobante.tipoComprobante()`, `TipoComprobante.desde(tipoDocumento)` | `TipoComprobante` | `FACTURA` (`01`), `LIQUIDACION_COMPRA` (`03`), `NOTA_CREDITO` (`04`), `NOTA_DEBITO` (`05`), `GUIA_REMISION` (`06`), `RETENCION` (`07`); `null` si el código no se conoce |
| `Operation.esFinal()` | `boolean` | `true` si `estado` es cualquier valor distinto de `recibido`. |
| `Operation.esAutorizado()` | `boolean` | `true` si `estado` es `autorizado`. |
| `WebhookEvent.eventType()` | `TipoEventoWebhook` | `DOCUMENTO_AUTORIZADO`, `DOCUMENTO_RECHAZADO`, `DOCUMENTO_FALLIDO`, `OPERACION_REQUIERE_ATENCION`, `DESCONOCIDO` |

`EstadoOperacion` y `TipoComprobante` están en
`com.ecuafact.sdk.contracts`; `TipoEventoWebhook`, en `com.ecuafact.sdk`. Cada
uno tiene `desde(String)` y `valor()` (`codigo()` en `TipoComprobante`).

Los valores de `codEstado` están como constantes `int` en
`com.ecuafact.sdk.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.

## 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`) o el cuerpo no es un objeto JSON,
lanza `EcuafactWebhookException`. `WebhookSignature.construirEvento(...)` hace
lo mismo.

| Sobrecarga | Uso |
|---|---|
| `construir(secreto, cabecera, cuerpo)` | Un solo secreto. `cuerpo` como `String` o `byte[]`. |
| `construir(secretos, cabecera, cuerpo)` | Una colección de secretos (rotación). `cuerpo` como `String` o `byte[]`. |
| `construir(secretos, cabecera, cuerpo, tolerancia)` | Igual, con otra tolerancia (`Duration`). |

Con una colección de secretos, la entrega es válida si coincide con
cualquiera, así que 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).

El ejemplo siguiente usa el servidor HTTP incluido en el JDK, sin dependencias. Guarda tu
secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en
`ECUAFACT_WEBHOOK_SECRET_ANTERIOR`. Escucha en el puerto 3000, en la ruta
`/webhooks/ecuafact`.

```java
import com.ecuafact.sdk.EcuafactWebhookException;
import com.ecuafact.sdk.WebhookEvent;
import com.ecuafact.sdk.WebhookSignature;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.util.List;
import java.util.Objects;
import java.util.stream.Stream;

public class Webhook {
    public static void main(String[] args) throws Exception {
        List<String> secretos = Stream.of(
                System.getenv("ECUAFACT_WEBHOOK_SECRET"),
                System.getenv("ECUAFACT_WEBHOOK_SECRET_ANTERIOR"))
            .filter(Objects::nonNull).filter(s -> !s.isEmpty()).toList();

        HttpServer servidor = HttpServer.create(new InetSocketAddress(3000), 0);
        servidor.createContext("/webhooks/ecuafact", intercambio -> {
            byte[] cuerpoCrudo = intercambio.getRequestBody().readAllBytes();
            String cabecera = intercambio.getRequestHeaders().getFirst(WebhookSignature.HEADER);
            int estado;
            try {
                WebhookEvent evento = WebhookEvent.construir(secretos, cabecera == null ? "" : cabecera, cuerpoCrudo);
                // Deduplica por eventTypeRaw + resourceId antes de procesar y responde 2xx.
                switch (evento.eventType()) {
                    case DOCUMENTO_AUTORIZADO -> System.out.println("Autorizado " + evento.idOperacion() + " " + evento.claveAcceso());
                    case DOCUMENTO_RECHAZADO -> System.out.println("Rechazo fiscal " + evento.idOperacion() + " codEstado " + evento.codEstado() + " " + evento.errores());
                    case DOCUMENTO_FALLIDO -> System.out.println("No emitido " + evento.idOperacion() + " " + evento.estado() + " codEstado " + evento.codEstado());
                    default -> System.out.println("Evento " + evento.eventTypeRaw() + " prueba=" + evento.probe());
                }
                estado = 200;
            } catch (EcuafactWebhookException error) {
                estado = 401;
            }
            intercambio.sendResponseHeaders(estado, -1);
            intercambio.close();
        });
        servidor.start();
    }
}
```

Para comprobarlo, pulsa **Probar** en tu destino del portal, que envía el
evento de prueba. Tu consola muestra
`Evento operation.requires_attention prueba=true` y la entrega aparece en
**Entregas** con un 200. Si ves un 401, el secreto no coincide o el reloj del
servidor está desfasado más de 300 s.

| Método de `WebhookEvent` | Tipo | Descripción |
|---|---|---|
| `eventType()` | `TipoEventoWebhook` | Tipo de evento; un valor nuevo se lee como `DESCONOCIDO`. |
| `eventTypeRaw()` | `String` | Valor original de `eventType` (`document.authorized`, `document.rejected`, `document.failed`, `operation.requires_attention`). |
| `resourceId()` | `String` | Recurso del evento. Con `eventTypeRaw()` forma la clave de deduplicación. |
| `occurredAtUtc()` | `Instant` | Momento del evento; `null` si no vino o no se pudo leer. |
| `idOperacion()` | `String` | Operación a la que pertenece el evento. |
| `estado()` | `String` | El mismo `estado` del seguimiento en eventos `document.*`: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`. Su versión tipada es `estadoOperacion()`. |
| `tipoDocumento()` | `String` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. |
| `claveAcceso()` | `String` | Clave de acceso del comprobante, si aplica. |
| `codEstado()` | `Integer` | 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()` | `List<String>` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacía 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()` | `boolean` | `true` en el evento de prueba del portal. |

Si solo necesitas saber si la firma es válida, usa
`WebhookSignature.verify(secretos, cabecera, cuerpo)`, que devuelve `boolean` y
nunca lanza; acepta un secreto o una colección, y el cuerpo como `String` o
`byte[]`. Después lee el evento con `WebhookEvent.parse(cuerpo)`.

### 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`), que corresponden a la misma firma.
Con el SDK puedes verificar cualquiera de las dos, sin decidir cuál llegó.

| Método | Qué hace |
|---|---|
| `WebhookEvent.construirConCabeceras(secretos, cabeceras, cuerpo)` | Devuelve el `WebhookEvent` si `Ecuafact-Signature` o Standard Webhooks es válida; si no, lanza `EcuafactWebhookException`. Con otro `Duration` al final cambia la tolerancia. `cabeceras` es un `Map<String, ?>` cuyos nombres no distinguen mayúsculas. |
| `WebhookSignature.verificarCualquiera(secretos, cabeceras, cuerpo)` | Devuelve `boolean` con la misma regla y nunca lanza. También acepta un único secreto y, en lugar del mapa, una `Function<String, String>` que lee una cabecera por nombre. |
| `WebhookSignature.verificarEstandar(secretos, webhookId, webhookTimestamp, webhookSignature, cuerpo)` | Devuelve `boolean`. Verifica solo la firma de Standard Webhooks. |
| `WebhookSignature.firmarEstandar(secreto, webhookId, webhookTimestamp, cuerpo)` | Devuelve el valor de `webhook-signature` (`v1,<base64>`). Sirve para pruebas automatizadas. |

El secreto puede llevar o no el prefijo `whsec_`, y también aceptas una colección
de secretos para la rotación. Con el servidor HTTP del JDK, `getRequestHeaders()`
sirve como `cabeceras`.

```java
WebhookEvent evento = WebhookEvent.construirConCabeceras(secretos, intercambio.getRequestHeaders(), cuerpoCrudo);
```

### Probar tu receptor sin esperar una entrega

Para probar tu receptor en un test automatizado, firma un cuerpo de ejemplo con
el mismo secreto y comprueba que lo aceptas. Con `WebhookSignature.sign` generas
la cabecera `Ecuafact-Signature`, y con `firmarEstandar`, la de Standard Webhooks.

```java
String secreto = "secreto-de-prueba";
String cuerpo = "{\"eventType\":\"document.authorized\",\"resourceId\":\"r1\",\"estado\":\"autorizado\",\"codEstado\":2001}";
long ahora = java.time.Instant.now().getEpochSecond();

String cabecera = WebhookSignature.sign(secreto, ahora, cuerpo);
WebhookEvent evento = WebhookEvent.construir(secreto, cabecera, cuerpo);
// evento.eventType() == TipoEventoWebhook.DOCUMENTO_AUTORIZADO

// Una firma vencida, alterada o de otro secreto lanza EcuafactWebhookException.
```

> [!WARNING]
> Verifica la firma sobre el cuerpo crudo. En Spring, recibe el cuerpo como
> `@RequestBody byte[]` o `@RequestBody String` (no como objeto) para conservar
> los bytes exactos.

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 son `RuntimeException`, así que no necesitas
declararlas, y heredan de `EcuafactSdkException`. Las que vienen de una
respuesta de la API heredan además de `EcuafactApiException`. Captura primero
las específicas y al final `EcuafactSdkException`, que atrapa cualquier error
del SDK.

| Excepción | Hereda de | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL, la URL no es `https`, trae usuario, consulta o fragmento, o termina en `/v1`, la API Key tiene espacios o caracteres de control, o una opción es inválida (`maxAttempts(0)`, tiempo negativo, `correlationId` o `additionalInfo` inválido). | Corrige la configuración. No llama a la API. |
| `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API tras agotar los intentos. | Reintenta más tarde con la misma `idempotencyKey()`. Usa `correlationId()` para ubicar la llamada en tus registros. |
| `EcuafactTimeoutException` | `EcuafactSdkException` | El último intento superó `timeout`, o se agotó `totalTimeout` antes de un intento. | Reintenta con la misma `idempotencyKey()`; si emitías, consulta antes el seguimiento. Usa `correlationId()` para ubicar la llamada en tus registros. |
| `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo vacío o 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. |
| `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` o la `claveAcceso`. |
| `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()` 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 usaste `retryRateLimited(false)`. |
| `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()`. |
| `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El filtro `tipoDocumento` de `listarOperaciones` no es un tipo conocido. `emitir` y `validar` no la lanzan: el tipo lo da la clase del comprobante. | Usa un nombre (`factura`, `liquidacion`, `nota-credito`, `nota-debito`, `guia`, `retencion`) o un código (`01`, `03` a `07`). 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, falta el contribuyente por defecto o un parámetro obligatorio, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, hilo interrumpido, llamada cancelada, o una respuesta 2xx vacía o ilegible. | Corrige la llamada. Si ocurre al emitir, repite la emisión con la `idempotencyKey()` de la excepción, como se explica en [Idempotencia y reintentos](#idempotencia-y-reintentos). |

| Método 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 traía JSON. |
| `estado()` | `String` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`; `null` si la respuesta no traía JSON. |
| `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()` | `List<String>` | Detalle específico del error, como la ruta del campo que falla en un 3002. Nunca es `null` y está vacía cuando no hay detalle. |
| `correlationId()` | `String` | Cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. |
| `idempotencyKey()` | `String` | Clave usada en la emisión; reutilízala al reintentar. Todas las excepciones del SDK la exponen. |
| `retryAfter()` | `Duration` | Espera indicada por la cabecera `Retry-After`; `null` si no llegó. |
| `esReintentable()` | `boolean` | `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. |

`EcuafactConnectionException` y `EcuafactTimeoutException` no traen respuesta
de la API, así que no tienen `codEstado()`. Exponen `idempotencyKey()` y
`correlationId()`, que devuelve el `X-Correlation-Id` que enviaste con
`RequestOptions.correlationId(String)`, o `null` si no enviaste uno.

```java
import com.ecuafact.sdk.EcuafactApiException;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactConnectionException;
import com.ecuafact.sdk.EcuafactQuotaException;
import com.ecuafact.sdk.EcuafactRateLimitException;
import com.ecuafact.sdk.EcuafactTimeoutException;
import com.ecuafact.sdk.EcuafactValidationException;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
FacturaRequest comprobante = new ObjectMapper()
    .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)
    .readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class);

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

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 `infoTributaria.ruc` no coincide con el 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 | Cabeceras inválidas (por ejemplo, `Idempotency-Key` con caracteres no permitidos) o JSON mal formado. | 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 | Filtro de consulta fuera de rango (fechas o `max`). | Ajusta los filtros. |
| 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión (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, usa otro `secuencial` u omítelo 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 o la clave; 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 `null` o un texto vacío, el SDK genera un UUID sin
  guiones, lo 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
(`EcuafactSdkException`) conserva la `Idempotency-Key` en `idempotencyKey()` y
en su mensaje trae el `X-Correlation-Id` de la solicitud; 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. Un 429 sin el `codEstado` 5005, por ejemplo de un proxy intermedio, no se reintenta. |
| 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 y consultas | Sí | Como son `GET`, se reintentan 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. |

Antes del reintento número *n*, el SDK espera según estas reglas:

- `LINEAR`: `retryBaseDelay` x *n* más un margen aleatorio de hasta
  `retryJitter` x *n*.
- `EXPONENTIAL`: `retryBaseDelay` x 2^(*n*-1) más un margen aleatorio de hasta
  `retryJitter`.
- Si la respuesta trae un `Retry-After` mayor y `respectRetryAfter` es `true`,
  espera ese tiempo.
- La espera nunca supera `maxRetryDelay`, salvo que ese valor sea
  `Duration.ZERO`.

Con `totalTimeout`, cada intento se acorta al tiempo que queda. Si la siguiente
espera no cabe dentro del tope, el SDK no reintenta y lanza la excepción del
último intento; si el tope ya se agotó antes de un intento, lanza
`EcuafactTimeoutException`. Si interrumpes el hilo durante una llamada
síncrona, el SDK cancela la solicitud y lanza `EcuafactSdkException`.

## Opciones por llamada

Puedes cambiar el tiempo máximo, el tope total, la correlación, los reintentos o la
información adicional de una sola llamada sin tocar la configuración del
cliente. Lo que no indiques usa la configuración del cliente.

Los métodos que llaman a la API tienen una sobrecarga con `RequestOptions` como
último parámetro, también en la vista `para(...)` y `esperarResultado`. Algunas sobrecargas exigen además los parámetros anteriores.

- Emisión: `emitir(comprobante, idempotencyKey, opciones)` y
  `emitirEn(identificacion, comprobante, idempotencyKey, opciones)`; pasa `null`
  como `idempotencyKey` para que el SDK la genere.
- Espera: `esperarResultado(idOperacion, intervalo, maximo, opciones)`;
  `opciones` se aplica a cada consulta.

| Método de `RequestOptions` | Qué hace |
|---|---|
| `RequestOptions.create()` | Crea las opciones vacías. |
| `timeout(Duration)` | Tiempo máximo de cada intento, solo en esta llamada. Mayor que cero. |
| `totalTimeout(Duration)` | Tope de esta llamada, incluidos reintentos y esperas. Mayor que cero. |
| `correlationId(String)` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres: letras, dígitos y `.` `_` `-`. |
| `reintentos(false)` | Un solo intento en esta llamada. `reintentos(true)` aplica la política del cliente: no activa reintentos si el cliente los tiene desactivados. |
| `validarAntes(boolean)` | Solo en `emitir` y `emitirEn`: `true` llama a `/validar` antes de emitir y `false` no lo llama, sea cual sea `validarAntesDeEmitir` del cliente. |
| `additionalInfo(String)` | Valor de la cabecera `X-Additional-Info` solo en esta llamada; reemplaza el del cliente. Con una cadena vacía o `null` no se envía la cabecera en esta llamada. Mismas reglas que la opción del cliente. |

La API devuelve la correlación que enviaste. La encuentras en
`EmisionResultado.correlationId()` y en `EcuafactApiException.correlationId()`.
Úsala para relacionar tus registros con los nuestros y para pedirnos soporte.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import com.ecuafact.sdk.contracts.Contexto;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

// Un solo intento y correlacion propia para esta consulta.
Contexto contexto = client.getContexto(RequestOptions.create()
    .reintentos(false)
    .correlationId("pedido-2026-0457"));
System.out.println("Contribuyentes: " + contexto.contribuyentes().size());

// Mas tiempo para una descarga grande, con tope total de 2 minutos.
ArchivoComprobante ride = client.descargarRide(
    "0123456789001",
    "0710202601012345678900110010010000001231234567811",
    RequestOptions.create().timeout(Duration.ofSeconds(60)).totalTimeout(Duration.ofMinutes(2)));
Files.write(Path.of("ride.pdf"), ride.contenido());
```

Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu
emisor. Si pasas un valor inválido, como un `correlationId` con espacios o de
más de 64 caracteres, un `additionalInfo` fuera de sus reglas o un tiempo menor
o igual a cero, el SDK lanza `EcuafactConfigurationException` al armar las
opciones, sin llamar a la API.

### Variantes asíncronas y cancelación

Los métodos que llaman a la API tienen una variante `*Async` que devuelve un
`CompletableFuture` (por ejemplo `emitirEnAsync`, `getOperacionAsync`,
`descargarRideAsync` y `esperarResultadoAsync`).

- `cancel(true)` aborta la solicitud HTTP en curso y los reintentos pendientes.
  Lo mismo ocurre si el futuro termina por otra vía antes de la respuesta, por
  ejemplo con `orTimeout(...)` o `completeExceptionally(...)`.
- Los argumentos inválidos, como una `Idempotency-Key` mal formada, lanzan la
  excepción de inmediato, antes de devolver el futuro.
- Los errores de la API completan el futuro con la excepción del SDK como
  causa, que lees con `ExecutionException.getCause()` en `get()` y con
  `CompletionException.getCause()` en `join()`.
- `esperarResultadoAsync(idOperacion, intervalo, maximo, opciones)` consulta sin
  bloquear hilos entre consultas y se cancela igual.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactSdkException;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
FacturaRequest comprobante = new ObjectMapper()
    .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)
    .readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class);

CompletableFuture<EmisionResultado> envio = client.emitirEnAsync(
    "0123456789001", comprobante, "FACTURA-2026-0002",
    RequestOptions.create().correlationId("pedido-2026-0458"));

try {
    // Espera 30 s como maximo.
    EmisionResultado r = envio.get(30, TimeUnit.SECONDS);
    System.out.println(r.admission().estado() + " " + r.admission().idOperacion());
} catch (TimeoutException tiempo) {
    // Sin respuesta en 30 s: cancela el intento en curso y los reintentos pendientes.
    envio.cancel(true);
    System.out.println("Cancelada: reintenta despues con la misma Idempotency-Key");
} catch (ExecutionException error) {
    if (error.getCause() instanceof EcuafactSdkException sdk) {
        System.out.println("Error del SDK: " + sdk.getMessage() + " clave=" + sdk.idempotencyKey());
    }
}
```

Si cancelas una emisión, no sabes si la API la recibió. Reintenta después con la
**misma** `Idempotency-Key` y el mismo cuerpo. Si ya se había recibido, la API
responde con el mismo `idOperacion` y el estado actual de la operación.

En lugar de `get(30, TimeUnit.SECONDS)` y `cancel(true)` puedes encadenar
`orTimeout`. Al vencer el tiempo, el futuro termina con `TimeoutException` y el
SDK aborta la solicitud en curso.

```java
import com.ecuafact.sdk.EmisionResultado;
import java.util.concurrent.TimeUnit;

EmisionResultado r = client.emitirEnAsync("0123456789001", comprobante, "FACTURA-2026-0002", null)
    .orTimeout(30, TimeUnit.SECONDS)
    .join(); // CompletionException con TimeoutException como causa si vence
```

## 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.additionalInfo(String)` | Se envía en todas las solicitudes del cliente, incluidas las de `esperarResultado`, `esperarResultadoAsync` y la vista `para(...)`. |
| `RequestOptions.additionalInfo(String)` | Reemplaza el valor del cliente solo en esa llamada. Si no lo llamas, se usa el del cliente; con cadena vacía o `null` no se 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.

Si no cumple, el método lanza `EcuafactConfigurationException` sin llamar a la
API. El valor no aparece en `toString()` de las opciones ni del cliente, ni en
los mensajes de las excepciones. No pongas en él la API Key ni datos
personales.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.Contexto;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .additionalInfo("erp=MiERP/4.2; sucursal=001"));

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

// Solo esta llamada lleva otro valor.
Contexto otro = client.getContexto(RequestOptions.create()
    .additionalInfo("erp=MiERP/4.2; sucursal=002; lote=2026-10-08"));
System.out.println("Contribuyentes: " + contexto.contribuyentes().size());
```

| Error | Por qué pasa | Qué hacer |
|---|---|---|
| `EcuafactConfigurationException` al configurar el cliente | `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 armar `RequestOptions` | El mismo problema en `RequestOptions.additionalInfo(String)`. No se llamó a la API. | Corrige el valor de esa llamada. |

## Conexión: proxy, TLS y HttpClient propio

Si necesitas salir por un proxy corporativo, confiar en una CA propia o usar un
certificado de cliente, puedes configurarlo con `proxy`, `sslContext`,
`executor` y `connectTimeout`. Si no indicas nada, el SDK crea su propio
`java.net.http.HttpClient` con un `connectTimeout` de 10 s.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RetryBackoff;
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.time.Duration;
import javax.net.ssl.SSLContext;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .retryBackoff(RetryBackoff.EXPONENTIAL)
        .retryBaseDelay(Duration.ofMillis(500))
        .retryRateLimited(true)
        .totalTimeout(Duration.ofSeconds(60))
        .proxy(ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080)))
        .sslContext(SSLContext.getDefault())
        .connectTimeout(Duration.ofSeconds(5)));
System.out.println(client.getContexto().contribuyentes().size() + " contribuyentes");
```

Si ya tienes un `HttpClient` configurado (por ejemplo, compartido con otras
integraciones), pásalo con `httpClient(...)`. En ese caso el SDK no crea el
suyo e ignora `proxy`, `sslContext`, `executor` y `connectTimeout`.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.http.HttpClient;
import java.time.Duration;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient http = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(5))
    .proxy(ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080)))
    .build();

EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .httpClient(http));
System.out.println(client.getContexto().contribuyentes().size() + " contribuyentes");
```

El `timeout` por intento y los reintentos siguen siendo los de
`EcuafactClientOptions` aunque pases tu propio `HttpClient`.

## Constructores de comprobantes

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

`ComprobanteBuilder` es opcional. Solo ensambla el request de su tipo (`FacturaRequest`, `NotaCreditoRequest`, etc.) con los
valores que le das: no calcula totales, impuestos ni redondeos, y no completa
valores por defecto. Tú calculas los importes y la API los calcula y valida
igual que si armaras el JSON a mano. No es seguro para uso concurrente, así
que crea un constructor por comprobante.

```java
import com.ecuafact.sdk.ComprobanteBuilder;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.Tarifa;
import com.ecuafact.sdk.contracts.DetalleCompraVenta;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.ecuafact.sdk.contracts.Impuesto;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.ZoneId;
import java.util.List;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

// Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor.
ComprobanteBuilder<FacturaRequest> factura = ComprobanteBuilder.factura("0123456789001", "001", "001")
    .referencias("MiERP", "FACTURA-2026-0002")
    .fechaEmision(LocalDate.now(ZoneId.of("America/Guayaquil")))
    .comprador("07", "9999999999999", "CONSUMIDOR FINAL")
    .moneda("DOLAR")
    // Los importes de la linea y de totalConImpuestos los das tu: el SDK no los calcula.
    .linea(new DetalleCompraVenta("SERV-001", null, "Servicio de prueba", new BigDecimal("1"),
        new BigDecimal("10.00"), BigDecimal.ZERO, new BigDecimal("10.00"),
        List.of(new Impuesto("2", "4", new BigDecimal("15"), new BigDecimal("10.00"), new BigDecimal("1.50"))),
        null))
    .totalSinImpuestos(new BigDecimal("10.00"))
    .totalDescuento(BigDecimal.ZERO)
    .totalConImpuestos(List.of(new Impuesto("2", "4", new BigDecimal("15"), new BigDecimal("10.00"),
        new BigDecimal("1.50"))))
    .propina(BigDecimal.ZERO)
    .importeTotal(new BigDecimal("11.50"))
    .pago("01", new BigDecimal("11.50"));

FacturaRequest comprobante = factura.construir();
System.out.println("importeTotal " + comprobante.info().importeTotal()); // 11.50

EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0002",
    RequestOptions.create().correlationId("pedido-2026-0458"));
System.out.println(r.admission().estado() + " " + r.admission().idOperacion() + " " + r.correlationId());
```

Deberías ver `importeTotal 11.50` y luego
`recibido <idOperacion> pedido-2026-0458`. Si ejecutas el programa 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.

| Tipo | Entrada | Métodos propios |
|---|---|---|
| Factura (`01`) | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `comprador`, `direccionComprador`, `correo`, `telefono`, `linea`, `ice`, `propina`, `moneda`, `pago` |
| Liquidación de compra (`03`) | `ComprobanteBuilder.liquidacionCompra(ruc, estab, ptoEmi)` | `proveedor`, `direccionProveedor`, `linea`, `ice`, `moneda`, `pago` |
| Nota de crédito (`04`) | `ComprobanteBuilder.notaCredito(ruc, estab, ptoEmi)` | `comprador`, `docModificado`, `totalDocumentoSustento`, `motivo(razon)`, `linea`, `ice`, `moneda` |
| Nota de débito (`05`) | `ComprobanteBuilder.notaDebito(ruc, estab, ptoEmi)` | `comprador`, `docModificado`, `iva(Tarifa)`, `motivo(razon, valor)`, `valorTotal`, `impuestos`, `pago` |
| Guía de remisión (`06`) | `ComprobanteBuilder.guiaRemision(ruc, estab, ptoEmi)` | `dirPartida`, `transportista`, `placa`, `fechasTransporte`, `destinatario`, `codEstabDestino`, `ruta`, `docAduaneroUnico`, `bien(codigoInterno, descripcion, cantidad)` |
| Retención (`07`) | `ComprobanteBuilder.retencion(ruc, estab, ptoEmi)` | `sujetoRetenido`, `periodoFiscal`, `parteRelacionada`, `docSustento`, `impuestoSustento`, `lineaRetencion`, `pago` |

Todos los constructores tienen además `referencias(origen, externa)`, `secuencial`, `fechaEmision`
(texto `dd/MM/yyyy` o `LocalDate`), `dirEstablecimiento`,
`infoAdicional(nombre, valor)` y `construir()`.

Algunos métodos tienen reglas propias:

- En `linea(codigo, descripcion, cantidad, precioUnitario, descuento, tarifa)`,
  `codigo` es el `codigoPrincipal` en la factura y la liquidación, y el
  `codigoInterno` en la nota de crédito. `descuento` es un importe en dólares y `tarifa` es un `Tarifa.of(codigoPorcentaje, tarifa)`. `linea(DetalleCompraVenta)` (factura y liquidación) y
  `linea(DetalleNotaCredito)` agregan una línea armada por ti, con sus importes.
- `ice(codigoPorcentaje, tarifa)`, `codigoAuxiliar` (no existe en la nota de crédito) y
  `detalleAdicional(nombre, valor)` se aplican a la última `linea`.
- El pago se agrega con `pago(formaPago)`, `pago(formaPago, total)` o
  `pago(formaPago, total, plazo, unidadTiempo)`. En la retención, los pagos van
  dentro del documento de sustento.
- `bien`, `codEstabDestino`, `ruta` y `docAduaneroUnico` se aplican al último
  `destinatario(identificacion, razonSocial, direccion, motivoTraslado)`.
- `docSustento(codSustento, codDocSustento, numDocSustento, fechaEmisionDocSustento, fechaRegistroContable, numAutDocSustento)`
  agrega el documento de sustento de la retención; `impuestoSustento`,
  `lineaRetencion`, `pagoLocExt`, `totalSinImpuestos` e `importeTotal` se aplican a él. `pagoLocExt` no tiene valor por defecto.
- Puedes asignar estos totales: `totalSinImpuestos`, `totalDescuento`,
  `totalConImpuestos`, `importeTotal`, `valorModificacion` (nota de crédito),
  `valorTotal` e `impuestos` (nota de débito).

**El constructor es genérico por tipo.** `ComprobanteBuilder.factura(...)` devuelve `ComprobanteBuilder<FacturaRequest>` y `construir()` devuelve `FacturaRequest`; lo mismo en los demás tipos. Un dato que el tipo no tiene (por ejemplo `proveedor(...)` en una factura) lanza `EcuafactSdkException` al construir, en lugar de descartarse en silencio.

**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 `BigDecimal` conservan su precisión sin pérdida.

| Elemento | Detalle |
|---|---|
| Tarifa de una línea | `Tarifa.of(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. |
| Validación | El constructor no valida reglas de negocio ni calcula: solo ayuda 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 los métodos de `EcuafactClient`. La identificación
que reciben es siempre el valor `identificacion` del contexto. Los métodos que
llaman a la API tienen además una sobrecarga con `RequestOptions`, descrita en
[Opciones por llamada](#opciones-por-llamada), y todos
tienen una variante `*Async`, descrita en
[Variantes asíncronas](#variantes-asincronas-y-cancelacion).

| Método | Endpoint | Devuelve |
|---|---|---|
| `getContexto()` | `GET /v1/contexto` | `Contexto` (ver [Contexto y consumo](#contexto-y-consumo)) |
| `emitir(comprobante)` / `emitir(comprobante, idempotencyKey)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` (ver [Ruta de emisión por tipo de comprobante](#ruta-de-emision-por-tipo-de-comprobante)) |
| `emitirEn(identificacion, comprobante)` / `emitirEn(identificacion, comprobante, idempotencyKey)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` |
| `validar(comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` (ver [Validar sin emitir](#validar-sin-emitir)) |
| `validarEn(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` |
| `getOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `idOperacion` debe ser un UUID. |
| `consultarOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) |
| `esperarResultado(idOperacion)` / `esperarResultado(idOperacion, intervalo, maximo)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Opcional; por defecto cada 5 s hasta 120 s. |
| `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` | `boolean`: `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, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` (`cambios` es un `PerfilEmisorUpdate`) |
| `actualizarLogo(identificacion, contenido, contentType, nombreArchivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) |
| `consultarContribuyente(identificacion)` / `consultarContribuyente(identificacion, fusionar, fuente)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta`. Sin argumentos extra envía `fusionar=true`. |
| `buscarContribuyentes(apellidos)` / `buscarContribuyentes(apellidos, nombres, clase, max)` | `GET /v1/consultas/contribuyentes` | `List<BusquedaContribuyente>` |
| `listarEstablecimientos(ruc)` / `listarEstablecimientos(ruc, filtro)` | `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) | `EcuafactContribuyente` (ver [Varios contribuyentes](#varios-contribuyentes)) |
| `WebhookEvent.construir(...)` y `WebhookSignature.verify(...)` | - (local) | `WebhookEvent` o `boolean` (ver [Webhooks](#webhooks)) |

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

- Si no configuras `identificacion` en las opciones, `emitir` lanza
  `EcuafactSdkException`. En ese caso usa la variante que recibe la
  identificación o la vista `para(...)`.
- `ArchivoComprobante` tiene `contenido()` (`byte[]`) y `contentType()`. Las
  descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml).
- `PerfilEmisor` y `PerfilEmisorUpdate` son clases con campos
  públicos (`perfil.razonSocial`), no `record`.

## Importes exactos

Todos los importes, cantidades, precios y tarifas son `java.math.BigDecimal`
(por ejemplo `InfoFactura.importeTotal()`, `DetalleCompraVenta.precioUnitario()`,
`Comprobante.total()`). Un `BigDecimal` creado desde
texto guarda `11.50` exacto y el SDK lo envía como número JSON sin notación
científica. `Pago.plazo()` es un `BigDecimal` (el contrato lo tipa `number`) que cuenta
unidades de `unidadTiempo`; `pago(...)` del constructor acepta también un
`Integer`.

Crea los importes desde texto, como `new BigDecimal("11.50")`, y nunca desde un
`double`, porque `new BigDecimal(11.5)` arrastra el error binario. Después
redondea a 2 decimales.

```java
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
ObjectMapper mapper = new ObjectMapper().enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS);
ObjectNode json = (ObjectNode) mapper.readTree(Files.readString(Path.of("comprobante.json")));

BigDecimal baseImponible = new BigDecimal("10.00");
BigDecimal iva = baseImponible.multiply(new BigDecimal("0.15")).setScale(2, RoundingMode.HALF_UP); // 1.50
((ObjectNode) json.get("info")).put("totalSinImpuestos", baseImponible);
((ObjectNode) json.get("info")).put("importeTotal", baseImponible.add(iva));                    // 11.50

System.out.println(json.get("info").get("importeTotal").decimalValue()); // 11.50
```

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, pasa la identificación en
cada llamada o crea una vista por contribuyente. La vista repite la
identificación por ti en cada método.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactContribuyente;
import com.ecuafact.sdk.contracts.PerfilEmisor;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

EcuafactContribuyente matriz = client.para("0123456789001");

PerfilEmisor perfil = matriz.getPerfil();
System.out.println(perfil.razonSocial + " (" + perfil.identificacion + ")");
```

La vista `EcuafactContribuyente` tiene estos métodos. Los que llaman a la API
aceptan además `RequestOptions` al final; en `emitir`, después de
`idempotencyKey`.

| Método | Equivale a |
|---|---|
| `identificacion()` | La identificación de la vista. |
| `emitir(comprobante)` / `emitir(comprobante, idempotencyKey)` | `client.emitirEn(identificacion, ...)` |
| `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)` | `client.actualizarLogo(identificacion, ...)` |
| `esperarResultado(idOperacion)` / `esperarResultado(idOperacion, intervalo, maximo)` | `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. Acepta PNG o JPEG de hasta 512 KB, y `contentType`
es obligatorio (`image/png` o `image/jpeg`); si no indicas `nombreArchivo`, el
SDK usa `logo`. Un archivo vacío lanza `EcuafactSdkException` sin llamar a la
API, y la subida no se reintenta automáticamente.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.PerfilEmisor;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

byte[] logo = Files.readAllBytes(Path.of("logo.png"));
PerfilEmisor perfil = client.actualizarLogo("0123456789001", logo, "image/png", "logo.png");
System.out.println("Logo actualizado para " + perfil.razonSocial + ": " + perfil.logo);
```

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.

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.Contexto;
import com.ecuafact.sdk.contracts.QuotaBucket;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

Contexto contexto = client.getContexto();
contexto.contribuyentes().forEach(c ->
    System.out.println(c.identificacion() + " " + c.puedeEmitir() + " " + c.tiposComprobante()));

QuotaBucket cupo = client.getConsumo();
System.out.println("Disponibles " + cupo.disponibles() + " de " + cupo.limiteDocumentos()
    + "; vigente hasta " + cupo.vigenteHasta());
```

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

| Método | Tipo | Descripción |
|---|---|---|
| `Contexto.idCliente()` | `String` | Identificador de tu integración. |
| `Contexto.nombre()` | `String` | Nombre de tu integración. |
| `Contexto.contribuyentes()` | `List<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()` | `boolean` | `true` si tu API Key puede emitir para este contribuyente. |
| `Contribuyente.puedeRecibir()` | `boolean` | `true` si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. |
| `Contribuyente.tiposComprobante()` | `List<String>` | Códigos de los tipos de comprobante habilitados (`01`, `03`, `04`, `05`, `06`, `07`). |
| `Contribuyente.marcaBlanca()` | `boolean` | `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.

| Método | 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 los cuatro valores 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 pueden ir en `null`: `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.

```java
import com.ecuafact.sdk.contracts.Comprobante;
import com.ecuafact.sdk.contracts.PaginaComprobantes;

int numero = 1;
PaginaComprobantes pagina;
do {
    pagina = client.listarOperaciones("0123456789001", "2026-11-01", "2026-11-30", null, null, numero, 50);
    for (Comprobante fila : pagina.comprobantes()) {
        System.out.println(fila.numeroDocumento() + " " + fila.estado() + " " + fila.codEstado() + " " + fila.total());
    }
    numero++;
} while (Boolean.TRUE.equals(pagina.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 `listarOperaciones` con la
identificación fija.

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

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactNotFoundException;
import com.ecuafact.sdk.contracts.CatalogoDetalle;
import com.ecuafact.sdk.contracts.CatalogoItem;
import com.ecuafact.sdk.contracts.Catalogos;
import com.ecuafact.sdk.contracts.EstadoServicio;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

EstadoServicio estado = client.obtenerEstadoServicio();
System.out.println(estado.estado() + " " + estado.disponibilidad90Dias());
estado.componentes().forEach(c -> System.out.println(c.nombre() + " " + c.estado()));
estado.incidentes().forEach(i -> System.out.println(i.inicio() + " " + i.impacto() + " " + i.titulo() + " " + i.fin()));

Catalogos indice = client.listarCatalogos();
indice.catalogos().forEach(c -> System.out.println(c.nombre() + " " + c.descripcion()));

try {
    CatalogoDetalle tarifas = client.obtenerCatalogo("tarifas-iva");
    for (CatalogoItem fila : tarifas.items()) {
        System.out.println(fila.codigo() + " " + fila.descripcion() + " " + fila.valor());
    }
} catch (EcuafactNotFoundException error) {
    System.out.println("Ese catálogo no existe");
}
```

Si el catálogo `tarifas-iva` existe, el programa 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`, un `record` con los
mismos campos que la [respuesta de la consulta](/v1/guias/estado-del-servicio#respuesta).

| Método | 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()` | `List<ComponenteEstado>` | Componentes monitoreados. |
| `disponibilidad90Dias()` | `Double` | Porcentaje de minutos sin caída en los últimos 90 días. `null` si aún no hay muestras. |
| `incidentes()` | `List<IncidentePublico>` | Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo. |

| Método de `ComponenteEstado` | Tipo | Descripción |
|---|---|---|
| `nombre()` | `String` | Nombre del componente. |
| `estado()` | `String` | `operativo`, `degradado`, `caido` o `sin_datos`. |

| Método 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).

| Método | Tipo | Descripción |
|---|---|---|
| `Catalogos.catalogos()` | `List<CatalogoResumen>` | Catálogos disponibles, en el orden de la ficha técnica del SRI. |
| `CatalogoResumen.nombre()` | `String` | Clave del catálogo; es el valor que recibe `obtenerCatalogo`. |
| `CatalogoResumen.descripcion()` | `String` | Descripción breve de lo que contiene. |
| `CatalogoDetalle.nombre()` | `String` | Clave del catálogo. |
| `CatalogoDetalle.descripcion()` | `String` | Descripción breve del catálogo. |
| `CatalogoDetalle.fuente()` | `String` | Tabla o anexo de la ficha técnica del SRI de donde proviene. |
| `CatalogoDetalle.items()` | `List<CatalogoItem>` | Filas del catálogo. |
| `CatalogoItem.codigo()` | `String` | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. |
| `CatalogoItem.descripcion()` | `String` | Descripción del código. |
| `CatalogoItem.valor()` | `BigDecimal` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. `null` si el catálogo no lo tiene. |
| `CatalogoItem.vigenteDesde()` | `String` | Primer día de vigencia (`yyyy-MM-dd`). `null` si la fila no está acotada por el inicio. |
| `CatalogoItem.vigenteHasta()` | `String` | Último día de vigencia (`yyyy-MM-dd`). `null` si sigue vigente. |
| `CatalogoItem.atributos()` | `Map<String, Object>` | Atributos propios del catálogo. `null` si no hay. |

## Consultas SRI

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

```java
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.BusquedaContribuyente;
import com.ecuafact.sdk.contracts.ContribuyenteConsulta;
import com.ecuafact.sdk.contracts.EstablecimientosContribuyente;
import com.ecuafact.sdk.contracts.ValidacionIdentificacion;
import java.util.List;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

ValidacionIdentificacion validacion = client.validarIdentificacion("0123456789001");
ContribuyenteConsulta contribuyente = client.consultarContribuyente("0123456789001");
List<BusquedaContribuyente> encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
EstablecimientosContribuyente establecimientos = client.listarEstablecimientos("0123456789001", "SoloActivos");
System.out.println(validacion.valido() + " " + encontrados.size());
```

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

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

