Download the PHP package ecuafact/sdk without Composer

ecuafact/sdk (PHP)

Cliente oficial en PHP del API publico de facturacion electronica Ecuafact (contrato v1). Cubre autenticacion, idempotencia, reintentos configurables, espera del resultado, recorrido de paginas, logo del perfil y firma de webhooks. Compatible con PHP 8.2+.

Instalacion

Requisitos

• [ ] PHP 8.2+ con ext-curl y ext-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).

Multi-RUC

La vista expone emitir, listarEmitidos, iterarEmitidos, descargarRide, descargarXml, enviarCorreo, getPerfil, actualizarPerfil, actualizarLogo, esperarResultado y getConsumo.

Variables de entorno

El SDK no distingue ambientes: el ambiente lo define la URL. La URL debe ser absoluta (http o https) y no debe terminar en /v1: el SDK agrega /v1 a cada ruta. 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. En las respuestas, Comprobante::$total y CatalogoItem::$tarifa se leen como float (precision de double).

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 ->idSeguimiento en el error).

getOperacion, consultarOperacion y esperarResultado exigen un idOperacion UUID.

Reintentos

Se reintentan solo solicitudes idempotentes (GET, o POST/PUT con Idempotency-Key) ante errores de red y los estados de retryableStatusCodes (408, 425, 500, 502, 503, 504).

• 429 con codigo 501 (cupo agotado): nunca se reintenta.
• 429 con codigo 104 (limite de solicitudes): solo con retryRateLimited: true, respetando Retry-After y maxRetryDelaySeconds.

Opciones

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.

Opciones por llamada

Todos los metodos que llaman al API (tambien para(), esperarResultado e iterarEmitidos) aceptan como ultimo argumento ?RequestOptions $opciones. Solo afectan a esa llamada.

• Un correlationId invalido o un tiempo <= 0 lanza EcuafactConfigurationException.
• La correlacion queda en EmisionResultado::$correlationId, en EcuafactApiException::$idSeguimiento y en EcuafactConnectionException::$correlationId / EcuafactTimeoutException::$correlationId.
• timeout por llamada se aplica con el transporte cURL (o uno que implemente TimeoutOverrideTransportInterface); con un transporte PSR-18 lo controla tu cliente HTTP.
• PHP no tiene cancelacion cooperativa: acota la llamada con timeout o totalTimeout.

Constructores de comprobantes

Opcionales. Producen el mismo ComprobanteRequest; puedes seguir armandolo a mano.

• Tipos: factura, liquidacionCompra, notaCredito, notaDebito, guiaRemision, retencion.
• Lo que asignas nunca se sobrescribe (importeTotal(), detalle(Detalle), configurar(fn)...).
• Reglas del API: subtotal redondear(cantidad x precio - descuento); IVA sobre la base sin redondear mas el ICE; cabecera agrupada por codigo + codigoPorcentaje (IVA y luego ICE) sumando las lineas; total = subtotal + IVA + ICE + propina.
• Precision: new Precision(escalaImportes: 2, escalaCantidades: 6, redondeo: ModoRedondeo::HALF_UP) como ultimo argumento de la fabrica.
• Sin constructor: ComprobanteBuilder::calcularTotales($request) (devuelve una copia) y ComprobanteBuilder::validarComprobante($request).
• Calculo exacto: usa bcmath si esta instalado y, si no, aritmetica decimal propia sobre strings.

Recorrer paginas

desde/hasta son fechas de calendario de Ecuador (Y-m-d). Un DateTimeInterface se formatea como Y-m-d en su propia zona horaria. iterarEmitidos pide cada pagina solo cuando la necesitas y para con hayMas = false o en la pagina 10000.

Estados tipados

Operation::estadoOperacion() (EstadoOperacion), Operation::estadoAutorizacionTipado() (EstadoAutorizacion), Operation::tipoComprobante() (TipoComprobante), Operation::esFinal() y Operation::esAutorizado(). Un valor nuevo del API se lee como Desconocido (o null en TipoComprobante); los campos string originales no cambian.

Errores

Las de API heredan de EcuafactApiException (codigo, mensaje, errores, estadoHttp, idSeguimiento, idempotencyKey, retryAfter, esReintentable); todas heredan de EcuafactSdkException.

Webhooks

WebhookSignature::verify($secretos, $cabecera, $cuerpo) devuelve false (nunca lanza) ante una cabecera malformada, vencida o con firma distinta.

Documentacion

• Guia del SDK PHP

Licencia

MIT.