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:
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óncurlhabilitada (aparece en la lista dephp -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
codEstado3010 (ip_no_autorizada). - Un contribuyente con
puedeEmitiren tu contexto. El sandbox crea uno con el establecimiento001y el punto de emisión001.
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.
timeoutno es mayor que 0, omaxAttemptses menor que 1.- Un tiempo es negativo.
maxResponseByteses negativo.retryBackoffno eslinearniexponential.additionalInfotiene 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
validoesfalseo hayerrores, lanzanEcuafactValidationException(HTTP 422,codEstado3002) con esoserrores, y la emisión no se envía. - Si es válido, envían la emisión y las
advertenciasquedan enEmisionResultado::$advertencias. Una advertencia no bloquea.
Por defecto es false, porque duplica las peticiones: sin la opción, una emisión
hace 1 petición; con ella, 2.
$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->idempotencyKeyo, 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, lanzaEcuafactSdkExceptionsin llamar a la API.
Atención
Si reintentas una emisión desde tu aplicación, reutiliza la misma
Idempotency-Key. Una clave nueva para el mismo comprobante puede duplicar la
emisión.
Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción
(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:retryBaseDelaySecondsxn, más un margen aleatorio de hastaretryJitterSecondsxn. Con los valores por defecto, espera 0.2 s y 0.4 s, más hasta 0.05 s y 0.1 s.Exponential:retryBaseDelaySecondsx 2^(n-1), más un margen aleatorio de hastaretryJitterSeconds.
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:
EmisionResultadotraeadmission,idempotencyKeyycorrelationId(cabeceraX-Correlation-Id).admissiontiene los mismos campos queOperation, que se describen en Seguimiento del resultado. En una emisión aceptada,estadoesrecibidoycodEstadoes 1001 o 1002: con 1001,claveAccesotodavía esnull, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores.urlEstadoes la URL completa del seguimiento.- Si no configuras
identificacionen las opciones,emitiryvalidarlanzanEcuafactSdkException. En ese caso usa los métodos...Enopara(). ArchivoComprobantetienecontenido(stringbinario) ycontentType. Las descargas solo existen con el comprobante autorizado; ver Descargar XML.PerfilEmisorUpdatetienenombreComercial,direccionMatriz,correo,telefono,ciudadyprovincia, y las propiedades ennullno 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 porfloat. Es la forma exacta. - Un float se envía con 15 dígitos significativos, así que
0.1 + 0.2viaja como0.3. - Un texto con otro formato, como
'10,50'o'1e3', se rechaza conEcuafactSdkExceptionantes de llamar a la API. - Las propiedades en
nullno 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#
- Factura: revisa todos los campos y las reglas de cálculo para construir tus comprobantes.
- Seguimiento de una operación: consulta qué significa cada
estadoy cadacodEstado. - Webhooks: recibe el resultado del SRI sin consultar en bucle.
- Visión general de los SDK: compara los cinco SDK y decide entre SDK o HTTP directo.