Download the PHP package grodtech/ecf-php without Composer

grodtech/ecf-php

SDK PHP oficial para consumir la pasarela ECF GRODTECH (facturación electrónica DGII República Dominicana).

El SDK se encarga de:

• abrir la conexión HTTPS contra la pasarela con TLS estricto,
• enviar el comprobante (en JSON o XML),
• mantener la API Key fuera de los logs,
• normalizar la respuesta heterogénea de DGII a un enum DgiiOutcome.

Solo servidor. Nunca incruste la API Key en aplicaciones front‑end (navegador, móvil, escritorio) ni en repositorios públicos.

Índice

• Cómo encaja en tu arquitectura
• Requisitos
• Instalación
• Uso
• API del SDK
• Estados (DgiiOutcome)
• Endpoints cubiertos
• Entornos disponibles
• Seguridad
• Manejo de errores
• Buenas prácticas
• Pruebas
• FAQ
• Soporte
• Licencia

Cómo encaja en tu arquitectura

• Tu backend autentica al CRM con la API Key que generaste en https://ecf.grodtech.com. La API Key viaja en el header Authorization: Bearer ….
• El CRM autentica con DGII por su cuenta: usa el certificado .p12 que cargaste en el portal y obtiene el token DGII vía el flujo semilla → validacioncertificado. Tu sistema nunca ve ese token.
• Tu sistema nunca firma localmente: el CRM firma cada XML con tu .p12 antes de reenviarlo a DGII.

Requisitos

• PHP 8.1 o superior
• Extensiones PHP: json, curl
• Cuenta activa en ecf.grodtech.com con:
  • RNC autorizado como emisor electrónico ante DGII
  • Certificado .p12 cargado en el portal
  • API Key generada desde el panel

Instalación

El paquete se distribuye dentro del repositorio de la aplicación, como path repository de Composer. En el composer.json de tu proyecto:

Si más adelante el paquete se publica en un Git privado (GitHub, GitLab, Bitbucket), basta con cambiar el bloque repositories a "type": "vcs" apuntando a la URL del repo y declarar la versión deseada.

Uso

1. Enviar un e‑CF en JSON

El SDK acepta el mismo árbol JSON que documenta DOCUMENTACION_API_ECF_GRODTECH.txt — raíz ECF para los tipos 31, 32, 33, 34, 41, 43, 44, 45, 46 y 47, raíz RFCE para el Resumen de Factura de Consumo (Tipo 32 < RD$250 000).

Los placeholders {{RNC}}, {{RAZON_SOCIAL}}, {{DIRECCION_EMISOR}} y {{FECHA_EMISION}} los reemplaza el CRM con los datos del contribuyente registrado en el portal — si los actualiza ahí, los siguientes envíos los reflejan sin tocar código. Ver sección 9 del DOCUMENTACION_API_ECF_GRODTECH.txt para la lista completa.

2. Enviar un Resumen Factura de Consumo (Tipo 32 < RD$250 000)

3. Previsualizar el XML antes de enviarlo

JsonToXml::documentFromArray() produce el XML sin firma — útil para validarlo offline contra el XSD oficial DGII v1.0 antes del POST.

4. Enviar XML ya firmado por tu propio sistema

Si tu sistema firma localmente con su propio .p12 (caso avanzado), envía el XML directamente:

5. Aprobación Comercial Electrónica (ACECF)

Cuando tu sistema acepta o rechaza un e-CF recibido de un proveedor, envía el ACECF firmado:

6. Interpretar la consulta posterior a DGII

Cuando consultes el estado por trackId directamente al endpoint consultaresultado de DGII, la respuesta cruda se normaliza así:

API del SDK

Grodtech\Ecf\Client

Validaciones del constructor (lanzan \InvalidArgumentException):

• baseUrl no vacío y bien formado
• baseUrl debe usar HTTPS (a menos que allowInsecureHttp = true, reservado para tests locales)
• apiKey no vacío
• timeouts positivos

Grodtech\Ecf\JsonToXml

Grodtech\Ecf\ResultInterpreter

Grodtech\Ecf\StandardPlaceholders

Constantes para no equivocarse al construir plantillas dinámicas:

Grodtech\Ecf\GatewayRecepcionResult (DTO inmutable)

Grodtech\Ecf\DgiiConsultaResult (DTO inmutable)

Estados (DgiiOutcome)

Endpoints cubiertos

La verificación de conectividad y de la API Key se hace con un GET simple a /fe/autenticacion/api/autenticacion (no expuesto como método del SDK por ser trivial — un curl o file_get_contents con el header Authorization: Bearer … basta).

Entornos disponibles

Cambiar de entorno = simplemente cambiar la baseUrl que pasa al Client. La pasarela detecta el entorno y enruta a la DGII correspondiente.

Seguridad

Esta sección describe el modelo de amenazas del SDK y las contramedidas integradas. Si descubre una vulnerabilidad, repórtela según SECURITY.md.

Contramedidas implementadas

Lo que el SDK NO hace (responsabilidad del integrador)

• Almacenar la API Key: úsela desde variables de entorno o un secret manager. Nunca la commitee.
• Rate limiting: implemente throttling en su lado.
• Reintentos automáticos: el SDK no reintenta por sí solo. Si quiere reintentar ante 5xx o curl_error, hágalo con jitter exponencial en su capa.
• Persistir auditoría: la pasarela ya conserva el XML firmado, el PDF y la respuesta DGII por 10 años (descargables desde el panel). Aun así, persistir trackId y outcome en su sistema agiliza la conciliación contable.
• Generar el eNCF: la pasarela no asigna secuencias e-NCF; eso lo hace su sistema con las series autorizadas por DGII.
• Firmar el XML localmente: la pasarela firma con el .p12 que usted cargó en el portal. Si firma localmente, use recepcionXml().

Reglas de oro

1. NUNCA ponga la API Key en JavaScript del navegador, en apps móviles, ni en repos públicos.
2. NUNCA desactive la verificación TLS. Este SDK no lo permite, y por buena razón.
3. NUNCA pase HTTP en baseUrl para producción. El SDK lo rechaza con InvalidArgumentException.
4. NUNCA logee el cuerpo completo del request (puede contener PII de clientes finales). Logee trackId y outcome.
5. NUNCA acepte input directo del usuario en el eNCF o RNC sin validar (riesgo de abuso de su cuota DGII).
6. SIEMPRE rote la API Key si sospecha exposición; hágalo desde el panel ECF GRODTECH.
7. SIEMPRE valide la respuesta con ResultInterpreter antes de marcar internamente el documento como “aceptado”.

Cifrado de la API Key en disco

Si por requisito operacional necesita guardar la API Key en su servidor, ciérrela con permisos restrictivos:

Lo recomendado es leerla desde una variable de entorno gestionada por el secret manager de su plataforma (Vault, AWS Secrets Manager, Doppler, GCP Secret Manager, etc.) y nunca commitearla.

Manejo de errores

Errores HTTP que devuelve la pasarela

Patrón de manejo recomendado

Buenas prácticas

1. Idempotencia del eNCF: nunca reenvíe el mismo eNCF en flujos lógicos distintos. La DGII rechazará por “secuencia ya utilizada”.
2. Aproveche TestCF y CerteCF antes de pasar a eCF. Cambiar de entorno solo requiere cambiar la baseUrl del Client.
3. Persistencia de auditoría: la pasarela ya retiene el XML firmado y el PDF por 10 años; usted persista al menos trackId y outcome en su sistema para conciliación.
4. Validación previa: use JsonToXml::documentFromArray() para verificar que su JSON produce un XML estructurado antes de enviarlo.
5. Order-aware: respete el orden de las claves en el JSON. El XSD DGII v1.0 es estricto en IdDoc, Emisor, Totales, etc.
6. Timeouts realistas: si su flujo es síncrono (web request), considere bajar timeoutSeconds a 30–60 y reintente en background con curlError.
7. Contingencia activada en el panel: si la DGII tiene un outage, sus envíos quedarán encolados (queued: true) y se reintentarán automáticamente.

Pruebas

El paquete está diseñado para ser fácil de testear:

Para tests de integración, mocke Client con una clase que implemente la misma firma pública.

FAQ

¿Necesito firmar el XML yo mismo? No. La pasarela firma con el .p12 cargado en su portal. Solo envíe JSON (recepcionJson) y olvídese del openssl_*.

¿Qué pasa si la DGII está caída? La pasarela detecta el fallo y, si tiene contingencia activada, encola el documento (queued: true, ok: true). Luego reintenta automáticamente.

¿Cómo cambio de entorno (CerteCF → eCF)? Cambie la baseUrl que pasa al new Client(...). No hace falta reinstalar el SDK.

¿Puedo enviar múltiples e-CFs en paralelo? Sí, instancie un Client por hilo / proceso. El SDK no comparte estado mutable.

¿El SDK soporta async / corutinas? No nativamente; usa cURL síncrono. Para concurrencia masiva use ReactPHP/Amphp envolviendo el Client o haga curl_multi_* por su cuenta con los mismos endpoints.

¿Por qué JsonToXml reemplaza tags con caracteres extraños por Nodo? Es una protección anti-inyección XML: si una clave no cumple [A-Za-z_][A-Za-z0-9_.-]*, se sanea para evitar romper el XML.

¿Por qué el constructor lanza excepción si paso http://? Porque la API Key viaja en el header Authorization y un MITM podría capturarla en HTTP plano. Use HTTPS siempre. Para tests locales, pase allowInsecureHttp: true explícitamente.

¿Dónde quedan los XML firmados y PDFs? La pasarela los persiste 10 años en su panel: Panel → Archivo de Comprobantes. Puede descargar PDF o XML por cada e-CF. Si pierde el archivo en disco, el PDF se regenera bajo demanda desde el XML firmado conservado en la base.

Soporte

• Portal: ecf.grodtech.com
• Documentación API: [https://](https://grodtech.com/documentacion-para-desarrolladores-ecf/)
• Reportar vulnerabilidades: ver SECURITY.md

Licencia

Software propietario. Ver LICENSE.

Copyright © 2026 GRODTECH. Todos los derechos reservados.