Saltar al contenido principal

Inicio Rápido

Tu primer e-CF en 10 minutos​

Esta guía te lleva desde cero hasta emitir un comprobante en el ambiente de pruebas de la DGII (testecf), consultar su estado y descargar el XML firmado.

Prerrequisitos​

  • Cuenta en Facturo ECF con tu empresa registrada
  • API Key con permisos de emisión y consulta (por ejemplo documents.emit, documents.view)
  • UUID de la empresa (company_id) en Facturo
  • Certificado digital cargado para la empresa
  • curl o uno de los clientes oficiales
¿No tienes esto listo?

Sigue la configuración de cuenta y la guía de credenciales API.

Paso 1: Configura tus credenciales​

export FACTURO_BASE_URL="https://ecf.facturord.app"
export FACTURO_API_KEY="tu_api_key"
export FACTURO_COMPANY_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Todas las peticiones llevan el header X-API-Key. No hay que obtener tokens previamente. Más detalles en Autenticación y Ambientes.

Paso 2: Emite el comprobante​

Envía el e-CF dentro del campo ecf, indicando el ambiente con dgii_env:

curl -X POST \
  "$FACTURO_BASE_URL/api/v1/companies/$FACTURO_COMPANY_ID/emission/ecf" \
  -H "X-API-Key: $FACTURO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d @factura.json

Donde factura.json contiene:

{
  "dgii_env": "testecf",
  "ecf": {
    "Encabezado": {
      "Version": "1.0",
      "IdDoc": {
        "TipoeCF": 31,
        "eNCF": "E310000000001",
        "FechaVencimientoSecuencia": "31-12-2026",
        "TipoIngresos": "01",
        "TipoPago": 1
      },
      "Emisor": {
        "RNCEmisor": "131234567",
        "RazonSocialEmisor": "MI EMPRESA SRL",
        "DireccionEmisor": "Calle Principal #123, Santo Domingo",
        "FechaEmision": "17-01-2026"
      },
      "Comprador": {
        "RNCComprador": "101234567",
        "RazonSocialComprador": "CLIENTE EJEMPLO SA"
      },
      "Totales": {
        "MontoGravadoTotal": 1000.00,
        "MontoGravadoI1": 1000.00,
        "ITBIS1": 18,
        "TotalITBIS": 180.00,
        "TotalITBIS1": 180.00,
        "MontoTotal": 1180.00
      }
    },
    "DetallesItems": {
      "Item": [
        {
          "NumeroLinea": 1,
          "IndicadorFacturacion": 1,
          "NombreItem": "Laptop Dell Latitude 5420",
          "IndicadorBienoServicio": 1,
          "CantidadItem": 1,
          "PrecioUnitarioItem": 1000.00,
          "MontoItem": 1000.00
        }
      ]
    }
  }
}

El objeto ecf usa los nombres de elemento del XML e-CF de la DGII (PascalCase) y las fechas van en formato DD-MM-AAAA. La estructura completa está en Estructura del e-CF.

Respuesta:

{
  "document_id": "9f1c2d3e-4b5a-6789-0abc-def123456789",
  "encf": "E310000000001",
  "track_id": "b7a1c3e5-...",
  "internal_status": "...",
  "dgii_status": "...",
  "message": null,
  "qr_url": "https://...",
  "security_code": "A1B2C3",
  "emission_exact": "..."
}

Guarda document_id, encf y track_id.

Paso 3: Consulta el estado en la DGII​

curl -X GET \
  "$FACTURO_BASE_URL/api/v1/companies/$FACTURO_COMPANY_ID/emission/invoices/$TRACK_ID/status" \
  -H "X-API-Key: $FACTURO_API_KEY"
{
  "track_id": "b7a1c3e5-...",
  "invoice_number": "E310000000001",
  "dgii_status": "...",
  "internal_status": "...",
  "last_status": "...",
  "last_updated_at": "..."
}

La DGII procesa los documentos de forma asíncrona: si el estado aún no es definitivo, vuelve a consultar con un intervalo creciente.

Paso 4: Descarga el XML firmado​

Por document_id o directamente por e-NCF:

curl -X GET \
  "$FACTURO_BASE_URL/api/v1/companies/$FACTURO_COMPANY_ID/emission/documents/E310000000001/signed-xml?download=true&dgii_env=testecf" \
  -H "X-API-Key: $FACTURO_API_KEY" \
  -o E310000000001.xml
¡Listo!

Has emitido tu primer e-CF con Facturo ECF. Cuando tu integración esté validada, cambia dgii_env a certecf (certificación) y luego a ecf (producción).

Con los clientes oficiales​

Los clientes oficiales encapsulan autenticación, rutas y manejo de errores. La URL base por defecto es https://ecf.facturord.app/.

import os
from ecf_client import FacturoClient, FacturoAPIError

client = FacturoClient(
    api_key=os.environ["FACTURO_API_KEY"],
    company_id=os.environ["FACTURO_COMPANY_ID"],
)

try:
    res = client.emit_rich_ecf({"dgii_env": "testecf", "ecf": ecf_payload})
    print(res.encf, res.track_id)

    status = client.get_tracking_status(res.track_id)
    print(status.dgii_status)

    xml_bytes = client.get_signed_xml(res.encf, dgii_env="testecf")
    with open(f"{res.encf}.xml", "wb") as f:
        f.write(xml_bytes)
except FacturoAPIError as e:
    print(f"Error ({e.status_code}): {e}")

Solución de problemas comunes​

Error 401 / 403​

  • Verifica que el header sea exactamente X-API-Key.
  • Confirma que la API Key tenga los permisos necesarios para la operación.
  • Comprueba que el company_id de la ruta corresponda a la empresa de la API Key.

"company_id is required"​

Los clientes oficiales necesitan el UUID de la empresa, ya sea al crear el cliente o en cada llamada.

e-NCF inválido​

El e-NCF debe tener 13 caracteres exactos: serie (1), tipo (2) y secuencia (10). Ejemplo: E310000000001.

Secuencia ya usada o rechazada​

No reutilices e-NCF. Si una secuencia nunca fue aceptada por la DGII, anúlala con ANECF; si ya fue aceptada, emite una Nota de Crédito (E34).

Próximos pasos​