En esta página
SDK Java
Biblioteca oficial para emitir comprobantes desde Java 17 o superior, seguir su autorización, descargar el RIDE y verificar webhooks.
Si desarrollas en Java, puedes integrarte con nuestros servicios de facturación
usando nuestro SDK para Java. En lugar de armar cada petición HTTP, llamas a
métodos como emitirEn o descargarRide, que reciben y devuelven objetos
tipados, en versión síncrona o con CompletableFuture. 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.
La guía sigue el orden de una integración. Primero instalas el paquete, configuras el cliente, emites tu primera factura y haces el seguimiento hasta el resultado del SRI; después recibes webhooks y manejas errores, y al final ajustas los reintentos, las opciones por llamada y la conexión, y armas comprobantes con los constructores. La referencia completa está en Métodos. 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 Java 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-java.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 la dependencia com.ecuafact:sdk:1.0.1 en Maven o Gradle. 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. Requiere Java 17 o superior. 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.
Paquete#
| Dato | Valor |
|---|---|
| Coordenadas Maven | com.ecuafact:sdk |
| Versión | 1.0.1 |
| Java | 17 o superior |
| Dependencias | Jackson Databind 2.18.2. Es una dependencia transitiva, así que no necesitas declararla. |
| Cliente | Síncrono, sobre java.net.http.HttpClient, con variantes *Async que devuelven CompletableFuture. Seguro para uso concurrente. |
Requisitos#
- El JDK 17 o superior, que compruebas con
java -version, y Maven o Gradle. - 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#
El paquete se publica en Maven Central, así que Maven y Gradle lo resuelven sin configurar repositorios adicionales.
Con Maven, agrega la dependencia a tu pom.xml:
<dependency>
<groupId>com.ecuafact</groupId>
<artifactId>sdk</artifactId>
<version>1.0.1</version>
</dependency>
Con Gradle y el Kotlin DSL, agrégala en build.gradle.kts:
dependencies {
implementation("com.ecuafact:sdk:1.0.1")
}
Para comprobar la instalación, ejecuta mvn dependency:tree o
gradle dependencies. Debe aparecer com.ecuafact:sdk:jar:1.0.1 con
jackson-databind debajo.
Configuración#
Crea el cliente una vez y reutilízalo, porque sirve para todos los
contribuyentes de tu API Key. Las opciones se encadenan
sobre EcuafactClientOptions.create(baseAddress, apiKey).
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import java.time.Duration;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
.identificacion("0123456789001") // opcional: contribuyente por defecto
.timeout(Duration.ofSeconds(60))); // opcional
System.out.println(client); // la API Key aparece como ***
Si pasas null como apiKey, el SDK lee la variable de entorno ECUAFACT_API_KEY, y si pasas null como
baseAddress, lee ECUAFACT_BASE_URL. Con las dos variables definidas basta
new EcuafactClient() o EcuafactClientOptions.fromEnvironment(). Los nombres
están en las constantes EcuafactClientOptions.ENV_API_KEY y
EcuafactClientOptions.ENV_BASE_URL.
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 |
String |
ECUAFACT_BASE_URL |
Primer argumento de create. URL https absoluta, sin usuario, sin consulta, sin fragmento y sin /v1. El SDK rechaza http. |
apiKey |
String |
ECUAFACT_API_KEY |
Segundo argumento de create. Tu API Key; viaja en la cabecera X-Api-Key. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en toString(). |
identificacion |
String |
null |
Contribuyente por defecto para emitir y validar sin identificación. Usa el valor identificacion de GET /v1/contexto (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). |
validarAntesDeEmitir(boolean) |
boolean |
false |
Si es true, emitir y emitirEn llaman antes a /validar y solo envían la emisión si la API la da por válida (2 peticiones por emisión). Se explica en Validar antes de cada emisión. |
timeout |
Duration |
PT30S (30 s) |
Tiempo máximo de cada intento, incluida la lectura de la respuesta. Mayor que cero. Por llamada lo cambias con RequestOptions.timeout(Duration). |
maxResponseBytes |
Long |
32 MiB (33554432); 100 MiB (104857600) en las descargas de RIDE y XML |
Tope en bytes del cuerpo de una respuesta. Un valor positivo lo aplica a todas las llamadas, incluidas las descargas; null o 0 lo desactiva. Al superarlo lanza EcuafactResponseTooLargeException con limite() y bytesLeidos(). |
userAgent |
String |
Ecuafact.Sdk/1.0 |
Valor de la cabecera User-Agent. No puede estar vacío ni tener caracteres de control. |
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. |
retryTransientFailures |
boolean |
true |
Reintenta fallos transitorios (ver Idempotencia y reintentos). false desactiva todo reintento. |
maxAttempts |
int |
3 |
Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. |
respectRetryAfter |
boolean |
true |
Espera lo que indique la cabecera Retry-After antes de reintentar. |
maxRetryDelay |
Duration |
PT60S (60 s) |
Espera máxima entre reintentos. Con Duration.ZERO no hay tope. |
retryRateLimited |
boolean |
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. Un 429 sin el codEstado 5005 tampoco se reintenta. |
retryableStatusCodes |
Set<Integer> |
408, 425, 500, 502, 503, 504 |
Estados HTTP que se reintentan (valores de 100 a 599). El 429 no va aquí: lo controla retryRateLimited. Los valores por defecto están en EcuafactClientOptions.DEFAULT_RETRYABLE_STATUS_CODES. |
retryBaseDelay |
Duration |
PT0.2S (200 ms) |
Espera base entre reintentos. No negativa. |
retryBackoff |
RetryBackoff |
RetryBackoff.LINEAR |
LINEAR: base x intento (200, 400, 600 ms). EXPONENTIAL: base x 2^(intento-1) (200, 400, 800 ms). |
retryJitter |
Duration |
PT0.05S (50 ms) |
Variación aleatoria máxima que se suma a cada espera (en LINEAR, multiplicada por el número de intento). No negativa. |
totalTimeout |
Duration |
null (sin tope) |
Tope de toda la llamada, incluidos reintentos y esperas. Ver Idempotencia y reintentos. |
httpClient |
HttpClient |
null |
Tu propio java.net.http.HttpClient. Si lo pasas, proxy, sslContext, executor y connectTimeout se ignoran: configúralos en ese cliente. |
proxy |
ProxySelector |
null |
Proxy, por ejemplo ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080)). |
sslContext |
SSLContext |
null (el del JDK) |
Contexto TLS propio: CA corporativa o certificado de cliente. |
executor |
Executor |
null |
Executor del HttpClient y de las esperas entre reintentos. Sin valor, el JDK usa el suyo y las esperas usan ForkJoinPool.commonPool(). |
connectTimeout |
Duration |
PT10S (10 s) |
Tiempo máximo para abrir la conexión. Mayor que cero. |
EcuafactClientOptions.create(baseAddress, apiKey).maxResponseBytes(64L * 1024 * 1024); // null desactiva el tope
Cada método de opción valida su valor y lanza
EcuafactConfigurationException si no es válido, por ejemplo con
maxAttempts(0), con un tiempo negativo o con un additionalInfo con tildes.
Al crear el cliente se validan además la URL y la API Key. Si faltan, si la URL
no es una URL https, si trae usuario, consulta o fragmento, o si termina en /v1, o si la API Key tiene
espacios, el constructor lanza la misma excepción antes de hacer cualquier
llamada. El mensaje nunca incluye la API Key ni el valor de additionalInfo.
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 desde la que ejecutas el
programa, que es la raíz de tu proyecto Maven. 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 la
plataforma asigna 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
}
]
}
]
}
Nota
El cuerpo no lleva infoTributaria.tipoDocumento: el tipo lo da la clase que usas, en este caso FacturaRequest, como se explica en Ruta de emisión por tipo de comprobante.
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. Cada campo está explicado en Factura.
Paso 2. Escribe el programa#
Guarda el código siguiente como src/main/java/Quickstart.java en un proyecto
Maven que tenga la dependencia de Instalación. Los modelos del SDK son record
inmutables, por eso el programa ajusta el JSON con Jackson antes de convertirlo
en FacturaRequest. El ObjectMapper usa USE_BIG_DECIMAL_FOR_FLOATS
para que los importes no pasen por double.
El paso 4 usa esperarResultado, 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. Ese flujo evita que tu proceso se quede
esperando.
import com.ecuafact.sdk.EcuafactApiException;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import com.ecuafact.sdk.contracts.Contexto;
import com.ecuafact.sdk.contracts.Contribuyente;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.ecuafact.sdk.contracts.Operation;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
public class Quickstart {
public static void main(String[] args) throws Exception {
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
ObjectMapper mapper = new ObjectMapper().enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS);
try {
// 1. Contexto: que contribuyentes puede usar tu API Key.
Contexto contexto = client.getContexto();
Contribuyente emisor = contexto.contribuyentes().stream()
.filter(Contribuyente::puedeEmitir).findFirst().orElseThrow();
System.out.println("Emisor " + emisor.identificacion());
// 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador).
ObjectNode json = (ObjectNode) mapper.readTree(Files.readString(Path.of("comprobante.json")));
((ObjectNode) json.get("infoTributaria")).put("ruc", emisor.identificacion());
((ObjectNode) json.get("info")).put("fechaEmision",
LocalDate.now(ZoneOffset.ofHours(-5)).format(DateTimeFormatter.ofPattern("dd/MM/yyyy")));
FacturaRequest comprobante = mapper.treeToValue(json, FacturaRequest.class);
// 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key.
EmisionResultado emision = client.emitirEn(emisor.identificacion(), comprobante, "FACTURA-2026-0001");
String idOperacion = emision.admission().idOperacion();
// codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos.
System.out.println("estado " + emision.admission().estado() + " codEstado " + emision.admission().codEstado()
+ " idOperacion " + idOperacion);
// 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min).
Operation operacion = client.esperarResultado(idOperacion);
System.out.println("estado " + operacion.estado() + " codEstado " + operacion.codEstado());
operacion.errores().forEach(detalle -> System.out.println(" - " + detalle));
// 5. RIDE: solo existe cuando el comprobante esta autorizado.
if (operacion.esAutorizado()) {
ArchivoComprobante ride = client.descargarRide(emisor.identificacion(), operacion.claveAcceso());
Files.write(Path.of("ride.pdf"), ride.contenido());
System.out.println("RIDE guardado en ride.pdf; claveAcceso " + operacion.claveAcceso());
} else if (!operacion.esFinal()) {
System.out.println("Aun sin resultado: consulta mas tarde o espera el webhook.");
}
} catch (EcuafactApiException error) {
System.out.println("HTTP " + error.estadoHttp() + " codEstado " + error.codEstado() + ": " + error.msgError());
error.errores().forEach(detalle -> System.out.println(" - " + detalle));
System.out.println("X-Correlation-Id: " + error.correlationId());
}
}
}
Paso 3. Ejecuta y verifica#
Con Maven, ejecuta la clase con el plugin exec; también puedes ejecutarla desde
tu IDE.
mvn -q compile exec:java -Dexec.mainClass=Quickstart
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 que empiezan con - 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. | Sigue la fila de su codEstado en Códigos de resultado de una operación. |
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. Lee las líneas que empiezan con -. |
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
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.
EmisionResultado es un record con estos métodos:
| Método | Tipo | Descripción |
|---|---|---|
admission() |
Admission |
La respuesta de la emisión, con los mismos campos que Operation, que se describen en Seguimiento y resultado. En una emisión aceptada, estado() es recibido: aceptamos el comprobante, que todavía no está autorizado. Un reintento con la misma Idempotency-Key y el mismo cuerpo responde igual. |
admission().codEstado() |
Integer |
1001 si todavía no hay clave de acceso, con claveAcceso() en null, o 1002 si ya la trae. Tu código debe aceptar los dos valores. |
admission().idOperacion() |
String |
UUID de la operación. Guárdalo: lo necesitas para el seguimiento. |
admission().urlEstado() |
String |
URL completa del seguimiento de esta operación. |
idempotencyKey() |
String |
La Idempotency-Key usada (la tuya o la que generó el SDK). |
correlationId() |
String |
Cabecera X-Correlation-Id de la respuesta. |
Ruta de emisión por tipo de comprobante#
Cada tipo de comprobante tiene su propia clase de solicitud, igual que tiene su propio endpoint en la API. El SDK
elige la ruta por la clase del objeto que pasas a emitir, emitirEn, validar y validarEn, así que no
indicas el tipo en ningún otro lugar y el cuerpo de la solicitud no incluye tipoDocumento. Las seis clases están en
com.ecuafact.sdk.contracts y comparten la interfaz SolicitudComprobante, que solo agrupa los seis tipos para que el
compilador rechace cualquier otro objeto.
| Código | Comprobante | Clase | Cabecera y líneas | Ruta de emisión |
|---|---|---|---|---|
01 |
Factura | FacturaRequest |
InfoFactura, DetalleCompraVenta |
POST /v1/contribuyentes/{identificacion}/facturas |
03 |
Liquidación de compra | LiquidacionCompraRequest |
InfoLiquidacionCompra, DetalleCompraVenta |
POST /v1/contribuyentes/{identificacion}/liquidaciones-compra |
04 |
Nota de crédito | NotaCreditoRequest |
InfoNotaCredito, DetalleNotaCredito |
POST /v1/contribuyentes/{identificacion}/notas-credito |
05 |
Nota de débito | NotaDebitoRequest |
InfoNotaDebito, Motivo |
POST /v1/contribuyentes/{identificacion}/notas-debito |
06 |
Guía de remisión | GuiaRemisionRequest |
InfoGuiaRemision, Destinatario, DetalleGuia |
POST /v1/contribuyentes/{identificacion}/guias-remision |
07 |
Comprobante de retención | RetencionRequest |
InfoComprobanteRetencion, DocsSustento, RetencionLinea, ImpuestoDocSustento |
POST /v1/contribuyentes/{identificacion}/retenciones |
FacturaRequest factura = ...;
EmisionResultado emision = client.emitirEn(identificacion, factura, "FACTURA-2026-0001"); // POST .../facturas
ValidacionResultado validacion = client.validarEn(identificacion, factura); // POST .../facturas/validar
Todas las clases comparten InfoTributaria, Impuesto, Pago y CampoAdicional. Cada clase tiene exactamente las
propiedades de su esquema en el contrato, con los mismos nombres, tipos y nulabilidad; los campos que el contrato
marca como obligatorios se listan en el Javadoc de cada clase. La validación usa la misma ruta del tipo con
/validar al final.
Validar sin emitir#
Las reglas de negocio de los comprobantes (campos requeridos, formatos de
estab, ptoEmi y secuencial, catálogos, topes, coherencia aritmética) viven
solo en la API. El SDK no las revisa: validar siempre llama a /validar, y
emitir envía el comprobante directo y lanza EcuafactValidationException con
el 422 de la API. Así, cuando la API cambia una regla no tienes que actualizar el SDK.
Antes de emitir puedes comprobar que un comprobante está bien armado con
validarEn(identificacion, comprobante), o con validar(comprobante) si
configuraste la identificación por defecto. El método recibe el mismo
request que usarías para emitir, elige la ruta con
la clase del comprobante y agrega /validar, y aplica las mismas reglas,
pero no emite nada, no consume cupo y no necesita Idempotency-Key. Te sirve
sobre todo cuando generas comprobantes de forma automática: validas el lote,
corriges lo que falle y emites después solo lo que pasó.
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.ValidacionResultado;
// Dentro de: public static void main(String[] args) throws Exception
ValidacionResultado validacion = client.validarEn("0123456789001", comprobante);
if (validacion.valido()) {
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println("Emitido: " + resultado.admission().idOperacion());
} else {
System.out.println("Comprobante con errores (codEstado " + validacion.codEstado() + "):");
validacion.errores().forEach(error -> System.out.println("- " + error));
}
Cuando el comprobante cumple todas las reglas, valido() es true. Cuando no
las cumple, la API responde lo mismo que respondería al emitirlo, un 422 con el
codEstado 3002 (comprobante_invalido), y el SDK no lanza una excepción: te devuelve valido() en false,
con el código y el problema en errores(), para que decidas qué hacer con ese
comprobante. Cualquier otro error lanza la misma excepción que en el resto de
llamadas, descrita en Errores; por ejemplo, si el contribuyente, su
RUC o el tipo de comprobante no están habilitados para tu API Key, recibes
EcuafactAuthException con el codEstado 3011 (acceso_denegado). Como validar no tiene efectos, el SDK
repite la llamada ante un fallo transitorio igual que hace con las consultas.
Un resultado válido significa que la emisión no tendrá errores de validación con ese mismo contenido, pero al emitir todavía pueden aparecer otras respuestas, como el cupo agotado o un comprobante duplicado. El detalle de las reglas está en Validar sin emitir de la guía de emisión.
Validar antes de cada emisión#
Si quieres que cada emisión pase primero por /validar, activa
EcuafactClientOptions.validarAntesDeEmitir(true), o
RequestOptions.create().validarAntes(true) para una sola llamada (la opción de
la llamada reemplaza a la del cliente). Con la opción activa, emitir y
emitirEn (y sus variantes asíncronas) llaman primero a /validar:
- Si
valido()esfalseo hayerrores(), lanzanEcuafactValidationException(HTTP 422,codEstado3002) con esoserrores(), y la emisión no se envía. - Si es válido, envían la emisión y las
advertenciasquedan enEmisionResultado.advertencias(). Una advertencia no bloquea.
Por defecto es false, porque duplica las peticiones: sin la opción, una emisión
hace 1 petición; con ella, 2.
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
.validarAntesDeEmitir(true));
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
resultado.advertencias().forEach(aviso -> System.out.println("Aviso: " + aviso));
ValidacionResultado es un record con estos métodos:
| Método | Tipo | Descripción |
|---|---|---|
valido() |
boolean |
true si el comprobante cumple todas las reglas de la emisión. |
codEstado() |
Integer |
null si es válido, o 3002 (CodEstado.COMPROBANTE_INVALIDO) si no lo es. |
msgError() |
String |
Descripción general del código; null si es válido. |
errores() |
List<String> |
Vacía si es válido; si no, el problema encontrado con la ruta del campo, por ejemplo $.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa. |
advertencias() |
List<String> |
Avisos que la API devuelve junto al resultado (por ejemplo, que ignora la firma de un XML que la trae); vacía si no hay. Un aviso no impide emitir. |
Seguimiento y resultado#
Después de emitir tienes un idOperacion, y con él consultas la operación
hasta que el SRI responde. Puedes hacerlo de tres formas.
| Forma | Cuándo usarla |
|---|---|
getOperacion(idOperacion) (o su alias consultarOperacion) |
Haces una consulta puntual, por ejemplo desde un proceso programado que revisa las operaciones pendientes. |
esperarResultado(idOperacion) / esperarResultado(idOperacion, intervalo, maximo) |
Necesitas el resultado en el mismo proceso, como en scripts, pruebas o procesos por lotes. Por defecto consulta cada 5 s durante 120 s como máximo. |
| Webhooks | En producción, recibes el resultado sin consultar en bucle. |
esperarResultado se detiene en cuanto esFinal() es true o al agotar
maximo, y devuelve la última lectura, así que revisa esFinal() antes de
usarla.
intervalo debe ser mayor que cero y maximo no puede ser negativo; si no,
lanza EcuafactSdkException. Si interrumpes el hilo durante la espera, también
lanza EcuafactSdkException. getOperacion, consultarOperacion y
esperarResultado exigen que idOperacion sea un UUID, con o sin guiones; si
no lo es, lanzan EcuafactSdkException sin llamar a la API.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.EstadoOperacion;
import com.ecuafact.sdk.contracts.Operation;
import java.time.Duration;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
// Consulta cada 10 s durante 5 minutos como maximo.
Operation operacion = client.esperarResultado(
"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", Duration.ofSeconds(10), Duration.ofMinutes(5));
String accion = switch (operacion.estadoOperacion()) {
case AUTORIZADO -> "Descarga el RIDE con la claveAcceso " + operacion.claveAcceso();
case RECIBIDO, DESCONOCIDO -> "Aun sin resultado: consulta mas tarde o espera el webhook";
default -> "Terminada sin autorizacion: codEstado " + operacion.codEstado() + " " + operacion.msgError()
+ " " + String.join(" | ", operacion.errores());
};
System.out.println(accion);
Reemplaza el idOperacion del ejemplo por el que recibiste al emitir.
Operation es un record con los campos de
Seguimiento de una operación.
| Método | Tipo | Descripción |
|---|---|---|
estado() |
String |
recibido, autorizado, rechazado, rechazo_configuracion, error o cancelado. Solo recibido no es final. |
codEstado() |
Integer |
Código numérico del resultado; su primer dígito es el estado. En recibido es 1001, sin clave de acceso, o 1002, con claveAcceso(); en autorizado, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (rechazo_sri) o 4002 (firma_no_valida). Compáralo con las constantes de CodEstado. |
msgError() |
String |
Descripción general y fija del código. null con recibido y autorizado. |
errores() |
List<String> |
Detalle del resultado; en un rechazo del SRI trae su mensaje. Nunca es null y está vacía si no hay detalle. |
idOperacion() |
String |
El identificador que consultaste. |
urlEstado() |
String |
URL completa del seguimiento. |
ambiente() |
Integer |
1 = pruebas, 2 = producción. |
tipoDocumento() |
String |
Tipo de comprobante (01 a 07). |
numeroDocumento() |
String |
Número del comprobante, por ejemplo 001-001-000000123. |
referenciaExterna() |
String |
La referenciaExterna que enviaste al emitir. |
claveAcceso() |
String |
Clave de acceso de 49 dígitos; es null con el codEstado 1001. |
fhRecibido() |
String |
Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). |
fhAutorizacion() |
String |
Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con estado(). |
Estados tipados#
Operation, Admission y Comprobante conservan los campos de la API (estado(),
codEstado(), tipoDocumento()) y agregan métodos tipados. Un valor nuevo
de la API 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.
| Método | Tipo | Valores |
|---|---|---|
Operation.estadoOperacion(), Comprobante.estadoOperacion() |
EstadoOperacion |
RECIBIDO, AUTORIZADO, RECHAZADO, RECHAZO_CONFIGURACION, ERROR, CANCELADO, DESCONOCIDO |
Operation.tipoComprobante(), Comprobante.tipoComprobante(), TipoComprobante.desde(tipoDocumento) |
TipoComprobante |
FACTURA (01), LIQUIDACION_COMPRA (03), NOTA_CREDITO (04), NOTA_DEBITO (05), GUIA_REMISION (06), RETENCION (07); null si el código no se conoce |
Operation.esFinal() |
boolean |
true si estado es cualquier valor distinto de recibido. |
Operation.esAutorizado() |
boolean |
true si estado es autorizado. |
WebhookEvent.eventType() |
TipoEventoWebhook |
DOCUMENTO_AUTORIZADO, DOCUMENTO_RECHAZADO, DOCUMENTO_FALLIDO, OPERACION_REQUIERE_ATENCION, DESCONOCIDO |
EstadoOperacion y TipoComprobante están en
com.ecuafact.sdk.contracts; TipoEventoWebhook, en com.ecuafact.sdk. Cada
uno tiene desde(String) y valor() (codigo() en TipoComprobante).
Los valores de codEstado están como constantes int en
com.ecuafact.sdk.contracts.CodEstado, con el nombre de cada código del
catálogo en mayúsculas, por ejemplo
CodEstado.RECHAZO_SRI (3001), CodEstado.COMPROBANTE_INVALIDO (3002) o
CodEstado.LIMITE_SOLICITUDES (5005). 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, y CodEstado.nombre(codigo) devuelve su
nombre.
Webhooks#
Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y,
antes de procesar cada entrega, comprobar que te la enviamos nosotros. El SDK te
ayuda a recibir webhooks: verifica la firma y te entrega el evento tipado, pero
no administra los destinos. Los destinos (la URL a la que enviamos cada evento,
sus eventos suscritos y su secreto) los administras 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.
WebhookEvent.construir verifica la cabecera Ecuafact-Signature
(t=<epoch>,v1=<hmac>) contra el cuerpo crudo y, si es válida, devuelve el
evento tipado. Si la firma no coincide, está fuera de la tolerancia (300 s por
defecto, WebhookSignature.DEFAULT_TOLERANCE) o el cuerpo no es un objeto JSON,
lanza EcuafactWebhookException. WebhookSignature.construirEvento(...) hace
lo mismo.
| Sobrecarga | Uso |
|---|---|
construir(secreto, cabecera, cuerpo) |
Un solo secreto. cuerpo como String o byte[]. |
construir(secretos, cabecera, cuerpo) |
Una colección de secretos (rotación). cuerpo como String o byte[]. |
construir(secretos, cabecera, cuerpo, tolerancia) |
Igual, con otra tolerancia (Duration). |
Con una colección de secretos, la entrega es válida si coincide con cualquiera, así que 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 ejemplo siguiente usa el servidor HTTP incluido en el JDK, sin dependencias. Guarda tu
secreto en ECUAFACT_WEBHOOK_SECRET y, durante una rotación, el anterior en
ECUAFACT_WEBHOOK_SECRET_ANTERIOR. Escucha en el puerto 3000, en la ruta
/webhooks/ecuafact.
import com.ecuafact.sdk.EcuafactWebhookException;
import com.ecuafact.sdk.WebhookEvent;
import com.ecuafact.sdk.WebhookSignature;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.util.List;
import java.util.Objects;
import java.util.stream.Stream;
public class Webhook {
public static void main(String[] args) throws Exception {
List<String> secretos = Stream.of(
System.getenv("ECUAFACT_WEBHOOK_SECRET"),
System.getenv("ECUAFACT_WEBHOOK_SECRET_ANTERIOR"))
.filter(Objects::nonNull).filter(s -> !s.isEmpty()).toList();
HttpServer servidor = HttpServer.create(new InetSocketAddress(3000), 0);
servidor.createContext("/webhooks/ecuafact", intercambio -> {
byte[] cuerpoCrudo = intercambio.getRequestBody().readAllBytes();
String cabecera = intercambio.getRequestHeaders().getFirst(WebhookSignature.HEADER);
int estado;
try {
WebhookEvent evento = WebhookEvent.construir(secretos, cabecera == null ? "" : cabecera, cuerpoCrudo);
// Deduplica por eventTypeRaw + resourceId antes de procesar y responde 2xx.
switch (evento.eventType()) {
case DOCUMENTO_AUTORIZADO -> System.out.println("Autorizado " + evento.idOperacion() + " " + evento.claveAcceso());
case DOCUMENTO_RECHAZADO -> System.out.println("Rechazo fiscal " + evento.idOperacion() + " codEstado " + evento.codEstado() + " " + evento.errores());
case DOCUMENTO_FALLIDO -> System.out.println("No emitido " + evento.idOperacion() + " " + evento.estado() + " codEstado " + evento.codEstado());
default -> System.out.println("Evento " + evento.eventTypeRaw() + " prueba=" + evento.probe());
}
estado = 200;
} catch (EcuafactWebhookException error) {
estado = 401;
}
intercambio.sendResponseHeaders(estado, -1);
intercambio.close();
});
servidor.start();
}
}
Para comprobarlo, pulsa Probar en tu destino del portal, que envía el
evento de prueba. Tu consola muestra
Evento operation.requires_attention prueba=true y la entrega aparece en
Entregas con un 200. Si ves un 401, el secreto no coincide o el reloj del
servidor está desfasado más de 300 s.
Método de WebhookEvent |
Tipo | Descripción |
|---|---|---|
eventType() |
TipoEventoWebhook |
Tipo de evento; un valor nuevo se lee como DESCONOCIDO. |
eventTypeRaw() |
String |
Valor original de eventType (document.authorized, document.rejected, document.failed, operation.requires_attention). |
resourceId() |
String |
Recurso del evento. Con eventTypeRaw() forma la clave de deduplicación. |
occurredAtUtc() |
Instant |
Momento del evento; null si no vino o no se pudo leer. |
idOperacion() |
String |
Operación a la que pertenece el evento. |
estado() |
String |
El mismo estado del seguimiento en eventos document.*: autorizado, rechazado, rechazo_configuracion o error. Su versión tipada es estadoOperacion(). |
tipoDocumento() |
String |
Tipo de comprobante (01 a 07), cuando el evento lo trae. |
claveAcceso() |
String |
Clave de acceso del comprobante, si aplica. |
codEstado() |
Integer |
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. Decide con estado() y codEstado(), no solo con el tipo del evento. |
msgError() |
String |
Descripción fija del código; null cuando no hay error. |
errores() |
List<String> |
Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacía si no hay detalle. |
fhAutorizacion() |
String |
Momento de la autorización del SRI, cuando existe. |
ruc() |
String |
RUC del documento; en el evento de prueba, el RUC al que se limita el destino. null si no viene. |
probe() |
boolean |
true en el evento de prueba del portal. |
Si solo necesitas saber si la firma es válida, usa
WebhookSignature.verify(secretos, cabecera, cuerpo), que devuelve boolean y
nunca lanza; acepta un secreto o una colección, y el cuerpo como String o
byte[]. Después lee el evento con WebhookEvent.parse(cuerpo).
Standard Webhooks#
Cada entrega trae además las cabeceras del estándar
Standard Webhooks (webhook-id,
webhook-timestamp y webhook-signature), que corresponden a la misma firma.
Con el SDK puedes verificar cualquiera de las dos, sin decidir cuál llegó.
| Método | Qué hace |
|---|---|
WebhookEvent.construirConCabeceras(secretos, cabeceras, cuerpo) |
Devuelve el WebhookEvent si Ecuafact-Signature o Standard Webhooks es válida; si no, lanza EcuafactWebhookException. Con otro Duration al final cambia la tolerancia. cabeceras es un Map<String, ?> cuyos nombres no distinguen mayúsculas. |
WebhookSignature.verificarCualquiera(secretos, cabeceras, cuerpo) |
Devuelve boolean con la misma regla y nunca lanza. También acepta un único secreto y, en lugar del mapa, una Function<String, String> que lee una cabecera por nombre. |
WebhookSignature.verificarEstandar(secretos, webhookId, webhookTimestamp, webhookSignature, cuerpo) |
Devuelve boolean. Verifica solo la firma de Standard Webhooks. |
WebhookSignature.firmarEstandar(secreto, webhookId, webhookTimestamp, cuerpo) |
Devuelve el valor de webhook-signature (v1,<base64>). Sirve para pruebas automatizadas. |
El secreto puede llevar o no el prefijo whsec_, y también aceptas una colección
de secretos para la rotación. Con el servidor HTTP del JDK, getRequestHeaders()
sirve como cabeceras.
WebhookEvent evento = WebhookEvent.construirConCabeceras(secretos, intercambio.getRequestHeaders(), cuerpoCrudo);
Probar tu receptor sin esperar una entrega#
Para probar tu receptor en un test automatizado, firma un cuerpo de ejemplo con
el mismo secreto y comprueba que lo aceptas. Con WebhookSignature.sign generas
la cabecera Ecuafact-Signature, y con firmarEstandar, la de Standard Webhooks.
String secreto = "secreto-de-prueba";
String cuerpo = "{\"eventType\":\"document.authorized\",\"resourceId\":\"r1\",\"estado\":\"autorizado\",\"codEstado\":2001}";
long ahora = java.time.Instant.now().getEpochSecond();
String cabecera = WebhookSignature.sign(secreto, ahora, cuerpo);
WebhookEvent evento = WebhookEvent.construir(secreto, cabecera, cuerpo);
// evento.eventType() == TipoEventoWebhook.DOCUMENTO_AUTORIZADO
// Una firma vencida, alterada o de otro secreto lanza EcuafactWebhookException.
Atención
Verifica la firma sobre el cuerpo crudo. En Spring, recibe el cuerpo como
@RequestBody byte[] o @RequestBody String (no como objeto) para conservar
los bytes exactos.
Los eventos y su contenido están en Webhooks, y el algoritmo de la firma, en Verificación de firma.
Errores#
Todas las excepciones son RuntimeException, así que no necesitas
declararlas, y heredan de EcuafactSdkException. Las que vienen de una
respuesta de la API heredan además de EcuafactApiException. Captura primero
las específicas y al final EcuafactSdkException, que atrapa 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, trae usuario, consulta o fragmento, o termina en /v1, la API Key tiene espacios o caracteres de control, o una opción es inválida (maxAttempts(0), tiempo negativo, correlationId o additionalInfo inválido). |
Corrige la configuración. No llama a la API. |
EcuafactConnectionException |
EcuafactSdkException |
Sin conexión con la API tras agotar los intentos. | Reintenta más tarde con la misma idempotencyKey(). Usa correlationId() para ubicar la llamada en tus registros. |
EcuafactTimeoutException |
EcuafactSdkException |
El último intento superó timeout, o se agotó totalTimeout antes de un intento. |
Reintenta con la misma idempotencyKey(); si emitías, consulta antes el seguimiento. Usa correlationId() para ubicar la llamada en tus registros. |
EcuafactWebhookException |
EcuafactSdkException |
Firma de webhook inválida o vencida, o cuerpo vacío o que no es un objeto 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. |
EcuafactValidationException |
EcuafactApiException |
HTTP 400, 413, 415, 422 o 501: solicitud rechazada, con el codEstado 3002 (comprobante_invalido), 3003 (solicitud_invalida), 3006 (cuerpo_excedido), 3007 (version_no_soportada), 3008 (no_implementado) o 3012 (filtros_invalidos). |
Corrige según errores(). Un 422 con el codEstado 3002 no consume cupo. |
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 usaste retryRateLimited(false). |
EcuafactQuotaException |
EcuafactApiException |
HTTP 429 con el codEstado 4004 (cupo_agotado): cupo agotado. |
Amplía el cupo (GET /v1/consumo). No reintentes. |
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. |
Si esReintentable() es true, reintenta más tarde con la misma idempotencyKey(). |
EcuafactApiException |
EcuafactSdkException |
Cualquier otro estado de error de la API que no corresponda a las filas anteriores (por ejemplo, un 418). | Revisa codEstado(), msgError() y errores(). |
EcuafactTipoComprobanteException |
EcuafactSdkException |
El filtro tipoDocumento de listarOperaciones no es un tipo conocido. emitir y validar no la lanzan: el tipo lo da la clase del comprobante. |
Usa un nombre (factura, liquidacion, nota-credito, nota-debito, guia, retencion) o un código (01, 03 a 07). No llama a la API. |
EcuafactResponseTooLargeException |
EcuafactSdkException |
El cuerpo de la respuesta supera el tope maxResponseBytes. Trae limite() y bytesLeidos(). |
Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. |
EcuafactSdkException |
RuntimeException |
Otros errores locales: Idempotency-Key inválida, idOperacion que no es UUID, falta el contribuyente por defecto o un parámetro obligatorio, identificacion que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, . o .., hilo interrumpido, llamada cancelada, o una respuesta 2xx vacía o ilegible. |
Corrige la llamada. Si ocurre al emitir, repite la emisión con la idempotencyKey() de la excepción, como se explica en Idempotencia y reintentos. |
Método de EcuafactApiException |
Tipo | Descripción |
|---|---|---|
codEstado() |
int |
Código numérico del catálogo de codEstado, por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de CodEstado. Es 0 si la respuesta no traía JSON. |
estado() |
String |
estado de la respuesta de error, como rechazado, rechazo_configuracion o error; null si la respuesta no traía JSON. |
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. |
errores() |
List<String> |
Detalle específico del error, como la ruta del campo que falla en un 3002. Nunca es null y está vacía cuando no hay detalle. |
correlationId() |
String |
Cabecera X-Correlation-Id. Inclúyelo al pedir soporte. |
idempotencyKey() |
String |
Clave usada en la emisión; reutilízala al reintentar. Todas las excepciones del SDK la exponen. |
retryAfter() |
Duration |
Espera indicada por la cabecera Retry-After; null si no llegó. |
esReintentable() |
boolean |
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) no es reintentable. |
EcuafactConnectionException y EcuafactTimeoutException no traen respuesta
de la API, así que no tienen codEstado(). Exponen idempotencyKey() y
correlationId(), que devuelve el X-Correlation-Id que enviaste con
RequestOptions.correlationId(String), o null si no enviaste uno.
import com.ecuafact.sdk.EcuafactApiException;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactConnectionException;
import com.ecuafact.sdk.EcuafactQuotaException;
import com.ecuafact.sdk.EcuafactRateLimitException;
import com.ecuafact.sdk.EcuafactTimeoutException;
import com.ecuafact.sdk.EcuafactValidationException;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
FacturaRequest comprobante = new ObjectMapper()
.enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)
.readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class);
try {
EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println(r.admission().estado() + " " + r.admission().idOperacion());
} catch (EcuafactValidationException error) {
// Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual.
error.errores().forEach(System.out::println);
} catch (EcuafactQuotaException error) {
System.out.println("Cupo agotado: compra un paquete. No reintentes.");
} catch (EcuafactRateLimitException error) {
System.out.println("Limite de solicitudes: espera " + error.retryAfter() + " y reintenta con " + error.idempotencyKey());
} catch (EcuafactApiException error) {
System.out.println(error.estadoHttp() + " codEstado " + error.codEstado() + " " + error.msgError() + " " + error.errores()
+ " reintentable=" + error.esReintentable() + " correlation=" + error.correlationId());
} catch (EcuafactConnectionException | EcuafactTimeoutException error) {
// Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key.
System.out.println(error.getMessage() + " clave=" + error.idempotencyKey());
}
Estos son los códigos que verás con más frecuencia. El catálogo completo, con
el nombre de cada código, está en
Errores, y las constantes de CodEstado
llevan ese mismo nombre, escrito con la convención del lenguaje.
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 llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el correlationId(). |
| 3011 | acceso_denegado |
403 | Contribuyente, tipo de comprobante no habilitado, o infoTributaria.ruc no coincide con el contribuyente de la ruta. |
Revisa getContexto() (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. |
| 3003 | solicitud_invalida |
400 | Cabeceras inválidas (por ejemplo, Idempotency-Key con caracteres no permitidos) 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 | Filtro de consulta fuera de rango (fechas o max). |
Ajusta los filtros. |
| 3006 | cuerpo_excedido |
413 | Cuerpo mayor a 2 MiB en la emisión (1 MiB en otros POST/PUT). |
Reduce el cuerpo. |
| 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 referenciaExterna con otro contenido. |
Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. |
| 4004 | cupo_agotado |
429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa getConsumo(); compra un paquete. |
| 3013 | no_encontrado |
404 | Operación, comprobante o RIDE no encontrado. | Verifica el id o la clave; 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 o de una caída de la red.
- Si no la pasas, o pasas
nullo un texto vacío, el SDK genera un UUID sin guiones, lo usa en todos sus reintentos y te la devuelve enresultado.idempotencyKey()o, si falla, enerror.idempotencyKey(). - Te recomendamos pasar un valor estable por intención, como tu número interno de factura, o un UUID v4 que guardes 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.
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.
Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción
(EcuafactSdkException) conserva la Idempotency-Key en idempotencyKey() y
en su mensaje trae el X-Correlation-Id de la solicitud; repite la emisión con
esa misma clave y no se duplica el comprobante.
| Situación | Se reintenta | Detalle |
|---|---|---|
| HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con retryableStatusCodes. Solo en GET y en POST/PUT con Idempotency-Key (la emisión siempre la lleva). |
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. Un 429 sin el codEstado 5005, por ejemplo de un proxy intermedio, no se reintenta. |
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í | Se reintenta en las mismas condiciones; al agotar los intentos lanza EcuafactConnectionException o EcuafactTimeoutException. |
| Descarga de RIDE/XML y consultas | Sí | Como son GET, se reintentan ante un estado HTTP transitorio o un error de red. |
Validación sin emitir (validar, validarEn) |
Sí | Se reintenta como una consulta ante un estado HTTP transitorio o un error de red. No lleva Idempotency-Key porque no emite nada. |
actualizarPerfil, actualizarLogo |
No | No llevan Idempotency-Key, así que un reintento automático podría repetir el efecto. |
| Cualquier otro 4xx | No | Se lanza la excepción de inmediato. |
Antes del reintento número n, el SDK espera según estas reglas:
LINEAR:retryBaseDelayx n más un margen aleatorio de hastaretryJitterx n.EXPONENTIAL:retryBaseDelayx 2^(n-1) más un margen aleatorio de hastaretryJitter.- Si la respuesta trae un
Retry-Aftermayor yrespectRetryAfterestrue, espera ese tiempo. - La espera nunca supera
maxRetryDelay, salvo que ese valor seaDuration.ZERO.
Con totalTimeout, cada intento se acorta al tiempo que queda. Si la siguiente
espera no cabe dentro del tope, el SDK no reintenta y lanza la excepción del
último intento; si el tope ya se agotó antes de un intento, lanza
EcuafactTimeoutException. Si interrumpes el hilo durante una llamada
síncrona, el SDK cancela la solicitud y lanza EcuafactSdkException.
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. Lo que no indiques usa la configuración del cliente.
Los métodos que llaman a la API tienen una sobrecarga con RequestOptions como
último parámetro, también en la vista para(...) y esperarResultado. Algunas sobrecargas exigen además los parámetros anteriores.
- Emisión:
emitir(comprobante, idempotencyKey, opciones)yemitirEn(identificacion, comprobante, idempotencyKey, opciones); pasanullcomoidempotencyKeypara que el SDK la genere. - Espera:
esperarResultado(idOperacion, intervalo, maximo, opciones);opcionesse aplica a cada consulta.
Método de RequestOptions |
Qué hace |
|---|---|
RequestOptions.create() |
Crea las opciones vacías. |
timeout(Duration) |
Tiempo máximo de cada intento, solo en esta llamada. Mayor que cero. |
totalTimeout(Duration) |
Tope de esta llamada, incluidos reintentos y esperas. Mayor que cero. |
correlationId(String) |
Se envía en la cabecera X-Correlation-Id. De 1 a 64 caracteres: letras, dígitos y . _ -. |
reintentos(false) |
Un solo intento en esta llamada. reintentos(true) aplica la política del cliente: no activa reintentos si el cliente los tiene desactivados. |
validarAntes(boolean) |
Solo en emitir y emitirEn: true llama a /validar antes de emitir y false no lo llama, sea cual sea validarAntesDeEmitir del cliente. |
additionalInfo(String) |
Valor de la cabecera X-Additional-Info solo en esta llamada; reemplaza el del cliente. Con una cadena vacía o null no se envía la cabecera en esta llamada. Mismas reglas que la opción del cliente. |
La API devuelve la correlación que enviaste. La encuentras en
EmisionResultado.correlationId() y en EcuafactApiException.correlationId().
Úsala para relacionar tus registros con los nuestros y para pedirnos soporte.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import com.ecuafact.sdk.contracts.Contexto;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
// Un solo intento y correlacion propia para esta consulta.
Contexto contexto = client.getContexto(RequestOptions.create()
.reintentos(false)
.correlationId("pedido-2026-0457"));
System.out.println("Contribuyentes: " + contexto.contribuyentes().size());
// Mas tiempo para una descarga grande, con tope total de 2 minutos.
ArchivoComprobante ride = client.descargarRide(
"0123456789001",
"0710202601012345678900110010010000001231234567811",
RequestOptions.create().timeout(Duration.ofSeconds(60)).totalTimeout(Duration.ofMinutes(2)));
Files.write(Path.of("ride.pdf"), ride.contenido());
Reemplaza la claveAcceso del ejemplo por la de un comprobante autorizado de tu
emisor. Si pasas un valor inválido, como un correlationId con espacios o de
más de 64 caracteres, un additionalInfo fuera de sus reglas o un tiempo menor
o igual a cero, el SDK lanza EcuafactConfigurationException al armar las
opciones, sin llamar a la API.
Variantes asíncronas y cancelación#
Los métodos que llaman a la API tienen una variante *Async que devuelve un
CompletableFuture (por ejemplo emitirEnAsync, getOperacionAsync,
descargarRideAsync y esperarResultadoAsync).
cancel(true)aborta la solicitud HTTP en curso y los reintentos pendientes. Lo mismo ocurre si el futuro termina por otra vía antes de la respuesta, por ejemplo conorTimeout(...)ocompleteExceptionally(...).- Los argumentos inválidos, como una
Idempotency-Keymal formada, lanzan la excepción de inmediato, antes de devolver el futuro. - Los errores de la API completan el futuro con la excepción del SDK como
causa, que lees con
ExecutionException.getCause()enget()y conCompletionException.getCause()enjoin(). esperarResultadoAsync(idOperacion, intervalo, maximo, opciones)consulta sin bloquear hilos entre consultas y se cancela igual.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactSdkException;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
FacturaRequest comprobante = new ObjectMapper()
.enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)
.readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class);
CompletableFuture<EmisionResultado> envio = client.emitirEnAsync(
"0123456789001", comprobante, "FACTURA-2026-0002",
RequestOptions.create().correlationId("pedido-2026-0458"));
try {
// Espera 30 s como maximo.
EmisionResultado r = envio.get(30, TimeUnit.SECONDS);
System.out.println(r.admission().estado() + " " + r.admission().idOperacion());
} catch (TimeoutException tiempo) {
// Sin respuesta en 30 s: cancela el intento en curso y los reintentos pendientes.
envio.cancel(true);
System.out.println("Cancelada: reintenta despues con la misma Idempotency-Key");
} catch (ExecutionException error) {
if (error.getCause() instanceof EcuafactSdkException sdk) {
System.out.println("Error del SDK: " + sdk.getMessage() + " clave=" + sdk.idempotencyKey());
}
}
Si cancelas una emisión, no sabes si la API la recibió. Reintenta después con la
misma Idempotency-Key y el mismo cuerpo. Si ya se había recibido, la API
responde con el mismo idOperacion y el estado actual de la operación.
En lugar de get(30, TimeUnit.SECONDS) y cancel(true) puedes encadenar
orTimeout. Al vencer el tiempo, el futuro termina con TimeoutException y el
SDK aborta la solicitud en curso.
import com.ecuafact.sdk.EmisionResultado;
import java.util.concurrent.TimeUnit;
EmisionResultado r = client.emitirEnAsync("0123456789001", comprobante, "FACTURA-2026-0002", null)
.orTimeout(30, TimeUnit.SECONDS)
.join(); // CompletionException con TimeoutException como causa si vence
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(String) |
Se envía en todas las solicitudes del cliente, incluidas las de esperarResultado, esperarResultadoAsync y la vista para(...). |
RequestOptions.additionalInfo(String) |
Reemplaza el valor del cliente solo en esa llamada. Si no lo llamas, se usa el del cliente; con cadena vacía o null no se 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.
Si no cumple, el método lanza EcuafactConfigurationException sin llamar a la
API. El valor no aparece en toString() de las opciones ni del cliente, ni en
los mensajes de las excepciones. No pongas en él la API Key ni datos
personales.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.Contexto;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("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 = client.getContexto();
// Solo esta llamada lleva otro valor.
Contexto otro = client.getContexto(RequestOptions.create()
.additionalInfo("erp=MiERP/4.2; sucursal=002; lote=2026-10-08"));
System.out.println("Contribuyentes: " + contexto.contribuyentes().size());
| Error | Por qué pasa | Qué hacer |
|---|---|---|
EcuafactConfigurationException al configurar 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 al armar RequestOptions |
El mismo problema en RequestOptions.additionalInfo(String). No se llamó a la API. |
Corrige el valor de esa llamada. |
Conexión: proxy, TLS y HttpClient propio#
Si necesitas salir por un proxy corporativo, confiar en una CA propia o usar un
certificado de cliente, puedes configurarlo con proxy, sslContext,
executor y connectTimeout. Si no indicas nada, el SDK crea su propio
java.net.http.HttpClient con un connectTimeout de 10 s.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RetryBackoff;
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.time.Duration;
import javax.net.ssl.SSLContext;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
.retryBackoff(RetryBackoff.EXPONENTIAL)
.retryBaseDelay(Duration.ofMillis(500))
.retryRateLimited(true)
.totalTimeout(Duration.ofSeconds(60))
.proxy(ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080)))
.sslContext(SSLContext.getDefault())
.connectTimeout(Duration.ofSeconds(5)));
System.out.println(client.getContexto().contribuyentes().size() + " contribuyentes");
Si ya tienes un HttpClient configurado (por ejemplo, compartido con otras
integraciones), pásalo con httpClient(...). En ese caso el SDK no crea el
suyo e ignora proxy, sslContext, executor y connectTimeout.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.http.HttpClient;
import java.time.Duration;
// Dentro de: public static void main(String[] args) throws Exception
HttpClient http = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(5))
.proxy(ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080)))
.build();
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
.httpClient(http));
System.out.println(client.getContexto().contribuyentes().size() + " contribuyentes");
El timeout por intento y los reintentos siguen siendo los de
EcuafactClientOptions aunque pases tu propio HttpClient.
Constructores de comprobantes#
Puedes armar la Estructura del comprobante con métodos en lugar de escribir el JSON.
ComprobanteBuilder es opcional. Solo ensambla el request de su tipo (FacturaRequest, NotaCreditoRequest, etc.) con los
valores que le das: no calcula totales, impuestos ni redondeos, y no completa
valores por defecto. Tú calculas los importes y la API los calcula y valida
igual que si armaras el JSON a mano. No es seguro para uso concurrente, así
que crea un constructor por comprobante.
import com.ecuafact.sdk.ComprobanteBuilder;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.Tarifa;
import com.ecuafact.sdk.contracts.DetalleCompraVenta;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.ecuafact.sdk.contracts.Impuesto;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.ZoneId;
import java.util.List;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
// Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor.
ComprobanteBuilder<FacturaRequest> factura = ComprobanteBuilder.factura("0123456789001", "001", "001")
.referencias("MiERP", "FACTURA-2026-0002")
.fechaEmision(LocalDate.now(ZoneId.of("America/Guayaquil")))
.comprador("07", "9999999999999", "CONSUMIDOR FINAL")
.moneda("DOLAR")
// Los importes de la linea y de totalConImpuestos los das tu: el SDK no los calcula.
.linea(new DetalleCompraVenta("SERV-001", null, "Servicio de prueba", new BigDecimal("1"),
new BigDecimal("10.00"), BigDecimal.ZERO, new BigDecimal("10.00"),
List.of(new Impuesto("2", "4", new BigDecimal("15"), new BigDecimal("10.00"), new BigDecimal("1.50"))),
null))
.totalSinImpuestos(new BigDecimal("10.00"))
.totalDescuento(BigDecimal.ZERO)
.totalConImpuestos(List.of(new Impuesto("2", "4", new BigDecimal("15"), new BigDecimal("10.00"),
new BigDecimal("1.50"))))
.propina(BigDecimal.ZERO)
.importeTotal(new BigDecimal("11.50"))
.pago("01", new BigDecimal("11.50"));
FacturaRequest comprobante = factura.construir();
System.out.println("importeTotal " + comprobante.info().importeTotal()); // 11.50
EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0002",
RequestOptions.create().correlationId("pedido-2026-0458"));
System.out.println(r.admission().estado() + " " + r.admission().idOperacion() + " " + r.correlationId());
Deberías ver importeTotal 11.50 y luego
recibido <idOperacion> pedido-2026-0458. Si ejecutas el programa otro día con la
misma Idempotency-Key, la API responde 409 con el codEstado 3005 (conflicto_idempotencia); en ese caso usa una
Idempotency-Key y una referenciaExterna nuevas.
| Tipo | Entrada | Métodos propios |
|---|---|---|
Factura (01) |
ComprobanteBuilder.factura(ruc, estab, ptoEmi) |
comprador, direccionComprador, correo, telefono, linea, ice, propina, moneda, pago |
Liquidación de compra (03) |
ComprobanteBuilder.liquidacionCompra(ruc, estab, ptoEmi) |
proveedor, direccionProveedor, linea, ice, moneda, pago |
Nota de crédito (04) |
ComprobanteBuilder.notaCredito(ruc, estab, ptoEmi) |
comprador, docModificado, totalDocumentoSustento, motivo(razon), linea, ice, moneda |
Nota de débito (05) |
ComprobanteBuilder.notaDebito(ruc, estab, ptoEmi) |
comprador, docModificado, iva(Tarifa), motivo(razon, valor), valorTotal, impuestos, pago |
Guía de remisión (06) |
ComprobanteBuilder.guiaRemision(ruc, estab, ptoEmi) |
dirPartida, transportista, placa, fechasTransporte, destinatario, codEstabDestino, ruta, docAduaneroUnico, bien(codigoInterno, descripcion, cantidad) |
Retención (07) |
ComprobanteBuilder.retencion(ruc, estab, ptoEmi) |
sujetoRetenido, periodoFiscal, parteRelacionada, docSustento, impuestoSustento, lineaRetencion, pago |
Todos los constructores tienen además referencias(origen, externa), secuencial, fechaEmision
(texto dd/MM/yyyy o LocalDate), dirEstablecimiento,
infoAdicional(nombre, valor) y construir().
Algunos métodos tienen reglas propias:
- En
linea(codigo, descripcion, cantidad, precioUnitario, descuento, tarifa),codigoes elcodigoPrincipalen la factura y la liquidación, y elcodigoInternoen la nota de crédito.descuentoes un importe en dólares ytarifaes unTarifa.of(codigoPorcentaje, tarifa).linea(DetalleCompraVenta)(factura y liquidación) ylinea(DetalleNotaCredito)agregan una línea armada por ti, con sus importes. ice(codigoPorcentaje, tarifa),codigoAuxiliar(no existe en la nota de crédito) ydetalleAdicional(nombre, valor)se aplican a la últimalinea.- El pago se agrega con
pago(formaPago),pago(formaPago, total)opago(formaPago, total, plazo, unidadTiempo). En la retención, los pagos van dentro del documento de sustento. bien,codEstabDestino,rutaydocAduaneroUnicose aplican al últimodestinatario(identificacion, razonSocial, direccion, motivoTraslado).docSustento(codSustento, codDocSustento, numDocSustento, fechaEmisionDocSustento, fechaRegistroContable, numAutDocSustento)agrega el documento de sustento de la retención;impuestoSustento,lineaRetencion,pagoLocExt,totalSinImpuestoseimporteTotalse aplican a él.pagoLocExtno tiene valor por defecto.- Puedes asignar estos totales:
totalSinImpuestos,totalDescuento,totalConImpuestos,importeTotal,valorModificacion(nota de crédito),valorTotaleimpuestos(nota de débito).
El constructor es genérico por tipo. ComprobanteBuilder.factura(...) devuelve ComprobanteBuilder<FacturaRequest> y construir() devuelve FacturaRequest; lo mismo en los demás tipos. Un dato que el tipo no tiene (por ejemplo proveedor(...) en una factura) lanza EcuafactSdkException al construir, en lugar de descartarse en silencio.
Lo que asignas se envía tal cual. Todo valor que asignes (subtotal de
línea, impuestos, bases, totales, propina, moneda, pagos) se envía exactamente
como lo diste, y lo que no asignes no se envía: el constructor no completa
totales, impuestos, propina, moneda, pagoLocExt ni el total de un pago.
Los BigDecimal conservan su precisión sin pérdida.
| Elemento | Detalle |
|---|---|
| Tarifa de una línea | Tarifa.of(codigoPorcentaje, tarifa) con el codigoPorcentaje del catálogo y la tarifa en porcentaje (15, no 0.15). El SDK envía la pareja tal como la defines. |
| Validación | El constructor no valida reglas de negocio ni calcula: solo ayuda a armar el cuerpo. Valida con client.validar(...) o emite y lee el 422 de la API, que es la única que calcula y decide. |
Métodos#
Esta es la referencia de los métodos de EcuafactClient. La identificación
que reciben es siempre el valor identificacion del contexto. Los métodos que
llaman a la API tienen además una sobrecarga con RequestOptions, descrita en
Opciones por llamada, y todos
tienen una variante *Async, descrita en
Variantes asíncronas.
| Método | Endpoint | Devuelve |
|---|---|---|
getContexto() |
GET /v1/contexto |
Contexto (ver Contexto y consumo) |
emitir(comprobante) / emitir(comprobante, idempotencyKey) |
POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo} |
EmisionResultado (ver Ruta de emisión por tipo de comprobante) |
emitirEn(identificacion, comprobante) / emitirEn(identificacion, comprobante, idempotencyKey) |
POST /v1/contribuyentes/{identificacion}/{ruta del tipo} |
EmisionResultado |
validar(comprobante) |
POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar |
ValidacionResultado (ver Validar sin emitir) |
validarEn(identificacion, comprobante) |
POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar |
ValidacionResultado |
getOperacion(idOperacion) |
GET /v1/operaciones/{idOperacion} |
Operation. idOperacion debe ser un UUID. |
consultarOperacion(idOperacion) |
GET /v1/operaciones/{idOperacion} |
Operation (alias) |
esperarResultado(idOperacion) / esperarResultado(idOperacion, intervalo, maximo) |
GET /v1/operaciones/{idOperacion} en bucle |
Operation: la última leída. Opcional; por defecto cada 5 s hasta 120 s. |
descargarRide(identificacion, claveAcceso) |
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride |
ArchivoComprobante (PDF) |
descargarXml(identificacion, claveAcceso) |
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml |
ArchivoComprobante (XML del comprobante autorizado) |
getConsumo() |
GET /v1/consumo |
QuotaBucket (ver Contexto y consumo) |
listarOperaciones(identificacion, desde, hasta, tipoDocumento, buscar, pagina, tamanoPagina) |
GET /v1/operaciones |
PaginaComprobantes (ver Listado de operaciones) |
obtenerSalud() |
GET /salud |
boolean: true si el servicio responde. No envía API Key. Ver Estado del servicio y catálogos. |
obtenerEstadoServicio() |
GET /estado |
EstadoServicio (ver Estado del servicio y catálogos). No envía API Key. |
listarCatalogos() |
GET /v1/catalogos |
Catalogos (ver Estado del servicio y catálogos) |
obtenerCatalogo(nombre) |
GET /v1/catalogos/{nombre} |
CatalogoDetalle (ver Estado del servicio y catálogos) |
getPerfil(identificacion) |
GET /v1/contribuyentes/{identificacion}/perfil |
PerfilEmisor |
actualizarPerfil(identificacion, cambios) |
PUT /v1/contribuyentes/{identificacion}/perfil |
PerfilEmisor (cambios es un PerfilEmisorUpdate) |
actualizarLogo(identificacion, contenido, contentType, nombreArchivo) |
POST /v1/contribuyentes/{identificacion}/perfil/logo |
PerfilEmisor (ver Logo del perfil) |
consultarContribuyente(identificacion) / consultarContribuyente(identificacion, fusionar, fuente) |
GET /v1/consultas/contribuyentes/{identificacion} |
ContribuyenteConsulta. Sin argumentos extra envía fusionar=true. |
buscarContribuyentes(apellidos) / buscarContribuyentes(apellidos, nombres, clase, max) |
GET /v1/consultas/contribuyentes |
List<BusquedaContribuyente> |
listarEstablecimientos(ruc) / listarEstablecimientos(ruc, filtro) |
GET /v1/consultas/establecimientos/{ruc} |
EstablecimientosContribuyente |
validarIdentificacion(numero) |
GET /v1/consultas/identificacion/validar/{numero} |
ValidacionIdentificacion (revisa valido()) |
decodificarClaveAcceso(claveAcceso) |
GET /v1/consultas/comprobantes/decodificar/{claveAcceso} |
ClaveAccesoDecodificada |
para(identificacion) |
- (no llama a la API) | EcuafactContribuyente (ver Varios contribuyentes) |
WebhookEvent.construir(...) y WebhookSignature.verify(...) |
- (local) | WebhookEvent o boolean (ver Webhooks) |
Ten en cuenta además estos detalles de los métodos y de sus tipos:
- Si no configuras
identificacionen las opciones,emitirlanzaEcuafactSdkException. En ese caso usa la variante que recibe la identificación o la vistapara(...). ArchivoComprobantetienecontenido()(byte[]) ycontentType(). Las descargas solo existen con el comprobante autorizado; ver Descargar XML.PerfilEmisoryPerfilEmisorUpdateson clases con campos públicos (perfil.razonSocial), norecord.
Importes exactos#
Todos los importes, cantidades, precios y tarifas son java.math.BigDecimal
(por ejemplo InfoFactura.importeTotal(), DetalleCompraVenta.precioUnitario(),
Comprobante.total()). Un BigDecimal creado desde
texto guarda 11.50 exacto y el SDK lo envía como número JSON sin notación
científica. Pago.plazo() es un BigDecimal (el contrato lo tipa number) que cuenta
unidades de unidadTiempo; pago(...) del constructor acepta también un
Integer.
Crea los importes desde texto, como new BigDecimal("11.50"), y nunca desde un
double, porque new BigDecimal(11.5) arrastra el error binario. Después
redondea a 2 decimales.
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.nio.file.Files;
import java.nio.file.Path;
// Dentro de: public static void main(String[] args) throws Exception
ObjectMapper mapper = new ObjectMapper().enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS);
ObjectNode json = (ObjectNode) mapper.readTree(Files.readString(Path.of("comprobante.json")));
BigDecimal baseImponible = new BigDecimal("10.00");
BigDecimal iva = baseImponible.multiply(new BigDecimal("0.15")).setScale(2, RoundingMode.HALF_UP); // 1.50
((ObjectNode) json.get("info")).put("totalSinImpuestos", baseImponible);
((ObjectNode) json.get("info")).put("importeTotal", baseImponible.add(iva)); // 11.50
System.out.println(json.get("info").get("importeTotal").decimalValue()); // 11.50
Las reglas de cálculo de cada comprobante están en Factura.
Varios contribuyentes#
Si no configuras identificacion en las opciones, pasa la identificación en
cada llamada o crea una vista por contribuyente. La vista repite la
identificación por ti en cada método.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactContribuyente;
import com.ecuafact.sdk.contracts.PerfilEmisor;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
EcuafactContribuyente matriz = client.para("0123456789001");
PerfilEmisor perfil = matriz.getPerfil();
System.out.println(perfil.razonSocial + " (" + perfil.identificacion + ")");
La vista EcuafactContribuyente tiene estos métodos. Los que llaman a la API
aceptan además RequestOptions al final; en emitir, después de
idempotencyKey.
| Método | Equivale a |
|---|---|
identificacion() |
La identificación de la vista. |
emitir(comprobante) / emitir(comprobante, idempotencyKey) |
client.emitirEn(identificacion, ...) |
validar(comprobante) |
client.validarEn(identificacion, comprobante) |
descargarRide(claveAcceso) |
client.descargarRide(identificacion, claveAcceso) |
descargarXml(claveAcceso) |
client.descargarXml(identificacion, claveAcceso) |
getPerfil() |
client.getPerfil(identificacion) |
actualizarPerfil(cambios) |
client.actualizarPerfil(identificacion, cambios) |
actualizarLogo(contenido, contentType, nombreArchivo) |
client.actualizarLogo(identificacion, ...) |
esperarResultado(idOperacion) / esperarResultado(idOperacion, intervalo, maximo) |
client.esperarResultado(...) |
getConsumo() |
client.getConsumo() (el cupo es de la API Key, no del contribuyente) |
Logo del perfil#
Con actualizarLogo 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, y contentType
es obligatorio (image/png o image/jpeg); si no indicas nombreArchivo, el
SDK usa logo. Un archivo vacío lanza EcuafactSdkException sin llamar a la
API, y la subida no se reintenta automáticamente.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.PerfilEmisor;
import java.nio.file.Files;
import java.nio.file.Path;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
byte[] logo = Files.readAllBytes(Path.of("logo.png"));
PerfilEmisor perfil = client.actualizarLogo("0123456789001", logo, "image/png", "logo.png");
System.out.println("Logo actualizado para " + perfil.razonSocial + ": " + perfil.logo);
Las reglas del archivo y los errores posibles están en Perfil del emisor.
Contexto y consumo#
Antes de emitir puedes preguntar con qué contribuyentes puedes trabajar y
cuántos documentos te quedan. getContexto() lee el
contexto de tu API Key y getConsumo() lee tu
cupo. Ninguna de las dos consume cupo.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.Contexto;
import com.ecuafact.sdk.contracts.QuotaBucket;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
Contexto contexto = client.getContexto();
contexto.contribuyentes().forEach(c ->
System.out.println(c.identificacion() + " " + c.puedeEmitir() + " " + c.tiposComprobante()));
QuotaBucket cupo = client.getConsumo();
System.out.println("Disponibles " + cupo.disponibles() + " de " + cupo.limiteDocumentos()
+ "; vigente hasta " + cupo.vigenteHasta());
getContexto() devuelve un Contexto. La identificacion() de cada
contribuyente es la completa que devuelve el contexto, y es la que va en las
rutas y en infoTributaria.ruc.
| Método | Tipo | Descripción |
|---|---|---|
Contexto.idCliente() |
String |
Identificador de tu integración. |
Contexto.nombre() |
String |
Nombre de tu integración. |
Contexto.contribuyentes() |
List<Contribuyente> |
Contribuyentes habilitados para tu API Key en el ambiente de la URL. |
Contribuyente.identificacion() |
String |
Identificación completa del contribuyente; úsala en las rutas. |
Contribuyente.puedeEmitir() |
boolean |
true si tu API Key puede emitir para este contribuyente. |
Contribuyente.puedeRecibir() |
boolean |
true si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. |
Contribuyente.tiposComprobante() |
List<String> |
Códigos de los tipos de comprobante habilitados (01, 03, 04, 05, 06, 07). |
Contribuyente.marcaBlanca() |
boolean |
true si el contribuyente es un emisor de marca blanca: sus comprobantes no tienen RIDE, y el XML se descarga igual. |
getConsumo() devuelve un QuotaBucket. Cada comprobante que el SRI autoriza
o rechaza consume un documento de tu cupo, y uno cancelado no lo consume.
| Método | Tipo | Descripción |
|---|---|---|
limiteDocumentos() |
int |
Documentos contratados en total: la suma de tus paquetes vigentes. |
reservados() |
int |
Documentos de emisiones recibidas que aún no tienen resultado final. |
consumidos() |
int |
Documentos descontados por emisiones con resultado final. |
disponibles() |
int |
Documentos que aún puedes emitir con tus paquetes vigentes. |
vigenteHasta() |
String |
Fecha y hora (ISO 8601, UTC) en que vence el próximo paquete con saldo. |
limiteExtra(), reservadosExtra(), consumidosExtra(), disponiblesExtra() |
int |
Se mantienen por compatibilidad y valen 0: todo el saldo está en los cuatro valores anteriores. |
El significado de cada valor, con un ejemplo numérico, está en Consumo y cuotas.
Listado de operaciones#
listarOperaciones devuelve una página de los comprobantes de un contribuyente
(GET /v1/operaciones) y no consume cupo. La identificacion es obligatoria; los
demás filtros pueden ir en null: desde y hasta en formato yyyy-MM-dd,
tipoDocumento (el código o el nombre del tipo), buscar (número, clave de
acceso, contraparte o referencia), pagina desde 1 y tamanoPagina de 1 a 100.
Si un filtro no tiene el formato esperado, el SDK lanza EcuafactSdkException
sin llamar a la API.
import com.ecuafact.sdk.contracts.Comprobante;
import com.ecuafact.sdk.contracts.PaginaComprobantes;
int numero = 1;
PaginaComprobantes pagina;
do {
pagina = client.listarOperaciones("0123456789001", "2026-11-01", "2026-11-30", null, null, numero, 50);
for (Comprobante fila : pagina.comprobantes()) {
System.out.println(fila.numeroDocumento() + " " + fila.estado() + " " + fila.codEstado() + " " + fila.total());
}
numero++;
} while (Boolean.TRUE.equals(pagina.hayMas()));
La respuesta es un PaginaComprobantes con comprobantes, pagina,
tamanoPagina y hayMas; mientras hayMas sea true, pide la página siguiente.
Cada fila es un Comprobante con claveAcceso, numeroDocumento,
tipoDocumento, fechaEmision, identificacionContraparte,
razonSocialContraparte, total, estado, codEstado, msgError, errores y
fhAutorizacion; estadoOperacion() y tipoComprobante() devuelven los valores
tipados. La vista client.para(identificacion) ofrece listarOperaciones con la
identificación fija.
Estado del servicio y catálogos#
Puedes consultar el estado público del servicio y los catálogos del SRI sin
armar ninguna petición. obtenerEstadoServicio() lee el
estado del servicio y no envía API Key, así que
sirve para comprobar la disponibilidad antes de configurar una credencial o
desde tus propias alertas. listarCatalogos() y obtenerCatalogo(nombre) leen
los catálogos del SRI con la API Key del cliente. Los
catálogos cambian pocas veces al año, así que puedes guardar sus respuestas en
caché por una hora.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EcuafactNotFoundException;
import com.ecuafact.sdk.contracts.CatalogoDetalle;
import com.ecuafact.sdk.contracts.CatalogoItem;
import com.ecuafact.sdk.contracts.Catalogos;
import com.ecuafact.sdk.contracts.EstadoServicio;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
EstadoServicio estado = client.obtenerEstadoServicio();
System.out.println(estado.estado() + " " + estado.disponibilidad90Dias());
estado.componentes().forEach(c -> System.out.println(c.nombre() + " " + c.estado()));
estado.incidentes().forEach(i -> System.out.println(i.inicio() + " " + i.impacto() + " " + i.titulo() + " " + i.fin()));
Catalogos indice = client.listarCatalogos();
indice.catalogos().forEach(c -> System.out.println(c.nombre() + " " + c.descripcion()));
try {
CatalogoDetalle tarifas = client.obtenerCatalogo("tarifas-iva");
for (CatalogoItem fila : tarifas.items()) {
System.out.println(fila.codigo() + " " + fila.descripcion() + " " + fila.valor());
}
} catch (EcuafactNotFoundException error) {
System.out.println("Ese catálogo no existe");
}
Si el catálogo tarifas-iva existe, el programa imprime una línea por cada
código de IVA con su tarifa. Con una clave que no está en el índice, la API
responde 404 con el codEstado 3013 (no_encontrado) y el SDK lanza
EcuafactNotFoundException. Los demás errores siguen la jerarquía de
Errores. Un nombre vacío lanza EcuafactSdkException sin llamar a
la API.
Estado del servicio#
obtenerEstadoServicio() devuelve un EstadoServicio, un record con los
mismos campos que la respuesta de la consulta.
| Método | Tipo | Descripción |
|---|---|---|
estado() |
String |
Estado general: operativo, degradado, caido o sin_datos. |
medidoEn() |
String |
Momento de la última medición (ISO 8601, UTC). null si todavía no hay mediciones. |
componentes() |
List<ComponenteEstado> |
Componentes monitoreados. |
disponibilidad90Dias() |
Double |
Porcentaje de minutos sin caída en los últimos 90 días. null si aún no hay muestras. |
incidentes() |
List<IncidentePublico> |
Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo. |
Método de ComponenteEstado |
Tipo | Descripción |
|---|---|---|
nombre() |
String |
Nombre del componente. |
estado() |
String |
operativo, degradado, caido o sin_datos. |
Método de IncidentePublico |
Tipo | Descripción |
|---|---|---|
inicio() |
String |
Inicio del incidente (ISO 8601, UTC). |
fin() |
String |
Fin del incidente. null mientras sigue abierto. |
impacto() |
String |
degradado o caido. |
titulo() |
String |
Título breve. |
detalle() |
String |
Qué significó para tus integraciones. null si no hay detalle. |
Qué hacer ante cada estado se explica en
Valores de estado.
Para comprobar solo que el servicio responde, obtenerSalud() llama a
GET /salud, que no requiere API Key, y devuelve true; si la respuesta no es
2xx, lanza la excepción correspondiente.
Catálogos#
listarCatalogos() devuelve un Catalogos y obtenerCatalogo(nombre), un
CatalogoDetalle. El nombre es la clave que devuelve el índice, como
tarifas-iva; las claves disponibles están en
Catálogos disponibles.
| Método | Tipo | Descripción |
|---|---|---|
Catalogos.catalogos() |
List<CatalogoResumen> |
Catálogos disponibles, en el orden de la ficha técnica del SRI. |
CatalogoResumen.nombre() |
String |
Clave del catálogo; es el valor que recibe obtenerCatalogo. |
CatalogoResumen.descripcion() |
String |
Descripción breve de lo que contiene. |
CatalogoDetalle.nombre() |
String |
Clave del catálogo. |
CatalogoDetalle.descripcion() |
String |
Descripción breve del catálogo. |
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. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. |
CatalogoItem.descripcion() |
String |
Descripción del código. |
CatalogoItem.valor() |
BigDecimal |
Valor numérico asociado, por ejemplo la tarifa en porcentaje. null si el catálogo no lo tiene. |
CatalogoItem.vigenteDesde() |
String |
Primer día de vigencia (yyyy-MM-dd). null si la fila no está acotada por el inicio. |
CatalogoItem.vigenteHasta() |
String |
Último día de vigencia (yyyy-MM-dd). null si sigue vigente. |
CatalogoItem.atributos() |
Map<String, Object> |
Atributos propios del catálogo. null si no hay. |
Consultas SRI#
Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo.
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.BusquedaContribuyente;
import com.ecuafact.sdk.contracts.ContribuyenteConsulta;
import com.ecuafact.sdk.contracts.EstablecimientosContribuyente;
import com.ecuafact.sdk.contracts.ValidacionIdentificacion;
import java.util.List;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
ValidacionIdentificacion validacion = client.validarIdentificacion("0123456789001");
ContribuyenteConsulta contribuyente = client.consultarContribuyente("0123456789001");
List<BusquedaContribuyente> encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
EstablecimientosContribuyente establecimientos = client.listarEstablecimientos("0123456789001", "SoloActivos");
System.out.println(validacion.valido() + " " + encontrados.size());
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.
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.