Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

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.

Importante

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:

Prompt para agentes

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.

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

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.

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 de tu API Key.

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

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, emite una factura, espera el resultado del SRI con el seguimiento y descarga el RIDE, 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 de la serie estab-ptoEmi. El programa reemplaza ruc por el de tu contexto y fechaEmision por la fecha de hoy.

{
  "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 y un punto de emisión de tu emisor; el sandbox crea el establecimiento 001 con el punto de emisión 001. El detalle de cada campo está en Factura.

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, sin que tu proceso se quede esperando.

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#

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

Nota

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, en el catálogo de codEstado y en 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. 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)
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.
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)
SaludAsync() GET /salud EstadoServicio (Servicio y Estado). No envía la API Key.
ObtenerEstadoServicioAsync() GET /estado EstadoPublico (ver Estado del servicio y catálogos). 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)
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)

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

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

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

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

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

// 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: 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.

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

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.

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.

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

Atención

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.

// 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; 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; el algoritmo, en Verificación de 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). 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, 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.
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, 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.
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.

Atención

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.

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

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

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.

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

// 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:

// 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 con IHttpClientFactory.

Inyección de dependencias#

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

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:

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:

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:

{
  "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
    ]
  }
}
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.

Atención

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:

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:

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.

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

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

// 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; el SDK no los conoce. Para comprobar el cuerpo antes de emitir usa ValidarAsync o activa ValidarAntesDeEmitir.

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:

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.

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:

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.

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.

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.

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, Contribuyentes por nombre, Establecimientos de un RUC, Validar identificación y Decodificar clave de 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 (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.

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.

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.

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

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.