ecuafact / sdk
Cliente oficial de Ecuafact para PHP: emite y consulta los seis comprobantes electronicos del SRI de Ecuador (factura, liquidacion de compra, notas de credito y debito, guia de remision y retencion). Incluye validacion previa, seguimiento hasta el estado final, descarga de RIDE y XML, reintentos seg
Requires (Dev)
- phpunit/phpunit: ^11.5
Suggests
- psr/http-client: Para usar Psr18Transport con tu cliente PSR-18 (Guzzle, Symfony HttpClient).
- psr/http-factory: Fabricas PSR-17 que necesita Psr18Transport.
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-14 03:40:10 UTC
README
Cliente oficial en PHP del API publico de facturacion electronica Ecuafact (contrato v1). Cubre autenticacion, idempotencia, reintentos configurables, espera del resultado, logo del perfil y verificacion de la firma de los webhooks que recibes. Compatible con PHP 8.2+.
Versión actual: v1.0.0.
Instalacion
composer require "ecuafact/sdk:^1.0"
Requisitos
- PHP 8.2+ con
ext-curlyext-json. - Una API Key de integracion.
- La URL base del despliegue (sandbox
https://staging-api.mynexusapi.com/).
Uso
La identificacion de cada ruta es el valor identificacion que devuelve GET /v1/contexto para tu
contribuyente (por ejemplo 0123456789).
<?php use Ecuafact\Sdk\Contracts\FacturaRequest; use Ecuafact\Sdk\Contracts\InfoTributaria; use Ecuafact\Sdk\EcuafactClient; use Ecuafact\Sdk\EcuafactClientOptions; // Sin argumentos, el SDK lee ECUAFACT_API_KEY y ECUAFACT_BASE_URL del entorno. $client = new EcuafactClient(new EcuafactClientOptions( identificacion: '0123456789001', // identificacion de GET /v1/contexto (RUC de 13 digitos); opcional )); $comprobante = new FacturaRequest(); $comprobante->origenReferencia = 'MiERP'; $comprobante->referenciaExterna = 'FACTURA-2026-0001'; $comprobante->infoTributaria = new InfoTributaria(); $comprobante->infoTributaria->ruc = '0123456789001'; // identificacion de GET /v1/contexto $comprobante->infoTributaria->estab = '002'; $comprobante->infoTributaria->ptoEmi = '001'; // $comprobante->info = new InfoFactura(); $comprobante->detalles = [new DetalleCompraVenta(), ...]; $resultado = $client->emitir($comprobante); // 202 con estado "recibido": aun no autorizado $operacion = $client->esperarResultado($resultado->admission->idOperacion); if ($operacion->esAutorizado()) { echo $operacion->claveAcceso . PHP_EOL; } elseif ($operacion->esFinal()) { // codEstado numerico (por ejemplo 3001), msgError general y errores con el detalle echo $operacion->estado . ' ' . $operacion->codEstado . ': ' . $operacion->msgError . PHP_EOL; print_r($operacion->errores); }
Cada tipo de comprobante tiene su propia clase de solicitud, igual que tiene su propio endpoint, y emitir,
emitirEn, validar y validarEn eligen la ruta por la clase que les pasas: FacturaRequest va a facturas,
LiquidacionCompraRequest a liquidaciones-compra, NotaCreditoRequest a notas-credito, NotaDebitoRequest a
notas-debito, GuiaRemisionRequest a guias-remision y RetencionRequest a retenciones. No hay campo de tipo
en el cuerpo ni opcion de tipo en la llamada. Cada clase tiene solo las propiedades de su esquema del contrato y
usa su Info* (InfoFactura, InfoLiquidacionCompra, InfoNotaCredito, InfoNotaDebito, InfoGuiaRemision,
InfoComprobanteRetencion) y sus lineas (DetalleCompraVenta para factura y liquidacion, DetalleNotaCredito,
Motivo, Destinatario con DetalleGuia, y DocsSustento con ImpuestoDocSustento y RetencionLinea), con los
modelos comunes InfoTributaria, Pago, Impuesto y CampoAdicional. En el docblock de cada propiedad,
Obligatorio. marca las que el contrato exige; el SDK no las valida, lo hace el API.
Multi-RUC
$ruc = $client->para('0123456789001'); $operacion = $ruc->esperarResultado($idOperacion); $ride = $ruc->descargarRide($claveAcceso); $perfil = $ruc->actualizarLogo(file_get_contents('logo.png'), 'image/png', 'logo.png');
La vista expone emitir, validar, descargarRide, descargarXml, getPerfil, actualizarPerfil,
actualizarLogo, esperarResultado, listarOperaciones y getConsumo.
Listado de comprobantes y salud
listarOperaciones (GET /v1/operaciones, sin consumir cupo) devuelve una PaginaComprobantes (comprobantes,
pagina, tamanoPagina, hayMas). Filtros: desde y hasta (yyyy-MM-dd), tipoDocumento (codigo o nombre),
buscar, pagina desde 1 y tamanoPagina de 1 a 100. obtenerSalud() llama a GET /salud (sin API Key) y devuelve
true; con una respuesta que no es 2xx lanza la excepcion que corresponde.
obtenerEstadoServicio() (GET /estado, sin API Key) devuelve un EstadoServicio con estado, medidoEn,
componentes, disponibilidad90Dias e incidentes. listarCatalogos() (GET /v1/catalogos) devuelve un Catalogos con
la clave y la descripcion de cada catalogo, y obtenerCatalogo('tarifas-iva') (GET /v1/catalogos/{nombre}) devuelve un
CatalogoDetalle con sus items (codigo, descripcion, valor, vigenteDesde, vigenteHasta, atributos); un
catalogo inexistente lanza EcuafactNotFoundException.
$pagina = 1; do { $resultado = $client->listarOperaciones('0123456789001', desde: '2026-11-01', pagina: $pagina); foreach ($resultado->comprobantes as $fila) { echo $fila->numeroDocumento . ' ' . $fila->estado . PHP_EOL; } $pagina++; } while ($resultado->hayMas);
Destinos de webhooks
El SDK te ayuda a recibir webhooks (verificar la firma y leer el evento; mas abajo, en la seccion Webhooks). Los destinos (crear, pausar, rotar el secreto, revisar entregas) los administras desde el portal, la CLI, el servidor MCP o la API REST.
Variables de entorno
| Variable | Se usa cuando | Ejemplo |
|---|---|---|
ECUAFACT_API_KEY |
No pasas apiKey (o pasas null/false) |
ek_live_... |
ECUAFACT_BASE_URL |
No pasas baseAddress (o pasas null/false) |
https://staging-api.mynexusapi.com/ |
El SDK no distingue ambientes: el ambiente lo define la URL. La URL debe ser absoluta y usar
https, sin usuario, consulta ni fragmento, y no debe terminar en /v1: el SDK agrega /v1 a
cada ruta. Una URL con http, una URL invalida o una
API Key con espacios al inicio o al final o con caracteres de control lanza
EcuafactConfigurationException.
Importes exactos
Importes, cantidades, precios y tarifas de la solicitud aceptan float o string decimal. El string
('11.50') viaja como numero JSON literal (11.50), sin pasar por float. Un float se envia con 15
digitos significativos: 0.1 + 0.2 viaja como 0.3. Un string que no sea decimal ('1e3') lanza
EcuafactSdkException antes de enviar.
Hydrator::hydrate() convierte cada valor al tipo declarado y, si no puede, lanza
EcuafactSdkException (nunca un TypeError).
Idempotencia
idempotencyKey es opcional: si no se envia, el SDK la genera, la reutiliza en los reintentos y la
devuelve en resultado->idempotencyKey (y en el error, como ->idempotencyKey). Formato: solo letras,
digitos y - _ . : /, maximo 128 caracteres; otra clave lanza EcuafactSdkException sin llamar al API.
Al reintentar, reutiliza la clave devuelta. La correlacion queda en resultado->correlationId
(o ->correlationId en el error).
getOperacion, consultarOperacion y esperarResultado exigen un idOperacion UUID.
Validar sin emitir
Las reglas de negocio de los comprobantes (campos requeridos, formatos, catalogos, topes, coherencia aritmetica) viven
solo en el API; el SDK no las revisa. validar siempre llama a /validar y emitir envia directo y lanza
EcuafactValidationException con el 422 del API.
validar($comprobante) y validarEn($identificacion, $comprobante) aplican las reglas de la emision sin
emitir, sin consumir cupo y sin Idempotency-Key. Usan la ruta del tipo y le agregan
/validar (por ejemplo .../notas-credito/validar), y envian el cuerpo del tipo tal cual. Devuelven
ValidacionResultado (valido, codEstado, msgError, errores, advertencias, correlationId). Con un
comprobante valido, codEstado y msgError son null y errores esta vacio; advertencias trae los avisos que el
API devuelve junto al resultado (por ejemplo, que ignora la firma de un XML que la trae) y no impide emitir.
$validacion = $client->validarEn('0123456789001', $comprobante); if (!$validacion->valido) { // 422 con codEstado 3002: no lanza print_r($validacion->errores); }
Cualquier otro error lanza la excepcion habitual (por ejemplo EcuafactAuthException con 403 y codEstado 3011).
Como no tiene efectos, se reintenta igual que un GET.
Validar antes de cada emision (opcional)
Con validarAntesDeEmitir: true en EcuafactClientOptions (o validarAntes: true en RequestOptions para una sola
llamada), emitir/emitirEn llaman primero a /validar. Si valido es false o hay errores, lanzan
EcuafactValidationException (422, codEstado 3002) sin enviar la emision; las advertencias no bloquean y quedan en
EmisionResultado::$advertencias. Por defecto es false para no duplicar peticiones: sin la opcion se hace 1
peticion por emision, con ella 2.
Reintentos
Se reintentan solo solicitudes idempotentes (GET, validar/validarEn, o POST/PUT con Idempotency-Key) ante errores de red
y los estados de retryableStatusCodes (408, 425, 500, 502, 503, 504).
429concodEstado5005 (limite_solicitudes): se reintenta por defecto, respetandoRetry-Aftercon el topemaxRetryDelaySeconds.retryRateLimited: falselo desactiva.429concodEstado4004 (cupo_agotado), con otro codigo o sin cuerpo: nunca se reintenta.
Opciones
| Opcion | Default | Descripcion |
|---|---|---|
baseAddress |
ECUAFACT_BASE_URL |
URL base del despliegue, sin /v1 |
apiKey |
ECUAFACT_API_KEY |
Credencial X-Api-Key; no se muestra en var_dump, print_r ni trazas |
identificacion |
null |
Contribuyente por defecto (opcional) |
timeout |
30.0 |
Tiempo maximo por intento, en segundos (admite fracciones) |
userAgent |
Ecuafact.Sdk/1.0 |
User-Agent |
retryTransientFailures |
true |
false desactiva todos los reintentos |
maxAttempts |
3 |
Intentos por solicitud (minimo 1) |
respectRetryAfter |
true |
Espera al menos lo que indica Retry-After |
maxRetryDelaySeconds |
60.0 |
Espera maxima entre reintentos (0 = sin tope) |
retryRateLimited |
true |
Reintenta el 429 con codEstado 5005; nunca el 4004 |
retryableStatusCodes |
[408, 425, 500, 502, 503, 504] |
Estados HTTP reintentables |
retryBaseDelaySeconds |
0.2 |
Espera base entre reintentos |
retryBackoff |
RetryBackoff::Linear |
Linear (base x intento) o Exponential (base x 2^(intento-1)); acepta 'linear'/'exponential' |
retryJitterSeconds |
0.05 |
Variacion aleatoria maxima (por intento en Linear) |
totalTimeoutSeconds |
null |
Tope de toda la llamada, incluidos reintentos (EcuafactTimeoutException) |
transport |
CurlTransport |
Transporte propio (TransportInterface) o Psr18Transport |
connectTimeout |
null |
Tiempo maximo de conexion, en segundos (solo cURL) |
proxy |
null |
URL del proxy (solo cURL) |
caInfo |
null |
Bundle de CA en PEM (solo cURL) |
verifyPeer |
true |
false desactiva la validacion TLS; solo pruebas locales (solo cURL) |
curlOptions |
[] |
Opciones CURLOPT_* extra (solo cURL) |
maxResponseBytes |
32 MiB (100 MiB en descargas) | Tope en bytes de la respuesta; null o 0 lo desactiva. Al superarlo lanza EcuafactResponseTooLargeException ($limite, $bytesLeidos) |
validarAntesDeEmitir |
false |
true llama a /validar antes de cada emision (2 peticiones); si no es valido lanza EcuafactValidationException sin emitir |
additionalInfo |
null |
Cabecera X-Additional-Info en todas las solicitudes: ASCII imprimible, sin espacios al inicio/fin, maximo 256; null/'' no la envia; no aparece en var_dump |
El transporte cURL reutiliza el mismo handle (keep-alive). Para usar Guzzle o Symfony HttpClient,
instala psr/http-client y psr/http-factory y pasa
transport: new Psr18Transport($cliente, $requestFactory, $streamFactory); el timeout, el proxy y TLS
los configura tu cliente. Psr18Transport distingue timeout de error de conexion por el tipo de
excepcion (errno 28 de cURL en getHandlerContext() de Guzzle, TimeoutExceptionInterface de
Symfony) y usa el texto del mensaje solo como respaldo.
Cada modelo de respuesta guarda en extra (array) los campos que el API devuelve y el modelo no
declara; extra no se envia al API.
Opciones por llamada
Todos los metodos que llaman al API (tambien para() y esperarResultado) aceptan
como ultimo argumento ?RequestOptions $opciones. Solo afectan a esa llamada.
use Ecuafact\Sdk\RequestOptions; $opciones = new RequestOptions( timeout: 20.0, // por intento; reemplaza al timeout del cliente totalTimeout: 45.0, // tope de la llamada, incluidos reintentos correlationId: 'PED-2026-0457', // cabecera X-Correlation-Id: 1-64 de A-Z a-z 0-9 . _ - reintentos: true, // false: sin reintentos en esta llamada additionalInfo: 'erp=MiERP/4.2; caja=3', // cabecera X-Additional-Info; reemplaza a la del cliente validarAntes: true, // solo emitir: llama a /validar antes; null usa validarAntesDeEmitir del cliente ); $resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001', $opciones); echo $resultado->correlationId; // la correlacion que devolvio el API
- Un
correlationIdinvalido, unadditionalInfoinvalido o un tiempo<= 0lanzaEcuafactConfigurationException. - La correlacion queda en
EmisionResultado::$correlationId, enEcuafactApiException::$correlationIdy enEcuafactConnectionException::$correlationId/EcuafactTimeoutException::$correlationId. timeoutpor llamada se aplica con el transporte cURL (o uno que implementeTimeoutOverrideTransportInterface); con un transporte PSR-18 lo controla tu cliente HTTP.- PHP no tiene cancelacion cooperativa: acota la llamada con
timeoutototalTimeout.
Constructores de comprobantes
Opcionales. Solo ensamblan la solicitud de su tipo (FacturaRequest, NotaCreditoRequest...) con los valores que les das (no calculan totales ni
impuestos, no redondean y no completan valores por defecto); puedes seguir armandolo a mano.
use Ecuafact\Sdk\Builders\ComprobanteBuilder; use Ecuafact\Sdk\Builders\Tarifa; $builder = ComprobanteBuilder::factura('0123456789001', '002', '001') ->referencias('MiERP', 'FACTURA-2026-0001') ->fechaEmision('07/10/2026') ->comprador('05', '0123456789', 'CONTRIBUYENTE DE PRUEBAS') ->moneda('DOLAR') ->linea('SERV-001', 'CONSULTORIA', 3, '12.50', '2.50', Tarifa::iva('4', 15)) ->totalSinImpuestos('35.00') // los importes los calculas tu ->importeTotal('40.25') ->pago('01', '40.25'); $resultado = $client->emitirEn('0123456789001', $builder->construir(), 'FACTURA-2026-0001');
- Tipos:
factura,liquidacionCompra,notaCredito,notaDebito,guiaRemision,retencion. - Lo que asignas se envia tal cual (
importeTotal(),detalle(DetalleCompraVenta),configurar(fn)...) y lo que no asignas no se envia: sin totales, impuestos,moneda,propina,pagoLocExtnitotalde pago por defecto. - Los importes (
int,floato texto decimal como'10.00') conservan su precision sin perdida. - Los constructores no calculan ni validan reglas de negocio: usa
validaro emite y lee el 422 del API, que es quien calcula y decide.
Estados tipados
La operacion y el webhook llevan estado con uno de estos valores
(EstadoOperacion):
| estado | Caso | Final |
|---|---|---|
recibido (Recibido) |
El comprobante paso las validaciones y se acepto; aun no hay resultado | No |
autorizado (Autorizado) |
Autorizado por el SRI | Si |
rechazado (Rechazado) |
Rechazado por el contenido del comprobante | Si |
rechazo_configuracion (RechazoConfiguracion) |
Falta o esta mal una configuracion del emisor | Si |
error (Error) |
Un fallo impidio definitivamente la autorizacion | Si |
cancelado (Cancelado) |
Envio cancelado por la plataforma | Si |
Junto al estado llega codEstado, un numero de 4 digitos cuyo primer digito es el estado: 1001 recibido
sin clave de acceso, 1002 recibido con claveAcceso, 2001 autorizado, 3xxx rechazado (3001 rechazo_sri),
4xxx rechazo de configuracion (4002 firma_no_valida, 4004 cupo_agotado), 5xxx error y 6001 cancelado. En
los estados finales distintos de autorizado, msgError describe el codigo y errores trae el detalle (por
ejemplo el mensaje del SRI); sin error, msgError es null y errores esta vacio. Contracts\CodEstado trae
una constante por codigo, CodEstado::estado($codigo) devuelve el EstadoOperacion de un codigo (tambien de
uno nuevo) y CodEstado::nombre($codigo) su nombre en el catalogo.
La emision (Admission) y la operacion (Operation) tienen los mismos campos: estado, codEstado,
msgError, errores, idOperacion, urlEstado (URL absoluta de la operacion), ambiente, tipoDocumento,
numeroDocumento, referenciaExterna, claveAcceso, fhRecibido y fhAutorizacion.
Admission y Operation ofrecen estadoOperacion(), tipoComprobante() (TipoComprobante, a partir de
tipoDocumento), esFinal() y esAutorizado(); EstadoOperacion tambien tiene esFinal() y
esAutorizado(). Un valor nuevo del API se lee como Desconocido (no final) o null en TipoComprobante;
los campos string originales no cambian.
Errores
| Excepcion | Cuando | Que hacer |
|---|---|---|
EcuafactAuthException |
401/403 | Revisa la API Key y el contribuyente autorizado |
EcuafactValidationException |
400/413/415/422/501 | Corrige los datos segun errores |
EcuafactNotFoundException |
404 | Revisa la identificacion, la clave o el id |
EcuafactConflictException |
409 | Misma Idempotency-Key con otro contenido, o comprobante duplicado |
EcuafactRateLimitException |
429 con codEstado 5005 |
Espera retryAfter segundos y repite |
EcuafactQuotaException |
429 con codEstado 4004 |
Compra cupo; no repitas |
EcuafactServerException |
5xx | Repite con la misma Idempotency-Key si esReintentable |
EcuafactConnectionException |
Sin respuesta HTTP | Repite con la misma Idempotency-Key |
EcuafactTimeoutException |
Tiempo agotado | Consulta la operacion o repite con la misma clave |
EcuafactConfigurationException |
Opcion invalida | Corrige la configuracion |
EcuafactTipoComprobanteException |
El filtro tipoDocumento de listarOperaciones no es un tipo valido |
Usa 01, 03, 04, 05, 06, 07 o su nombre |
EcuafactResponseTooLargeException |
Respuesta mayor que maxResponseBytes |
Sube o desactiva el tope; no se reintenta |
EcuafactWebhookException |
Firma de webhook invalida | Responde 400 y no proceses el evento |
Todo error del API tiene la misma forma: { "estado": "rechazado", "codEstado": 3002, "msgError": "...", "errores": [...] }. Las de API heredan de EcuafactApiException (codEstado como int, estado, msgError,
errores, status con el codigo HTTP, correlationId, idempotencyKey, retryAfter, esReintentable;
estadoHttp es el mismo valor que status); todas heredan de EcuafactSdkException. Una respuesta 2xx con cuerpo vacio o ilegible lanza
EcuafactInvalidResponseException (status, idempotencyKey, correlationId): en una emision, repite con la misma
Idempotency-Key y no emitas con otra. Si el cuerpo de un error no era
JSON, codEstado vale 0. Compara codEstado con las constantes de Contracts\CodEstado:
use Ecuafact\Sdk\Contracts\CodEstado; use Ecuafact\Sdk\EcuafactApiException; try { $client->emitir($comprobante); } catch (EcuafactApiException $e) { if ($e->codEstado === CodEstado::COMPROBANTE_INVALIDO) { print_r($e->errores); // detalle por campo } error_log($e->status . ' ' . $e->codEstado . ' ' . $e->msgError . ' ' . $e->correlationId); }
Contracts\EstadosPublicos trae los valores de texto de estado.
Webhooks
use Ecuafact\Sdk\Contracts\TipoEventoWebhook; use Ecuafact\Sdk\EcuafactWebhookException; use Ecuafact\Sdk\WebhookSignature; $cuerpo = file_get_contents('php://input'); try { // Uno o varios secretos (rotacion); tolerancia por defecto 300 s. $evento = WebhookSignature::construirEvento([$secretoActual, $secretoAnterior], $_SERVER['HTTP_ECUAFACT_SIGNATURE'] ?? '', $cuerpo); } catch (EcuafactWebhookException) { http_response_code(400); return; } switch ($evento->eventType) { case TipoEventoWebhook::DocumentoAutorizado: // estado autorizado, codEstado 2001 // $evento->idOperacion, $evento->claveAcceso, $evento->tipoDocumento, $evento->fhAutorizacion break; case TipoEventoWebhook::DocumentoRechazado: // rechazado con codEstado 3001 // $evento->errores trae el mensaje del SRI break; case TipoEventoWebhook::DocumentoFallido: // rechazado (3002), rechazo_configuracion (4xxx) o error (5xxx) // $evento->estado, $evento->codEstado, $evento->msgError, $evento->errores; siempre final break; case TipoEventoWebhook::OperacionRequiereAtencion: // aviso no final (sigue recibido) o evento de prueba break; }
document.authorized llega con estado autorizado; document.rejected, solo con rechazado y codEstado
3001 (rechazo_sri); document.failed, con rechazado y 3002 (comprobante_invalido), con
rechazo_configuracion o con error, y siempre es final. El cuerpo trae codEstado, errores, msgError
(solo si hay error) fhAutorizacion (si existe) y ruc. operation.requires_attention es un aviso no final: el documento sigue recibido
y el resultado llega despues con otro evento. Un documento cancelado no genera evento. $evento->cuerpo trae
el cuerpo completo decodificado.
WebhookSignature::verify($secretos, $cabecera, $cuerpo) devuelve false (nunca lanza) ante una
cabecera malformada, vencida o con firma distinta.
Standard Webhooks y cualquiera de las dos firmas
Cada entrega trae tambien las cabeceras de Standard Webhooks
(webhook-id, webhook-timestamp y webhook-signature), firmadas con el mismo secreto decodificado de
Base64. Basta con verificar una de las dos. construirEventoDesdeCabeceras recibe las cabeceras de la
peticion, verifica Ecuafact-Signature si viene y, si no viene o no es valida, Standard Webhooks:
try { // getallheaders(), $_SERVER o $request->getHeaders() de PSR-7; los nombres no distinguen mayusculas. $evento = WebhookSignature::construirEventoDesdeCabeceras([$secretoActual, $secretoAnterior], getallheaders(), $cuerpo); } catch (EcuafactWebhookException) { http_response_code(400); return; }
WebhookSignature::verificarCabeceras($secretos, $cabeceras, $cuerpo) hace lo mismo y devuelve bool, y
WebhookSignature::verificarStandardWebhooks($secretos, $webhookId, $webhookTimestamp, $webhookSignature, $cuerpo)
verifica solo el estandar. Aceptan el secreto con o sin el prefijo whsec_; un secreto que no es Base64 da
false. La tolerancia por defecto tambien es de 300 segundos.
Documentacion
Licencia
MIT.