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:
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
codEstado3010 (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.
MaxAttemptses menor que 1.TimeoutoTotalTimeoutno son mayores que cero.MaxRetryDelay,RetryBaseDelayoRetryJitterson negativos.RetryableStatusCodestrae un código fuera del rango de 100 a 599.MaxResponseBytesoMaxFileResponseBytesson negativos.AdditionalInfono 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:
EmisionResultadotraeAdmission,IdempotencyKey(la clave usada) yCorrelationId(la cabeceraX-Correlation-Id).Admissiontiene los mismos campos queOperation, que se describen en Esperar el resultado. En una emisión aceptada,EstadoesrecibidoyCodEstadoes 1001 o 1002: con 1001,ClaveAccesotodavía esnull, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores.UrlEstadoes la URL completa del seguimiento.ArchivoComprobantetraeContenido(byte[]) yContentType. Las descargas solo existen con el comprobante autorizado; ver Descargar XML.QuotaBuckettraeLimiteDocumentos,Reservados,Consumidos,Disponibles,VigenteHastay 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 enEmisionResultado.IdempotencyKeyo, si la llamada falla, en la propiedadIdempotencyKeyde 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, lanzaEcuafactSdkExceptionsin llamar a la API. GetOperacionAsyncconstringexige un UUID (con o sin guiones); si no lo es, lanzaEcuafactSdkExceptionsin 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#
- Factura: revisa todos los campos y las reglas de cálculo para construir tus comprobantes.
- Seguimiento de una operación: consulta qué significa cada
estadoy cadacodEstado. - Webhooks: recibe el resultado del SRI sin consultar en bucle.
- Visión general de los SDK: compara los cinco SDK y decide entre SDK o HTTP directo.