SDK PHP

Cliente oficial de la API para PHP. Cubre autenticacion, idempotencia, reintentos y firma de webhook.

  • Paquete: ecuafact/sdk.
  • Requiere PHP 8.2+ con ext-curl.

Como se instala#

composer require ecuafact/sdk

Configuracion#

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

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://staging-api.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    identificacion: '1790012345001', // solo integraciones de un RUC
));
Opcion Default Descripcion
baseAddress - Direccion base del API (obligatoria; define el ambiente)
apiKey - API Key (obligatoria)
identificacion null RUC por defecto (opcional)
timeout 100.0 Tiempo maximo por intento (segundos)
userAgent Ecuafact.Sdk/1.0 User-Agent
retryTransientFailures true Reintenta 408/425/429/5xx
maxAttempts 3 Intentos por solicitud
respectRetryAfter true Respeta Retry-After en 429/503
maxRetryDelaySeconds 60.0 Espera maxima entre reintentos

Metodos#

Metodo Que hace Devuelve
emitir($comprobante) Emite para el RUC por defecto EmisionResultado
emitirEn($ruc, $comprobante) Emite para un RUC explicito EmisionResultado
para($ruc) Fija un contribuyente EcuafactContribuyente
getOperacion($id) Consulta el seguimiento de la operacion Operation
getContexto() Contexto de tu API Key Contexto
getConsumo() Cupo disponible QuotaBucket
listarEmitidos(...) Listan comprobantes PaginaComprobantes
consultarContribuyente($id) Consulta un contribuyente en el SRI ContribuyenteConsulta
buscarContribuyentes(...) Busca por nombre BusquedaContribuyente[]
listarEstablecimientos($ruc) Establecimientos de un RUC EstablecimientosContribuyente
validarIdentificacion($numero) Valida el formato (sin red) ValidacionIdentificacion
decodificarClaveAcceso($clave) Descompone una clave de acceso ClaveAccesoDecodificada
verify(...) Verifica la firma de un webhook bool

Emision#

use Ecuafact\Sdk\Contracts\ComprobanteRequest;
use Ecuafact\Sdk\Contracts\Detalle;
use Ecuafact\Sdk\Contracts\Impuesto;
use Ecuafact\Sdk\Contracts\InfoDocumento;
use Ecuafact\Sdk\Contracts\InfoTributaria;
use Ecuafact\Sdk\Contracts\Pago;

$comprobante = new ComprobanteRequest();
$comprobante->origenReferencia = 'MiERP';
$comprobante->referenciaExterna = 'FACTURA-2026-0001';
$comprobante->infoTributaria = new InfoTributaria();
$comprobante->infoTributaria->ruc = '1790012345001';
$comprobante->infoTributaria->codDoc = '01';
$comprobante->infoTributaria->estab = '002';
$comprobante->infoTributaria->ptoEmi = '001';
$comprobante->infoTributaria->secuencial = '000000123';

$totalConImpuestos = new Impuesto();
$totalConImpuestos->codigo = '2';
$totalConImpuestos->codigoPorcentaje = '4';
$totalConImpuestos->baseImponible = 100.0;
$totalConImpuestos->valor = 15.0;

$pago = new Pago();
$pago->formaPago = '01';
$pago->total = 115.0;

$comprobante->info = new InfoDocumento();
$comprobante->info->fechaEmision = '01/01/2026';
$comprobante->info->tipoIdentificacionComprador = '04';
$comprobante->info->identificacionComprador = '1790012345001';
$comprobante->info->razonSocialComprador = 'Cliente Ejemplo';
$comprobante->info->totalSinImpuestos = 100.0;
$comprobante->info->totalDescuento = 0.0;
$comprobante->info->totalConImpuestos = [$totalConImpuestos];
$comprobante->info->importeTotal = 115.0;
$comprobante->info->moneda = 'DOLAR';
$comprobante->info->pagos = [$pago];

$impuesto = new Impuesto();
$impuesto->codigo = '2';
$impuesto->codigoPorcentaje = '4';
$impuesto->tarifa = 15.0;
$impuesto->baseImponible = 100.0;
$impuesto->valor = 15.0;

$detalle = new Detalle();
$detalle->codigoPrincipal = 'SERV-001';
$detalle->descripcion = 'Servicio de ejemplo';
$detalle->cantidad = 1;
$detalle->precioUnitario = 100.0;
$detalle->descuento = 0.0;
$detalle->precioTotalSinImpuesto = 100.0;
$detalle->impuestos = [$impuesto];
$comprobante->detalles = [$detalle];

$resultado = $client->emitir($comprobante);
echo $resultado->admission->idOperacion . ' ' . $resultado->admission->codigo . PHP_EOL;

Emision con RUC explicito: $client->emitirEn('1790012345001', $comprobante).

Multi-RUC#

$ruc = $client->para('1790099987001');
$pagina = $ruc->listarEmitidos();

Estado y consultas#

$operacion = $client->getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
$contexto = $client->getContexto();
$cupo = $client->getConsumo();

Consultas SRI#

Consultas al SRI (contribuyentes, establecimientos, identificaciones y claves de acceso). Son de solo lectura, no consumen cupo y usan la misma API Key.

$contribuyente = $client->consultarContribuyente('1760013210001');
$encontrados = $client->buscarContribuyentes('PEREZ LOPEZ', 'JUAN', 'PersonaNatural', 10);
$establecimientos = $client->listarEstablecimientos('1760013210001', 'SoloActivos');
$validacion = $client->validarIdentificacion('1760013210001');
$clave = $client->decodificarClaveAcceso($claveAcceso);

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 EcuafactApiException->idempotencyKey). Al reintentar, reutiliza la clave devuelta. La correlacion de la respuesta queda en resultado->correlationId (o EcuafactApiException->idSeguimiento en error). Los fallos transitorios (408/425/429/5xx) se reintentan respetando Retry-After; el resto de los 4xx no.

Webhooks#

use Ecuafact\Sdk\WebhookSignature;

$valido = WebhookSignature::verify($secreto, $cabecera, $cuerpoCrudo, time(), 300);

Ve Verificacion de firma y Webhooks.

Errores#

EcuafactApiException trae codigo, mensaje, estadoHttp, idSeguimiento, errores e idempotencyKey. Los errores locales son EcuafactSdkException.

Siguientes pasos#

No se pudo completar la operacion. Recargar ✕