Skip to content
↑↓ navigate ↵ open Esc close
Quickstart

From zero to first signed e-CF in five minutes

Four verifiable steps. If your team has the X-Api-Key and a customer loaded in the workspace, you will reach the dgii.aprobado webhook faster than it takes to read this page.

Before you begin

  • An active X-Api-Key with a future expiry, issued in a workspace on the Corporativo plan.
  • Your workspace subdomain: if you open the app at tuempresa.factura.com.do, your base URL is https://tuempresa.factura.com.do/api/v1.
  • A BranchId from your workspace (found in Settings → Branches).
  • A CurrencyId and UnitId from the catalog (the API exposes catalog endpoints).
  • A public endpoint that accepts POST and returns 200 (a Cloudflare Worker or minimal Lambda will do).

Four verifiable steps

  1. 01

    Load X-Api-Key into your environment

    Store it as a secret variable (FACTURA_API_KEY). Do not embed it in the client or commit it to the repo.

  2. 02

    POST /api/v1/consumer-invoices

    Send the V1CreateInvoiceDto body: branchId, issuedAt, paymentTermId, limitDate, currencyId, currencyRate and lines. Optional fields are customerId (for E32), sequence (if omitted, the next NCF from the active sequence is used), externalReference, freight, notes and payments. If you omit payments, the invoice is settled with the default payment method.

  3. 03

    Read DocumentId and ConsultationUrl

    DocumentId is the internal ID; save it. ConsultationUrl is the DGII URL the recipient opens to verify the document.

  4. 04

    Subscribe to dgii.aprobado

    Configure a webhook with your receiver endpoint. When the DGII responds, you receive a POST with Event, Timestamp and data.

Create the consumer invoice

Call the POST /api/v1/consumer-invoices endpoint with the X-Api-Key header and the minimal body. The example line invoices RD$ 4,500 of professional services with 18% ITBIS for a total of RD$ 5,310 collected in a single payment reference.

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())

Response

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

Read the immediate response

When the POST is accepted, the API responds 200 OK with two fields: documentId and consultationUrl. The final document status with the DGII arrives later via webhook.

Next steps

Next step

Continue here