El primer segmento de la URL identifica la cuenta con el formato TU_ID-TU_ID_URL. Para las acciones de emisión, las credenciales se envían en el cuerpo JSON, no como un Bearer token.
POST/api/TU_ID-TU_ID_URL/ACCION
Campo
Contenido
api_rnc
RNC de la cuenta emisora. Debe coincidir con la cuenta de la URL.
api_token
Token suministrado al activar la cuenta.
api_data
Objeto con la información del comprobante: encabezado, detalles y demás nodos requeridos.
Cabecera: Content-Type: application/json. Mantén el token en tu backend y evita publicarlo en JavaScript, repositorios o registros de depuración.
03. Rutas de emisión
POST/api/TU_ID-TU_ID_URL/VALIDAR_ECF
Genera y firma el XML para validar su estructura contra el XSD configurado. Esta acción no equivale a la aceptación del comprobante por la DGII y puede guardar un XML de validación.
POST/api/TU_ID-TU_ID_URL/FIRMAR_ECF
Procesa la generación y firma del documento y su flujo de envío según configuración, tipo de e-CF y ambiente. Revisa el estado retornado: firmar, enviar y aceptar son pasos distintos.
No envíes documentos reales a producción para probar la conectividad. Solicita primero una cuenta de pruebas. Una respuesta técnica exitosa no demuestra aceptación fiscal.
04. Ejemplos para tu desarrollador
La URL, token, RNC y e-NCF son marcadores de ejemplo. La estructura JSON siguiente es un esquema orientativo, no un comprobante fiscal completo ni listo para emitir: añade los campos y reglas del tipo de e-CF de acuerdo con su XSD.
# URL y credenciales suministradas al activar la cuenta.
# payload.json debe contener el documento completo de tu e-CF.
curl --request POST \
'https://clusterhubdgii.com.do/api/TU_ID-TU_ID_URL/VALIDAR_ECF' \
--header 'Content-Type: application/json' \
--data-binary '@payload.json' \
--connect-timeout 10 --max-time 60
PHP · conexión desde el backend
// Ejecutar únicamente en el servidor, nunca en el navegador.
$url = getenv('CLUSTERHUB_ACCOUNT_URL') . '/VALIDAR_ECF';
$payload = [
'api_rnc' => getenv('CLUSTERHUB_RNC'),
'api_token' => getenv('CLUSTERHUB_TOKEN'),
'api_data' => $documentoCompleto
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60
]);
$raw = curl_exec($ch);
if ($raw === false) {
throw new RuntimeException(curl_error($ch));
}
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$response = json_decode($raw, true);
// Revisar HTTP, api_error y estado fiscal por separado.
// api_error_msg puede ser una cadena o un arreglo.
No pegues credenciales reales en esta web. Los ejemplos no se ejecutan y no crean comprobantes.
05. Cómo interpretar las respuestas
Comprueba el código HTTP y el contenido JSON. api_error puede representarse como cadena o número; api_error_msg puede contener una cadena o un arreglo. Los campos disponibles dependen de la acción y del resultado.
Campo
Uso
api_response_code
Código de respuesta informado por la API.
api_error / api_error_msg
Indicador y detalle del error técnico o de validación.
api_encf / api_encf_firmado
Comprobante procesado e indicador de firma.
api_ecf_estatus / api_encf_estatus
Estado del proceso y del comprobante. No son intercambiables.
api_trackId
Identificador de seguimiento cuando está disponible.
api_url_consulta
URL de consulta cuando la genera el flujo.
Errores que contempla el router: 400 para JSON inválido; 401 para problemas de cuenta, token, certificado o conexión de cuenta; 404 para URL vacía o mal formada; 405 para cuenta/acción no indicada o método no autorizado; 500 para error interno. Revisa siempre el mensaje específico.
No hagas reintentos ilimitados. Antes de reenviar un e-NCF, verifica el estado y coordina la estrategia con soporte para evitar duplicidades.
06. Recepción y webhooks
El flujo de recepción utiliza rutas distintas de la emisión. La configuración y el registro de estas direcciones deben coordinarse durante la implementación.
No reutilices el cuerpo JSON de emisión en estas rutas. La recepción contempla archivos XML y autenticación propia del flujo receptor; el equipo técnico entrega los detalles de configuración para tu cuenta.
07. Checklist de una integración responsable
Usar HTTPS sin desactivar la verificación del certificado TLS.
Guardar secretos y certificados fuera del código público.
Registrar errores sin incluir tokens, claves o datos fiscales innecesarios.
Separar pruebas, certificación y producción.
Interpretar estados técnicos y fiscales antes de actualizar tu factura.
Acordar soporte, conservación de XML y recuperación en la propuesta de servicio.
Esta es una referencia inicial basada en las rutas actuales. El esquema completo del documento y el alcance de integración deben confirmarse para tu cuenta y tipo de comprobante.
08. Respuestas de ejemplo y errores frecuentes
Ejemplos orientativos con datos ficticios. No son comprobantes ni respuestas obtenidas de una operación real. El contenido exacto depende del flujo ejecutado.
Error de credenciales
{
"api_response_code": 401,
"api_error": "1",
"api_error_msg": "TOKEN NO VALIDO PARA ESTA CUENTA"
}
Estado de un comprobante aceptado recuperado
El código contempla devolver FIN para proceso finalizado y ACE para un comprobante aceptado recuperado. No asumas estos valores cuando únicamente validas o firmas.
JSON válido, contenido UTF-8, Content-Type y objeto esperado.
LA CUENTA EN LA URL NO COINCIDE CON EL RNC ENVIADO
Correspondencia entre URL asignada y api_rnc.
TOKEN NO VALIDO PARA ESTA CUENTA
Token de esa cuenta, sin espacios añadidos ni credenciales de otro ambiente.
CERTIFICADO NO VERIFICADO PARA ESTA CUENTA
Coordinar con soporte la configuración y vigencia del certificado.
METODO NO AUTORIZADO
Usar POST para las acciones JSON de emisión.
Errores de XSD / campos del documento
Revisar api_error_msg y adaptar los campos al tipo de e-CF.
Timeout o respuesta incompleta
No asumir rechazo ni reenviar a ciegas. Confirmar el estado antes de repetir el mismo e-NCF.
09. De pruebas a producción
Definir el escenario: RNC, tipos de e-CF, volumen y flujo de recepción.
Preparar la cuenta: obtener URL y token mediante el canal de implementación acordado, configurar certificado y ambiente.
Mapear los datos: comprobar totales, encabezados, detalle y reglas del documento contra el XSD correspondiente.
Probar casos positivos y negativos: datos correctos, errores de estructura, credenciales equivocadas y manejo de timeout, siempre en el ambiente de pruebas acordado.
Verificar la operación: conservar referencias de e-NCF, separar errores técnicos de estados fiscales y definir reintentos con soporte.
Autorizar el paso a producción: confirmar habilitación del emisor, certificado vigente, secuencias autorizadas y aprobación de la integración.
Acompañar el inicio: revisar las primeras operaciones, estados y procedimiento de incidencias.
Cambiar un parámetro de esta web no activa producción. La configuración del ambiente corresponde a la cuenta de la API.