SDK .NET

Cliente oficial de la API para .NET. Cubre autenticacion, idempotencia, reintentos y firma de webhook.

Paquetes#

Paquete Uso
Ecuafact.Sdk Cliente, modelos de datos, excepciones y firma de webhooks
Ecuafact.Sdk.Core Registro del cliente para inyeccion de dependencias (ASP.NET Core o Worker Service)

Compatible con netstandard2.0 (.NET Framework 4.6.1+) y net10.0.

Instalacion#

dotnet add package Ecuafact.Sdk
dotnet add package Ecuafact.Sdk.Core   # opcional, para inyeccion de dependencias

Uso basico#

Crea el cliente una vez y reutilizalo.

using Ecuafact.Sdk;

var client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://staging-api.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    Identificacion = "1790012345001" // solo integraciones de un RUC
});

// comprobante: la Estructura del comprobante (ver [Factura](/v1/guias/emision-01)).
EmisionResultado r = await client.EmitirAsync(comprobante);
Console.WriteLine($"Operacion {r.Admission.IdOperacion} / codigo: {r.Admission.Codigo}");

DateTime desde = new DateTime(2026, 1, 1);
DateTime hasta = new DateTime(2026, 1, 31);
PaginaComprobantes emitidos = await client.ListarEmitidosAsync(
    new ListadoRequest { Desde = desde, Hasta = hasta });
QuotaBucket cupo = await client.GetConsumoAsync();
Contexto contexto = await client.GetContextoAsync();

Para varias API Key o varios RUC de la misma cuenta:

IEcuafactContribuyente a = client.Para("1790012345001");
IEcuafactContribuyente b = client.Para("1790099987001");

await a.EmitirAsync(comprobanteA);
await b.EmitirAsync(comprobanteB); // concurrente y seguro

Uso con inyeccion de dependencias#

En aplicaciones con Microsoft.Extensions.DependencyInjection (ASP.NET Core, Worker Service) registra el cliente y resuelve la interfaz.

using Ecuafact.Sdk.Core;

builder.Services.AddEcuafactClient(o =>
{
    o.BaseAddress = new Uri(configuration["Ecuafact:BaseUrl"]!);
    o.ApiKey = configuration["Ecuafact:ApiKey"]!;
    // o.Identificacion = "1790012345001"; // solo un RUC
});

public sealed class Facturacion(IEcuafactClient client)
{
    public async Task EmitirAsync(ComprobanteRequest comprobante, CancellationToken ct)
    {
        EmisionResultado r = await client.EmitirAsync(comprobante, ct: ct);
        Console.WriteLine(r.Admission.IdOperacion);
    }
}

Varias integraciones (varios clientes):

builder.Services.AddEcuafactClient("integracionA", o =>
{
    o.BaseAddress = new Uri(configuration["EcuafactA:BaseUrl"]!);
    o.ApiKey = configuration["EcuafactA:ApiKey"]!;
});
builder.Services.AddEcuafactClient("integracionB", o =>
{
    o.BaseAddress = new Uri(configuration["EcuafactB:BaseUrl"]!);
    o.ApiKey = configuration["EcuafactB:ApiKey"]!;
});

public sealed class Multi(IEcuafactClientProvider provider)
{
    public Task Emitir(CancellationToken ct)
        => provider.GetClient("integracionA").EmitirAsync(comprobante, ct: ct);
}

El cliente por defecto tambien queda inyectable como IEcuafactClient.

Idempotencia#

Idempotency-Key es opcional. Si no se envia, el SDK la genera, la usa en todos los reintentos y la devuelve en EmisionResultado.IdempotencyKey; si la llamada falla, viaja en EcuafactApiException.IdempotencyKey.

Al reintentar a nivel de aplicacion reutiliza la clave devuelta: generar otra puede duplicar la emision. Los fallos transitorios (timeout, 408/425/429/5xx) se reintentan con la misma clave respetando Retry-After; el resto de los 4xx no. La espera se ajusta con RespectRetryAfter y MaxRetryDelay.

Consultas SRI#

Consultas al SRI (contribuyentes, establecimientos, identificaciones y claves de acceso). Son de solo lectura, no consumen cupo y requieren la misma API Key.

ContribuyenteConsulta contribuyente = await client.ConsultarContribuyenteAsync("1760013210001");
IReadOnlyList<BusquedaContribuyente> encontrados =
    await client.BuscarContribuyentesAsync("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
EstablecimientosContribuyente establecimientos =
    await client.ListarEstablecimientosAsync("1760013210001", "SoloActivos");
ValidacionIdentificacion validacion = await client.ValidarIdentificacionAsync("1760013210001");
ClaveAccesoDecodificada decodificada = await client.DecodificarClaveAccesoAsync(claveAcceso);

Webhook saliente#

using Ecuafact.Sdk;

bool valido = WebhookSignature.Verify(secreto, cabecera, cuerpoCrudo, DateTimeOffset.UtcNow, TimeSpan.FromMinutes(5));

Errores#

Los errores del API se exponen como EcuafactApiException (Codigo, Mensaje, EstadoHttp, IdSeguimiento, Errores). Errores es una lista de strings y solo trae mensajes en errores de validacion. Los errores locales de configuracion o transporte son EcuafactSdkException.

En emisiones exitosas, EmisionResultado.CorrelationId conserva el X-Correlation-Id de la respuesta; guardalo al reportar un incidente.

Siguientes pasos#

No se pudo completar la operacion. Recargar ✕