ECF Connector API
Integra tu sistema con la facturación electrónica dominicana (e‑CF) a través de una API REST simple y segura. Firma, envía y consulta comprobantes fiscales electrónicos ante la DGII.
Solicitar tu API KeyDescripción general
El ECF Connector es un módulo desarrollado por RutiversoTech que expone una API REST para crear, firmar y enviar Comprobantes Fiscales Electrónicos (e-CF) a la DGII, directamente desde cualquier sistema externo.
Todos los endpoints tienen el prefijo base:
{URL_proporcionada}/api/ecf
Autenticación
Todos los endpoints requieren un API Key enviada en el encabezado Authorization. La clave se genera automáticamente al crear un conector en el sistema.
Authorization: ECF-{id}-{32_caracteres_aleatorios}
inactive o pending_paid son rechazados en todos los endpoints operativos.Formato de respuesta
Todas las respuestas son JSON con la siguiente estructura estándar:
{
"message": "Descripción del resultado",
"code": 200,
"data": { /* datos específicos del endpoint */ }
}
| Campo | Tipo | Descripción |
|---|---|---|
message | string | Mensaje descriptivo del resultado |
code | integer | Código HTTP de la respuesta (200, 400, 500) |
data | object | array | Payload con los datos de la respuesta |
Códigos de error comunes
| Código | Significado |
|---|---|
200 | Operación exitosa |
400 | Solicitud inválida (parámetros faltantes o incorrectos) |
401 | API Key no válida o conector inactivo |
500 | Error interno del servidor |
Estados ECF
Los comprobantes pasan por los siguientes estados ante la DGII:
El campo ecf_status reporta sent mientras el comprobante está firmado y en cola o ya enviado. El estado interno exacto viene en ecf_status_detail (init = en cola, aún no recibido por la DGII). Consulta /invoice/{id}/status hasta obtener success, conditional o failure.
Tipos de NCF soportados
El prefijo del campo ncf determina automáticamente el tipo de documento y el movimiento contable que se crea.
IDs de impuestos
Cada línea indica sus impuestos con tax_ids: una lista de IDs del servidor del API, no de tu sistema. Los IDs dependen del servidor donde está tu conector, así que los que aparecen en esta documentación (1, 2, 5) son solo ilustrativos. Usa siempre los tuyos.
Dónde obtenerlos
- Desde tu portal: entra a
clientes.rutiversotech.comcon tu usuario y pulsa el botón de descargar IDs de impuestos. El archivo trae el ID, el nombre, el porcentaje y el uso (venta o compra) de cada impuesto. - Desde el API: llama a
GET /api/ecf/taxes. Es la misma lista, lista para que tu sistema la lea al arrancar.
# Exportar tus IDs a CSV desde la terminal (requiere jq)
curl -s "$ECF_API_URL/api/ecf/taxes" -H "Authorization: $ECF_API_KEY" \
| jq -r '.data[] | [.id, .name, .amount, .type_tax_use] | @csv' > impuestos_ecf.csv
Cómo mapearlos
Guarda el ID del API junto a cada impuesto de tu sistema y tradúcelo al enviar. Por ejemplo:
| Impuesto en tu sistema | Busca en la lista | Envía en tax_ids |
|---|---|---|
| ITBIS 18 % ventas | amount = 18 · type_tax_use = "sale" | el id de esa fila |
| ITBIS 16 % ventas | amount = 16 · type_tax_use = "sale" | el id de esa fila |
| Exento | amount = 0 · type_tax_use = "sale" | el id de esa fila |
Endpoints
Verifica que la API Key sea válida y devuelve la información del conector. Úsalo para confirmar la autenticación antes de realizar operaciones.
Encabezados
| Header | Tipo | Descripción | |
|---|---|---|---|
Authorization | string | REQ | API Key del conector |
Respuesta exitosa
{
"message": "Autenticación exitosa",
"code": 200,
"data": {
"client_id": 42,
"client_name": "Mi Empresa S.R.L.",
"state": "active"
}
}
Devuelve todos los impuestos configurados en el sistema. Los IDs obtenidos se usan en el campo tax_ids al crear facturas. También puedes descargarlos desde tu portal: ver IDs de impuestos.
Respuesta exitosa
{
"code": 200,
"data": [
{ "id": 1, "name": "ITBIS 18%", "amount": 18.0, "type_tax_use": "sale" },
{ "id": 2, "name": "ITBIS 16%", "amount": 16.0, "type_tax_use": "sale" },
{ "id": 5, "name": "Exento (0%)", "amount": 0.0, "type_tax_use": "sale" }
]
}
Retorna todos los tipos de documentos fiscales disponibles en el sistema.
Respuesta exitosa
{
"code": 200,
"data": [
{ "id": 10, "name": "Factura de Crédito Fiscal Electrónica", "prefix": "E31" },
{ "id": 11, "name": "Factura de Consumo Electrónica", "prefix": "E32" }
]
}
Busca un tipo de documento específico por su prefijo (ej. E31, E34).
Parámetros de ruta
| Parámetro | Tipo | Descripción | |
|---|---|---|---|
prefix | string | REQ | Prefijo del tipo de NCF (ej. E31) |
GET /api/ecf/type/document/E31
Crea un nuevo cliente en el sistema. Devuelve el id para usarlo como partner_id en futuras facturas.
Body (JSON)
| Campo | Tipo | Descripción | |
|---|---|---|---|
name | string | REQ | Nombre o razón social del cliente |
type_client | string | REQ | Tipo de cliente (ver tipos) |
rnc | string | OPT* | RNC o cédula. Obligatorio para todos salvo non_payer |
Ejemplo de solicitud
{
"name": "Comercial Los Girasoles S.R.L.",
"type_client": "tax_payer",
"rnc": "101234567"
}
Respuesta exitosa
{
"code": 200,
"data": {
"id": 89,
"name": "Comercial Los Girasoles S.R.L.",
"type": "tax_payer",
"rnc": "101234567"
}
}
Endpoint principal. Crea la factura en el sistema, la firma digitalmente con el certificado P12 y responde de inmediato con el QR, la fecha de firma y el código de seguridad. El envío a la DGII se hace en segundo plano (en unos 2 minutos) o en el momento en que consultas /invoice/{id}/status. Para esperar la respuesta de la DGII en la misma llamada envía "wait_dgii": true.
ncf e invoice_date_due (vencimiento de la secuencia e-NCF autorizada por la DGII, no del pago). Para identificar al cliente usa partner_id (ID existente) o la combinación client_name + client_vat.ncf (o el mismo external_ref) recibes la misma factura con "message": "Documento existente", sin duplicarla. Útil para reintentar tras un timeout.Campos comunes
| Campo | Tipo | Descripción | |
|---|---|---|---|
ncf | string | REQ | Número de comprobante fiscal (ej. E310000000001) |
invoice_date_due | string | REQ | Vencimiento de la secuencia e-NCF (YYYY-MM-DD). No es la fecha límite de pago: para ventas a crédito usa payment_due_date |
partner_id | integer | OPT* | ID de cliente existente en el sistema |
client_name | string | OPT* | Nombre del cliente (alternativa a partner_id) |
client_vat | string | OPT | RNC/cédula al usar client_name |
invoice_date | string | OPT | Fecha de emisión (YYYY-MM-DD). Por defecto: hoy |
ref / external_ref | string | OPT | Referencia interna / número de orden. Si se repite, se devuelve la factura existente (no se duplica) |
description | string | OPT | Descripción general del comprobante |
items | array | OPT | Líneas de producto (ver tabla de ítems) |
payment_type | string | OPT | Tipo de pago: "1" contado, "2" crédito, "3" gratuito (ver tabla). Si no se envía: "1" (contado) |
payment_due_date | string | OPT* | Fecha límite de pago (YYYY-MM-DD). Obligatoria si payment_type es "2"; no puede ser anterior a invoice_date. Genera FechaLimitePago en el e-CF |
payment_term | string | OPT | Término de pago, máx. 15 caracteres (ej. "30 dias"). Requiere payment_type. Genera TerminoPago (no aplica a E34 ni E43) |
wait_dgii | boolean | OPT | true envía a la DGII dentro de la misma llamada y espera su respuesta. Por defecto: false (envío en segundo plano) |
Ítems de línea (items[])
| Campo | Tipo | Descripción | |
|---|---|---|---|
name | string | REQ | Descripción del producto o servicio |
quantity | float | REQ | Cantidad |
price_unit | float | REQ | Precio unitario (sin impuestos) |
product_id | integer | OPT | ID del producto en el sistema |
tax_ids | integer[] | OPT | IDs de impuestos a aplicar |
discount | float | OPT | Porcentaje de descuento (0–100) |
E33 — Nota de Débito
| Campo | Tipo | Descripción | |
|---|---|---|---|
ncf_modificate | string | REQ | NCF del documento que se modifica |
modification_code | string | REQ | Código de modificación (ver tabla) |
income_type | string | REQ | Tipo de ingreso (ver tabla) |
base_amount | float | REQ | Monto base a debitar |
tax_ids | integer[] | OPT | Impuestos sobre el monto base |
E34 — Nota de Crédito
| Campo | Tipo | Descripción | |
|---|---|---|---|
ncf_modificate | string | REQ | NCF de la factura original que se anula/modifica |
modification_code | string | REQ | Código de modificación |
base_amount | float | REQ | Monto base a acreditar |
tax_ids | integer[] | OPT | Impuestos a devolver |
E43 — Gastos Menores (compra)
| Campo | Tipo | Descripción | |
|---|---|---|---|
expense_type | string | OPT | Tipo de gasto. Por defecto: "01". Ver tabla |
E31 / E32 / E44 / E45 / E46 — Ventas
| Campo | Tipo | Descripción | |
|---|---|---|---|
income_type | string | OPT | Tipo de ingreso (ver tabla) |
Ejemplo — Factura de venta (E32)
POST /api/ecf/send
Authorization: ECF-5-abc123...
{
"ncf": "E320000000001",
"invoice_date_due": "2026-07-30",
"partner_id": 89,
"income_type": "01",
"items": [
{
"name": "Servicio de consultoría",
"quantity": 1,
"price_unit": 5000.00,
"tax_ids": [1],
"discount": 0
}
]
}
Ejemplo — Factura de crédito fiscal a crédito (E31)
Venta a 30 días: payment_type "2" + payment_due_date. El e-CF sale con TipoPago=2, FechaLimitePago y TerminoPago.
POST /api/ecf/send
Authorization: ECF-5-abc123...
{
"ncf": "E310000000001",
"invoice_date_due": "2028-12-31",
"invoice_date": "2026-09-27",
"partner_id": 89,
"income_type": "01",
"payment_type": "2",
"payment_due_date": "2026-10-27",
"payment_term": "30 dias",
"items": [
{
"name": "Servicio de consultoría",
"quantity": 1,
"price_unit": 5000.00,
"tax_ids": [1]
}
]
}
Ejemplo — Nota de crédito (E34)
POST /api/ecf/send
Authorization: ECF-5-abc123...
{
"ncf": "E340000000001",
"invoice_date_due": "2026-07-30",
"partner_id": 89,
"ncf_modificate": "E320000000001",
"modification_code": "1",
"base_amount": 5000.00,
"tax_ids": [1]
}
Respuesta exitosa
{
"message": "Documento creado correctamente",
"code": 200,
"data": {
"invoice_id": 145,
"invoice_name": "INV/2026/00145",
"partner_id": 89,
"partner_name": "Comercial Los Girasoles S.R.L.",
"ncf": "E310000000001",
"origin_ncf": null,
"ecf_status": "sent",
"ecf_status_detail": "init",
"status_url": "/api/ecf/invoice/145/status",
"fecha_firma": "27-09-2026 10:15:30",
"codigo_seguridad": "Wr3u19",
"qr_link": "https://ecf.dgii.gov.do/...",
"payment_type": "2",
"payment_due_date": "2026-10-27",
"payment_term": "30 dias",
"move_type": "out_invoice",
"amount_untaxed": 5000.00,
"amount_tax": 900.00,
"amount_total": 5900.00
}
}
payment_due_date solo viene en ventas a crédito (null en contado/gratuito). El QR se entrega antes de la aprobación de la DGII: consulta status_url hasta ver success antes de dar la factura por aceptada.
Consulta el estado actual de una factura. Si el comprobante todavía está en cola (ecf_status_detail = init), lo envía a la DGII en ese momento y devuelve el resultado. Devuelve los mismos campos que /send (QR, fecha de firma, tipo de pago, etc.).
Parámetros de ruta
| Parámetro | Tipo | Descripción |
|---|---|---|
id | integer | ID interno de la factura |
{
"code": 200,
"data": {
"invoice_id": 145,
"ncf": "E320000000001",
"ecf_status": "success",
"ecf_status_detail": "success",
"amount_total": 5900.00,
"message_dgii": "Aceptado"
}
}
Lista las facturas creadas por el conector con paginación y filtro opcional por estado.
Query params
| Parámetro | Tipo | Descripción | |
|---|---|---|---|
ecf_status | string | OPT | Filtrar: sent (incluye los que están en cola), success, conditional, failure |
limit | integer | OPT | Registros por página (20–100, por defecto: 20) |
GET /api/ecf/invoices?ecf_status=sent&limit=50
Fuerza una consulta en tiempo real a la DGII para actualizar el estado de la factura. Si todavía está en cola, primero la envía.
Descarga el XML sin firma del comprobante. La respuesta tiene Content-Type: application/xml.
GET /api/ecf/get/145/xml
# Response Content-Type: application/xml
# Body: <?xml version="1.0" ...><ECF>...</ECF>
E45 Gubernamental paso a paso
El E45 se emite cuando le vendes a una institución del Estado: ministerios, ayuntamientos, hospitales públicos, etc. Es una factura de venta con ítems, igual que un E31, pero el comprador siempre debe identificarse con su RNC.
client_name + client_vat (RNC), o créala antes con POST /new/client y "type_client": "governmental" y usa su partner_id.El flujo completo
- Lee tus IDs de impuestos y busca el ITBIS 18 % de venta. Nunca pongas el ID fijo en el código.
- Envía el E45 a
/sendcon unexternal_ref(tu número de orden). Si la llamada se corta, reenvíala igual: el API devuelve la misma factura y no la duplica. - Guarda
invoice_id,codigo_seguridadyqr_link: con eso ya puedes imprimir la factura. - Consulta
/invoice/{id}/statusesperando cada vez más (3 s, 6 s, 12 s… hasta 30 s) hasta recibirsuccess,conditionalofailure. - Descarga el XML con
/get/{id}/xmlpara tu archivo.
El cuerpo del E45
10 laptops y su instalación (con 10 % de descuento) para un ayuntamiento, a crédito a 30 días:
POST /api/ecf/send
Authorization: ECF-5-abc123...
{
"ncf": "E450000000001",
"invoice_date_due": "2027-12-31",
"invoice_date": "2026-11-19",
"client_name": "Ayuntamiento Municipal de Ejemplo",
"client_vat": "430000001",
"external_ref": "OC-2026-0457",
"income_type": "01",
"payment_type": "2",
"payment_due_date": "2026-12-19",
"payment_term": "30 dias",
"items": [
{ "name": "Laptop Core i7 16 GB", "quantity": 10, "price_unit": 48500.00, "tax_ids": [1] },
{ "name": "Instalación y configuración", "quantity": 10, "price_unit": 2500.00, "tax_ids": [1], "discount": 10 }
]
}
Respuesta (resumida). Base 485,000 + 22,500 = 507,500; ITBIS 18 % = 91,350; total 598,850:
{
"message": "Documento creado correctamente",
"code": 200,
"data": {
"invoice_id": 212,
"ncf": "E450000000001",
"ecf_status": "sent",
"ecf_status_detail": "init",
"status_url": "/api/ecf/invoice/212/status",
"codigo_seguridad": "Kp7Q2x",
"qr_link": "https://ecf.dgii.gov.do/...",
"move_type": "out_invoice",
"amount_untaxed": 507500.00,
"amount_tax": 91350.00,
"amount_total": 598850.00
}
}
Integración completa en tu lenguaje
Los cuatro ejemplos hacen el flujo entero: buscan el ITBIS, envían el E45, reintentan si se cae la red o el servidor responde 5xx, esperan la respuesta de la DGII y guardan el XML. Lee la URL y la API Key de las variables de entorno ECF_API_URL y ECF_API_KEY.
# bash + jq · --retry reintenta caídas de red y 5xx; --fail corta el script en 4xx (quítalo para ver el mensaje del API)
set -euo pipefail
export ECF_API_URL="https://tu-servidor" ECF_API_KEY="ECF-5-..."
api() { curl -sS --fail --retry 4 --retry-connrefused --max-time 30 \
-H "Authorization: $ECF_API_KEY" -H "Content-Type: application/json" "$@"; }
# 1) ID del ITBIS 18 % de venta
ITBIS=$(api "$ECF_API_URL/api/ecf/taxes" \
| jq -e '[.data[] | select(.type_tax_use == "sale" and .amount == 18)][0].id')
# 2) El cuerpo va a un archivo: curl solo puede reintentar un POST si puede releerlo
jq -n --argjson t "$ITBIS" '{
ncf: "E450000000001", invoice_date_due: "2027-12-31", invoice_date: "2026-11-19",
client_name: "Ayuntamiento Municipal de Ejemplo", client_vat: "430000001",
external_ref: "OC-2026-0457", income_type: "01",
payment_type: "2", payment_due_date: "2026-12-19", payment_term: "30 dias",
items: [
{name: "Laptop Core i7 16 GB", quantity: 10, price_unit: 48500, tax_ids: [$t]},
{name: "Instalación y configuración", quantity: 10, price_unit: 2500, tax_ids: [$t], discount: 10}
]}' > e45.json
ID=$(api -X POST "$ECF_API_URL/api/ecf/send" -d @e45.json | jq -e '.data.invoice_id')
# 3) Esperar a la DGII
for espera in 3 6 12 24 30 30 30 30; do
ESTADO=$(api "$ECF_API_URL/api/ecf/invoice/$ID/status" | jq -r '.data.ecf_status')
case "$ESTADO" in success|conditional|failure) break;; esac
sleep "$espera"
done
echo "E45 $ID: $ESTADO"
# 4) Guardar el XML
api "$ECF_API_URL/api/ecf/get/$ID/xml" -o E450000000001.xml
# Python 3.9+ · pip install requests
import os
import time
import requests
API = os.environ["ECF_API_URL"].rstrip("/") + "/api/ecf"
FINAL = {"success", "conditional", "failure"}
http = requests.Session()
http.headers.update({"Authorization": os.environ["ECF_API_KEY"]})
def call(method, path, **kwargs):
"""Llama al API y devuelve "data". Reintenta caídas de red y errores 5xx.
Reintentar /send es seguro: con el mismo ncf o external_ref el API
devuelve la factura ya creada en vez de duplicarla.
"""
for intento in range(4):
try:
r = http.request(method, API + path, timeout=30, **kwargs)
except (requests.ConnectionError, requests.Timeout):
time.sleep(2 ** intento)
continue
if r.status_code >= 500:
time.sleep(2 ** intento)
continue
body = r.json()
if r.status_code != 200:
raise RuntimeError(f"[{r.status_code}] {body.get('message')}")
return body["data"]
raise RuntimeError(f"El API no respondió: {method} {path}")
def tax_id(percent, use="sale"):
for tax in call("GET", "/taxes"):
if tax["type_tax_use"] == use and float(tax["amount"]) == percent:
return tax["id"]
raise LookupError(f"No hay impuesto {percent}% de {use}: revisa tus IDs en el portal")
def esperar_dgii(invoice_id, max_segundos=300):
limite, espera = time.monotonic() + max_segundos, 3
while True:
data = call("GET", f"/invoice/{invoice_id}/status")
if data["ecf_status"] in FINAL:
return data
if time.monotonic() > limite:
raise TimeoutError(f"La DGII no respondió para la factura {invoice_id}")
time.sleep(espera)
espera = min(espera * 2, 30)
itbis = tax_id(18.0)
e45 = call("POST", "/send", json={
"ncf": "E450000000001",
"invoice_date_due": "2027-12-31",
"invoice_date": "2026-11-19",
"client_name": "Ayuntamiento Municipal de Ejemplo",
"client_vat": "430000001",
"external_ref": "OC-2026-0457",
"income_type": "01",
"payment_type": "2",
"payment_due_date": "2026-12-19",
"payment_term": "30 dias",
"items": [
{"name": "Laptop Core i7 16 GB", "quantity": 10, "price_unit": 48500.00, "tax_ids": [itbis]},
{"name": "Instalación y configuración", "quantity": 10, "price_unit": 2500.00,
"tax_ids": [itbis], "discount": 10},
],
})
print(f"{e45['ncf']} firmado · código {e45['codigo_seguridad']} · total {e45['amount_total']:,.2f}")
final = esperar_dgii(e45["invoice_id"])
if final["ecf_status"] == "failure":
raise SystemExit(f"Rechazado por la DGII: {final.get('message_dgii')}")
xml = http.get(f"{API}/get/{e45['invoice_id']}/xml", timeout=30)
xml.raise_for_status()
with open(f"{e45['ncf']}.xml", "wb") as f:
f.write(xml.content)
print("DGII:", final["ecf_status"])
// Node.js 18+ (fetch nativo) · guárdalo como e45.mjs y ejecuta: node e45.mjs
import { writeFile } from "node:fs/promises";
const API = process.env.ECF_API_URL.replace(/\/$/, "") + "/api/ecf";
const HEADERS = { Authorization: process.env.ECF_API_KEY, "Content-Type": "application/json" };
const FINAL = new Set(["success", "conditional", "failure"]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// Reintenta caídas de red y 5xx. Reintentar /send es seguro: mismo ncf/external_ref = misma factura.
async function call(method, path, body) {
for (let intento = 0; intento < 4; intento++) {
let res;
try {
res = await fetch(API + path, {
method,
headers: HEADERS,
body: body ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(30_000),
});
} catch {
await sleep(2 ** intento * 1000);
continue;
}
if (res.status >= 500) {
await sleep(2 ** intento * 1000);
continue;
}
const json = await res.json();
if (!res.ok) throw new Error(`[${res.status}] ${json.message}`);
return json.data;
}
throw new Error(`El API no respondió: ${method} ${path}`);
}
async function taxId(percent, use = "sale") {
const taxes = await call("GET", "/taxes");
const tax = taxes.find((t) => t.type_tax_use === use && Number(t.amount) === percent);
if (!tax) throw new Error(`No hay impuesto ${percent}% de ${use}: revisa tus IDs en el portal`);
return tax.id;
}
async function esperarDgii(id, maxMs = 300_000) {
const limite = Date.now() + maxMs;
for (let espera = 3_000; ; espera = Math.min(espera * 2, 30_000)) {
const data = await call("GET", `/invoice/${id}/status`);
if (FINAL.has(data.ecf_status)) return data;
if (Date.now() > limite) throw new Error(`La DGII no respondió para la factura ${id}`);
await sleep(espera);
}
}
const itbis = await taxId(18);
const e45 = await call("POST", "/send", {
ncf: "E450000000001",
invoice_date_due: "2027-12-31",
invoice_date: "2026-11-19",
client_name: "Ayuntamiento Municipal de Ejemplo",
client_vat: "430000001",
external_ref: "OC-2026-0457",
income_type: "01",
payment_type: "2",
payment_due_date: "2026-12-19",
payment_term: "30 dias",
items: [
{ name: "Laptop Core i7 16 GB", quantity: 10, price_unit: 48500, tax_ids: [itbis] },
{ name: "Instalación y configuración", quantity: 10, price_unit: 2500, tax_ids: [itbis], discount: 10 },
],
});
console.log(`${e45.ncf} firmado · código ${e45.codigo_seguridad} · total ${e45.amount_total}`);
const final = await esperarDgii(e45.invoice_id);
if (final.ecf_status === "failure") throw new Error(`Rechazado por la DGII: ${final.message_dgii}`);
const xml = await fetch(`${API}/get/${e45.invoice_id}/xml`, { headers: HEADERS });
if (!xml.ok) throw new Error(`XML no disponible [${xml.status}]`);
await writeFile(`${e45.ncf}.xml`, Buffer.from(await xml.arrayBuffer()));
console.log("DGII:", final.ecf_status);
// .NET 8 · dotnet new console -n E45 && reemplaza Program.cs con esto
using System.Net.Http.Json;
using System.Text.Json.Nodes;
var api = Environment.GetEnvironmentVariable("ECF_API_URL")!.TrimEnd('/') + "/api/ecf/";
using var http = new HttpClient { BaseAddress = new Uri(api), Timeout = TimeSpan.FromSeconds(30) };
// La API Key va tal cual (sin "Bearer"), por eso no se usa AuthenticationHeaderValue.
http.DefaultRequestHeaders.TryAddWithoutValidation("Authorization", Environment.GetEnvironmentVariable("ECF_API_KEY"));
var itbis = (await Call(HttpMethod.Get, "taxes")).AsArray()
.First(t => (string)t!["type_tax_use"]! == "sale" && (double)t["amount"]! == 18.0)!["id"]!
.GetValue<int>();
var e45 = await Call(HttpMethod.Post, "send", new
{
ncf = "E450000000001",
invoice_date_due = "2027-12-31",
invoice_date = "2026-11-19",
client_name = "Ayuntamiento Municipal de Ejemplo",
client_vat = "430000001",
external_ref = "OC-2026-0457",
income_type = "01",
payment_type = "2",
payment_due_date = "2026-12-19",
payment_term = "30 dias",
items = new object[]
{
new { name = "Laptop Core i7 16 GB", quantity = 10, price_unit = 48500.00, tax_ids = new[] { itbis } },
new { name = "Instalación y configuración", quantity = 10, price_unit = 2500.00, tax_ids = new[] { itbis }, discount = 10 },
},
});
var id = e45["invoice_id"]!.GetValue<int>();
var ncf = (string)e45["ncf"]!;
var codigo = (string?)e45["codigo_seguridad"];
var total = (decimal)e45["amount_total"]!;
Console.WriteLine($"{ncf} firmado · código {codigo} · total {total:N2}");
var final = await EsperarDgii(id, TimeSpan.FromMinutes(5));
var estado = (string)final["ecf_status"]!;
if (estado == "failure")
{
var motivo = (string?)final["message_dgii"];
throw new Exception($"Rechazado por la DGII: {motivo}");
}
await File.WriteAllBytesAsync($"{ncf}.xml", await http.GetByteArrayAsync($"get/{id}/xml"));
Console.WriteLine($"DGII: {estado}");
// Reintenta caídas de red y 5xx. Reintentar "send" es seguro: mismo ncf/external_ref = misma factura.
async Task<JsonNode> Call(HttpMethod method, string path, object? body = null)
{
for (var intento = 0; intento < 4; intento++)
{
HttpResponseMessage res;
try
{
using var req = new HttpRequestMessage(method, path);
if (body is not null) req.Content = JsonContent.Create(body);
res = await http.SendAsync(req);
}
catch (Exception e) when (e is HttpRequestException or TaskCanceledException)
{
await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, intento)));
continue;
}
if ((int)res.StatusCode >= 500)
{
await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, intento)));
continue;
}
var json = JsonNode.Parse(await res.Content.ReadAsStringAsync())!;
if (!res.IsSuccessStatusCode)
{
var mensaje = (string?)json["message"];
throw new InvalidOperationException($"[{(int)res.StatusCode}] {mensaje}");
}
return json["data"]!;
}
throw new TimeoutException($"El API no respondió: {method} {path}");
}
async Task<JsonNode> EsperarDgii(int invoiceId, TimeSpan max)
{
var limite = DateTime.UtcNow + max;
for (var espera = 3.0; ; espera = Math.Min(espera * 2, 30))
{
var data = await Call(HttpMethod.Get, $"invoice/{invoiceId}/status");
if ((string)data["ecf_status"]! is "success" or "conditional" or "failure") return data;
if (DateTime.UtcNow > limite) throw new TimeoutException($"La DGII no respondió para la factura {invoiceId}");
await Task.Delay(TimeSpan.FromSeconds(espera));
}
}
ncf que no empieza por E45, o un tax_ids con un ID que no es de tu servidor. Si la DGII lo rechaza (failure), el motivo viene en message_dgii.Tipos de pago
Campo payment_type en /send. Corresponde al elemento TipoPago del e-CF (XSD de la DGII).
| Código | Descripción | Requiere |
|---|---|---|
"1" | Contado (valor por defecto si no se envía) | — |
"2" | Crédito | payment_due_date (genera FechaLimitePago) |
"3" | Gratuito | — |
Códigos de modificación
Usados en E33 (Notas de Débito) y E34 (Notas de Crédito) en el campo modification_code.
| Código | Descripción |
|---|---|
"1" | Anulación de la factura referenciada |
"2" | Corrección de la información de la factura |
"3" | Descuento posterior |
"4" | Devolución de bienes o rescisión de servicios |
"5" | Error en la tasa del ITBIS |
Tipos de ingreso
Campo income_type en comprobantes E31, E32, E33, E45, E46, E47.
| Código | Descripción |
|---|---|
"01" | Ingresos por operaciones (actividad principal) |
"02" | Ingresos financieros |
"03" | Ingresos extraordinarios |
"04" | Ingresos por arrendamientos |
"05" | Ingresos por venta de activos depreciables |
"06" | Otros ingresos |
Tipos de gasto
Campo expense_type en comprobantes E43 (Gastos Menores).
| Código | Descripción |
|---|---|
"01" | Gastos de personal |
"02" | Gastos por trabajo, suministros y servicios |
"03" | Arrendamientos |
"04" | Gastos de activos fijos |
"05" | Representación y otros gastos deducibles |
"06" | Otras deducciones permitidas |
"07" | Gastos computados a tasas especiales |
"08" | Gastos no deducibles |
"09" | Costo de ventas |
"10" | Adquisiciones de activos |
"11" | Gastos de seguro |
Tipos de cliente
Campo type_client en el endpoint POST /new/client.
| Valor | Descripción | RNC requerido |
|---|---|---|
tax_payer | Contribuyente registrado (persona jurídica o natural) | Sí |
non_payer | Consumidor final (sin RNC) | No |
nonprofit | Organización sin fines de lucro | Sí |
special | Régimen tributario especial | Sí |
governmental | Institución gubernamental | Sí |
foreigner | Persona o empresa extranjera | Sí |
Facturación del conector
El conector incluye un sistema de facturación mensual automático para cobrar a los clientes que usan el servicio.
Ciclo de facturación
Un cron job se ejecuta diariamente a las 15:59 UTC. Al llegar al último día del mes, cierra el ciclo activo y genera automáticamente facturas de uso a cada conector activo.
| Campo del modelo | Descripción |
|---|---|
price_by_ncf | Precio a cobrar por cada comprobante emitido |
ncf_count | Cantidad de comprobantes emitidos en el mes actual |
amount_to_paid | Total a cobrar = price_by_ncf × ncf_count |
billing_date | Fecha de inicio del ciclo de facturación |
Estados del conector
| Estado | Descripción | Puede crear facturas |
|---|---|---|
active | Conector operativo | Sí |
inactive | Desactivado manualmente | No |
pending_paid | Pendiente de pago del ciclo anterior | No |
active una vez que se registra el pago correspondiente y se reinicia el ciclo de facturación.¿Listo para integrarte?
Solicita tu API Key y conecta tu sistema con la facturación electrónica dominicana en minutos.
Solicitar tu API Key