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

# SDK .NET

Biblioteca oficial para emitir comprobantes desde .NET, seguir su autorización, descargar el RIDE y verificar webhooks sin armar las llamadas HTTP.

Si desarrollas en C# o en cualquier otro lenguaje de .NET, puedes integrarte con
nuestros servicios de facturación usando nuestro SDK para .NET. Lo instalas
desde NuGet y, en lugar de armar cada petición HTTP, llamas a métodos como
`EmitirAsync` o `DescargarRideAsync`, que reciben y devuelven objetos tipados.
Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la
`Idempotency-Key` en sus reintentos. Además, envía tu API Key en cada llamada,
te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica
la firma de los webhooks que te enviamos.

Esta guía empieza con la instalación, la configuración del cliente y un
quickstart que va de la API Key al RIDE en tres pasos. Después documenta cada
método, los errores, los reintentos, la inyección de dependencias en ASP.NET
Core y los constructores de comprobantes. 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 .NET 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-dotnet.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 dotnet add package Ecuafact.Sdk. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Usa Ecuafact.Sdk.Core solo si el proyecto ya usa inyección de dependencias. 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.
```

## Paquetes

| Paquete | Versión | Uso |
|---|---|---|
| `Ecuafact.Sdk` | `1.0.1` | Contiene el cliente (`EcuafactClient`), los modelos, las excepciones, los estados tipados y la verificación de webhooks. Es el único que necesitas para empezar. |
| `Ecuafact.Sdk.Core` | `1.0.1` | Registra el cliente con `AddEcuafactClient` en el contenedor de dependencias de ASP.NET Core o de un Worker Service. Es opcional. |

Ambos paquetes se compilan para `netstandard2.0` y `net10.0`, así que funcionan
en .NET 10, en .NET Core 2.0 o superior y en .NET Framework 4.6.1 o superior. Se
distribuyen en [NuGet](https://www.nuget.org/packages/Ecuafact.Sdk).

Esta guía documenta la versión `1.0.1`.

## Requisitos

- [ ] El SDK de .NET instalado. Para comprobarlo, ejecuta `dotnet --version`,
      que debe responder con un número de versión.
- [ ] 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

Crea un proyecto de consola y agrega el paquete.

```bash
dotnet new console -n EcuafactPrueba
cd EcuafactPrueba
dotnet add package Ecuafact.Sdk
dotnet list package
```

La instalación funcionó si `dotnet list package` muestra `Ecuafact.Sdk` con la
versión `1.0.1`. Si vas a usar inyección de dependencias, agrega también
`Ecuafact.Sdk.Core`, como se explica en
[Inyección de dependencias](#inyeccion-de-dependencias).

## Configuración

Crea el cliente **una vez** y reutilízalo en toda la aplicación. Es seguro para
uso concurrente y sirve para todos los [contribuyentes](/v1/guias/glosario) de tu
API Key.

```csharp
using Ecuafact.Sdk;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    Identificacion = "0123456789001" // opcional: contribuyente por defecto
});

Console.WriteLine(client); // EcuafactClient { BaseAddress = https://api-sandbox.mynexusapi.com/, ApiKey = *** }
```

Si no configuras `ApiKey`, el SDK lee la variable de entorno
`ECUAFACT_API_KEY`, y si no configuras `BaseAddress` (ni tu `HttpClient` trae
una), lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta
`EcuafactClient.Create(new EcuafactClientOptions())`. Los nombres están en las
constantes `EcuafactClientOptions.ApiKeyEnvironmentVariable` y
`EcuafactClientOptions.BaseUrlEnvironmentVariable`.

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` | `Uri?` | `null` | URL base de la API, sin `/v1`. Si es `null`, usa la del `HttpClient` y, si tampoco existe, `ECUAFACT_BASE_URL`. Debe ser absoluta HTTPS, sin credenciales, query string ni fragmento. |
| `ApiKey` | `string?` | `null` | Tu API Key; viaja en la cabecera `X-Api-Key`. Si es `null` o vacía, usa `ECUAFACT_API_KEY`. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en `ToString()` ni en el depurador. |
| `Identificacion` | `string?` | `null` | Contribuyente por defecto para `EmitirAsync(comprobante)` y `ValidarAsync(comprobante)`. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). Déjalo vacío si tu API Key maneja varios contribuyentes. |
| `Timeout` | `TimeSpan` | `00:00:30` (30 s) | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta. Mayor que cero o `Timeout.InfiniteTimeSpan`. El valor por defecto está en `EcuafactClientOptions.DefaultTimeout`. Por llamada lo cambias con `RequestOptions.Timeout`. |
| `UserAgent` | `string` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. |
| `RetryTransientFailures` | `bool` | `true` | Reintenta fallos transitorios (ver [Reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. |
| `MaxAttempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. |
| `RespectRetryAfter` | `bool` | `true` | Si la cabecera `Retry-After` pide una espera mayor que la calculada, espera ese tiempo (con el tope de `MaxRetryDelay`). |
| `MaxRetryDelay` | `TimeSpan` | `00:01:00` (60 s) | Espera máxima entre reintentos. Con `TimeSpan.Zero` no hay tope. |
| `RetryRateLimited` | `bool` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `MaxRetryDelay`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. |
| `RetryableStatusCodes` | `ISet<int>` | `408`, `425`, `500`, `502`, `503`, `504` | Estados HTTP que se reintentan, entre 100 y 599. Para el 429 usa `RetryRateLimited` (agregar 429 aquí tiene el mismo efecto). Los valores por defecto están en `EcuafactClientOptions.DefaultRetryableStatusCodes`. |
| `RetryBaseDelay` | `TimeSpan` | `200 ms` | Espera base entre reintentos. |
| `RetryBackoff` | `RetryBackoff` | `RetryBackoff.Linear` | `Linear`: base x intento (200, 400, 600 ms). `Exponential`: base x 2^(intento-1) (200, 400, 800 ms). |
| `RetryJitter` | `TimeSpan` | `50 ms` | Variación aleatoria que se suma a cada espera: en el intento *n*, un valor al azar de 0 a `RetryJitter` x *n*. Evita que varios procesos reintenten al mismo tiempo. |
| `TotalTimeout` | `TimeSpan?` | `null` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas. Al superarlo lanza `EcuafactTimeoutException`. |
| `MaxResponseBytes` | `long?` | `33554432` (32 MiB) | Tamaño máximo, en bytes, de cada respuesta de la API. El SDK la lee por partes y la aborta al superarlo con `EcuafactResponseTooLargeException`. `null` o `0` quitan el tope; no admite negativos. Por llamada lo cambias con `RequestOptions.MaxResponseBytes`. |
| `MaxFileResponseBytes` | `long?` | `104857600` (100 MiB) | Igual que `MaxResponseBytes`, pero para las descargas de archivos (`DescargarRideAsync` y `DescargarXmlAsync`). `null` o `0` quitan el tope. |
| `ValidarAntesDeEmitir` | `bool` | `false` | Si es `true`, `EmitirAsync` llama antes a `/validar` y no emite cuando la API responde `valido: false` (lanza `EcuafactValidationException`). Cada emisión hace 2 peticiones. Ver [Validar antes de cada emisión](#validar-antes-de-cada-emision). |
| `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). |
| `Handler` | `HttpMessageHandler?` | `null` | Handler para proxy, certificados, TLS o tiempo de conexión (`SocketsHttpHandler.ConnectTimeout`). Lo usa `EcuafactClient.Create` y, con inyección de dependencias, entra como handler principal de `IHttpClientFactory`. El SDK no lo libera. No aplica si pasas tu propio `HttpClient` (ver [HttpClient propio, proxy y TLS](#httpclient-propio-proxy-y-tls)). |

Las opciones se validan al crear el cliente, antes de cualquier llamada.
`Create` y el constructor lanzan `EcuafactConfigurationException` en cualquiera
de estos casos:

- Falta la API Key o la URL.
- La URL no es HTTPS, contiene credenciales, query string o fragmento, o termina en `/v1`.
- La API Key tiene espacios al inicio o al final, o caracteres de control.
- `MaxAttempts` es menor que 1.
- `Timeout` o `TotalTimeout` no son mayores que cero.
- `MaxRetryDelay`, `RetryBaseDelay` o `RetryJitter` son negativos.
- `RetryableStatusCodes` trae un código fuera del rango de 100 a 599.
- `MaxResponseBytes` o `MaxFileResponseBytes` son negativos.
- `AdditionalInfo` no cumple sus reglas.

El mensaje de la excepción nunca incluye la API Key ni el valor de
`AdditionalInfo`. Además, el cliente guarda una copia de las opciones, así que
cambiar tu instancia de `EcuafactClientOptions` después de crearlo no lo
afecta. La configuración efectiva está en `client.Options`, y al imprimirla la
API Key aparece como `***`.

## 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 del proyecto. Es una
factura a consumidor final, con el tipo de identificación `07` y la
identificación `9999999999999`, que solo se admite en facturas de hasta 50.00.
Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No
lleva `secuencial`, porque te asignamos el siguiente [secuencial](/v1/guias/glosario) de la serie
`estab`-`ptoEmi`. El 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
        }
      ]
    }
  ]
}
```

`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`. El detalle de cada campo está en [Factura](/v1/guias/emision-01).

### Paso 2. Escribe el programa

Reemplaza el contenido de `Program.cs` por el código siguiente. El paso 4 usa
`EsperarResultadoAsync`, 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), sin que
tu proceso se quede esperando.

```csharp
using System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

try
{
    // 1. Contexto: que contribuyentes puede usar tu API Key.
    Contexto contexto = await client.GetContextoAsync();
    Contribuyente emisor = contexto.Contribuyentes!.First(c => c.PuedeEmitir);
    Console.WriteLine($"Emisor {emisor.Identificacion}");

    // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador).
    FacturaRequest comprobante = JsonSerializer.Deserialize<FacturaRequest>(
        await File.ReadAllTextAsync("comprobante.json"))!;
    comprobante.InfoTributaria!.Ruc = emisor.Identificacion;
    comprobante.Info!.FechaEmision = DateTime.UtcNow.AddHours(-5).ToString("dd/MM/yyyy");

    // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key.
    EmisionResultado emision = await client.EmitirAsync(
        emisor.Identificacion!, comprobante, idempotencyKey: "FACTURA-2026-0001");
    // CodEstado es 1001 (aun sin clave de acceso) o 1002 (con ClaveAcceso); acepta los dos.
    Console.WriteLine($"estado {emision.Admission.Estado} codEstado {emision.Admission.CodEstado} idOperacion {emision.Admission.IdOperacion}");

    // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min).
    Operation operacion = await client.EsperarResultadoAsync(emision.Admission.IdOperacion);
    Console.WriteLine($"estado {operacion.Estado} codEstado {operacion.CodEstado} {operacion.MsgError}".TrimEnd());
    foreach (string detalle in operacion.Errores)
    {
        Console.WriteLine($" - {detalle}");
    }

    // 5. RIDE: solo existe cuando el comprobante esta autorizado.
    if (operacion.EsAutorizado)
    {
        ArchivoComprobante ride = await client.DescargarRideAsync(emisor.Identificacion!, operacion.ClaveAcceso!);
        await File.WriteAllBytesAsync("ride.pdf", ride.Contenido);
        Console.WriteLine($"RIDE guardado en ride.pdf; claveAcceso {operacion.ClaveAcceso}");
    }
    else if (!operacion.EsFinal)
    {
        Console.WriteLine("Aun sin resultado: consulta mas tarde o espera el webhook.");
    }
}
catch (EcuafactApiException error)
{
    Console.WriteLine($"HTTP {error.EstadoHttp} codEstado {error.CodEstado}: {error.MsgError}");
    foreach (string detalle in error.Errores)
    {
        Console.WriteLine($" - {detalle}");
    }
    Console.WriteLine($"X-Correlation-Id: {error.CorrelationId}");
}
```

### Paso 3. Ejecuta y verifica

```bash
dotnet run
```

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 `-` 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. | Busca el `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion) y sigue lo que indica. |
| `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, por ejemplo totales que no cuadran. Las líneas `-` muestran el detalle de `Errores`. | 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 de
> hoy 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.

Los valores posibles de `Estado` y `CodEstado` están en
[Seguimiento de una operación](/v1/guias/consulta-operacion), en el
[catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado) y en
[Estados tipados](#estados-tipados).

## Métodos

Todos los métodos que llaman a la API son asíncronos y aceptan, después de sus
parámetros, un `CancellationToken ct` opcional y un `RequestOptions? opciones`
opcional, que se explica en [Opciones por llamada](#opciones-por-llamada). En
las rutas `/v1/contribuyentes/...`, la identificación es siempre el valor
`identificacion` que devuelve el contexto, que es la identificación completa del
contribuyente y también el valor de `infoTributaria.ruc`. El SDK rechaza, sin
llamar a la API, una identificación que no tenga de 5 a 13 dígitos (por ejemplo
vacía, `.` o `..`), y lo mismo hace con una `claveAcceso`, un RUC o un número
vacíos, de solo espacios, `.` o `..` en las descargas y las consultas.

Igual que la API tiene un endpoint por tipo de documento, el SDK tiene un
request por tipo de documento, y `EmitirAsync` y `ValidarAsync` eligen la ruta
por el tipo del request que les pasas. El cuerpo HTTP es el request tal cual: no
existe `infoTributaria.tipoDocumento` ni un modelo genérico de comprobante.

| Request | Documento | Ruta de emisión | Ruta de validación |
|---|---|---|---|
| `FacturaRequest` | Factura | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST /v1/contribuyentes/{identificacion}/facturas/validar` |
| `LiquidacionCompraRequest` | Liquidación de compra | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar` |
| `NotaCreditoRequest` | Nota de crédito | `POST /v1/contribuyentes/{identificacion}/notas-credito` | `POST /v1/contribuyentes/{identificacion}/notas-credito/validar` |
| `NotaDebitoRequest` | Nota de débito | `POST /v1/contribuyentes/{identificacion}/notas-debito` | `POST /v1/contribuyentes/{identificacion}/notas-debito/validar` |
| `GuiaRemisionRequest` | Guía de remisión | `POST /v1/contribuyentes/{identificacion}/guias-remision` | `POST /v1/contribuyentes/{identificacion}/guias-remision/validar` |
| `RetencionRequest` | Comprobante de retención | `POST /v1/contribuyentes/{identificacion}/retenciones` | `POST /v1/contribuyentes/{identificacion}/retenciones/validar` |

Cada request contiene solo las propiedades de su esquema del contrato, con sus
mismos nombres, tipos, nulabilidad y campos obligatorios (los obligatorios
llevan el atributo informativo `[Obligatorio]`; el SDK no valida, lo hace la
API). Todos comparten `InfoTributaria`, `Pago`, `Impuesto` y `CampoAdicional`.
Cada tipo agrega su cuerpo propio:

| Request | Información | Líneas |
|---|---|---|
| `FacturaRequest` | `InfoFactura` (incluye los nueve campos de exportación) | `Detalles`: `DetalleCompraVenta` |
| `LiquidacionCompraRequest` | `InfoLiquidacionCompra` | `Detalles`: `DetalleCompraVenta` |
| `NotaCreditoRequest` | `InfoNotaCredito` | `Detalles`: `DetalleNotaCredito` |
| `NotaDebitoRequest` | `InfoNotaDebito` | `Motivos`: `Motivo` |
| `GuiaRemisionRequest` | `InfoGuiaRemision` | `Destinatarios`: `Destinatario` con `DetalleGuia` |
| `RetencionRequest` | `InfoComprobanteRetencion` | `DocsSustento`: `DocsSustento` con `ImpuestoDocSustento` y `RetencionLinea` |

Los métodos `EmitirAsync` y `ValidarAsync` aceptan cualquiera de los seis
requests (heredan de `ComprobanteRequestBase`, que no se puede extender fuera
del SDK). Un argumento nulo lanza `ArgumentNullException` sin llamar a la API.

| Método | Endpoint | Devuelve |
|---|---|---|
| `GetContextoAsync()` | `GET /v1/contexto` | `Contexto` (cliente y contribuyentes de tu API Key) |
| `EmitirAsync(comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{Identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` |
| `EmitirAsync(identificacion, comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` |
| `ValidarAsync(comprobante)` | `POST /v1/contribuyentes/{Identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` (revisa `Valido`; ver [Validar sin emitir](#validar-sin-emitir)) |
| `ValidarAsync(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` |
| `GetOperacionAsync(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (seguimiento). Acepta `Guid` o, como extensión, un `string` con un UUID. |
| `ConsultarOperacionAsync(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias del anterior) |
| `EsperarResultadoAsync(idOperacion, intervalo?, maximo?)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Opcional; ver [Esperar el resultado](#esperar-el-resultado). |
| `DescargarRideAsync(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) |
| `DescargarXmlAsync(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) |
| `GetConsumoAsync()` | `GET /v1/consumo` | `QuotaBucket` (cupo) |
| `ListarOperacionesAsync(identificacion, desde?, hasta?, tipoDocumento?, buscar?, pagina?, tamanoPagina?)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de comprobantes emitidos](#listado-de-comprobantes-emitidos)) |
| `SaludAsync()` | `GET /salud` | `EstadoServicio` (`Servicio` y `Estado`). No envía la API Key. |
| `ObtenerEstadoServicioAsync()` | `GET /estado` | `EstadoPublico` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía la API Key. |
| `ListarCatalogosAsync()` | `GET /v1/catalogos` | `Catalogos` |
| `ObtenerCatalogoAsync(nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` |
| `GetPerfilAsync(identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` |
| `ActualizarPerfilAsync(identificacion, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` |
| `ActualizarLogoAsync(identificacion, contenido, contentType, nombreArchivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (PNG o JPEG, hasta 512 KB; ver [Logo del perfil](#logo-del-perfil)) |
| `ConsultarContribuyenteAsync(identificacion, fusionar = true, fuente?)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` |
| `BuscarContribuyentesAsync(apellidos, nombres?, clase?, max?)` | `GET /v1/consultas/contribuyentes` | `IReadOnlyList<BusquedaContribuyente>` |
| `ListarEstablecimientosAsync(ruc, filtro?)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente` |
| `ValidarIdentificacionAsync(numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `Valido`) |
| `DecodificarClaveAccesoAsync(claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` |
| `Para(identificacion)` | - (no llama a la API) | `IEcuafactContribuyente` fijado a un contribuyente |
| `WebhookEvent.Construir(...)`, `WebhookEvent.ConstruirDesdeEntrega(...)`, `WebhookSignature.Verify(...)`, `WebhookSignature.VerificarEntrega(...)` y `StandardWebhookSignature.Verify(...)` (espacio de nombres `Ecuafact.Sdk.Webhooks`) | - (local) | `WebhookEvent` o `bool` (ver [Webhooks](#webhooks)) |

`EsperarResultadoAsync` y la sobrecarga de `GetOperacionAsync` con `string` son métodos de extensión de `EcuafactClientExtensions` (espacio de
nombres `Ecuafact.Sdk`), así que funcionan tanto sobre `EcuafactClient` como
sobre `IEcuafactClient`.

Algunos tipos de la respuesta traen datos que conviene conocer:

- `EmisionResultado` trae `Admission`, `IdempotencyKey` (la clave usada) y
  `CorrelationId` (la cabecera `X-Correlation-Id`). `Admission` tiene los mismos
  campos que `Operation`, que se describen en
  [Esperar el resultado](#esperar-el-resultado). En una emisión aceptada,
  `Estado` es `recibido` y `CodEstado` es 1001 o 1002: con 1001, `ClaveAcceso`
  todavía es `null`, y con 1002 ya trae la clave de acceso. Tu código debe
  aceptar los dos valores. `UrlEstado` es la URL completa del seguimiento.
- `ArchivoComprobante` trae `Contenido` (`byte[]`) y `ContentType`. Las descargas
  solo existen con el comprobante autorizado; ver
  [Descargar XML](/v1/guias/consulta-xml).
- `QuotaBucket` trae `LimiteDocumentos`, `Reservados`, `Consumidos`, `Disponibles`,
  `VigenteHasta` y los campos `...Extra`, que se mantienen por compatibilidad y valen 0. Cada comprobante
  autorizado o rechazado consume un documento de tu cupo, y uno cancelado lo
  libera; el detalle está en [Consumo](/v1/guias/consumo).

## Validar sin emitir

Antes de emitir puedes comprobar que un comprobante está bien armado con
`ValidarAsync`. La validación aplica las mismas reglas que la emisión y recibe
el mismo request del tipo, pero no emite nada, no consume cupo ni usa un
número de la serie, y no necesita `Idempotency-Key`. Usa la misma ruta del tipo
que la emisión, seguida de `/validar`. Te sirve sobre todo cuando generas
comprobantes de forma automática, porque validas el lote completo, corriges lo
que falle y emites después solo lo que pasó. Cada validación cuenta para tu
[límite de solicitudes](/v1/guias/limite-de-request) por minuto.

`ValidarAsync` devuelve un `ValidacionResultado` con seis propiedades:
`Valido`, `CodEstado`, `MsgError`, `Errores`, `Advertencias` y `CorrelationId` (la cabecera
`X-Correlation-Id`). Si el comprobante cumple las reglas, `Valido` es `true`,
`CodEstado` es `null` y `Errores` viene vacía. `Advertencias` trae los avisos que
no impiden emitir, por ejemplo que la firma incluida en un XML se ignora, y viene
vacía si no hay ninguno. Si el comprobante no cumple las reglas, el método no
lanza una excepción: `Valido` es `false`, `CodEstado` es 3002
(`CodEstado.ComprobanteInvalido`) y `Errores` trae el mismo detalle que
recibirías al emitirlo, con la ruta del campo que falla.

Los demás errores se comportan igual que en cualquier otro método y lanzan la
excepción que corresponde (ver [Errores](#errores)). Por ejemplo, si el
contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API
Key, recibes una `EcuafactAuthException` con el `CodEstado` 3011 (`acceso_denegado`). Como validar no
tiene efectos, el SDK reintenta los fallos transitorios igual que en una
consulta.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
using System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

Contexto contexto = await client.GetContextoAsync();
Contribuyente emisor = contexto.Contribuyentes!.First(c => c.PuedeEmitir);

FacturaRequest comprobante = JsonSerializer.Deserialize<FacturaRequest>(
    await File.ReadAllTextAsync("comprobante.json"))!;
comprobante.InfoTributaria!.Ruc = emisor.Identificacion;
comprobante.Info!.FechaEmision = DateTime.UtcNow.AddHours(-5).ToString("dd/MM/yyyy");

ValidacionResultado validacion = await client.ValidarAsync(emisor.Identificacion!, comprobante);
if (validacion.Valido)
{
    Console.WriteLine("Comprobante valido: ya puedes emitirlo con EmitirAsync.");
}
else
{
    Console.WriteLine($"Comprobante invalido (codEstado {validacion.CodEstado}):");
    foreach (string error in validacion.Errores)
    {
        Console.WriteLine($" - {error}");
    }
}
```

Con el `comprobante.json` del [Quickstart](#quickstart-de-la-api-key-al-ride),
el programa imprime `Comprobante valido`. Si cambias el `valor` de un impuesto
para que no coincida con su base y su tarifa, imprime el error
`$.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa.`

Un comprobante válido no garantiza que la emisión se acepte: la validación no
comprueba tu cupo ni si ya emitiste ese comprobante. El detalle está en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir). También puedes
validar desde la vista de un contribuyente con
`client.Para(identificacion).ValidarAsync(comprobante)`.

### Validar antes de cada emisión

Es opcional y viene apagada. Con `ValidarAntesDeEmitir = true` en
`EcuafactClientOptions`, `EmitirAsync` llama primero a `/validar` y emite solo si
la API da el comprobante por válido; son 2 peticiones por emisión. Con el valor
por defecto (`false`) `EmitirAsync` envía directo, hace 1 petición y, si el
comprobante no cumple, la API responde 422 y el SDK lanza
`EcuafactValidationException` con `Errores`. Con la opción activa, si
`Valido` es `false` el SDK lanza esa misma excepción (422, `CodEstado` 3002) sin
emitir ni consumir cupo, y las advertencias de la validación quedan en
`EmisionResultado.Advertencias` (vacía si no hubo). Con inyección de
dependencias, la clave de configuración es `ValidarAntesDeEmitir`.

```csharp
using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    ValidarAntesDeEmitir = true
});
```

## Esperar el resultado

Después de emitir, el comprobante queda **recibido**, que es lo que significa el
`202 Accepted`, y el SRI responde en segundos o en minutos. Puedes conocer el
resultado de dos formas.

| Forma | Cómo | Cuándo usarla |
|---|---|---|
| Seguimiento | `GetOperacionAsync(idOperacion)` una vez, o `EsperarResultadoAsync(idOperacion)` en bucle. | Scripts, procesos por lotes o pantallas que esperan al usuario. |
| [Webhooks](#webhooks) | Te avisamos en tu URL cuando hay resultado. | Producción con muchos comprobantes: no ocupas tu proceso esperando. |

`EsperarResultadoAsync(idOperacion, intervalo?, maximo?, ct, opciones)` consulta
`GET /v1/operaciones/{idOperacion}` hasta que `EsFinal` es `true` o hasta que
pasa `maximo`, y devuelve la última `Operation` leída. No lanza una excepción
al agotar el tiempo, así que revisa `EsFinal` en el resultado.

| Parámetro | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
| `idOperacion` | `Guid` | - | El `Admission.IdOperacion` de la emisión. |
| `intervalo` | `TimeSpan?` | 5 s (`EcuafactClientExtensions.IntervaloEsperaPorDefecto`) | Espera entre consultas. Mayor que cero; si no, lanza `ArgumentOutOfRangeException`. |
| `maximo` | `TimeSpan?` | 120 s (`EcuafactClientExtensions.MaximoEsperaPorDefecto`) | Tiempo total de espera. No negativo; con `TimeSpan.Zero` consulta una sola vez. |
| `ct` | `CancellationToken` | `default` | Cancela la espera; lanza `OperationCanceledException`. |
| `opciones` | `RequestOptions?` | `null` | Se aplica a cada consulta (ver [Opciones por llamada](#opciones-por-llamada)). |

Cada consulta cuenta para tu límite de solicitudes por minuto; por eso no
conviene usar intervalos de menos de unos segundos.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

// Usa el idOperacion que devolvio tu emision.
Guid idOperacion = Guid.Parse("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
Operation operacion = await client.EsperarResultadoAsync(
    idOperacion, intervalo: TimeSpan.FromSeconds(10), maximo: TimeSpan.FromMinutes(5));

if (operacion.EsAutorizado)
{
    Console.WriteLine($"Autorizado. claveAcceso {operacion.ClaveAcceso}");
}
else if (operacion.EsFinal)
{
    Console.WriteLine($"Sin autorizacion: estado {operacion.Estado}, codEstado {operacion.CodEstado}: {operacion.MsgError}");
    foreach (string detalle in operacion.Errores)
    {
        Console.WriteLine($" - {detalle}");
    }
}
else
{
    Console.WriteLine($"Aun sin resultado ({operacion.Estado}): consulta mas tarde o espera el webhook.");
}
```

`Operation` trae los campos de [Seguimiento de una operación](/v1/guias/consulta-operacion):
`Estado`, `CodEstado`, `MsgError`, `Errores`, `IdOperacion`, `UrlEstado`,
`Ambiente`, `TipoDocumento`, `NumeroDocumento`, `ReferenciaExterna`,
`ClaveAcceso`, `FhRecibido` y `FhAutorizacion`, más las propiedades tipadas de
la sección siguiente. `MsgError` es la descripción fija del código y es `null`
mientras no hay error; el detalle, como el mensaje del SRI en un rechazo 3001
(`rechazo_sri`), llega en `Errores`. `FhRecibido` es el momento en que la API
aceptó la emisión, y `FhAutorizacion`, el de la autorización del SRI, cuando
existe. `Admission` tiene exactamente los mismos campos.

## Estados tipados

`Operation`, `Admission` y `Comprobante` conservan los campos de la API (`Estado`,
`CodEstado`, `TipoDocumento`) y agregan propiedades tipadas para comparar sin
errores de escritura. Un valor que tu versión del SDK no conoce 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`.

| Propiedad | Tipo | Valores |
|---|---|---|
| `Operation.EstadoOperacion`, `Comprobante.EstadoOperacion`, `Admission.EstadoOperacion` | `EstadoOperacion` | `Recibido`, `Autorizado`, `Rechazado`, `RechazoConfiguracion`, `Error`, `Cancelado`, `Desconocido` |
| `Operation.TipoComprobante`, `Comprobante.TipoComprobante` | `TipoComprobante?` | `Factura` (`01`), `LiquidacionCompra` (`03`), `NotaCredito` (`04`), `NotaDebito` (`05`), `GuiaRemision` (`06`), `Retencion` (`07`); `null` si el código no se conoce |
| `Operation.EsFinal`, `Comprobante.EsFinal` | `bool` | `true` si `estado` es cualquier valor distinto de `recibido`: `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. |
| `Operation.EsAutorizado`, `Comprobante.EsAutorizado` | `bool` | `true` si `estado` es `autorizado`. |
| `WebhookEvent.Tipo` | `TipoEventoWebhook` | `DocumentoAutorizado`, `DocumentoRechazado`, `DocumentoFallido`, `OperacionRequiereAtencion`, `Desconocido` |

Los enums están en `Ecuafact.Sdk.Contracts` (`TipoEventoWebhook`, en
`Ecuafact.Sdk.Webhooks`). `EstadosApi.ParseEstadoOperacion`,
`EstadosApi.ParseTipoComprobante` (devuelve `TipoComprobante?`) y
`EstadosApi.TipoDocumento(tipo)` convierten entre texto y enum, y
`EstadosApi.EsFinal(estado)` te dice si un estado es final. Los valores de
`codEstado` están como constantes `int` en la clase `CodEstado`, por ejemplo
`CodEstado.RechazoSri` (3001), `CodEstado.ComprobanteInvalido` (3002) o
`CodEstado.LimiteSolicitudes` (5005), y `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. Los valores de `estado` están en
`EstadosPublicos`, por ejemplo `EstadosPublicos.Recibido`.

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

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

Operation operacion = await client.GetOperacionAsync("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
string accion = operacion.EstadoOperacion switch
{
    EstadoOperacion.Autorizado => "Descarga el RIDE",
    EstadoOperacion.Rechazado when operacion.CodEstado == CodEstado.RechazoSri => "Corrige y emite un comprobante nuevo",
    EstadoOperacion.Recibido => "Consulta mas tarde",
    _ => $"Revisa codEstado {operacion.CodEstado}: {operacion.MsgError} {string.Join(" | ", operacion.Errores)}"
};
Console.WriteLine($"{operacion.TipoComprobante?.ToString() ?? "Tipo no reconocido"}: {accion}");
```

## Webhooks

Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle. Antes
de procesar una entrega, verifica que te la enviamos nosotros con
`WebhookEvent.ConstruirDesdeEntrega`, del espacio de nombres
`Ecuafact.Sdk.Webhooks`. Cada entrega trae dos firmas, la cabecera
`Ecuafact-Signature` y las cabeceras de
[Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks), y este método
acepta cualquiera de las dos.

`WebhookEvent.ConstruirDesdeEntrega(secretos, cabeceras, cuerpo, tolerancia?)`
recibe las cabeceras de la petición, ya sea como una función que devuelve el
valor por nombre (`nombre => request.Headers[nombre]`) o como pares
nombre-valor, y las comprueba contra el cuerpo **crudo**. Si alguna firma es
válida, devuelve el evento tipado. Si ninguna coincide, está fuera de la
tolerancia (300 s por defecto, `WebhookSignature.DefaultTolerance`) o el cuerpo
no es un evento JSON, lanza `EcuafactWebhookException`. Los secretos se aceptan
con o sin el prefijo `whsec_`.

Si solo recibes la firma `Ecuafact-Signature` (`t=<epoch>,v1=<hmac>`), puedes
usar `WebhookEvent.Construir(secretos, cabecera, cuerpo, tolerancia?)`, que
verifica solo esa cabecera y se comporta igual.

| Parámetro | Tipo | Descripción |
|---|---|---|
| `secretos` | `IEnumerable<string>` o `string` | Secreto del destino, que ves al crearlo. Con una lista, la entrega es válida si coincide con cualquiera. |
| `cabeceras` | `Func<string, string?>` o `IEnumerable<KeyValuePair<string, string>>` | Cabeceras de la petición. En `Construir` se pasa en su lugar `cabecera`, un `string` con el valor de `Ecuafact-Signature` (nombre en `WebhookSignature.HeaderName`). |
| `cuerpo` | `string` o `byte[]` | Cuerpo crudo, tal como llegó. |
| `tolerancia` | `TimeSpan?` | Antigüedad máxima de la firma. Por defecto 300 s. |

Con una lista de secretos 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 SDK no administra los destinos de webhooks, solo verifica la firma y construye
el evento. Los destinos los creas, listas, pausas y rotas 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).

El ejemplo siguiente usa ASP.NET Core con una minimal API. Guarda tu secreto en
`ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en
`ECUAFACT_WEBHOOK_SECRET_ANTERIOR`.

```csharp
// Program.cs de un proyecto creado con: dotnet new web
// Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run
using Ecuafact.Sdk;
using Ecuafact.Sdk.Webhooks;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
WebApplication app = builder.Build();

string[] secretos = new[]
{
    Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET"),
    Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET_ANTERIOR")
}.OfType<string>().Where(s => s.Length > 0).ToArray();

app.MapPost("/webhooks/ecuafact", async (HttpRequest request) =>
{
    using MemoryStream copia = new();
    await request.Body.CopyToAsync(copia);
    byte[] cuerpoCrudo = copia.ToArray();

    WebhookEvent evento;
    try
    {
        evento = WebhookEvent.ConstruirDesdeEntrega(secretos, nombre => request.Headers[nombre], cuerpoCrudo);
    }
    catch (EcuafactWebhookException)
    {
        return Results.Unauthorized();
    }

    // Deduplica por EventTypeRaw + ResourceId antes de procesar y responde 2xx.
    switch (evento.Tipo)
    {
        case TipoEventoWebhook.DocumentoAutorizado:
            Console.WriteLine($"Autorizado {evento.IdOperacion} claveAcceso {evento.ClaveAcceso}");
            break;
        case TipoEventoWebhook.DocumentoRechazado:
            Console.WriteLine($"Rechazo fiscal {evento.IdOperacion}: codEstado {evento.CodEstado} {string.Join(" | ", evento.Errores)}");
            break;
        case TipoEventoWebhook.DocumentoFallido:
            Console.WriteLine($"No emitido {evento.IdOperacion}: estado {evento.Estado}, codEstado {evento.CodEstado}");
            break;
        default:
            Console.WriteLine($"Evento {evento.EventTypeRaw} (prueba: {evento.Probe})");
            break;
    }
    return Results.Ok();
});

app.Run();
```

| Propiedad de `WebhookEvent` | Tipo | Descripción |
|---|---|---|
| `Tipo` | `TipoEventoWebhook` | `DocumentoAutorizado`, `DocumentoRechazado`, `DocumentoFallido`, `OperacionRequiereAtencion` o `Desconocido` (un tipo nuevo). |
| `EventTypeRaw` | `string` | Texto original de `eventType` (`document.authorized`, `document.rejected`, `document.failed`, `operation.requires_attention`). |
| `ResourceId` | `string?` | Recurso del evento: el `idOperacion` en los eventos `document.*`. Úsalo con `EventTypeRaw` para descartar entregas repetidas. |
| `OccurredAtUtc` | `DateTimeOffset?` | Momento del evento (UTC). |
| `IdOperacion` | `Guid?` | Operación de la emisión. |
| `Estado` | `string?` | El mismo `estado` del seguimiento: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`, y `recibido` en el aviso `operation.requires_attention`. Su versión tipada es `EstadoOperacion`. |
| `TipoDocumento` | `string?` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. |
| `Ruc` | `string?` | Identificación del contribuyente emisor. Sirve para enrutar un destino compartido por varios contribuyentes; es `null` en el evento de prueba. |
| `ClaveAcceso` | `string?` | Clave de acceso. En `document.failed` puede faltar. |
| `CodEstado` | `int?` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Compáralo con las constantes de `CodEstado`. |
| `MsgError` | `string?` | Descripción fija del código; `null` cuando no hay error. |
| `Errores` | `IReadOnlyList<string>` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacía si no hay detalle. |
| `FhAutorizacion` | `DateTimeOffset?` | Fecha y hora de la autorización del SRI, cuando existe. |
| `Probe` | `bool` | `true` en el evento de prueba que envía el botón **Probar** del portal (`operation.requires_attention`). |

Si solo necesitas saber si la firma es válida, usa
`WebhookSignature.VerificarEntrega(secretos, cabeceras, cuerpo, tolerancia?)`, que
acepta cualquiera de las dos firmas, o
`WebhookSignature.Verify(secretos, cabecera, cuerpo, tolerancia?)`, que comprueba
solo `Ecuafact-Signature`. Los dos devuelven `bool` y no lanzan ante una firma o
cabecera inválida; aceptan un secreto o una lista, y el cuerpo como `string` o
`byte[]`. `StandardWebhookSignature.Verify(secreto, id, timestamp, firma, cuerpo, tolerancia?)`
comprueba solo la firma de Standard Webhooks con los valores de `webhook-id`,
`webhook-timestamp` y `webhook-signature`.

> [!WARNING]
> Verifica la firma sobre el cuerpo crudo, tal como llegó. Si deserializas y
> vuelves a serializar el JSON, la firma no coincide.

Cada verificación termina de una de estas maneras, y en todas las que no son válidas debes responder 401 sin procesar el evento.

| Situación | `Construir` y `ConstruirDesdeEntrega` | `Verify` y `VerificarEntrega` |
|---|---|---|
| Firma válida | Devuelven el `WebhookEvent` tipado. | Devuelven `true`. |
| Cuerpo alterado, aunque sea por un espacio | Lanzan `EcuafactWebhookException`. | Devuelven `false`. |
| Firma vencida (más antigua que la tolerancia) o con fecha futura | Lanzan `EcuafactWebhookException`. | Devuelven `false`. |
| Secreto equivocado o ninguno de la lista coincide | Lanzan `EcuafactWebhookException`. | Devuelven `false`. |
| Cabecera ausente, vacía o mal formada | Lanzan `EcuafactWebhookException`. | Devuelven `false`, sin lanzar. |
| Firma válida, pero el cuerpo no es un evento JSON | Lanzan `EcuafactWebhookException`. | Devuelven `true`: la firma es correcta. |

Puedes probar tu receptor sin esperar un evento real. El programa siguiente firma un
cuerpo de ejemplo con tu secreto y lo envía a tu endpoint local; si el receptor del
ejemplo anterior está funcionando en `http://localhost:5000`, responde 200. Si
cambias una letra del cuerpo después de firmarlo, responde 401.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
// Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run
using System.Text;
using Ecuafact.Sdk.Webhooks;

string secreto = Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!;
string cuerpo = "{\"eventType\":\"operation.requires_attention\",\"probe\":\"true\"}";
string firma = WebhookSignature.Sign(secreto, DateTimeOffset.UtcNow.ToUnixTimeSeconds(), cuerpo);

using HttpClient http = new();
using HttpRequestMessage peticion = new(HttpMethod.Post, "http://localhost:5000/webhooks/ecuafact")
{
    Content = new StringContent(cuerpo, Encoding.UTF8, "application/json")
};
peticion.Headers.Add(WebhookSignature.HeaderName, firma);
HttpResponseMessage respuesta = await http.SendAsync(peticion);
Console.WriteLine((int)respuesta.StatusCode);
```

Responde con un 2xx en cuanto verifiques y registres el evento, y deja el
procesamiento pesado para después. Qué hacer ante cada evento está en
[Webhooks](/v1/guias/webhooks#que-hacer-ante-cada-evento); por ejemplo, ante
`document.rejected` corriges el comprobante y lo emites con una
`Idempotency-Key` y una `referenciaExterna` nuevas. Decide siempre con `Estado`
y `CodEstado`, no solo con el tipo del evento.

Los eventos (`document.authorized`, `document.rejected`, `document.failed` y
el aviso `operation.requires_attention`, que también es el de prueba) y su contenido están en
[Webhooks](/v1/guias/webhooks); el algoritmo, en
[Verificación de firma](/v1/guias/webhooks-firma).

## Errores

Todas las excepciones del SDK heredan de `EcuafactSdkException`, y las que
vienen de una respuesta de la API heredan además de `EcuafactApiException`.
Captura primero las específicas y al final las generales: un
`catch (EcuafactApiException)` atrapa todas las respuestas de error de la API, y
un `catch (EcuafactSdkException)`, 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, contiene credenciales, query string o fragmento, o termina en `/v1`; la API Key tiene espacios o caracteres de control; `MaxAttempts` es menor que 1 o un tiempo es inválido. | Corrige la configuración. No llama a la API. |
| `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API (DNS, TLS, conexión rechazada o cortada) tras agotar los intentos. | Reintenta más tarde con la misma `IdempotencyKey`. `EsReintentable` es `true`. |
| `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `Timeout` en el último intento o `TotalTimeout` de la llamada. | Reintenta con la misma `IdempotencyKey`; si emitías, consulta antes el seguimiento. `EsReintentable` es `true`. |
| `EcuafactResponseTooLargeException` | `EcuafactSdkException` | La respuesta superó `MaxResponseBytes` (o `MaxFileResponseBytes` en una descarga). Trae `Limite`, `BytesLeidos` e `IdempotencyKey`. | Sube el tope en las opciones o en esa llamada (`0` lo quita) si esperas una respuesta de ese tamaño. Si emitías, conserva la `IdempotencyKey` y consulta el seguimiento. |
| `EcuafactInvalidResponseException` | `EcuafactSdkException` | La API respondió con éxito (2xx), pero el cuerpo no se puede leer como el contrato, por ejemplo porque un proxy lo truncó. Trae `EstadoHttp`, `CorrelationId` e `IdempotencyKey`. | Si estabas emitiendo, la operación pudo haberse creado: repite la emisión con la misma `IdempotencyKey` para recuperar su resultado sin duplicar el comprobante. Si consultabas o validabas, repite la llamada. |
| `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo que no es un evento 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. No reintentes sin cambiar nada. |
| `EcuafactValidationException` | `EcuafactApiException` | HTTP 400 o 422, con el `CodEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3007 (`version_no_soportada`) o 3012 (`filtros_invalidos`). | Corrige según `Errores`. Un 422 consume 1 documento como intento. |
| `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 desactivaste `RetryRateLimited`. |
| `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `CodEstado` 4004 (`cupo_agotado`). | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes, porque esperar no lo repone. |
| `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. | Reintenta más tarde con la misma `IdempotencyKey`. Un 501 no se reintenta. |
| `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API, por ejemplo 413 con el `CodEstado` 3006 (`cuerpo_excedido`). | Revisa `CodEstado`, `MsgError` y `Errores`. |
| `EcuafactSdkException` | `Exception` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, falta el contribuyente por defecto, falta un dato obligatorio de una consulta (`apellidos`, `ruc`), cliente con nombre no registrado en inyección de dependencias o respuesta no reconocida. | Corrige la llamada. |

Además, el SDK usa excepciones estándar de .NET que no heredan de
`EcuafactSdkException`:

| Excepción | Cuándo ocurre | Qué hacer |
|---|---|---|
| `OperationCanceledException` | Cancelaste el `CancellationToken` que pasaste al método. | Nada: es tu cancelación. Si cancelaste una emisión, consulta el seguimiento antes de reenviarla con la misma `Idempotency-Key`. |
| `ArgumentNullException`, `ArgumentException`, `ArgumentOutOfRangeException` | Argumento nulo o vacío (comprobante, destinatario, archivo del logo), o `intervalo` o `maximo` inválidos en `EsperarResultadoAsync`. | Corrige el argumento. No se llamó a la API. |

Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción
conserva la `Idempotency-Key` y el correlativo de la solicitud; repite la emisión
con esa misma clave y no se duplica el comprobante. En .NET, esa excepción es
`EcuafactInvalidResponseException`, que trae la clave en `IdempotencyKey` y el
`X-Correlation-Id` en `CorrelationId`.

`EcuafactApiException` y todas sus subclases tienen estas propiedades:

| Propiedad | 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 en tu código; las constantes están en `CodEstado`. Es 0 si la respuesta no trajo un cuerpo de error de la API. |
| `Estado` | `string?` | `estado` de la respuesta de error: `rechazado`, `rechazo_configuracion` o `error`. Su versión tipada es `EstadoOperacion`, que se deduce del primer dígito de `CodEstado` si el campo no llegó. |
| `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 de la respuesta. |
| `Errores` | `IReadOnlyList<string>` | Detalle específico del error, como la ruta del campo que falla en un 3002. Vacía cuando no hay detalle. |
| `CorrelationId` | `string?` | Valor de la cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. |
| `IdempotencyKey` | `string?` | Clave usada en la llamada (solo emisión). Reutilízala al reintentar. |
| `RetryAfter` | `TimeSpan?` | Espera indicada por la cabecera `Retry-After`; `null` si no llegó. |
| `EsReintentable` | `bool` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `CodEstado` 5005. El 429 con 4004 (cupo agotado) y un 501 no son reintentables. |

```csharp
using System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});
FacturaRequest comprobante = JsonSerializer.Deserialize<FacturaRequest>(
    await File.ReadAllTextAsync("comprobante.json"))!;

try
{
    EmisionResultado r = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
    Console.WriteLine($"{r.Admission.Estado} {r.Admission.IdOperacion}");
}
catch (EcuafactValidationException error)
{
    // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual.
    foreach (string detalle in error.Errores) Console.WriteLine(detalle);
}
catch (EcuafactQuotaException)
{
    Console.WriteLine("Cupo agotado: compra un paquete. No reintentes.");
}
catch (EcuafactRateLimitException error)
{
    Console.WriteLine($"Limite de solicitudes: espera {error.RetryAfter?.TotalSeconds ?? 1} s y reintenta con {error.IdempotencyKey}.");
}
catch (EcuafactApiException error) when (error.EsReintentable)
{
    Console.WriteLine($"{error.EstadoHttp} codEstado {error.CodEstado}: reintenta mas tarde con {error.IdempotencyKey}.");
}
catch (EcuafactApiException error)
{
    Console.WriteLine($"{error.EstadoHttp} codEstado {error.CodEstado} {error.MsgError} correlation={error.CorrelationId}");
}
catch (EcuafactInvalidResponseException error)
{
    Console.WriteLine($"Respuesta {error.EstadoHttp} ilegible: repite la emision con la MISMA Idempotency-Key ({error.IdempotencyKey}), correlation={error.CorrelationId}.");
}
catch (EcuafactConnectionException error)
{
    Console.WriteLine($"Sin conexion: reintenta mas tarde con la MISMA Idempotency-Key ({error.IdempotencyKey}).");
}
catch (EcuafactTimeoutException error)
{
    Console.WriteLine($"Sin respuesta a tiempo: consulta el seguimiento o reintenta con {error.IdempotencyKey}.");
}
```

Estos son los códigos que verás con más frecuencia. El catálogo completo está en
[Errores](/v1/guias/errores#catalogo-de-codestado), y cada constante de la clase
`CodEstado` lleva el nombre de la columna **Nombre** en PascalCase, por ejemplo
`CodEstado.CredencialesInvalidas`.

| `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 revisa proxies intermedios; si persiste, contacta a soporte con el `CorrelationId`. |
| 3011 | `acceso_denegado` | 403 | Contribuyente o tipo de comprobante no habilitado para tu API Key. | Revisa `GetContextoAsync()` (`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 de llamadas. |
| 3003 | `solicitud_invalida` | 400 | Cabeceras inválidas (por ejemplo, falta `Idempotency-Key`) 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 | Un filtro de consulta está fuera de rango (fechas o `max`). | Ajusta los filtros a los [límites](/v1/guias/limites). |
| 3006 | `cuerpo_excedido` | 413 | El cuerpo supera 2 MiB. | Reduce el comprobante. |
| 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 misma `referenciaExterna`) con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. |
| 4004 | `cupo_agotado` | 429 | Cupo de documentos agotado. El SDK no lo reintenta. | Revisa `GetConsumoAsync()`; compra un paquete. |
| 3013 | `no_encontrado` | 404 | Operación, comprobante o RIDE no encontrado. | Verifica el `idOperacion` o la `claveAcceso`; 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, de una caída de la red o de un
reinicio de tu proceso.

- Si no pasas `idempotencyKey`, el SDK genera una (un GUID sin guiones), la usa
  en todos sus reintentos y te la devuelve en `EmisionResultado.IdempotencyKey`
  o, si la llamada falla, en la propiedad `IdempotencyKey` de la excepción.
- Te recomendamos pasar un valor estable por intención, por ejemplo tu número
  interno de factura (`FACTURA-2026-0001`), y guárdalo 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.
- `GetOperacionAsync` con `string` exige un UUID (con o sin guiones); si no lo
  es, 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.

La tabla resume qué reintenta el SDK por ti y qué queda en tus manos.

| Situación | Se reintenta | Detalle |
|---|---|---|
| HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `RetryableStatusCodes`. Solo en `GET`, en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva) y en el cambio de logo. |
| HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `RetryRateLimited = false` | Espera lo que indica `Retry-After` y reintenta. Con `RetryRateLimited = false` lanza `EcuafactRateLimitException` con `RetryAfter`, y decides tú cuándo reintentar. |
| HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. |
| Error de red o timeout de un intento | Sí | Mismas condiciones. Al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. |
| Descarga de RIDE/XML y cambio de logo | Sí | Se reintentan ante los mismos estados HTTP y errores de red. El cambio de logo no lleva `Idempotency-Key`, pero lo reintentamos porque subir el mismo archivo otra vez deja el perfil igual. |
| `ActualizarPerfilAsync` | No | No lleva `Idempotency-Key`; un reintento automático podría repetir el efecto. |
| Cualquier otro 4xx | No | Es un error que debes corregir; se lanza la excepción de inmediato. |

Entre intentos, el SDK espera `RetryBaseDelay` x intento con `Linear` o
`RetryBaseDelay` x 2^(intento-1) con `Exponential`, más un margen aleatorio de 0
a `RetryJitter` x intento. Si la respuesta trae un `Retry-After` mayor y
`RespectRetryAfter` es `true`, espera ese tiempo. La espera nunca supera
`MaxRetryDelay`. Si configuraste `TotalTimeout` y la siguiente espera no cabe
en él, el SDK no reintenta y lanza la última excepción. Con los valores por
defecto hay como máximo 3 intentos por llamada, con esperas de unos 200 y
400 ms.

El ejemplo siguiente configura reintentos exponenciales, reintenta el 429 por
límite de solicitudes y fija un tope de 1 minuto por llamada.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    MaxAttempts = 5,
    RetryBackoff = RetryBackoff.Exponential, // 500 ms, 1 s, 2 s, 4 s
    RetryBaseDelay = TimeSpan.FromMilliseconds(500),
    RetryRateLimited = true,
    MaxRetryDelay = TimeSpan.FromSeconds(30),
    TotalTimeout = TimeSpan.FromMinutes(1)
});

QuotaBucket cupo = await client.GetConsumoAsync();
Console.WriteLine($"Disponibles: {cupo.Disponibles} de {cupo.LimiteDocumentos}");
```

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

Todo método que llama a la API acepta, como último parámetro,
`RequestOptions? opciones = null`. Incluye `EsperarResultadoAsync` y la vista
`Para(...)`. Cada
campo con valor reemplaza la configuración del cliente solo en esa llamada; un
campo `null` conserva la del cliente.

| Campo | Tipo | Valor por defecto | Qué hace |
|---|---|---|---|
| `Timeout` | `TimeSpan?` | `null` (usa `EcuafactClientOptions.Timeout`) | Tiempo máximo de cada intento de esta llamada. Mayor que cero o `Timeout.InfiniteTimeSpan`. |
| `TotalTimeout` | `TimeSpan?` | `null` (usa `EcuafactClientOptions.TotalTimeout`) | Tope de toda la llamada, incluidos reintentos y esperas. Al superarlo lanza `EcuafactTimeoutException`. Mayor que cero. |
| `CorrelationId` | `string?` | `null` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres: letras y dígitos ASCII y `.` `_` `-`. |
| `Reintentos` | `bool?` | `null` (política del cliente) | `false` hace un solo intento en esta llamada. `true` o `null` conservan la política del cliente: no reactivan los reintentos si `RetryTransientFailures` es `false`. |
| `MaxResponseBytes` | `long?` | `null` (usa `EcuafactClientOptions.MaxResponseBytes` o, en una descarga, `MaxFileResponseBytes`) | Tamaño máximo de la respuesta de esta llamada, en bytes. `0` quita el tope solo en esta llamada. No admite negativos. |
| `AdditionalInfo` | `string?` | `null` (usa `EcuafactClientOptions.AdditionalInfo`) | Valor de la cabecera `X-Additional-Info` solo en esta llamada; reemplaza el del cliente. Cadena vacía: no se envía la cabecera en esta llamada. Mismas reglas que la opción del cliente. |

La cancelación se hace con el `CancellationToken` de cada método: cancela el
intento en curso y las esperas entre reintentos.

La API devuelve la correlación que enviaste. La encuentras en
`EmisionResultado.CorrelationId`, en `EcuafactApiException.CorrelationId` y en
`CorrelationId` de `EcuafactConnectionException` y `EcuafactTimeoutException`.
Úsala para relacionar tus registros con los nuestros y para pedirnos soporte.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
// Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

// Un solo intento y correlacion propia para esta consulta.
Contexto contexto = await client.GetContextoAsync(opciones: new RequestOptions
{
    Reintentos = false,
    CorrelationId = "pedido-2026-0457"
});
Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}");

// Mas tiempo para una descarga grande, con tope total de 2 minutos.
ArchivoComprobante ride = await client.DescargarRideAsync(
    "0123456789001",
    "0710202601012345678900110010010000001231234567811",
    opciones: new RequestOptions
    {
        Timeout = TimeSpan.FromSeconds(60),
        TotalTimeout = TimeSpan.FromMinutes(2)
    });
await File.WriteAllBytesAsync("ride.pdf", ride.Contenido);
```

Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu
emisor.

| Error | Por qué pasa | Qué hacer |
|---|---|---|
| `EcuafactConfigurationException` sin llamar a la API | Un `CorrelationId` vacío, con espacios o de más de 64 caracteres, un tiempo menor o igual a cero, un `MaxResponseBytes` negativo, o un `AdditionalInfo` con caracteres fuera de ASCII imprimible, espacios al inicio o al final o más de 256 caracteres. | Corrige el valor de `RequestOptions`. |
| `EcuafactConfigurationException` con `IEcuafactClient` | Pasaste `opciones` a una implementación propia de `IEcuafactClient`. Con la interfaz, las sobrecargas son métodos de extensión que solo funcionan con la instancia que entrega el SDK (`EcuafactClient` o la registrada por inyección de dependencias). | Usa la instancia del SDK o pasa `opciones` nulo. |
| La llamada se corta antes del `Timeout` por llamada | Usas tu propio `HttpClient` y su `HttpClient.Timeout` es menor. | Sube `HttpClient.Timeout` o configúralo en `Timeout.InfiniteTimeSpan`. `EcuafactClient.Create` y el registro por inyección de dependencias ya lo dejan infinito. |

## 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` | Se envía en todas las solicitudes del cliente, incluidas las de `EsperarResultadoAsync` y la vista `Para(...)`. |
| `RequestOptions.AdditionalInfo` | Reemplaza el valor del cliente solo en esa llamada. `null` conserva el del cliente; cadena vacía no envía la cabecera en esa llamada. |

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

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

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

```csharp
// Program.cs de un proyecto creado con: dotnet new console
// Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    AdditionalInfo = "erp=MiERP/4.2; sucursal=001"
});

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

// Solo esta llamada lleva otro valor.
Contexto otro = await client.GetContextoAsync(opciones: new RequestOptions
{
    AdditionalInfo = "erp=MiERP/4.2; sucursal=002; lote=2026-10-08"
});
Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}");
```

Con inyección de dependencias asígnalo en `AddEcuafactClient` o con la clave
`AdditionalInfo` de la sección de configuración.

| Error | Por qué pasa | Qué hacer |
|---|---|---|
| `EcuafactConfigurationException` al crear o resolver 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` en una llamada | El mismo problema en `RequestOptions.AdditionalInfo`. No se llamó a la API. | Corrige el valor de esa llamada. |

## HttpClient propio, proxy y TLS

Si tu red sale a internet por un proxy, necesitas un certificado propio o
quieres limitar el tiempo de conexión, puedes configurar la conexión de tres
formas.

| Forma | Cuándo usarla | Quién libera el `HttpClient` |
|---|---|---|
| `EcuafactClient.Create(options)` con `options.Handler` | Aplicación de consola o servicio sin contenedor de dependencias. | El cliente libera su `HttpClient` al llamar `Dispose`; el handler es tuyo (el SDK no lo libera). |
| `AddEcuafactClient` con `options.Handler` | ASP.NET Core o Worker Service. El handler entra como handler principal de `IHttpClientFactory` (ver [Proxy, TLS y handlers propios](#proxy-tls-y-handlers-propios)). | `IHttpClientFactory`. El handler es tuyo: ni el SDK ni la fábrica lo liberan. |
| `new EcuafactClient(httpClient, options)` | Ya tienes un `HttpClient` (por ejemplo, de `IHttpClientFactory`). `options.Handler` no se usa. | Tú. `Dispose` del cliente no lo libera. |

Con un `HttpClient` propio, el SDK aplica igual en cada solicitud la API Key,
`Timeout` (por intento) y `UserAgent`, y usa la `BaseAddress` de las opciones o,
si es `null`, la del `HttpClient`. Su `HttpClient.Timeout` es también un tope:
si es menor que `Timeout`, la llamada se corta antes y lanza
`EcuafactTimeoutException`. Déjalo en `Timeout.InfiniteTimeSpan` para que mande
el `Timeout` del SDK.

El transporte predeterminado desactiva las redirecciones automáticas y las
cookies. Si proporcionas un handler o un `HttpClient`, configura también
`AllowAutoRedirect = false` y `UseCookies = false` en su transporte; el SDK no
puede cambiar las opciones de un cliente que ya construiste. Usa directamente
la URL HTTPS final del servicio.

Este ejemplo usa `Handler` para configurar un proxy y el tiempo de conexión, y
además ajusta los reintentos. `SocketsHttpHandler.ConnectTimeout` existe en
.NET 5 o superior; en .NET Framework usa `HttpClientHandler` con su propiedad
`Proxy`.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
using System.Net;
using System.Net.Http;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using SocketsHttpHandler handler = new()
{
    AllowAutoRedirect = false,
    UseCookies = false,
    Proxy = new WebProxy("http://proxy.miempresa.local:8080"),
    ConnectTimeout = TimeSpan.FromSeconds(10)
};

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    RetryBackoff = RetryBackoff.Exponential,
    RetryBaseDelay = TimeSpan.FromMilliseconds(500),
    RetryRateLimited = true,
    TotalTimeout = TimeSpan.FromMinutes(1),
    Handler = handler
});

Console.WriteLine(client.Options); // la API Key aparece como ***
Contexto contexto = await client.GetContextoAsync();
Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}");
```

Y este otro usa tu propio `HttpClient`:

```csharp
// Program.cs de un proyecto creado con: dotnet new console
using System.Net.Http;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using HttpClientHandler handler = new() { AllowAutoRedirect = false, UseCookies = false };
using HttpClient http = new(handler)
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    Timeout = Timeout.InfiniteTimeSpan // el SDK aplica su Timeout por intento
};

EcuafactClient client = new(http, new EcuafactClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

Contexto contexto = await client.GetContextoAsync();
Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}");
```

En ASP.NET Core usa [Proxy, TLS y handlers propios](#proxy-tls-y-handlers-propios)
con `IHttpClientFactory`.

## Inyección de dependencias

En ASP.NET Core o en un Worker Service, instala también el paquete
`Ecuafact.Sdk.Core`.

```bash
dotnet add package Ecuafact.Sdk.Core
```

Registra el cliente en `Program.cs`. La configuración de .NET lee las variables
de entorno, así que `ECUAFACT_API_KEY` está disponible en `builder.Configuration`:

```csharp
using Ecuafact.Sdk;
using Ecuafact.Sdk.Core;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddEcuafactClient(o =>
{
    o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/");
    o.ApiKey = builder.Configuration["ECUAFACT_API_KEY"]!;
    // o.Identificacion = "0123456789001"; // solo si usas un unico contribuyente
});

WebApplication app = builder.Build();

app.MapGet("/contexto", async (IEcuafactClient client) =>
{
    var contexto = await client.GetContextoAsync();
    return Results.Ok(contexto.Contribuyentes);
});

app.Run();
```

`AddEcuafactClient` registra un `HttpClient` administrado por
`IHttpClientFactory` y expone `IEcuafactClient` como transient, de modo que cada
resolución crea un cliente liviano sobre el `HttpClient` de la fábrica. Si no asignas
`ApiKey` ni `BaseAddress`, se leen `ECUAFACT_API_KEY` y `ECUAFACT_BASE_URL`.
Las opciones se validan al resolver el cliente, no al registrarlo: una
configuración inválida lanza `EcuafactConfigurationException` la primera vez
que se inyecta. Inyéctalo en tus servicios:

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

public sealed class Facturacion(IEcuafactClient client)
{
    public async Task<string> EmitirAsync(FacturaRequest comprobante, string numeroInterno, CancellationToken ct)
    {
        EmisionResultado r = await client.EmitirAsync("0123456789001", comprobante, numeroInterno, ct);
        return r.Admission.IdOperacion.ToString();
    }
}
```

### Desde configuración

También puedes registrar el cliente desde una sección de `appsettings.json`:

```json
{
  "Ecuafact": {
    "BaseAddress": "https://api-sandbox.mynexusapi.com/",
    "Identificacion": "0123456789001",
    "MaxAttempts": 3,
    "RetryRateLimited": true,
    "RetryBackoff": "Exponential",
    "TotalTimeout": "00:01:00",
    "RetryableStatusCodes": [
      408,
      425,
      500,
      502,
      503,
      504
    ]
  }
}
```

```csharp
using Ecuafact.Sdk.Core;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddEcuafactClient(builder.Configuration.GetSection("Ecuafact"));
WebApplication app = builder.Build();
app.Run();
```

La sección admite estas claves: `BaseAddress` (o `BaseUrl`), `ApiKey`, `Identificacion`,
`Timeout`, `UserAgent`, `RetryTransientFailures`, `MaxAttempts`,
`RespectRetryAfter`, `MaxRetryDelay`, `RetryRateLimited`,
`RetryableStatusCodes`, `RetryBaseDelay`, `RetryBackoff`, `RetryJitter`,
`TotalTimeout`, `MaxResponseBytes`, `MaxFileResponseBytes` (en bytes; `0` quita el tope) y `AdditionalInfo`. Los tiempos aceptan `hh:mm:ss` o segundos.

> [!WARNING]
> No guardes la API Key en `appsettings.json` ni en el repositorio. Usa
> `ECUAFACT_API_KEY`, secretos de usuario o un almacén de secretos.

### Proxy, TLS y handlers propios

`AddEcuafactHttpClient` registra el cliente y devuelve el `IHttpClientBuilder`
de su `HttpClient`, para configurar el handler principal (proxy, certificados,
tiempo de conexión) o agregar tus propios handlers:

```csharp
using System.Net;
using System.Net.Http;
using Ecuafact.Sdk.Core;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddEcuafactHttpClient(o =>
    {
        o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/");
        o.ApiKey = builder.Configuration["ECUAFACT_API_KEY"]!;
    })
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        AllowAutoRedirect = false,
        UseCookies = false,
        Proxy = new WebProxy("http://proxy.miempresa.local:8080"),
        ConnectTimeout = TimeSpan.FromSeconds(10)
    });

WebApplication app = builder.Build();
app.Run();
```

Para un cliente ya registrado con `AddEcuafactClient`, obtén el mismo builder con
`builder.Services.ConfigureEcuafactHttpClient("nombre")` (sin nombre, el cliente
por defecto).

También puedes asignar `options.Handler` en `AddEcuafactClient`: entra como
handler principal del `HttpClient` de la fábrica, así que todas las
resoluciones comparten sus conexiones y `AddHttpMessageHandler` sigue
funcionando. La fábrica no libera tu handler al rotar. Crea la instancia fuera
de la lambda de configuración, porque la lambda se ejecuta en cada resolución
y en cada rotación de la fábrica:

```csharp
using System.Net;
using System.Net.Http;
using Ecuafact.Sdk.Core;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

SocketsHttpHandler proxy = new()
{
    AllowAutoRedirect = false,
    UseCookies = false,
    Proxy = new WebProxy("http://proxy.miempresa.local:8080"),
    ConnectTimeout = TimeSpan.FromSeconds(10)
};

builder.Services.AddEcuafactClient(o =>
{
    o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/");
    o.ApiKey = builder.Configuration["ECUAFACT_API_KEY"]!;
    o.Handler = proxy;
});

WebApplication app = builder.Build();
app.Run();
```

Si además llamas a `ConfigurePrimaryHttpMessageHandler` sobre el builder que
devuelve `AddEcuafactHttpClient` o `ConfigureEcuafactHttpClient`, ese handler
tiene prioridad sobre `options.Handler`.

### Varias API Key

Si usas varias API Key, por ejemplo para dos integraciones distintas, registra
clientes con nombre y obtenlos con `IEcuafactClientProvider`.

```csharp
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
using Ecuafact.Sdk.Core;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddEcuafactClient("integracionA", o =>
{
    o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/");
    o.ApiKey = builder.Configuration["ECUAFACT_API_KEY_A"]!;
});
builder.Services.AddEcuafactClient("integracionB", builder.Configuration.GetSection("EcuafactB"));
builder.Services.AddTransient<Multi>();

WebApplication app = builder.Build();
app.MapGet("/contexto-a", async (Multi multi) => Results.Ok(await multi.ContextoAAsync()));
app.Run();

public sealed class Multi(IEcuafactClientProvider provider)
{
    public Task<Contexto> ContextoAAsync() => provider.GetClient("integracionA").GetContextoAsync();
}
```

`IEcuafactClient` solo se inyecta directamente para el cliente sin nombre; los
clientes con nombre se obtienen con `provider.GetClient("nombre")`. Un nombre no
registrado lanza `EcuafactSdkException`.

## Constructores de comprobantes

Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en
lugar de escribir el JSON. Los constructores solo ensamblan el cuerpo con los
valores que les entregas: no calculan subtotales, impuestos, totales ni
redondeos, no completan valores por defecto y no validan reglas de negocio. Esas
reglas viven solo en la API, que calcula y valida al emitir (o en
[`ValidarAsync`](#validar-sin-emitir)).

Los constructores son opcionales y están en `Ecuafact.Sdk.Builders`. Producen el
mismo request de su tipo (`FacturaRequest`, `NotaCreditoRequest`...) que armas a mano.

```csharp
// Program.cs de un proyecto creado con: dotnet new console
// Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run
using Ecuafact.Sdk;
using Ecuafact.Sdk.Builders;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

// Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor.
// Los importes los entregas tu; el SDK no los calcula.
Impuesto iva = new() { Codigo = "2", CodigoPorcentaje = "4", Tarifa = 15m, BaseImponible = 10.00m, Valor = 1.50m };
FacturaRequest comprobante = ComprobanteBuilder.Factura("0123456789001", "001", "001")
    .Referencias("MiERP", "FACTURA-2026-0002")
    .FechaEmision(DateTime.UtcNow.AddHours(-5).Date) // fecha de hoy en Ecuador
    .Comprador("07", "9999999999999", "CONSUMIDOR FINAL")
    .Linea("SERV-001", "Servicio de prueba", 1m, 10.00m, 0m, 10.00m, iva)
    .Configurar(r =>
    {
        r.Info!.TotalSinImpuestos = 10.00m;
        r.Info.TotalDescuento = 0m;
        r.Info.TotalConImpuestos = new List<Impuesto> { iva };
        r.Info.ImporteTotal = 11.50m;
        r.Info.Propina = 0m;
        r.Info.Moneda = "DOLAR";
    })
    .Pago("01", 11.50m)
    .Construir();

EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0002",
    opciones: new RequestOptions { CorrelationId = "pedido-2026-0458" });
Console.WriteLine($"{resultado.Admission.Estado} {resultado.Admission.IdOperacion} {resultado.CorrelationId}");
```

Deberías ver `recibido <idOperacion> pedido-2026-0458`. Si falta o no cuadra algún
importe, la API responde 422 (`codEstado` 3002) con `errores`. Si ejecutas el programa otro día con la
misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005; en ese caso usa una
`Idempotency-Key` y una `referenciaExterna` nuevas.

| Tipo | Entrada | Métodos propios |
|---|---|---|
| Factura (`01`) | `ComprobanteBuilder.Factura(ruc, estab, ptoEmi)` | `Comprador(tipoIdentificacion, identificacion, razonSocial, direccion?)`, `Linea`, `DetalleAdicional`, `Propina`, `Moneda`, `Pago(formaPago, total?, plazo?, unidadTiempo?)` |
| Liquidación de compra (`03`) | `ComprobanteBuilder.LiquidacionCompra(ruc, estab, ptoEmi)` | `Proveedor(tipoIdentificacion, identificacion, razonSocial, direccion?)`, `Linea`, `DetalleAdicional`, `Moneda`, `Pago` |
| Nota de crédito (`04`) | `ComprobanteBuilder.NotaCredito(ruc, estab, ptoEmi)` | `Comprador`, `DocumentoModificado(codDocModificado, numero, fechaEmision, totalDocumentoSustento?)`, `Motivo(motivo)`, `Linea` (el código va en `codigoInterno`), `DetalleAdicional`, `Moneda` |
| Nota de débito (`05`) | `ComprobanteBuilder.NotaDebito(ruc, estab, ptoEmi)` | `Comprador`, `DocumentoModificado(codDocModificado, numero, fechaEmision)`, `Impuestos(params Impuesto[])`, `Motivo(razon, valor)`, `Moneda`, `Pago` |
| Guía de remisión (`06`) | `ComprobanteBuilder.GuiaRemision(ruc, estab, ptoEmi)` | `DirPartida`, `Transportista(tipoIdentificacion, identificacion, razonSocial, placa)`, `Traslado(inicio, fin)`, `Destinatario(identificacion, razonSocial, direccion, motivoTraslado, codEstabDestino?, ruta?)`, `Detalle(codigoInterno, descripcion, cantidad)` |
| Retención (`07`) | `ComprobanteBuilder.Retencion(ruc, estab, ptoEmi)` | `SujetoRetenido`, `PeriodoFiscal(mes, anio)`, `ParteRelacionada`, `DocSustento(...)`, `ImpuestoDocSustento(...)`, `Retener(codigo, codigoRetencion, baseImponible, porcentajeRetener, valorRetenido?)`, `Pago` |

Todos los constructores tienen además `Referencias(origen, externa)`, `Secuencial`,
`DirEstablecimiento`, `InfoAdicional(nombre, valor)`,
`Configurar(Action<TRequest>)`, con el request del tipo (asigna cualquier campo tal cual) y
`Construir()`. `FechaEmision(DateTime)` existe en todos salvo la guía de
remisión, que usa `Traslado(inicio, fin)`; factura, liquidación de compra y nota
de crédito aceptan también el texto `dd/MM/yyyy`. `DetalleAdicional` se aplica a
la última línea agregada: llámalo después de `Linea`, o lanza
`InvalidOperationException`.

**Lo que asignas se envía tal cual.** Todo valor (subtotal de línea, impuestos,
bases, totales, propina, moneda, pagos) viaja sin cambios y lo que no asignas
queda sin enviar. Las tarifas de IVA y los códigos válidos están en el
[catálogo](/v1/guias/catalogos); el SDK no los conoce. Para comprobar el cuerpo
antes de emitir usa [`ValidarAsync`](#validar-sin-emitir) o activa
[`ValidarAntesDeEmitir`](#validar-antes-de-cada-emision).

## Importes exactos

Todos los importes, cantidades, precios y tarifas del SDK .NET son `decimal`
(`decimal?` en la solicitud). Un `decimal` guarda `0.30` como `0.30`, sin el
error de redondeo de `double`, y se envía como número JSON con punto decimal.
Calcula con `decimal` (sufijo `m` en los literales) y redondea a 2 decimales
antes de asignar:

```csharp
using System.Text.Json;
using Ecuafact.Sdk.Contracts;

FacturaRequest comprobante = JsonSerializer.Deserialize<FacturaRequest>(
    await File.ReadAllTextAsync("comprobante.json"))!;

decimal baseImponible = 10.00m;
decimal iva = Math.Round(baseImponible * 0.15m, 2, MidpointRounding.AwayFromZero); // 1.50
comprobante.Info!.TotalSinImpuestos = baseImponible;
comprobante.Info.ImporteTotal = baseImponible + iva;                                 // 11.50

Console.WriteLine(comprobante.Info.ImporteTotal); // 11.50
```

En las respuestas, `Comprobante.Total` y `CatalogoItem.Valor` también son
`decimal`. Las reglas de cálculo de cada comprobante están en
[Factura](/v1/guias/emision-01).

## Varios contribuyentes

Si tu API Key maneja varios contribuyentes, no fijes `Identificacion` en las
opciones. Pasa la identificación en cada llamada o crea una vista por
contribuyente con `Para`. La vista repite la identificación por ti en cada
método:

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

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

IEcuafactContribuyente matriz = client.Para("0123456789001");
PerfilEmisor perfil = await matriz.GetPerfilAsync();
Console.WriteLine($"{perfil.RazonSocial} ({perfil.Identificacion})");
```

La vista `IEcuafactContribuyente` tiene estos métodos:

| Método | Equivale a |
|---|---|
| `EmitirAsync(comprobante, idempotencyKey?)` | `client.EmitirAsync(identificacion, comprobante, idempotencyKey)` |
| `ValidarAsync(comprobante)` | `client.ValidarAsync(identificacion, comprobante)` |
| `DescargarRideAsync(claveAcceso)` | `client.DescargarRideAsync(identificacion, claveAcceso)` |
| `DescargarXmlAsync(claveAcceso)` | `client.DescargarXmlAsync(identificacion, claveAcceso)` |
| `GetPerfilAsync()` | `client.GetPerfilAsync(identificacion)` |
| `ActualizarPerfilAsync(cambios)` | `client.ActualizarPerfilAsync(identificacion, cambios)` |
| `ActualizarLogoAsync(contenido, contentType, nombreArchivo)` | `client.ActualizarLogoAsync(identificacion, ...)` |
| `EsperarResultadoAsync(idOperacion, intervalo?, maximo?)` | `client.EsperarResultadoAsync(idOperacion, ...)` |
| `GetConsumoAsync()` | `client.GetConsumoAsync()` (el cupo es de la API Key, no del contribuyente) |

Puedes usar varias vistas en paralelo con el mismo cliente.

## Logo del perfil

Con `ActualizarLogoAsync` 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. Si la subida
falla por un corte de red o un estado HTTP transitorio, nuestro SDK la
reintenta por ti.

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

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

byte[] logo = await File.ReadAllBytesAsync("logo.png");
PerfilEmisor perfil = await client.ActualizarLogoAsync("0123456789001", logo, "image/png", "logo.png");
Console.WriteLine($"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).

## Consultas SRI

Con estos métodos puedes consultar el catastro del SRI. No consumen cupo y
usan la misma API Key que el resto del cliente.

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

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

ValidacionIdentificacion validacion = await client.ValidarIdentificacionAsync("0123456789001");
ContribuyenteConsulta contribuyente = await client.ConsultarContribuyenteAsync("0123456789001");
IReadOnlyList<BusquedaContribuyente> encontrados =
    await client.BuscarContribuyentesAsync("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
EstablecimientosContribuyente establecimientos =
    await client.ListarEstablecimientosAsync("0123456789001", "SoloActivos");
Console.WriteLine($"valido={validacion.Valido}");
```

Los parámetros y las respuestas de cada consulta están en
[Contribuyente por identificación](/v1/guias/consulta-contribuyente),
[Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre),
[Establecimientos de un RUC](/v1/guias/consulta-establecimientos),
[Validar identificación](/v1/guias/consulta-identificacion) y
[Decodificar clave de acceso](/v1/guias/consulta-clave-acceso).

## Estado del servicio y catálogos

`ObtenerEstadoServicioAsync` devuelve el estado público del servicio: el estado
global, el estado de cada componente, la disponibilidad de los últimos 90 días y
los incidentes. Es la misma información de [Estado del servicio](/v1/guias/estado-del-servicio)
(`GET /estado`); no envía la API Key y no consume cupo. `ListarCatalogosAsync`
devuelve la clave y la descripción de cada catálogo del SRI, y
`ObtenerCatalogoAsync` devuelve las filas de uno de ellos a partir de esa clave.
Estas dos consultas usan tu API Key y tampoco consumen cupo. Los catálogos
cambian pocas veces al año, así que puedes guardar la respuesta en caché por una
hora.

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

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

EstadoPublico estado = await client.ObtenerEstadoServicioAsync();
Console.WriteLine($"{estado.Estado}, disponibilidad 90 días: {estado.Disponibilidad90Dias}");
foreach (IncidentePublico incidente in estado.Incidentes)
{
    Console.WriteLine($"{incidente.Inicio:u} {incidente.Impacto}: {incidente.Titulo}");
}

Catalogos indice = await client.ListarCatalogosAsync();
CatalogoDetalle tarifas = await client.ObtenerCatalogoAsync("tarifas-iva");
foreach (CatalogoItem fila in tarifas.Items)
{
    Console.WriteLine($"{fila.Codigo} {fila.Descripcion} {fila.Valor}");
}
```

`ObtenerEstadoServicioAsync` devuelve un `EstadoPublico`:

| Propiedad | Tipo | Descripción |
|---|---|---|
| `Estado` | `string` | Estado global: `operativo`, `degradado`, `caido` o `sin_datos`. |
| `MedidoEn` | `DateTime?` | Momento de la última medición. Es `null` mientras no hay mediciones. |
| `Componentes` | `List<ComponenteEstado>` | Componentes monitoreados, cada uno con `Nombre` y `Estado` (mismos valores que el estado global). |
| `Disponibilidad90Dias` | `decimal?` | Porcentaje de minutos sin caída en los últimos 90 días. Es `null` si aún no hay muestras. |
| `Incidentes` | `List<IncidentePublico>` | Incidentes de los últimos 90 días y los abiertos, del más reciente al más antiguo. Lista vacía si no hubo ninguno. |
| `Incidentes[].Inicio` | `DateTime` | Inicio del incidente. |
| `Incidentes[].Fin` | `DateTime?` | Fin del incidente. Es `null` mientras sigue abierto. |
| `Incidentes[].Impacto` | `string` | `degradado` o `caido`. |
| `Incidentes[].Titulo` | `string` | Título breve. |
| `Incidentes[].Detalle` | `string?` | Qué significó para las integraciones. Es `null` si no hay detalle. |

`ListarCatalogosAsync` devuelve un `Catalogos`, y `ObtenerCatalogoAsync`, un
`CatalogoDetalle`:

| Propiedad | Tipo | Descripción |
|---|---|---|
| `Catalogos.Items` | `List<CatalogoResumen>` | Catálogos disponibles, cada uno con `Nombre` (la clave que recibe `ObtenerCatalogoAsync`) y `Descripcion`. |
| `CatalogoDetalle.Nombre` | `string` | Clave del catálogo. |
| `CatalogoDetalle.Descripcion` | `string` | Descripción breve. |
| `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. |
| `CatalogoItem.Descripcion` | `string` | Descripción del código. |
| `CatalogoItem.Valor` | `decimal?` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. Es `null` si el catálogo no lo tiene. |
| `CatalogoItem.VigenteDesde` | `string?` | Primer día de vigencia, en formato `yyyy-MM-dd`. Es `null` si no está acotada por el inicio. |
| `CatalogoItem.VigenteHasta` | `string?` | Último día de vigencia, en formato `yyyy-MM-dd`. Es `null` si sigue vigente. |
| `CatalogoItem.Atributos` | `Dictionary<string, JsonElement>?` | Atributos propios del catálogo. Es `null` si no hay. |

Una clave de catálogo que no existe lanza `EcuafactNotFoundException`. El
significado de cada catálogo y de sus claves está en
[Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api).

## Listado de comprobantes emitidos

`ListarOperacionesAsync` consulta los comprobantes emitidos de un contribuyente.
Acepta `desde` y `hasta` en formato `yyyy-MM-dd`, `tipoDocumento`, `buscar`,
`pagina` desde 1 y `tamanoPagina` entre 1 y 100. Devuelve `PaginaComprobantes` con
`Comprobantes`, `Pagina`, `TamanoPagina` y `HayMas`. Incrementa `pagina` mientras
`HayMas` sea `true` para recorrer el resultado.

```csharp
// Archivo: Program.cs
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

PaginaComprobantes resultado = await client.ListarOperacionesAsync(
    "0123456789001", desde: "2026-11-01", hasta: "2026-11-12", tamanoPagina: 20);
Console.WriteLine($"Recibidos: {resultado.Comprobantes.Count}; hay mas: {resultado.HayMas}");
```

Todos los métodos del SDK admiten `CancellationToken ct` y `RequestOptions? opciones` al final.

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

