Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

SDK PHP

Biblioteca oficial para emitir comprobantes desde PHP 8.2 o superior, seguir su autorización, descargar el RIDE y verificar webhooks.

Si desarrollas en PHP, puedes integrarte con nuestros servicios de facturación usando nuestro SDK para PHP. Lo instalas con Composer y, en lugar de armar cada petición con cURL, llamas a métodos como emitirEn o descargarRide, que reciben y devuelven clases tipadas. Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la Idempotency-Key en sus reintentos; además envía tu API Key en cada llamada, te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te enviamos.

Esta guía sigue el orden de una integración. Primero instalas el paquete, configuras el cliente, emites tu primera factura y sigues su resultado; 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. 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 PHP 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-php.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 composer require ecuafact/sdk. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere PHP 8.2 o superior con ext-curl. 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
Paquete Composer ecuafact/sdk
Versión v1.0.1
PHP 8.2 o superior, con las extensiones curl y json.
Dependencias No necesita otras dependencias fuera de las extensiones. Solo si usas tu propio cliente PSR-18 necesitas psr/http-client y psr/http-factory.
Repositorio github.com/Ecuanexus/ecuafact-sdk-php
Cliente Es síncrono y usa cURL, o tu cliente PSR-18 con Psr18Transport.
Espacio de nombres Ecuafact\Sdk (cliente, opciones, excepciones, webhooks), Ecuafact\Sdk\Contracts (clases de datos), Ecuafact\Sdk\Builders (constructores).

Requisitos#

  • PHP 8.2 o superior, que compruebas con php -v, con la extensión curl habilitada (aparece en la lista de php -m) y Composer.
  • 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).
  • Un contribuyente con puedeEmitir en tu contexto. El sandbox crea uno con el establecimiento 001 y el punto de emisión 001.

Instalación#

Crea una carpeta para la prueba e instala el paquete.

mkdir ecuafact-prueba && cd ecuafact-prueba
composer require ecuafact/sdk

Si prefieres fijar la versión exacta, usa composer require ecuafact/sdk:1.0.1.

Composer crea vendor/autoload.php, que incluyes al inicio de cada script con require __DIR__ . '/vendor/autoload.php';. Para verificar la instalación, ejecuta este comando.

composer show ecuafact/sdk

La instalación funcionó si la salida muestra versions : * v1.0.1.

Configuración#

Crea el cliente una vez por proceso y reutilízalo, porque sirve para todos los contribuyentes de tu API Key. Las opciones se pasan como argumentos con nombre.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    identificacion: '0123456789001', // opcional: contribuyente por defecto
));
var_dump($client->options()); // la API Key aparece como ***

Si no pasas apiKey, o pasas null o el false que devuelve getenv() cuando la variable no existe, el SDK lee la variable de entorno ECUAFACT_API_KEY; si no pasas baseAddress, lee ECUAFACT_BASE_URL. Con las dos variables definidas basta new EcuafactClient(new EcuafactClientOptions()).

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 URL absoluta que debe usar https; el SDK rechaza http con EcuafactConfigurationException. Sin /v1, sin consulta (?), fragmento (#) ni usuario y contraseña.
apiKey ?string ECUAFACT_API_KEY Tu API Key; viaja en la cabecera X-Api-Key. No puede tener espacios al inicio o al final ni caracteres de control. Puedes leerla con $options->apiKey, que es de solo lectura, y no aparece en var_dump, print_r, var_export, json_encode ni en las trazas.
identificacion ?string null Contribuyente por defecto para emitir y validar. Usa el valor identificacion de GET /v1/contexto (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos).
validarAntesDeEmitir bool 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 float 30.0 Tiempo máximo de cada intento, incluida la lectura de la respuesta, en segundos, con fracciones. Debe ser mayor que 0 y solo se aplica con el transporte cURL.
userAgent string Ecuafact.Sdk/1.0 Valor de la cabecera User-Agent. Sin caracteres de control.
retryTransientFailures bool true Reintenta fallos transitorios (ver Reintentos). false desactiva todo reintento.
maxAttempts int 3 Intentos por solicitud, incluido el primero. Debe ser 1 o mayor.
transport ?TransportInterface null (cURL) Transporte HTTP propio, por ejemplo Transport\Psr18Transport para usar tu cliente PSR-18 (ver Conexión).
respectRetryAfter bool true Espera lo que indique la cabecera Retry-After antes de reintentar, si es mayor que la espera calculada.
maxRetryDelaySeconds float 60.0 Espera máxima entre reintentos, en segundos. Con 0 no hay tope.
retryRateLimited bool true Reintenta el 429 por límite de solicitudes, el que trae el codEstado 5005 (limite_solicitudes), respetando Retry-After y maxRetryDelaySeconds. El cupo agotado, un 429 con el codEstado 4004 (cupo_agotado), nunca se reintenta.
retryableStatusCodes ?int[] null = [408, 425, 500, 502, 503, 504] Estados HTTP que se reintentan (enteros entre 100 y 599). El 429 no va aquí: lo controla retryRateLimited. Los valores por defecto están en EcuafactClientOptions::DEFAULT_RETRYABLE_STATUS_CODES.
retryBaseDelaySeconds float 0.2 Espera base entre reintentos, en segundos.
retryBackoff RetryBackoff\|string RetryBackoff::Linear Linear: base x intento (0.2, 0.4, 0.6 s). Exponential: base x 2^(intento-1) (0.2, 0.4, 0.8 s). Acepta también 'linear' o 'exponential'.
retryJitterSeconds float 0.05 Variación aleatoria que se suma a cada espera, en segundos (ver Reintentos).
totalTimeoutSeconds ?float null (sin tope) Tope de toda la llamada, incluidos reintentos y esperas, en segundos. Al superarlo lanza EcuafactTimeoutException. Mayor que 0.
connectTimeout ?float null Tiempo máximo para abrir la conexión, en segundos. Mayor que 0. Solo con el transporte cURL.
proxy ?string null Proxy, por ejemplo http://proxy.miempresa.local:8080. Aparece como *** en var_dump. Solo con el transporte cURL.
caInfo ?string null Ruta a un bundle de CA propio (CA corporativa). Solo con el transporte cURL.
verifyPeer bool true Verificación del certificado TLS. Déjalo en true fuera de pruebas locales. Solo con el transporte cURL.
curlOptions array [] Opciones CURLOPT_* adicionales. Solo con el transporte cURL.
maxResponseBytes ?int 32 MiB (33554432); 100 MiB (104857600) en las descargas de RIDE y XML Tope en bytes del cuerpo de una respuesta. Un entero positivo lo aplica a todas las llamadas, incluidas las descargas; null o 0 lo desactiva. Al superarlo lanza EcuafactResponseTooLargeException con $limite y $bytesLeidos.
additionalInfo ?string null Valor de la cabecera X-Additional-Info en todas las solicitudes, por ejemplo erp=MiERP/4.2; sucursal=quito; no se guarda con el comprobante. Con null o '' no se envía la cabecera. Sus reglas están en Información adicional.
new EcuafactClientOptions(maxResponseBytes: 64 * 1024 * 1024); // 64 MiB; null desactiva el tope

Las opciones se validan al crearlas. EcuafactClientOptions lanza EcuafactConfigurationException, antes de hacer cualquier llamada, en cualquiera de estos casos:

  • Falta la API Key o la URL.
  • La URL no es válida o termina en /v1.
  • La API Key tiene espacios o caracteres de control.
  • timeout no es mayor que 0, o maxAttempts es menor que 1.
  • Un tiempo es negativo.
  • maxResponseBytes es negativo.
  • retryBackoff no es linear ni exponential.
  • additionalInfo tiene caracteres fuera de ASCII imprimible, espacios al inicio o al final o más de 256 caracteres.

El mensaje de la excepción nunca incluye la API Key.

Quickstart: de la API Key al RIDE#

Este script 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 junto al script. Es una factura a consumidor final, con el tipo de identificación 07 y la identificación 9999999999999, que solo se admite en facturas de hasta 50.00. Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva secuencial, porque te asignamos el siguiente secuencial de la serie estab-ptoEmi. El script 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 JSON no lleva el tipo del comprobante: lo da la clase que lo recibe (FacturaRequest en este caso), como se explica en Tipo de comprobante y ruta.

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 script#

Guarda el código siguiente como quickstart.php. Hydrator::hydrate convierte el JSON en las clases del SDK (FacturaRequest, InfoFactura, DetalleCompraVenta...); también puedes construir esos objetos propiedad por propiedad o con los constructores. Hydrator ignora las propiedades del JSON que no existen en las clases del SDK. El SDK usa la clase del comprobante para elegir la ruta.

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; así tu proceso no se queda esperando.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\EcuafactApiException;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\Support\Hydrator;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

try {
    // 1. Contexto: que contribuyentes puede usar tu API Key.
    $contexto = $client->getContexto();
    $emisor = null;
    foreach ($contexto->contribuyentes ?? [] as $contribuyente) {
        if ($contribuyente->puedeEmitir) {
            $emisor = $contribuyente;
            break;
        }
    }
    if ($emisor === null) {
        exit('Tu API Key no tiene un contribuyente habilitado para emitir.' . PHP_EOL);
    }
    echo "Emisor {$emisor->identificacion}" . PHP_EOL;

    // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador).
    /** @var FacturaRequest $comprobante */
    $comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));
    $comprobante->infoTributaria->ruc = $emisor->identificacion;
    $comprobante->info->fechaEmision = (new DateTimeImmutable('now', new DateTimeZone('America/Guayaquil')))->format('d/m/Y');

    // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key.
    $emision = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001');
    $idOperacion = $emision->admission->idOperacion;
    // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos.
    echo "estado {$emision->admission->estado} codEstado {$emision->admission->codEstado} idOperacion {$idOperacion}" . PHP_EOL;

    // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min).
    $operacion = $client->esperarResultado($idOperacion);
    echo "estado {$operacion->estado} codEstado {$operacion->codEstado}" . PHP_EOL;
    foreach ($operacion->errores ?? [] as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }

    // 5. RIDE: solo existe cuando el comprobante esta autorizado.
    if ($operacion->esAutorizado()) {
        $ride = $client->descargarRide($emisor->identificacion, $operacion->claveAcceso);
        file_put_contents('ride.pdf', $ride->contenido);
        echo "RIDE guardado en ride.pdf; claveAcceso {$operacion->claveAcceso}" . PHP_EOL;
    } elseif (!$operacion->esFinal()) {
        echo 'Aun sin resultado: consulta mas tarde o espera el webhook.' . PHP_EOL;
    }
} catch (EcuafactApiException $error) {
    echo "HTTP {$error->estadoHttp} codEstado {$error->codEstado}: {$error->msgError}" . PHP_EOL;
    foreach ($error->errores as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }
    echo "X-Correlation-Id: {$error->correlationId}" . PHP_EOL;
}

Paso 3. Ejecuta y verifica#

php quickstart.php

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 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 codEstado 3002, rechazo_configuracion o error El comprobante no se emitió por su contenido, por la configuración del emisor o por un fallo. Sigue la fila de su codEstado en Códigos de resultado de una operación.
estado cancelado codEstado 6001 La plataforma canceló el envío; no se emitió y no consumió cupo. Emite de nuevo con una nueva Idempotency-Key.
Aun sin resultado Pasaron 2 minutos y el estado sigue en recibido. Vuelve a consultar más tarde o espera el webhook. No emitas de nuevo.
HTTP 401 codEstado 3009 La API Key no es válida. Revisa ECUAFACT_API_KEY.
HTTP 403 codEstado 3011 El contribuyente o el tipo de comprobante no está habilitado, o ruc no coincide con el contribuyente de la ruta. Revisa puedeEmitir y tiposComprobante en el contexto.
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 script 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.

Tipo de comprobante y ruta#

Así como la API tiene un endpoint por tipo de documento, el SDK tiene una clase de solicitud por tipo, y esa clase elige la ruta de emisión y de validación. Pasas la clase a emitir, emitirEn, validar o validarEn y el SDK llama al endpoint de su tipo; no hay campo de tipo en el cuerpo ni argumento de tipo en la llamada.

$emision = $client->emitirEn($identificacion, $factura, 'FACTURA-2026-0001');      // $factura es un FacturaRequest
$validacion = $client->validarEn($identificacion, $notaCredito);                    // $notaCredito es un NotaCreditoRequest

Cada clase tiene solo las propiedades de su esquema del contrato, con los mismos nombres y tipos. En el docblock de cada propiedad, Obligatorio. marca las que el contrato exige; el SDK no las valida, la API responde con un 422 y su detalle. Las clases comunes se reutilizan en todos los tipos.

Clase de solicitud Cabecera Líneas Comunes
FacturaRequest InfoFactura (incluye la exportación) DetalleCompraVenta InfoTributaria, Pago, Impuesto, CampoAdicional
LiquidacionCompraRequest InfoLiquidacionCompra DetalleCompraVenta InfoTributaria, Pago, Impuesto, CampoAdicional
NotaCreditoRequest InfoNotaCredito DetalleNotaCredito InfoTributaria, Impuesto, CampoAdicional
NotaDebitoRequest InfoNotaDebito Motivo InfoTributaria, Pago, Impuesto, CampoAdicional
GuiaRemisionRequest InfoGuiaRemision Destinatario con DetalleGuia InfoTributaria, CampoAdicional
RetencionRequest InfoComprobanteRetencion DocsSustento con ImpuestoDocSustento y RetencionLinea InfoTributaria, Pago, CampoAdicional

Todas implementan SolicitudComprobante, que expone tipoComprobante() (un TipoComprobante), útil si guardas solicitudes de varios tipos en una misma lista. EcuafactTipoComprobanteException solo se lanza cuando el filtro tipoDocumento de listarOperaciones no es uno de los seis tipos.

Código Documento Ruta de emisión Ruta de validación
01 Factura POST /v1/contribuyentes/{identificacion}/facturas POST .../facturas/validar
03 Liquidación de compra POST .../liquidaciones-compra POST .../liquidaciones-compra/validar
04 Nota de crédito POST .../notas-credito POST .../notas-credito/validar
05 Nota de débito POST .../notas-debito POST .../notas-debito/validar
06 Guía de remisión POST .../guias-remision POST .../guias-remision/validar
07 Comprobante de retención POST .../retenciones POST .../retenciones/validar

emitir, emitirEn, validar y validarEn eligen la ruta por ti y no cambian su firma. Las rutas de seguimiento, consulta, descarga y correo no cambian.

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 cumple las reglas de la emisión con validar, o con validarEn si indicas la identificación del contribuyente. La validación usa la ruta del tipo y le agrega /validar; por ejemplo, una nota de crédito (04) se valida en POST .../notas-credito/validar. La validación no emite nada ni consume cupo, y no necesita Idempotency-Key; el SDK no la envía. El detalle de qué se valida está en Validar sin emitir.

El método devuelve un ValidacionResultado con valido, codEstado, msgError, errores, advertencias y correlationId. Cuando el comprobante cumple las reglas, la API responde 200, valido es true, codEstado y msgError son null y errores llega vacío. advertencias trae los avisos que la API devuelve junto al resultado (por ejemplo, que ignora la firma de un XML que la trae); un aviso no impide emitir. Cuando el comprobante no cumple una regla, la API responde 422 con el codEstado 3002 (comprobante_invalido) y el SDK no lanza una excepción: recibes valido en false y los problemas en errores, para que los corrijas antes de emitir.

$validacion = $client->validarEn($emisor->identificacion, $comprobante);
if ($validacion->valido) {
    $emision = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001');
} else {
    foreach ($validacion->errores as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }
}

Cualquier otra respuesta de error lanza la misma excepción que en la emisión. Por ejemplo, si el contribuyente 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 fallos de red o errores temporales del servidor igual que en una consulta. Un comprobante válido todavía puede fallar al emitirse por cupo o porque ya lo emitiste.

Validar antes de cada emisión#

Si quieres que cada emisión pase primero por /validar, activa validarAntesDeEmitir: true en EcuafactClientOptions, o validarAntes: true en RequestOptions para una sola llamada (la opción de la llamada reemplaza a la del cliente). Con la opción activa, emitir y emitirEn 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.

$client = new EcuafactClient(new EcuafactClientOptions(
    apiKey: getenv('ECUAFACT_API_KEY'),
    validarAntesDeEmitir: true,
));
$resultado = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001');
foreach ($resultado->advertencias as $aviso) {
    echo "Aviso: {$aviso}" . PHP_EOL;
}

Seguimiento del resultado#

La emisión responde 202 Accepted en cuanto la API recibe el comprobante, y el resultado del SRI llega después. Puedes conocerlo de tres formas.

Forma Método Cuándo usarla
Esperar en tu proceso esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0, $opciones = null) La usas en scripts, pruebas y procesos que pueden esperar unos segundos.
Consultar una vez getOperacion($idOperacion, $opciones = null) (alias: consultarOperacion) La usas en tareas programadas que revisan operaciones pendientes, o para mostrar el estado cuando un usuario lo pide.
Recibirlo Webhooks En producción, te avisamos sin que consultes.

esperarResultado consulta GET /v1/operaciones/{idOperacion} cada $intervalo segundos hasta que esFinal() sea true o hasta que pasen $maximo segundos, y devuelve la última operación leída, así que revisa esFinal() antes de decidir. Los tiempos se expresan en segundos (float), y un valor negativo lanza EcuafactSdkException. Cada consulta cuenta para tu límite de solicitudes por minuto. $opciones se aplica a cada consulta.

getOperacion, consultarOperacion y esperarResultado exigen que $idOperacion sea un UUID; si no lo es, lanzan EcuafactSdkException sin llamar a la API.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

// Consulta cada 3 segundos, hasta 1 minuto.
$operacion = $client->esperarResultado('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f', 3.0, 60.0);

if ($operacion->esAutorizado()) {
    echo "Autorizado: {$operacion->claveAcceso}" . PHP_EOL;
} elseif ($operacion->esFinal()) {
    echo "Final sin autorizacion: estado {$operacion->estado}, codEstado {$operacion->codEstado}: {$operacion->msgError}" . PHP_EOL;
    foreach ($operacion->errores ?? [] as $detalle) {
        echo " - {$detalle}" . PHP_EOL;
    }
} else {
    echo "Aun sin resultado ({$operacion->estado}); vuelve a consultar con getOperacion mas tarde." . PHP_EOL;
}

Reemplaza el idOperacion del ejemplo por el que recibiste al emitir.

Operation tiene estas propiedades, y todas pueden ser null:

Propiedad Tipo Descripción
estado ?string recibido, autorizado, rechazado, rechazo_configuracion, error o cancelado. Solo recibido no es final.
codEstado ?int 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 ?array Lista de textos con el detalle del resultado; en un rechazo del SRI trae su mensaje. La API la envía siempre, vacía si no hay detalle.
idOperacion ?string UUID de la operación.
urlEstado ?string URL completa del seguimiento.
ambiente ?int 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.

Como todos los modelos de respuesta, Operation tiene además la propiedad extra (array), que guarda los campos que la API devuelve y el modelo no declara, con su nombre como clave y los objetos JSON como arreglos asociativos. Está vacía ([]) cuando no hay campos nuevos y no se envía a la API si serializas el modelo.

El significado de cada estado y de cada codEstado está en Seguimiento de una operación.

Estados tipados#

Operation, Admission y Comprobante conservan las propiedades de la API (estado, codEstado, tipoDocumento) y agregan métodos que devuelven enums de PHP. Un valor que el SDK no conoce no rompe tu código, porque se lee como Desconocido, o como null en tipoComprobante(), y el texto original sigue en la propiedad.

Método Enum Casos
$operacion->estadoOperacion(), $comprobante->estadoOperacion() Contracts\EstadoOperacion Recibido, Autorizado, Rechazado, RechazoConfiguracion, Error, Cancelado, Desconocido
$operacion->tipoComprobante(), $comprobante->tipoComprobante() ?Contracts\TipoComprobante Factura (01), LiquidacionCompra (03), NotaCredito (04), NotaDebito (05), GuiaRemision (06), Retencion (07); null si el código no se conoce
$operacion->esFinal() bool true si estado es cualquier valor distinto de recibido.
$operacion->esAutorizado() bool true si estado es autorizado.
$evento->eventType Contracts\TipoEventoWebhook DocumentoAutorizado, DocumentoRechazado, DocumentoFallido, OperacionRequiereAtencion, Desconocido

Los valores de codEstado están como constantes int en 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.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\CodEstado;
use Ecuafact\Sdk\Contracts\EstadoOperacion;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$operacion = $client->getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
echo match (true) {
    $operacion->estadoOperacion() === EstadoOperacion::Autorizado => 'Descarga el RIDE',
    $operacion->estadoOperacion() === EstadoOperacion::Recibido => 'Consulta mas tarde',
    $operacion->codEstado === CodEstado::RECHAZO_SRI => 'Corrige y emite un comprobante nuevo: ' . implode(' | ', $operacion->errores ?? []),
    $operacion->estadoOperacion() === EstadoOperacion::Rechazado => "Corrige segun codEstado {$operacion->codEstado}: {$operacion->msgError}",
    $operacion->estadoOperacion() === EstadoOperacion::Cancelado => 'Emite de nuevo con nueva Idempotency-Key',
    default => 'Consulta mas tarde',
} . PHP_EOL;

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_SECONDS) o el cuerpo no es un objeto JSON, lanza EcuafactWebhookException.

Método Devuelve Lanza
WebhookEvent::construir($secretos, $cabecera, $cuerpo, $toleranceSeconds = 300, $now = null) WebhookEvent EcuafactWebhookException
WebhookSignature::construirEvento(...) Lo mismo que construir, con los mismos argumentos. EcuafactWebhookException
WebhookSignature::verify($secretos, $cabecera, $cuerpo, $now = null, $toleranceSeconds = 300) bool Nunca.
WebhookSignature::sign($secreto, $unixSeconds, $cuerpo) La cabecera t=...,v1=... Nunca. Útil para probar tu endpoint en local.

$secretos acepta un secreto (string) o un arreglo de secretos, y la entrega es válida si coincide con cualquiera; así 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. Pasa siempre un string o un arreglo, porque getenv() devuelve false si la variable no existe y false no es un argumento válido.

El ejemplo siguiente usa PHP sin framework. Guarda tu secreto en ECUAFACT_WEBHOOK_SECRET y, durante una rotación, el anterior en ECUAFACT_WEBHOOK_SECRET_ANTERIOR.

<?php
// Guarda como webhook.php y ejecuta: php -S localhost:3000 webhook.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\TipoEventoWebhook;
use Ecuafact\Sdk\EcuafactWebhookException;
use Ecuafact\Sdk\WebhookEvent;

$secretos = array_values(array_filter([
    getenv('ECUAFACT_WEBHOOK_SECRET') ?: null,
    getenv('ECUAFACT_WEBHOOK_SECRET_ANTERIOR') ?: null,
]));
$cuerpoCrudo = file_get_contents('php://input'); // Cuerpo crudo, sin parsear.
$cabecera = $_SERVER['HTTP_ECUAFACT_SIGNATURE'] ?? '';

try {
    $evento = WebhookEvent::construir($secretos, $cabecera, $cuerpoCrudo);
} catch (EcuafactWebhookException) {
    http_response_code(401);
    exit;
}

// Deduplica por eventTypeRaw + resourceId. Solo para el ejemplo: marca en disco;
// en produccion usa una tabla con clave unica.
$marca = sys_get_temp_dir() . '/ecuafact-' . hash('sha256', $evento->eventTypeRaw . '|' . $evento->resourceId);
if (file_exists($marca)) {
    http_response_code(200); // Duplicado: ya procesado.
    exit;
}
touch($marca);

match ($evento->eventType) {
    TipoEventoWebhook::DocumentoAutorizado => error_log("Autorizado {$evento->idOperacion} {$evento->claveAcceso}"),
    TipoEventoWebhook::DocumentoRechazado => error_log("Rechazo fiscal {$evento->idOperacion}: codEstado {$evento->codEstado} " . implode(' | ', $evento->errores)),
    TipoEventoWebhook::DocumentoFallido => error_log("No emitido {$evento->idOperacion}: estado {$evento->estado}, codEstado {$evento->codEstado}"),
    default => error_log("Evento {$evento->eventTypeRaw} prueba=" . var_export($evento->probe, true)),
};
http_response_code(200);

Para probarlo en local, firma un cuerpo con WebhookSignature::sign y envíalo con cURL.

<?php
// Guarda como firmar.php y ejecuta: php firmar.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\WebhookSignature;

$cuerpo = '{"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';
file_put_contents('evento.json', $cuerpo);
echo WebhookSignature::sign(getenv('ECUAFACT_WEBHOOK_SECRET'), time(), $cuerpo) . PHP_EOL;
FIRMA=$(php firmar.php)
curl -s -i -X POST "http://localhost:3000/" \
  -H "Ecuafact-Signature: $FIRMA" \
  -H "Content-Type: application/json" \
  --data-binary @evento.json
# HTTP/1.1 200 OK (con un secreto distinto responde 401)

WebhookEvent tiene estas propiedades:

Propiedad Tipo Descripción
eventType TipoEventoWebhook Tipo tipado; Desconocido si el SDK no conoce el valor.
eventTypeRaw string Valor original de eventType (por ejemplo document.authorized).
resourceId ?string En los eventos document.*, el idOperacion; en el evento de prueba, el identificador del destino.
occurredAtUtc ?\DateTimeImmutable Momento del evento, en UTC.
idOperacion, claveAcceso, tipoDocumento ?string Datos de la operación; tipoDocumento viene cuando el evento lo trae.
estado ?string El mismo estado del seguimiento: autorizado, rechazado, rechazo_configuracion o error.
codEstado ?int Código numérico del resultado, por ejemplo 2001 en document.authorized, 3001 (rechazo_sri) en document.rejected o 4002 (firma_no_valida) en document.failed. 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 string[] Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacío 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 bool true en el evento de prueba del portal.
cuerpo array El cuerpo completo decodificado.

Atención

Verifica la firma sobre el cuerpo crudo (php://input). En Laravel usa $request->getContent(); no uses $request->all() ni vuelvas a codificar el JSON.

Standard Webhooks#

Cada entrega trae además las cabeceras del estándar Standard Webhooks (webhook-id, webhook-timestamp y webhook-signature), firmadas con el mismo secreto. Con el SDK puedes verificar cualquiera de las dos firmas, sin decidir cuál llegó.

Método Qué hace
WebhookEvent::construirDesdeCabeceras($secretos, $cabeceras, $cuerpo, $toleranceSeconds = 300, $now = null) Devuelve el WebhookEvent si Ecuafact-Signature o Standard Webhooks es válida; si no, lanza EcuafactWebhookException.
WebhookSignature::construirEventoDesdeCabeceras(...) Lo mismo que el anterior, con los mismos argumentos.
WebhookSignature::verificarCabeceras($secretos, $cabeceras, $cuerpo, $now = null, $toleranceSeconds = 300) Devuelve bool con la misma regla y nunca lanza una excepción.
WebhookSignature::verificarStandardWebhooks($secretos, $webhookId, $webhookTimestamp, $webhookSignature, $cuerpo, $now = null, $toleranceSeconds = 300) Devuelve bool. Verifica solo la firma de Standard Webhooks.
WebhookSignature::firmarStandardWebhooks($secreto, $webhookId, $unixSeconds, $cuerpo) Devuelve el valor de webhook-signature (v1,<base64>). Sirve para pruebas automatizadas.

$cabeceras es un arreglo asociativo cuyos nombres no distinguen mayúsculas, así que sirven getallheaders(), las cabeceras de una petición PSR-7 o $_SERVER. El secreto puede llevar o no el prefijo whsec_, y también aceptas un arreglo de secretos para la rotación. Con construirDesdeCabeceras verificas Ecuafact-Signature si viene y, si no viene o no es válida, Standard Webhooks.

try {
    $evento = WebhookEvent::construirDesdeCabeceras($secretos, getallheaders(), $cuerpoCrudo);
} catch (EcuafactWebhookException) {
    http_response_code(401);
    exit;
}

Los eventos y su contenido están en Webhooks, y el algoritmo de la firma, en Verificación de firma.

Errores#

Todas las excepciones del SDK heredan de EcuafactSdkException, que extiende \RuntimeException, y las que vienen de una respuesta de la API heredan además de EcuafactApiException. Captura primero las específicas y al final las generales. Todas están en el espacio de nombres Ecuafact\Sdk.

Excepción Hereda de Cuándo ocurre Qué hacer
EcuafactConfigurationException EcuafactSdkException Falta la API Key o la URL, la URL no es válida o termina en /v1, la API Key tiene espacios o caracteres de control, o una opción del cliente o de RequestOptions es inválida. Corrige la configuración. No llama a la API.
EcuafactConnectionException EcuafactSdkException Sin conexión con la API tras agotar los intentos. Trae curlErrno cuando el error viene de cURL, idempotencyKey y correlationId. Reintenta más tarde con la misma idempotencyKey.
EcuafactTimeoutException EcuafactSdkException Se agotó timeout en el último intento o el tope total de la llamada. Trae idempotencyKey y correlationId. Si emitías, consulta antes el seguimiento o reintenta con la misma idempotencyKey.
EcuafactWebhookException EcuafactSdkException Firma de webhook inválida o vencida, o cuerpo 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, porque el comprobante no llegó a emitirse.
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, la claveAcceso o el ambiente (URL).
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 segundos y reintenta con la misma idempotencyKey. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste retryRateLimited.
EcuafactQuotaException EcuafactApiException HTTP 429 con el codEstado 4004 (cupo_agotado): 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.
EcuafactInvalidResponseException EcuafactSdkException La API respondió con un estado 2xx, pero el cuerpo está vacío o no es JSON válido. Trae status, idempotencyKey y correlationId. No se reintenta. Si emitías, repite la emisión con la misma idempotencyKey, como se explica en Idempotencia y reintentos, o consulta el resultado; no emitas de nuevo con otra clave. Si persiste, contacta a soporte con el correlationId.
EcuafactTipoComprobanteException EcuafactSdkException El filtro tipoDocumento de listarOperaciones no es un tipo válido. Usa el código (01, 03, 04, 05, 06, 07) o su nombre. 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, importe con formato inválido, falta el contribuyente por defecto, identificacion que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, . o .., argumento obligatorio vacío. Corrige la llamada.
Propiedad 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 trae cuerpo de error.
estado ?string estado de la respuesta de error, como rechazado, rechazo_configuracion o error.
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 string[] Detalle específico del error, como la ruta del campo que falla en un 3002. Vacío cuando no hay detalle.
correlationId ?string Cabecera X-Correlation-Id (la de la API o la que enviaste en RequestOptions). Inclúyelo al pedir soporte.
idempotencyKey ?string Clave usada en la emisión; reutilízala al reintentar. null en llamadas sin idempotencia.
retryAfter ?int Segundos indicados por la cabecera Retry-After; null si no llegó.
esReintentable bool true si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el codEstado 5005. El 429 con 4004 (cupo agotado) no es reintentable.
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\EcuafactApiException;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\EcuafactConnectionException;
use Ecuafact\Sdk\EcuafactQuotaException;
use Ecuafact\Sdk\EcuafactRateLimitException;
use Ecuafact\Sdk\EcuafactTimeoutException;
use Ecuafact\Sdk\EcuafactValidationException;
use Ecuafact\Sdk\Support\Hydrator;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));
$comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));

try {
    $r = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
    echo $r->admission->estado . ' ' . $r->admission->idOperacion . PHP_EOL;
} catch (EcuafactValidationException $error) {
    // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual.
    foreach ($error->errores as $detalle) {
        echo $detalle . PHP_EOL;
    }
} catch (EcuafactQuotaException $error) {
    echo 'Cupo agotado: compra un paquete. No reintentes.' . PHP_EOL;
} catch (EcuafactRateLimitException $error) {
    echo 'Limite de solicitudes: espera ' . ($error->retryAfter ?? 1) . " s y reintenta con {$error->idempotencyKey}" . PHP_EOL;
} catch (EcuafactApiException $error) {
    echo "{$error->estadoHttp} codEstado {$error->codEstado} {$error->msgError} reintentable=" . var_export($error->esReintentable, true)
        . " correlation={$error->correlationId}" . PHP_EOL;
} catch (EcuafactConnectionException | EcuafactTimeoutException $error) {
    // Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key.
    echo $error->getMessage() . " clave={$error->idempotencyKey}" . PHP_EOL;
}

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 ruc distinto del 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 JSON mal formado, cabecera inválida o parámetro de ruta con tipo inválido. Corrige según errores.
3002 comprobante_invalido 422 Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). Corrige según errores; consume 1 documento como intento.
3012 filtros_invalidos 400 Un filtro de una consulta está fuera de rango. Ajusta los filtros a los límites.
3006 cuerpo_excedido 413 Cuerpo mayor a 2 MiB en la emisión o 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, omite secuencial 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, la clave y el ambiente; 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 '', el SDK genera una de 32 caracteres hexadecimales, la 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 (EcuafactInvalidResponseException) conserva la Idempotency-Key en idempotencyKey y el X-Correlation-Id en correlationId; 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.
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 Sí Se reintenta 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.

Entre intentos, el SDK espera según estas reglas, donde n es el número del intento que falló:

  • Linear: retryBaseDelaySeconds x n, más un margen aleatorio de hasta retryJitterSeconds x n. Con los valores por defecto, espera 0.2 s y 0.4 s, más hasta 0.05 s y 0.1 s.
  • Exponential: retryBaseDelaySeconds x 2^(n-1), más un margen aleatorio de hasta retryJitterSeconds.

Si la respuesta trae un Retry-After mayor y respectRetryAfter es true, espera ese tiempo. Si maxRetryDelaySeconds es mayor que 0, la espera nunca lo supera. Si la siguiente espera no cabe en el tope total de la llamada, el SDK no reintenta y lanza el último error.

Opciones por llamada#

Puedes cambiar el tiempo máximo, el tope total, la correlación, la cabecera X-Additional-Info o los reintentos de una sola llamada sin tocar la configuración del cliente.

Todos los métodos del cliente y de la vista EcuafactContribuyente que llaman a la API aceptan como último argumento ?RequestOptions $opciones, incluido esperarResultado. Lo que no indiques usa la configuración del cliente.

Argumento de RequestOptions Valor por defecto Qué hace
timeout null (usa el del cliente) Tiempo máximo de cada intento, en segundos. Mayor que 0. Se aplica con el transporte cURL o con uno que implemente TimeoutOverrideTransportInterface; con un transporte PSR-18 se ignora y lo controla tu cliente HTTP.
totalTimeout null (usa totalTimeoutSeconds) Tope de la llamada, incluidos reintentos y esperas, en segundos. Al superarlo lanza EcuafactTimeoutException. Mayor que 0.
correlationId null Se envía en la cabecera X-Correlation-Id. De 1 a 64 caracteres A-Z a-z 0-9 . _ -.
reintentos true false desactiva los reintentos solo en esta llamada.
validarAntes null (usa el del cliente) Solo en emitir y emitirEn: true llama a /validar antes de emitir y false no lo llama, sea cual sea validarAntesDeEmitir.
additionalInfo null (usa el del cliente) Valor de la cabecera X-Additional-Info en esta llamada; reemplaza al additionalInfo del cliente. Sigue la misma validación que en el cliente, descrita en Información adicional. Con null usa el del cliente, y con '' no envía la cabecera en esta llamada.

PHP no tiene cancelación cooperativa, así que acota la llamada con timeout o totalTimeout.

La API devuelve la correlación que enviaste. La encuentras en EmisionResultado::$correlationId, en EcuafactApiException::$correlationId y en $correlationId de EcuafactConnectionException y EcuafactTimeoutException.

<?php
// Guarda como opciones.php y ejecuta: php opciones.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RequestOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    additionalInfo: 'erp=MiERP/4.2; sucursal=quito', // X-Additional-Info en todas las solicitudes
));

// Un solo intento, correlacion propia y X-Additional-Info distinta para esta consulta.
$contexto = $client->getContexto(new RequestOptions(
    reintentos: false,
    correlationId: 'pedido-2026-0457',
    additionalInfo: 'erp=MiERP/4.2; sucursal=quito; caja=3',
));
echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL;

// Mas tiempo para una descarga grande, con tope total de 2 minutos.
$ride = $client->descargarRide(
    '0123456789001',
    '0710202601012345678900110010010000001231234567811',
    new RequestOptions(timeout: 60.0, totalTimeout: 120.0),
);
file_put_contents('ride.pdf', $ride->contenido);

Reemplaza la claveAcceso del ejemplo por la de un comprobante autorizado de tu emisor. Un correlationId con espacios o de más de 64 caracteres, un additionalInfo inválido o un tiempo menor o igual a 0 lanzan EcuafactConfigurationException al crear RequestOptions, sin llamar a la API.

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 argumento additionalInfo Se envía en todas las solicitudes del cliente, incluidas las de esperarResultado y la vista EcuafactContribuyente ($client->para(...)). Con null o '' no se envía.
RequestOptions argumento additionalInfo Reemplaza el valor del cliente solo en esa llamada. Con null usa el del cliente, y con '' no envía la cabecera en esa llamada.

El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas:

  • Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, ñ ni saltos de línea.
  • Sin espacios al inicio ni al final.
  • Máximo 256 caracteres (EcuafactClientOptions::ADDITIONAL_INFO_MAX).

Si no cumple, el constructor lanza EcuafactConfigurationException sin llamar a la API. El valor aparece como *** en var_dump y no se incluye en las excepciones. No pongas en él la API Key ni datos personales.

<?php
// Guarda como info_adicional.php y ejecuta: php info_adicional.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RequestOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: 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 = $client->getContexto();

// Solo esta llamada lleva otro valor.
$consumo = $client->getConsumo(new RequestOptions(
    additionalInfo: 'erp=MiERP/4.2; sucursal=002; lote=2026-10-08',
));
echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL;
Error Por qué pasa Qué hacer
EcuafactConfigurationException al crear EcuafactClientOptions 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 crear RequestOptions El mismo problema en additionalInfo de la llamada. No se llamó a la API. Corrige el valor de esa llamada.

Conexión: proxy, TLS y PSR-18#

Si necesitas salir por un proxy, confiar en una CA propia o ajustar el tiempo de conexión, puedes configurarlo con las opciones del cliente. Por defecto el SDK usa cURL.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RetryBackoff;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    retryRateLimited: true,
    retryBaseDelaySeconds: 0.5,
    retryBackoff: RetryBackoff::Exponential,
    totalTimeoutSeconds: 60.0,
    connectTimeout: 5.0,
    proxy: 'http://proxy.miempresa.local:8080',
    caInfo: '/etc/ssl/certs/ca-miempresa.pem',
));
echo count($client->getContexto()->contribuyentes ?? []) . PHP_EOL;

Si tu aplicación ya usa un cliente PSR-18, como Guzzle o Symfony HttpClient, pásalo con Transport\Psr18Transport, que necesita el cliente y las fábricas PSR-17 de peticiones y de flujos. Con este transporte no se aplican timeout, connectTimeout, proxy, caInfo, verifyPeer ni curlOptions, así que configúralos en tu cliente. Los reintentos, totalTimeoutSeconds (que se comprueba antes de cada intento), la idempotencia, additionalInfo y las excepciones funcionan igual.

Cuando tu cliente PSR-18 falla, el SDK decide entre EcuafactTimeoutException y EcuafactConnectionException por el tipo de la excepción. Con Guzzle mira el errno de cURL que trae getHandlerContext(), donde 28 es un timeout y cualquier otro valor es un error de conexión; con Symfony HttpClient busca una TimeoutExceptionInterface en la cadena de excepciones. Solo si la excepción no trae esa información, el SDK revisa si el mensaje dice timeout o timed out. Una RequestExceptionInterface, que indica que la petición no se pudo armar, sin esa información es siempre EcuafactConnectionException. La excepción original queda en getPrevious().

El ejemplo siguiente usa Guzzle, que instalas con composer require guzzlehttp/guzzle.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\Transport\Psr18Transport;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$guzzle = new Client([
    'timeout' => 30,
    'connect_timeout' => 5,
    'proxy' => 'http://proxy.miempresa.local:8080',
]);
$fabrica = new HttpFactory(); // Fabrica PSR-17 de peticiones y de flujos.

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    transport: new Psr18Transport($guzzle, $fabrica, $fabrica),
));
echo count($client->getContexto()->contribuyentes ?? []) . PHP_EOL;

Constructores de comprobantes#

Puedes armar la Estructura del comprobante con métodos en lugar de escribir el JSON.

Los constructores son opcionales y están en Ecuafact\Sdk\Builders. Solo ensamblan la solicitud de su tipo (FacturaRequest, NotaCreditoRequest...) con los valores que les das: no calculan totales, impuestos ni redondeos, y no completan valores por defecto. Tú calculas los importes y la API los calcula y valida igual que si armaras el JSON a mano.

<?php
// Guarda como constructor.php y ejecuta: php constructor.php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Builders\ComprobanteBuilder;
use Ecuafact\Sdk\Builders\Tarifa;
use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\Contracts\Impuesto;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RequestOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

// Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor.
$factura = ComprobanteBuilder::factura('0123456789001', '001', '001')
    ->referencias('MiERP', 'FACTURA-2026-0002')
    ->fechaEmision(new DateTimeImmutable('now', new DateTimeZone('America/Guayaquil')))
    ->comprador('07', '9999999999999', 'CONSUMIDOR FINAL')
    ->moneda('DOLAR')
    ->linea('SERV-001', 'Servicio de prueba', 1, '10.00', 0, Tarifa::iva('4', 15))
    ->totalSinImpuestos('10.00')
    ->totalDescuento('0.00')
    ->propina('0.00')
    ->importeTotal('11.50')
    ->pago('01', '11.50')
    // Los importes de la linea y de totalConImpuestos los das tu: el SDK no los calcula.
    ->configurar(function (FacturaRequest $c): void {
        $c->detalles[0]->precioTotalSinImpuesto = '10.00';
        $c->detalles[0]->impuestos[0]->baseImponible = '10.00';
        $c->detalles[0]->impuestos[0]->valor = '1.50';
        $fila = new Impuesto();
        $fila->codigo = '2';
        $fila->codigoPorcentaje = '4';
        $fila->tarifa = '15';
        $fila->baseImponible = '10.00';
        $fila->valor = '1.50';
        $c->info->totalConImpuestos = [$fila];
    });

$comprobante = $factura->construir();
echo 'importeTotal ' . $comprobante->info->importeTotal . PHP_EOL; // 11.50

$r = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0002',
    new RequestOptions(correlationId: 'pedido-2026-0458'));
echo $r->admission->estado . ' ' . $r->admission->idOperacion . ' ' . $r->correlationId . PHP_EOL;

Deberías ver importeTotal 11.50 y luego recibido <idOperacion> pedido-2026-0458. Si ejecutas el script 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.

Las seis fábricas reciben ($ruc, $estab, $ptoEmi).

Tipo Fábrica Métodos propios
Factura (01) ComprobanteBuilder::factura(...) fechaEmision, comprador, linea, detalle, totalSinImpuestos, totalDescuento, propina, moneda, pago, importeTotal, guiaRemision
Liquidación de compra (03) ComprobanteBuilder::liquidacionCompra(...) fechaEmision, proveedor, linea, detalle, totalSinImpuestos, totalDescuento, moneda, pago, importeTotal
Nota de crédito (04) ComprobanteBuilder::notaCredito(...) fechaEmision, comprador, documentoModificado, motivo, linea, detalle, totalSinImpuestos, moneda, totalDocumentoSustento, valorModificacion
Nota de débito (05) ComprobanteBuilder::notaDebito(...) fechaEmision, comprador, documentoModificado, motivo($razon, $valor), iva, totalSinImpuestos, moneda, pago, valorTotal
Guía de remisión (06) ComprobanteBuilder::guiaRemision(...) transportista, traslado, destinatario, linea
Retención (07) ComprobanteBuilder::retencion(...) fechaEmision, sujetoRetenido, periodo, docSustento, impuestoSustento, lineaRetencion, pago

Estas son las firmas de los métodos más usados:

Método Firma
linea (01, 03, 04) linea($codigo, $descripcion, $cantidad, $precioUnitario, $descuento, Tarifa $iva, ?Tarifa $ice = null, ?string $codigoAuxiliar = null, ?array $detallesAdicionales = null). $descuento es un importe en dólares, no un porcentaje, y $detallesAdicionales admite hasta 3 pares nombre => valor.
comprador comprador($tipoIdentificacion, $identificacion, $razonSocial, ?string $direccion = null). proveedor (03) tiene la misma firma.
pago pago($formaPago, $total = null, ?int $plazo = null, ?string $unidadTiempo = null)
documentoModificado (04, 05) documentoModificado($codDocModificado, $numDocModificado, $fechaEmisionDocSustento). El número tiene la forma ddd-ddd-ddddddddd.
linea (06) linea($codigoInterno, $descripcion, $cantidad, ?string $codigoAdicional = null); agrega el producto al destinatario de la guía.
destinatario (06) destinatario($identificacion, $razonSocial, $direccion, $motivoTraslado, ?string $codEstabDestino = null, ?string $ruta = null, ?string $docAduaneroUnico = null). El constructor arma un solo destinatario, así que llamarlo otra vez reemplaza sus datos y conserva las líneas. Para varios destinatarios, usa configurar.
docSustento (07) docSustento($codSustento, $codDocSustento, $numDocSustento, $fechaEmisionDocSustento, $fechaRegistroContable, $totalSinImpuestos = null, $importeTotal = null, ?string $numAutDocSustento = null, ?string $pagoLocExt = null). $pagoLocExt no tiene valor por defecto: se envía solo si lo indicas.
impuestoSustento (07) impuestoSustento($codImpuesto, $codigoPorcentaje, $baseImponible, $tarifa, $valorImpuesto = null); $valorImpuesto se envía solo si lo indicas.
lineaRetencion (07) lineaRetencion($codigo, $codigoRetencion, $baseImponible, $porcentajeRetener, $valorRetenido = null); $valorRetenido se envía solo si lo indicas.

Todos los constructores tienen además referencias($origen, $externa), secuencial, dirEstablecimiento, correo, telefono, infoAdicional($nombre, $valor), configurar(fn (FacturaRequest $c) => ...) (con la clase de su tipo; asigna cualquier campo del contrato) y construir(). fechaEmision acepta un texto dd/MM/yyyy o un DateTimeInterface; la guía de remisión no lo tiene y usa traslado($dirPartida, $fechaInicio, $fechaFin). El ICE de una línea va en el séptimo argumento: linea(..., Tarifa::iva('4', 15), Tarifa::ice('3011', 10)). Los importes aceptan int, float o texto decimal como '10.00', que es la forma exacta.

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 importes que das como texto decimal ('10.00') conservan su precisión sin pérdida. Como construir() devuelve una copia, puedes seguir usando el constructor.

Elemento Detalle
Tarifa de una línea Tarifa::iva($codigoPorcentaje, $tarifa) o Tarifa::ice($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.
Importes int, float o texto decimal. Un texto como '10,50' lanza EcuafactSdkException porque no se puede enviar sin perder precisión.
Validación Los constructores no validan reglas de negocio ni calculan: solo ayudan 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 todos los métodos del cliente. Todos son síncronos y aceptan como último argumento ?RequestOptions $opciones, que se explica en Opciones por llamada. La identificación que reciben es siempre el valor identificacion del contexto, y las clases de datos están en Ecuafact\Sdk\Contracts.

Método Endpoint Devuelve
getContexto() GET /v1/contexto Contexto (ver Contexto y consumo)
emitir($comprobante, $idempotencyKey = null) POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo} EmisionResultado
emitirEn($identificacion, $comprobante, $idempotencyKey = null) POST /v1/contribuyentes/{identificacion}/{ruta del tipo} EmisionResultado
validar($comprobante) POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar ValidacionResultado (revisa valido)
validarEn($identificacion, $comprobante) POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar ValidacionResultado (ver Validar sin emitir)
getOperacion($idOperacion) GET /v1/operaciones/{idOperacion} Operation. $idOperacion debe ser un UUID.
consultarOperacion($idOperacion) GET /v1/operaciones/{idOperacion} Operation (alias)
esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0) GET /v1/operaciones/{idOperacion} en bucle Operation: la última leída. Opcional; tiempos en segundos.
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 bool: 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, PerfilEmisorUpdate $cambios) PUT /v1/contribuyentes/{identificacion}/perfil PerfilEmisor
actualizarLogo($identificacion, $contenido, $contentType, $nombreArchivo = 'logo') POST /v1/contribuyentes/{identificacion}/perfil/logo PerfilEmisor (ver Logo del perfil)
consultarContribuyente($identificacion, $fusionar = true, $fuente = null) GET /v1/consultas/contribuyentes/{identificacion} ContribuyenteConsulta
buscarContribuyentes($apellidos, $nombres = null, $clase = null, $max = null) GET /v1/consultas/contribuyentes BusquedaContribuyente[]
listarEstablecimientos($ruc, $filtro = null) 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; no recibe RequestOptions) EcuafactContribuyente
options() - (no llama a la API) EcuafactClientOptions

En emitir, emitirEn, validar y validarEn, {ruta del tipo} es la ruta de la tabla de Tipo de comprobante y ruta. El cuerpo de esas cuatro llamadas es el de la clase del comprobante, sin ningún campo de tipo.

Ten en cuenta además estos detalles de los métodos y de sus tipos:

  • EmisionResultado trae admission, idempotencyKey y correlationId (cabecera X-Correlation-Id). admission tiene los mismos campos que Operation, que se describen en Seguimiento del resultado. En una emisión aceptada, estado es recibido y codEstado es 1001 o 1002: con 1001, claveAcceso todavía es null, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores. urlEstado es la URL completa del seguimiento.
  • Si no configuras identificacion en las opciones, emitir y validar lanzan EcuafactSdkException. En ese caso usa los métodos ...En o para().
  • ArchivoComprobante tiene contenido (string binario) y contentType. Las descargas solo existen con el comprobante autorizado; ver Descargar XML.
  • PerfilEmisorUpdate tiene nombreComercial, direccionMatriz, correo, telefono, ciudad y provincia, y las propiedades en null no se envían. El detalle está en Perfil del emisor.

Importes exactos#

En PHP un float es binario, y por eso 0.1 + 0.2 da 0.30000000000000004. Los campos de importe, cantidad, precio y tarifa de la solicitud son float|string|null, y cada tipo se envía de una forma distinta.

  • Un texto decimal con punto, como '11.50', se envía como número JSON literal (11.50), sin pasar por float. Es la forma exacta.
  • Un float se envía con 15 dígitos significativos, así que 0.1 + 0.2 viaja como 0.3.
  • Un texto con otro formato, como '10,50' o '1e3', se rechaza con EcuafactSdkException antes de llamar a la API.
  • Las propiedades en null no se envían.

Pago::$plazo también acepta float|string. Calcula con bcmath, si la tienes, o en centavos enteros, y asigna el resultado como texto.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\Support\Hydrator;

/** @var FacturaRequest $comprobante */
$comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));

// Calcula en centavos enteros y asigna el resultado como texto con 2 decimales.
$baseCentavos = 1000;                                     // 10.00
$ivaCentavos = intdiv($baseCentavos * 15 + 50, 100);      // 150 = 1.50
$comprobante->info->totalSinImpuestos = number_format($baseCentavos / 100, 2, '.', '');               // '10.00'
$comprobante->info->importeTotal = number_format(($baseCentavos + $ivaCentavos) / 100, 2, '.', '');   // '11.50'

echo $comprobante->info->importeTotal . PHP_EOL; // 11.50

Si tu código lee esas propiedades con un tipo float estricto, conviértelas con (float). En las respuestas, Comprobante::$total se lee como float. Las reglas de cálculo de cada comprobante están en Factura.

Varios contribuyentes#

Si no configuras identificacion en las opciones, usa los métodos ...En o una vista por contribuyente. La vista repite la identificación por ti en cada método.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$matriz = $client->para('0123456789001');

$perfil = $matriz->getPerfil();
echo "{$perfil->razonSocial} ({$perfil->identificacion})" . PHP_EOL;

La vista EcuafactContribuyente tiene estos métodos, y todos aceptan RequestOptions al final. Además, identificacion() devuelve la identificación fija de la vista.

Método Equivale a
emitir($comprobante, $idempotencyKey = null) $client->emitirEn($identificacion, $comprobante, $idempotencyKey)
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 = 'logo') $client->actualizarLogo($identificacion, ...)
esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0) $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. La API acepta PNG o JPEG de hasta 512 KB; $contenido son los bytes del archivo y $contentType es image/png o image/jpeg. Un contenido vacío o un contentType con caracteres inválidos lanza EcuafactSdkException sin llamar a la API. La subida no se reintenta automáticamente.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$perfil = $client->actualizarLogo('0123456789001', file_get_contents('logo.png'), 'image/png', 'logo.png');
echo "Logo actualizado para {$perfil->razonSocial}: {$perfil->logo}" . PHP_EOL;

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.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$contexto = $client->getContexto();
foreach ($contexto->contribuyentes ?? [] as $c) {
    echo $c->identificacion . ' ' . var_export($c->puedeEmitir, true) . ' ' . implode(',', $c->tiposComprobante ?? []) . PHP_EOL;
}

$cupo = $client->getConsumo();
echo "Disponibles {$cupo->disponibles} de {$cupo->limiteDocumentos}; vigente hasta {$cupo->vigenteHasta}" . PHP_EOL;

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. Todas las propiedades pueden ser null.

Propiedad Tipo Descripción
idCliente ?string Identificador de tu integración.
nombre ?string Nombre de tu integración.
contribuyentes ?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 ?bool true si tu API Key puede emitir para este contribuyente.
Contribuyente::$puedeRecibir ?bool true si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión.
Contribuyente::$tiposComprobante ?string[] Códigos de los tipos de comprobante habilitados (01, 03, 04, 05, 06, 07).
Contribuyente::$marcaBlanca ?bool 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.

Propiedad 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 las cuatro propiedades 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 son opcionales: 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.

$pagina = 1;
do {
    $resultado = $client->listarOperaciones(
        identificacion: '0123456789001',
        desde: '2026-11-01',
        hasta: '2026-11-30',
        pagina: $pagina,
        tamanoPagina: 50,
    );
    foreach ($resultado->comprobantes as $fila) {
        echo $fila->numeroDocumento . ' ' . $fila->estado . ' ' . $fila->codEstado . ' ' . $fila->total . PHP_EOL;
    }
    $pagina++;
} while ($resultado->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 el mismo método con la identificación fija.

Consultas SRI#

Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$validacion = $client->validarIdentificacion('0123456789001');
$contribuyente = $client->consultarContribuyente('0123456789001');
$encontrados = $client->buscarContribuyentes('PEREZ LOPEZ', 'JUAN', 'PersonaNatural', 10);
$establecimientos = $client->listarEstablecimientos('0123456789001', 'SoloActivos');
$clave = $client->decodificarClaveAcceso('0710202601012345678900110010010000001231234567811');
echo var_export($validacion->valido, true) . ' ' . count($encontrados) . ' ' . $clave->rucEmisor . PHP_EOL;

Si un argumento obligatorio, como la identificación, los apellidos, el RUC, el número o la clave de acceso, llega vacío, el SDK lanza EcuafactSdkException sin llamar a la API. Los parámetros y las respuestas de cada consulta están en Contribuyente por identificación, Contribuyentes por nombre, Establecimientos de un RUC, Validar identificación y Decodificar clave de acceso.

Estado del servicio y catálogos#

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 ni consume cupo, 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.

<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\EcuafactNotFoundException;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

$estado = $client->obtenerEstadoServicio();
echo $estado->estado . ' ' . ($estado->disponibilidad90Dias ?? 'sin datos') . PHP_EOL;
foreach ($estado->componentes ?? [] as $componente) {
    echo $componente->nombre . ' ' . $componente->estado . PHP_EOL;
}
foreach ($estado->incidentes ?? [] as $incidente) {
    echo $incidente->inicio . ' ' . $incidente->impacto . ' ' . $incidente->titulo . ' ' . ($incidente->fin ?? 'abierto') . PHP_EOL;
}

foreach ($client->listarCatalogos()->catalogos ?? [] as $resumen) {
    echo $resumen->nombre . ': ' . $resumen->descripcion . PHP_EOL;
}

try {
    $tarifas = $client->obtenerCatalogo('tarifas-iva');
    foreach ($tarifas->items ?? [] as $fila) {
        echo $fila->codigo . ' ' . $fila->descripcion . ' ' . ($fila->valor ?? '') . PHP_EOL;
    }
} catch (EcuafactNotFoundException) {
    echo 'Ese catálogo no existe' . PHP_EOL;
}

Si el catálogo tarifas-iva existe, el script 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 con los mismos campos que la respuesta de la consulta. Todas las propiedades pueden ser null.

Propiedad 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 ?ComponenteEstado[] Componentes monitoreados.
disponibilidad90Dias float\|string\|null Porcentaje de minutos sin caída en los últimos 90 días. null si aún no hay muestras.
incidentes ?IncidentePublico[] Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo.
Propiedad de ComponenteEstado Tipo Descripción
nombre ?string Nombre del componente.
estado ?string operativo, degradado, caido o sin_datos.
Propiedad 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.

Propiedad de Catalogos Tipo Descripción
catalogos ?CatalogoResumen[] Catálogos disponibles, en el orden de la ficha técnica del SRI.
Propiedad de CatalogoResumen Tipo Descripción
nombre ?string Clave del catálogo; es el valor que recibe obtenerCatalogo.
descripcion ?string Descripción breve de lo que contiene.
Propiedad de CatalogoDetalle Tipo Descripción
nombre ?string Clave del catálogo.
descripcion ?string Descripción breve del catálogo.
fuente ?string Tabla o anexo de la ficha técnica del SRI de donde proviene.
items ?CatalogoItem[] Filas del catálogo.
Propiedad de CatalogoItem Tipo Descripción
codigo ?string Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga.
descripcion ?string Descripción del código.
valor float\|string\|null Valor numérico asociado, por ejemplo la tarifa en porcentaje. null si el catálogo no lo tiene.
vigenteDesde ?string Primer día de vigencia (yyyy-MM-dd). null si la fila no está acotada por el inicio.
vigenteHasta ?string Último día de vigencia (yyyy-MM-dd). null si sigue vigente.
atributos ?array Atributos propios del catálogo. null si no hay.

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.