SDK Java

Cliente oficial de la API para Java (17+). Cubre autenticacion, idempotencia, reintentos y firma de webhook.

Paquete: com.ecuafact:sdk.
Dependencia JSON: Jackson Databind.

Como se instala#

Agrega la dependencia a tu proyecto:

<dependency>
  <groupId>com.ecuafact</groupId>
  <artifactId>sdk</artifactId>
  <version>1.0.0-beta1</version>
</dependency>

Configuracion#

import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;

EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://staging-api.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .identificacion("1790012345001")); // solo integraciones de un RUC

Opcion	Default	Descripcion
`baseAddress`	-	Direccion base del API (obligatoria; define el ambiente)
`apiKey`	-	API Key (obligatoria)
`identificacion`	-	RUC por defecto (opcional)
`timeout`	`PT100S`	Tiempo maximo por intento
`userAgent`	`Ecuafact.Sdk/1.0`	User-Agent
`retryTransientFailures`	`true`	Reintenta `408/425/429/5xx`
`maxAttempts`	`3`	Intentos por solicitud
`respectRetryAfter`	`true`	Respeta `Retry-After` en `429`/`503`
`maxRetryDelay`	`PT60S`	Espera maxima entre reintentos

Metodos#

Metodo	Que hace	Devuelve
`emitir(comprobante)`	Emite para el RUC por defecto	`EmisionResultado`
`emitirEn(ruc, comprobante)`	Emite para un RUC explicito	`EmisionResultado`
`para(ruc)`	Fija un contribuyente	`EcuafactContribuyente`
`getOperacion(id)`	Consulta el seguimiento de la operacion	`Operation`
`getContexto()`	Contexto de tu API Key	`Contexto`
`getConsumo()`	Cupo disponible	`QuotaBucket`
`listarEmitidos(...)`	Listan comprobantes	`PaginaComprobantes`
`consultarContribuyente(id)`	Consulta un contribuyente en el SRI	`ContribuyenteConsulta`
`buscarContribuyentes(...)`	Busca por nombre	`List<BusquedaContribuyente>`
`listarEstablecimientos(ruc)`	Establecimientos de un RUC	`EstablecimientosContribuyente`
`validarIdentificacion(numero)`	Valida el formato (sin red)	`ValidacionIdentificacion`
`decodificarClaveAcceso(clave)`	Descompone una clave de acceso	`ClaveAccesoDecodificada`
`verify(...)`	Verifica la firma de un webhook	`boolean`

Emision#

import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.ComprobanteRequest;
import com.ecuafact.sdk.contracts.InfoTributaria;

// Los ultimos argumentos son las colecciones que no usa una factura.
ComprobanteRequest comprobante = new ComprobanteRequest(
    "MiERP", "FACTURA-2026-0001",
    new InfoTributaria("1790012345001", "01", "002", "001", "000000123"),
    null, null, null, null, null, null);

EmisionResultado resultado = client.emitir(comprobante);
System.out.println(resultado.admission().idOperacion() + " " + resultado.admission().codigo());

Emision con RUC explicito: client.emitirEn("1790012345001", comprobante).

Multi-RUC#

EcuafactContribuyente ruc = client.para("1790099987001");
PaginaComprobantes pagina = ruc.listarEmitidos();

Estado y consultas#

Operation operacion = client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
Contexto contexto = client.getContexto();
QuotaBucket cupo = client.getConsumo();

Consultas SRI#

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

ContribuyenteConsulta contribuyente = client.consultarContribuyente("1760013210001");
List<BusquedaContribuyente> encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
EstablecimientosContribuyente establecimientos = client.listarEstablecimientos("1760013210001", "SoloActivos");
ValidacionIdentificacion validacion = client.validarIdentificacion("1760013210001");
ClaveAccesoDecodificada clave = client.decodificarClaveAcceso(claveAcceso);

Idempotencia#

idempotencyKey es opcional: si no se envia, el SDK la genera, la reutiliza en los reintentos y la devuelve en resultado.idempotencyKey() (y en el error, como EcuafactApiException.idempotencyKey()). Al reintentar, reutiliza la clave devuelta. La correlacion de la respuesta queda en resultado.correlationId() (o EcuafactApiException.idSeguimiento() en error). Los fallos transitorios (408/425/429/5xx) se reintentan respetando Retry-After; el resto de los 4xx no.

Webhooks#

import com.ecuafact.sdk.WebhookSignature;
import java.time.Instant;

boolean valido = WebhookSignature.verify(secreto, cabecera, cuerpoCrudo, Instant.now(), 300);

Ve Verificacion de firma y Webhooks.

Errores#

EcuafactApiException trae codigo(), mensaje(), estadoHttp(), idSeguimiento(), errores() e idempotencyKey(). Los errores locales son EcuafactSdkException.

Siguientes pasos#

Vision general de los SDK: compara lenguajes y metodos.
Autenticacion: obten y usa tu API Key.
Emision: emite tu primer comprobante.
Verificacion de firma: valida los webhooks entrantes.