Primeros pasos

Primeros pasos

Esta guía te lleva de cero a tu primera emisión aceptada por DGII en ~5 minutos, asumiendo que ya cumples los pre-requisitos.

Pre-requisitos

Antes de usar la API necesitas:

  1. Ser Emisor Electrónico certificado por DGII. Si todavía no lo eres, el portal fe-portal.appworkcloud.com (opens in a new tab) tiene una guía paso a paso gratuita que te acompaña hasta la aprobación. El proceso suele tomar pocas semanas dependiendo de DGII.
  2. Tu certificado digital .p12 subido al portal. El certificado NO lo emite DGII: lo solicita el representante legal de la empresa (o un usuario a nombre de uno de sus representantes legales) ante una de las entidades de certificación autorizadas por INDOTEL — por ejemplo la Cámara de Comercio (Digifirma).
  3. Una cuenta activa en el portal (fe-portal.appworkcloud.com (opens in a new tab)) con permisos de administrador.
  4. Tu RNC y datos fiscales configurados en el portal.
  5. Tus secuencias NCF asignadas y vigentes para los prefijos que vayas a emitir (E31, E32, E33, E34, etc.).
⚠️

Sin la certificación de Emisor Electrónico, DGII rechaza cualquier e-CF a nombre de tu RNC — sin importar que el proveedor técnico (nosotros) esté correctamente certificado. Es un requisito legal del lado del contribuyente.

Crea tu cuenta y activa el API en el portal

Todo el proceso se hace desde el portal de Facturación Electrónica, sin necesidad de usar Digimart:

  1. Entra a fe-portal.appworkcloud.com (opens in a new tab) y crea tu cuenta.
  2. Configura tu empresa (o empresas): RNC, datos fiscales y certificado digital .p12.
  3. Certifica cada empresa como Emisor Electrónico ante DGII siguiendo la guía del portal.
  4. Activa el API de Facturación Electrónica desde el mismo portal, lee el acuerdo de cobros automáticos y márcalo.
  5. Opcional: agrega un correo de contacto técnico para notificaciones operativas.

A partir de ese momento tu cuenta queda lista para generar API keys y emitir.

Genera tu primera API key

En el mismo panel:

  1. Click en "Nueva API key".
  2. Asigna un nombre descriptivo (ej. "Servidor de producción").
  3. Elige el ambiente:
    • Producción (ecf) → emite e-CFs reales facturables.
    • Certificación (certecf) → pruebas oficiales DGII, gratis.
    • Pruebas (testecf) → desarrollo libre, gratis.
  4. Click en "Crear".
🔐

El apiSecret se muestra UNA sola vez. Guárdalo inmediatamente en un gestor de contraseñas o variable de entorno. Si lo pierdes, deberás revocar la key y crear una nueva.

Intercambia tus credenciales por un JWT

curl -X POST https://digimart-api-v2.appworkcloud.com/api/v1/fe/login \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyId": "fak_a1b2c3d4e5f6",
    "apiSecret": "tu_secret_aqui"
  }'

Respuesta:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "environment": "ecf",
  "scopes": ["invoices:write", "invoices:read", "usage:read", "billing:read"]
}

El JWT dura 1 hora. Vuelve a hacer POST /login cuando expire.

Emite tu primer e-CF

curl -X POST https://digimart-api-v2.appworkcloud.com/api/v1/fe/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "format": "digimart",
    "clientRequestId": "factura-001-2026-06-15",
    "payload": {
      "Encabezado": {
        "Version": "1.0",
        "IdDoc": {
          "eNCF": "E310000000001",
          "IndicadorMontoGravado": "0",
          "TipoIngresos": "01",
          "TipoPago": "1"
        },
        "Comprador": {
          "RNCComprador": "101672919",
          "RazonSocialComprador": "Cliente B2B SRL"
        }
      },
      "DetallesItems": {
        "Item": [{
          "NumeroLinea": 1,
          "IndicadorFacturacion": "1",
          "NombreItem": "Servicio profesional",
          "CantidadItem": 1,
          "PrecioUnitarioItem": 10000,
          "MontoItem": 10000
        }]
      }
    }
  }'
💡

¿Notaste lo que NO está en el payload? No mandamos TipoeCF, FechaVencimientoSecuencia, Emisor ni Totales — los rellenamos por ti del tenant y los items. Si prefieres mandar el shape completo tal cual lo espera DGII (control total), también funciona — solo agrega esos 4 campos y los respetamos. Más detalles en POST /invoices →.

Respuesta inmediata (202):

{
  "dgiiLogId": "a3f...",
  "status": "queued",
  "environment": "ecf",
  "billable": true,
  "message": "Invoice queued for processing"
}

El clientRequestId es opcional pero recomendado — si reintentas la misma request con el mismo id, devolvemos el envío existente en vez de duplicar.

Consulta el estado

DGII responde típicamente en 1-3 segundos. Consulta el estado:

curl https://digimart-api-v2.appworkcloud.com/api/v1/fe/invoices/a3f... \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Respuesta cuando DGII ya respondió:

{
  "dgiiLogId": "a3f...",
  "trackId": "DGII-2026-06-15-...",
  "environment": "ecf",
  "status": "Aceptado",
  "qrCodeUrl": "https://ecf.dgii.gov.do/...",
  "securityCode": "abc123",
  "ncfExpiration": "31-12-2026",
  "fechaHoraFirma": "2026-06-15T14:23:11Z",
  "submittedAt": "2026-06-15T14:23:10Z",
  "updatedAt": "2026-06-15T14:23:13Z"
}

status: "Aceptado" significa que DGII aceptó tu e-CF. Eres oficialmente emisor. 🎉

¿Qué sigue?

IntroducciónAutenticación