Saltar al contenido
↑↓ navegar ↵ abrir Esc cerrar
Quickstart

De cero a primer e-CF firmado en cinco minutos

Cuatro pasos verificables. Si tu equipo tiene la X-Api-Key y un cliente cargado en el espacio de trabajo, llegas al webhook dgii.aprobado en menos tiempo del que toma este readme.

Antes de empezar

  • Una X-Api-Key activa con vigencia futura, emitida en un espacio de trabajo con plan Corporativo.
  • El subdominio de tu espacio de trabajo: si entras a la app por tuempresa.factura.com.do, tu URL base es https://tuempresa.factura.com.do/api/v1.
  • Un BranchId del espacio de trabajo (lo encuentras en Configuración → Sucursales).
  • Un CurrencyId y UnitId del catálogo (la API expone endpoints de catálogo).
  • Un endpoint público que acepte POST y responda 200 (puede ser un Cloudflare Worker o un Lambda mínimo).

Cuatro pasos verificables

  1. 01

    Carga la X-Api-Key en tu entorno

    Guárdala como variable secreta (FACTURA_API_KEY). No la pegues en el cliente ni la commits al repo.

  2. 02

    POST /api/v1/consumer-invoices

    Envía el cuerpo de V1CreateInvoiceDto: branchId, issuedAt, paymentTermId, limitDate, currencyId, currencyRate y lines. Son opcionales customerId (en E32), sequence (si lo omites, se usa el siguiente NCF de la secuencia activa), externalReference, freight, notes y payments. Si omites payments, la factura queda saldada con la forma de pago por defecto.

  3. 03

    Lee DocumentId y ConsultationUrl

    DocumentId es el id interno; guárdalo. ConsultationUrl es la URL DGII que el receptor abre para verificar el comprobante.

  4. 04

    Suscribe dgii.aprobado

    Configura un webhook con tu endpoint receptor. Cuando la DGII responde, te llega un POST con Event, Timestamp y data.

Crear la factura de consumo

Llama al endpoint POST /api/v1/consumer-invoices con la cabecera X-Api-Key y el cuerpo mínimo. La línea de ejemplo factura RD$ 4 500 de servicios profesionales con ITBIS al 18% y total RD$ 5 310 cobrados en una sola referencia.

POST /api/v1/consumer-invoices

create-invoice.sh
curl -X POST https://tuempresa.factura.com.do/api/v1/consumer-invoices \
  -H "X-Api-Key: $FACTURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab",
    "sequence": "E320000000001",
    "issuedAt": "2026-05-08T10:00:00Z",
    "paymentTermId": 1,
    "limitDate": "2026-05-08T10:00:00Z",
    "currencyId": 1,
    "currencyRate": 1,
    "lines": [
      {
        "code": "SRV-001",
        "order": 1,
        "description": "Consultoría",
        "isService": true,
        "quantity": 1,
        "unitId": 1,
        "unitPrice": 4500.00,
        "isExempt": false,
        "taxes": [{ "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1 }]
      }
    ],
    "payments": [
      { "reference": "REF-1", "amount": 5310.00 }
    ]
  }'
create-invoice.ts
// 02-create-consumer-invoice.ts
const res = await fetch(
  "https://tuempresa.factura.com.do/api/v1/consumer-invoices",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.FACTURA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      branchId: "b1a2c3d4-e5f6-4789-abcd-1234567890ab",
      sequence: "E320000000001",
      issuedAt: new Date().toISOString(),
      paymentTermId: 1,
      limitDate: new Date().toISOString(),
      currencyId: 1,
      currencyRate: 1,
      lines: [
        {
          code: "SRV-001",
          order: 1,
          description: "Consultoría",
          isService: true,
          quantity: 1,
          unitId: 1,
          unitPrice: 4500,
          isExempt: false,
          taxes: [{ taxId: "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", rate: 18.0, taxTypeId: 1 }],
        },
      ],
      payments: [{ reference: "REF-1", amount: 5310 }],
    }),
  },
);


if (!res.ok) throw new Error(`factura.com.do: ${res.status}`);
const { documentId, consultationUrl } = await res.json();
console.log({ documentId, consultationUrl });
create_invoice.py
# 02_create_consumer_invoice.py
import os
import httpx


payload = {
    "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab",
    "sequence": "E320000000001",
    "issuedAt": "2026-05-08T10:00:00Z",
    "paymentTermId": 1,
    "limitDate": "2026-05-08T10:00:00Z",
    "currencyId": 1,
    "currencyRate": 1,
    "lines": [{
        "code": "SRV-001",
        "order": 1,
        "description": "Consultoría",
        "isService": True,
        "quantity": 1,
        "unitId": 1,
        "unitPrice": 4500.00,
        "isExempt": False,
        "taxes": [{"taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1}],
    }],
    "payments": [{"reference": "REF-1", "amount": 5310.00}],
}


with httpx.Client(headers={"X-Api-Key": os.environ["FACTURA_API_KEY"]}) as c:
    r = c.post("https://tuempresa.factura.com.do/api/v1/consumer-invoices", json=payload)
    r.raise_for_status()
    print(r.json())

Respuesta

response.json
{
  "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "consultationUrl": "https://fc.dgii.gov.do/ecf/consultatimbrefc?encf=E320000000001&montototal=5310.00&rncemisor=131000001&codigoseguridad=…"
}

Leer la respuesta inmediata

Cuando el POST se acepta, la API responde 200 OK con dos campos: documentId y consultationUrl. El estado final del comprobante en la DGII llega después por webhook.

Siguientes pasos

Siguiente paso

Continúa por aquí