Invoices

Tres endpoints alrededor del recurso invoice:

Todos requieren Authorization: Bearer <JWT>.

Tipos de e-CF soportados

POST /invoices acepta cualquiera de los siguientes tipos vía el campo TipoeCF del header (Encabezado.IdDoc.TipoeCF en JSON Digimart):

Otros documentos también soportados

POST /invoices también acepta Resumen de Facturas de Consumo (RFCE) y Aprobaciones Comerciales (ACECF / ANECF). El endpoint del cliente es el mismo — el worker auto-detecta el root element del XML/JSON y rutea al endpoint DGII correcto bajo el capó:

POST /invoices

Envía un comprobante para procesamiento async. Responde 202 con un identificador que puedes usar para consultar estado.

POST /api/v1/fe/invoices
Authorization: Bearer <JWT>
Content-Type: application/json

Scope requerido: invoices:write

Request body

Certificado y usuarios

Antes de emitir en producción necesitas un certificado digital (.p12) cargado. Tienes dos formas de subirlo desde el portal:

• A nivel de empresa (recomendado) — en Configuración → Certificado digital subes un solo .p12 + su clave. Se usa para todas tus emisiones. Ideal si tienes una sola identidad fiscal.
• A nivel de usuario — en Usuarios creas actores (p. ej. por sucursal o RNC) y le subes a cada uno su propio .p12. Eliges cuál usar con asUser/asUserId en la solicitud.

¿Cómo elige el worker qué certificado usar?

1. Si mandas asUser/asUserId → usa el certificado de ese usuario (y su emisorOverride, si tiene). Recomendado cuando manejas varios certificados.
2. Si NO mandas asUser y tienes un certificado de empresa → lo usa.
3. Si NO mandas asUser, no hay cert de empresa, y hay un solo usuario con certificado → lo selecciona automáticamente.
4. Si NO mandas asUser y hay varios usuarios con certificado (y sin cert de empresa) → la emisión falla pidiéndote indicar cuál vía asUser.

format: "xml"

Le pasas el XML del e-CF tal cual lo construiste. Lo firmamos y enviamos.

{
  "format": "xml",
  "clientRequestId": "factura-001-2026-06-15",
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ECF xmlns:xsi=\"...\">...</ECF>"
}

format: "digimart"

JSON estructurado que sigue el esquema DGII. Tienes dos modos de uso del mismo formato:

Modo A — auto-fill (recomendado)

Omites 4 campos y nosotros los rellenamos por ti:

Modo B — payload completo (tal cual DGII)

Si prefieres control total — porque ya tienes el cálculo de Totales por tu lado, quieres fijar un Emisor distinto al del tenant, o estás migrando desde un sistema que ya construye el shape DGII — manda los 4 campos explícitamente. Los respetamos sin cuestionar.

Ambos modos son el mismo format: 'digimart' — la diferencia es solo si incluyes esos 4 campos o los omites. Puedes mezclar: enviar Emisor explícito y dejar que calculemos Totales, o cualquier combinación.

{
  "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
        }
      ]
    }
  }
}

clientRequestId (idempotency)

Si tu sistema reintenta la misma factura (timeout de red, retry interno, etc.), envía el mismo clientRequestId en cada intento. Detectamos la duplicación y devolvemos el envío original en vez de procesar dos veces.

• Recomendación: usa un id determinístico desde TU sistema (ej. tu_factura_id + fecha).
• Longitud: 1-120 caracteres.
• Si lo omites, no hay protección contra retries duplicados.

Response — 202 Accepted

{
  "dgiiLogId": "a3f7b8c9-d1e2-3f4g-5h6i-7j8k9l0m1n2o",
  "status": "queued",
  "environment": "ecf",
  "billable": true,
  "message": "Invoice queued for processing"
}

Response — 400 Bad Request

{
  "message": "xml is required when format=\"xml\"",
  "statusCode": 400
}

Otros errores 400 comunes:

• payload is required when format="digimart"
• format must be one of: xml, digimart

Idempotency response

Si reutilizas un clientRequestId:

{
  "dgiiLogId": "a3f...",
  "status": "queued",
  "deduped": true,
  "message": "Existing submission returned (idempotency key matched)"
}

El deduped: true te dice que NO procesamos de nuevo — te devolvimos el envío original.

GET /invoices/:trackOrId

Consulta el estado de un comprobante. Acepta tanto el dgiiLogId (que te dimos al hacer POST) como el trackId (que DGII asigna después).

GET /api/v1/fe/invoices/{trackOrId}
Authorization: Bearer <JWT>

Scope requerido: invoices:read

Response — 200 OK (procesado)

{
  "dgiiLogId": "a3f7b8c9-...",
  "trackId": "DGII-2026-06-15-12345",
  "environment": "ecf",
  "status": "Aceptado",
  "qrCodeUrl": "https://ecf.dgii.gov.do/ConsultaTimbre?...",
  "securityCode": "abc123",
  "ncfExpiration": "31-12-2026",
  "fechaHoraFirma": "2026-06-15T14:23:11Z",
  "response": { /* respuesta completa de DGII */ },
  "submittedAt": "2026-06-15T14:23:10Z",
  "updatedAt": "2026-06-15T14:23:13Z",
  "clientRequestId": "factura-001-2026-06-15"
}

Estados posibles

Response — 200 OK (no encontrado)

{
  "found": false
}

Significa que el trackOrId no corresponde a ningún envío tuyo.

GET /invoices/:trackOrId/xml

Devuelve el XML que generamos y/o firmamos para un envío específico. Sirve para dos cosas concretas:

1. Debug de rechazos "XML Inválido" — DGII responde con código 400 y un mensaje genérico cuando el XSD no valida. Pidiendo este endpoint ves exactamente el documento que mandamos por ti y puedes detectar el campo problemático (formato de fecha mal, monto fuera de rango, NCF con prefijo equivocado, etc.).
2. Archivar el comprobante firmado — el XML con la sección <Signature> es la prueba legal del e-CF. Para tus copias internas o un sistema documental, este endpoint te devuelve esa pieza.

GET /api/v1/fe/invoices/{trackOrId}/xml
Authorization: Bearer <JWT>

Scope requerido: invoices:read

Path params

Response — 200 OK

{
  "dgiiLogId": "9e5c8010-fa9a-4190-9c3c-d727aa99b26c",
  "environment": "testecf",
  "status": "error",
  "source": "signed",
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ECF ...>...</ECF>"
}

Response — 200 OK (no encontrado)

{
  "found": false
}

GET /invoices

Lista paginada del historial de envíos del tenant. Solo retorna envíos hechos a través de esta API pública (source = 'fe-api').

GET /api/v1/fe/invoices?page=1&limit=50&from=2026-06-01&to=2026-06-30
Authorization: Bearer <JWT>

Scope requerido: invoices:read

Query params

Response — 200 OK

{
  "page": 1,
  "limit": 50,
  "total": 247,
  "items": [
    {
      "dgiiLogId": "a3f...",
      "trackId": "DGII-...",
      "environment": "ecf",
      "status": "Aceptado",
      "qrCodeUrl": "...",
      "submittedAt": "2026-06-15T14:23:10Z",
      "updatedAt": "2026-06-15T14:23:13Z",
      "clientRequestId": "factura-001-2026-06-15"
    }
    /* ... más items ... */
  ]
}

Ordenado por submittedAt DESC (más recientes primero).