Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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:

Prompt para agentes

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 codEstado 3010 (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() es false o hay errores(), lanzan EcuafactValidationException (HTTP 422, codEstado 3002) con esos errores(), y la emisión no se envía.
  • Si es válido, envían la emisión y las advertencias quedan en EmisionResultado.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 null o un texto vacío, el SDK genera un UUID sin guiones, lo usa en todos sus reintentos y te la devuelve en resultado.idempotencyKey() o, si falla, en error.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, lanza EcuafactSdkException sin llamar a la API.

Atención

Si reintentas una emisión desde tu aplicación, reutiliza la misma Idempotency-Key. Una clave nueva para el mismo comprobante puede duplicar la emisión.

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: retryBaseDelay x n más un margen aleatorio de hasta retryJitter x n.
  • EXPONENTIAL: retryBaseDelay x 2^(n-1) más un margen aleatorio de hasta retryJitter.
  • Si la respuesta trae un Retry-After mayor y respectRetryAfter es true, espera ese tiempo.
  • La espera nunca supera maxRetryDelay, salvo que ese valor sea Duration.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) y emitirEn(identificacion, comprobante, idempotencyKey, opciones); pasa null como idempotencyKey para que el SDK la genere.
  • Espera: esperarResultado(idOperacion, intervalo, maximo, opciones); opciones se 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 con orTimeout(...) o completeExceptionally(...).
  • Los argumentos inválidos, como una Idempotency-Key mal 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() en get() y con CompletionException.getCause() en join().
  • 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), codigo es el codigoPrincipal en la factura y la liquidación, y el codigoInterno en la nota de crédito. descuento es un importe en dólares y tarifa es un Tarifa.of(codigoPorcentaje, tarifa). linea(DetalleCompraVenta) (factura y liquidación) y linea(DetalleNotaCredito) agregan una línea armada por ti, con sus importes.
  • ice(codigoPorcentaje, tarifa), codigoAuxiliar (no existe en la nota de crédito) y detalleAdicional(nombre, valor) se aplican a la última linea.
  • El pago se agrega con pago(formaPago), pago(formaPago, total) o pago(formaPago, total, plazo, unidadTiempo). En la retención, los pagos van dentro del documento de sustento.
  • bien, codEstabDestino, ruta y docAduaneroUnico se aplican al último destinatario(identificacion, razonSocial, direccion, motivoTraslado).
  • docSustento(codSustento, codDocSustento, numDocSustento, fechaEmisionDocSustento, fechaRegistroContable, numAutDocSustento) agrega el documento de sustento de la retención; impuestoSustento, lineaRetencion, pagoLocExt, totalSinImpuestos e importeTotal se aplican a él. pagoLocExt no tiene valor por defecto.
  • Puedes asignar estos totales: totalSinImpuestos, totalDescuento, totalConImpuestos, importeTotal, valorModificacion (nota de crédito), valorTotal e impuestos (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 identificacion en las opciones, emitir lanza EcuafactSdkException. En ese caso usa la variante que recibe la identificación o la vista para(...).
  • ArchivoComprobante tiene contenido() (byte[]) y contentType(). Las descargas solo existen con el comprobante autorizado; ver Descargar XML.
  • PerfilEmisor y PerfilEmisorUpdate son clases con campos públicos (perfil.razonSocial), no record.

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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

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

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

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

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

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