Integración Simple en Menos de 10 Minutos

Integración con la DGII para Desarrolladores & IA

Esta guía está estructurada para que cualquier desarrollador junior o cualquier persona asistida por Inteligencia Artificial (ChatGPT, Claude, Cursor o Copilot) pueda conectar un ERP, sistema de punto de venta (POS) o tienda online directamente con la DGII mediante llamadas HTTP JSON simples.

🤖

Prompt Listo para Integración con Inteligencia Artificial

Copie este bloque y péguelo directamente en ChatGPT, Claude, Cursor o Copilot

Si no tienes experiencia previa con las normas de la DGII o quieres que una IA programe la integración completa en tu lenguaje favorito (PHP, Python, JavaScript, Java, C#, etc.), copia el siguiente prompt y reemplaza los datos entre corchetes:

Actúa como un desarrollador senior experto en Facturación Electrónica de República Dominicana (DGII Ley 32-23). Quiero integrar mi sistema de ventas con el motor fiscal API REST ubicado en: https://ecf.peguerogas.com/{ambiente}/documentos-ecf Mis credenciales son: - API Key: [MI_API_KEY] - RNC Emisor: [MI_RNC] - Ambiente: CerteCF (para pruebas y certificación) o eCF (para producción oficial) Por favor, crea una función en [MI_LENGUAJE: ej. PHP Laravel / Python / Node.js / C#] que: 1. Reciba los datos de una venta (número eNCF tipo E31 o E32, fecha, RNC cliente, lista de productos con precio, cantidad e ITBIS y montos totales). 2. Arme la estructura JSON requerida por el motor con el nodo raíz "ECF", "Encabezado" (IdDoc, Emisor, Comprador, Totales) y "DetallesItems". 3. Envíe una petición HTTP POST al endpoint con las cabeceras "X-API-KEY" y "X-RNC". 4. Si la respuesta contiene "valid": true y "status": "Aceptado", extraiga el 'securityCode' (6 caracteres) y la 'qr_url' para imprimirlos en el comprobante fiscal de mi cliente. 5. Maneje errores amigables si la DGII rechaza el comprobante mostrando el campo "message".

Arquitectura & Flujo en 3 Pasos

Paso 1: Autenticación

Obtén tu API Key en la sección API Keys del portal. Inclúyela en cada llamada en la cabecera X-API-KEY junto con tu RNC en X-RNC.

Paso 2: Envío de Factura

Realiza un POST HTTP al endpoint /{ambiente}/documentos-ecf enviando el objeto JSON de tu comprobante fiscal.

Paso 3: Timbrado & QR

El motor firma el XML con XAdES-BES en memoria, lo transmite a la DGII y te devuelve el Código de Seguridad y la URL oficial del código QR.

Ambientes Disponibles

El motor fiscal dispone de endpoints separados por ambiente en la URL:

Ambiente	URL del Endpoint	Uso
CerteCF	https://ecf.peguerogas.com/CerteCF/documentos-ecf	Set Oficial de Pruebas y Certificación ante la DGII.
eCF	https://ecf.peguerogas.com/eCF/documentos-ecf	Emisión oficial en Producción con validez fiscal tributaria ante la DGII.
TesteCF	https://ecf.peguerogas.com/TesteCF/documentos-ecf	Sandbox interno para pruebas sintéticas de integración.

Ejemplos de Integración por Lenguaje

Copie el código listo para su aplicación en el lenguaje que prefiera

<?php
// Ejemplo en PHP nativo (cURL) o Laravel
$url = "https://ecf.peguerogas.com/CerteCF/documentos-ecf";
$apiKey = "TU_API_KEY_AQUI";
$rncEmisor = "131090257";

$payload = [
    "ECF" => [
        "Encabezado" => [
            "IdDoc" => [
                "TipoeCF" => 31,
                "eNCF" => "E310000000219",
                "FechaVencimientoSecuencia" => "2026-12-31"
            ],
            "Emisor" => [
                "RNCEmisor" => $rncEmisor,
                "RznSocEmisor" => "PEGUERO GAS SRL"
            ],
            "Comprador" => [
                "RNCComprador" => "101842458",
                "RznSocComprador" => "CLIENTE EJEMPLO SRL"
            ],
            "Totales" => [
                "MontoTotal" => 2360.00,
                "TotalITBIS" => 360.00
            ]
        ],
        "DetallesItems" => [
            "Item" => [
                [
                    "NumeroLinea" => 1,
                    "NombreItem" => "GLP Granel 100 Galones",
                    "CantidadItem" => 100,
                    "PrecioUnitarioItem" => 20.00,
                    "MontoItem" => 2000.00
                ]
            ]
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-KEY: " . $apiKey,
    "X-RNC: " . $rncEmisor
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
if ($httpCode === 200 && ($result['valid'] ?? false) === true) {
    echo "¡Aceptado por DGII!
";
    echo "Código de Seguridad: " . $result['securityCode'] . "
";
    echo "URL Timbre QR: " . $result['qr_url'] . "
";
} else {
    echo "Error o Rechazo: " . ($result['message'] ?? 'Error desconocido') . "
";
}
?>

// Ejemplo en Node.js (Fetch o Axios)
const url = "https://ecf.peguerogas.com/CerteCF/documentos-ecf";
const apiKey = "TU_API_KEY_AQUI";
const rncEmisor = "131090257";

const payload = {
  ECF: {
    Encabezado: {
      IdDoc: {
        TipoeCF: 31,
        eNCF: "E310000000219",
        FechaVencimientoSecuencia: "2026-12-31"
      },
      Emisor: {
        RNCEmisor: rncEmisor,
        RznSocEmisor: "PEGUERO GAS SRL"
      },
      Comprador: {
        RNCComprador: "101842458",
        RznSocComprador: "CLIENTE EJEMPLO SRL"
      },
      Totales: {
        MontoTotal: 2360.00,
        TotalITBIS: 360.00
      }
    },
    DetallesItems: {
      Item: [
        {
          NumeroLinea: 1,
          NombreItem: "GLP Granel 100 Galones",
          CantidadItem: 100,
          PrecioUnitarioItem: 20.00,
          MontoItem: 2000.00
        }
      ]
    }
  }
};

async function enviarFactura() {
  const resp = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": apiKey,
      "X-RNC": rncEmisor
    },
    body: JSON.stringify(payload)
  });

  const data = await resp.json();
  if (resp.ok && data.valid) {
    console.log("¡Aceptado por DGII!");
    console.log("Código Seguridad:", data.securityCode);
    console.log("URL QR:", data.qr_url);
  } else {
    console.error("Error DGII:", data.message);
  }
}

enviarFactura();

# Ejemplo en Python con requests
import requests

url = "https://ecf.peguerogas.com/CerteCF/documentos-ecf"
api_key = "TU_API_KEY_AQUI"
rnc_emisor = "131090257"

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key,
    "X-RNC": rnc_emisor
}

payload = {
    "ECF": {
        "Encabezado": {
            "IdDoc": {
                "TipoeCF": 31,
                "eNCF": "E310000000219",
                "FechaVencimientoSecuencia": "2026-12-31"
            },
            "Emisor": {
                "RNCEmisor": rnc_emisor,
                "RznSocEmisor": "PEGUERO GAS SRL"
            },
            "Comprador": {
                "RNCComprador": "101842458",
                "RznSocComprador": "CLIENTE EJEMPLO SRL"
            },
            "Totales": {
                "MontoTotal": 2360.00,
                "TotalITBIS": 360.00
            }
        },
        "DetallesItems": {
            "Item": [
                {
                    "NumeroLinea": 1,
                    "NombreItem": "GLP Granel 100 Galones",
                    "CantidadItem": 100,
                    "PrecioUnitarioItem": 20.00,
                    "MontoItem": 2000.00
                }
            ]
        }
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if response.status_code == 200 and data.get("valid"):
    print("¡Aprobado por DGII!")
    print(f"Código Seguridad: {data['securityCode']}")
    print(f"URL QR Oficial: {data['qr_url']}")
else:
    print(f"Error DGII: {data.get('message')}")

// Ejemplo en C# .NET 8 (HttpClient)
using System.Net.Http.Json;

var client = new HttpClient();
var url = "https://ecf.peguerogas.com/CerteCF/documentos-ecf";
var apiKey = "TU_API_KEY_AQUI";
var rncEmisor = "131090257";

client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
client.DefaultRequestHeaders.Add("X-RNC", rncEmisor);

var payload = new
{
    ECF = new
    {
        Encabezado = new
        {
            IdDoc = new { TipoeCF = 31, eNCF = "E310000000219", FechaVencimientoSecuencia = "2026-12-31" },
            Emisor = new { RNCEmisor = rncEmisor, RznSocEmisor = "PEGUERO GAS SRL" },
            Comprador = new { RNCComprador = "101842458", RznSocComprador = "CLIENTE EJEMPLO SRL" },
            Totales = new { MontoTotal = 2360.00m, TotalITBIS = 360.00m }
        },
        DetallesItems = new
        {
            Item = new[] {
                new { NumeroLinea = 1, NombreItem = "GLP Granel", CantidadItem = 100, PrecioUnitarioItem = 20.00m, MontoItem = 2000.00m }
            }
        }
    }
};

var response = await client.PostAsJsonAsync(url, payload);
var result = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();

if (response.IsSuccessStatusCode && result != null && result.TryGetValue("securityCode", out var code))
{
    Console.WriteLine($"¡Aprobado DGII! Código Seguridad: {code}");
    Console.WriteLine($"URL QR: {result["qr_url"]}");
}

curl -X POST https://ecf.peguerogas.com/CerteCF/documentos-ecf   -H "Content-Type: application/json"   -H "X-API-KEY: TU_API_KEY_AQUI"   -H "X-RNC: 131090257"   -d '{
    "ECF": {
      "Encabezado": {
        "IdDoc": { "TipoeCF": 31, "eNCF": "E310000000219", "FechaVencimientoSecuencia": "2026-12-31" },
        "Emisor": { "RNCEmisor": "131090257", "RznSocEmisor": "PEGUERO GAS SRL" },
        "Comprador": { "RNCComprador": "101842458", "RznSocComprador": "CLIENTE EJEMPLO SRL" },
        "Totales": { "MontoTotal": 2360.00, "TotalITBIS": 360.00 }
      },
      "DetallesItems": {
        "Item": [
          { "NumeroLinea": 1, "NombreItem": "GLP Granel", "CantidadItem": 100, "PrecioUnitarioItem": 20.00, "MontoItem": 2000.00 }
        ]
      }
    }
  }'

Catálogo de Comprobantes Oficiales DGII

E31 Crédito Fiscal

Para empresas y gastos con crédito de ITBIS.

E32 Consumo

Para clientes finales y público en general.

E33 / E34 Notas Débito / Crédito

Modificación o anulación de comprobantes emitidos.

E41 / E43 Compras / Gastos Menores

Proveedores informales o gastos operativos pequeños.

🏢 Arquitectura Multi-Empresa & Marca Blanca

El motor fiscal está diseñado con soporte nativo para alojar múltiples empresas (ej. Peguero Gas, Supermercados, Farmacias, etc.) en un solo servidor de manera completamente segura y aislada:

1. Subdominio Exclusivo

Cada empresa apunta su subdominio exclusivo (ej: ecf.supermercadord.com) hacia la IP del servidor mediante un registro DNS Tipo A.

2. Bóveda Criptográfica Aislada

Cada empresa carga su archivo .p12 exclusivo con su contraseña cifrada en AES-256. Jamás se comparten llaves ni datos entre empresas.

3. Identidad Independiente ante DGII

La DGII interactúa directamente con el subdominio de cada empresa, garantizando que cada una mantenga su certificación independiente y registro oficial.

¿Necesitas asesoría técnica para tu integración?

Nuestro equipo de desarrollo te asiste directamente vía WhatsApp para resolver dudas de esquemas, errores DGII o configuración de webhooks en minutos.

Escribir por WhatsApp a Soporte (829-943-7780)