ECF Connector API

Verifica que la API Key sea válida y devuelve la información del conector. Úsalo para confirmar la autenticación antes de realizar operaciones.

Encabezados

Respuesta exitosa

{
  "message": "Autenticación exitosa",
  "code": 200,
  "data": {
    "client_id":   42,
    "client_name": "Mi Empresa S.R.L.",
    "state":       "active"
  }
}

Devuelve todos los impuestos configurados en el sistema. Los IDs obtenidos se usan en el campo tax_ids al crear facturas.

Respuesta exitosa

{
  "code": 200,
  "data": [
    { "id": 1, "name": "ITBIS 18%",  "amount": 18.0, "type_tax_use": "sale" },
    { "id": 2, "name": "ITBIS 16%",  "amount": 16.0, "type_tax_use": "sale" },
    { "id": 5, "name": "Exento (0%)", "amount": 0.0,  "type_tax_use": "sale" }
  ]
}

Retorna todos los tipos de documentos fiscales disponibles en el sistema.

Respuesta exitosa

{
  "code": 200,
  "data": [
    { "id": 10, "name": "Factura de Crédito Fiscal Electrónica", "prefix": "E31" },
    { "id": 11, "name": "Factura de Consumo Electrónica",       "prefix": "E32" }
  ]
}

Busca un tipo de documento específico por su prefijo (ej. E31, E34).

Parámetros de ruta

GET /api/ecf/type/document/E31

Crea un nuevo cliente en el sistema. Devuelve el id para usarlo como partner_id en futuras facturas.

Body (JSON)

Ejemplo de solicitud

{
  "name":        "Comercial Los Girasoles S.R.L.",
  "type_client": "tax_payer",
  "rnc":         "101234567"
}

Respuesta exitosa

{
  "code": 200,
  "data": {
    "id":   89,
    "name": "Comercial Los Girasoles S.R.L.",
    "type": "tax_payer",
    "rnc":  "101234567"
  }
}

Endpoint principal. Crea la factura en el sistema, la firma digitalmente con el certificado P12 y responde de inmediato con el QR, la fecha de firma y el código de seguridad. El envío a la DGII se hace en segundo plano (en unos 2 minutos) o en el momento en que consultas /invoice/{id}/status. Para esperar la respuesta de la DGII en la misma llamada envía "wait_dgii": true.

Campos comunes

Ítems de línea (items[])

E33 — Nota de Débito

E34 — Nota de Crédito

E43 — Régimen Especial (compra)

E31 / E32 / E45 / E46 / E47 — Ventas

Ejemplo — Factura de venta (E32)

POST /api/ecf/send
Authorization: ECF-5-abc123...

{
  "ncf":              "E320000000001",
  "invoice_date_due": "2026-07-30",
  "partner_id":       89,
  "income_type":      "01",
  "items": [
    {
      "name":       "Servicio de consultoría",
      "quantity":   1,
      "price_unit": 5000.00,
      "tax_ids":    [1],
      "discount":   0
    }
  ]
}

Ejemplo — Factura de crédito fiscal a crédito (E31)

Venta a 30 días: payment_type "2" + payment_due_date. El e-CF sale con TipoPago=2, FechaLimitePago y TerminoPago.

POST /api/ecf/send
Authorization: ECF-5-abc123...

{
  "ncf":              "E310000000001",
  "invoice_date_due": "2028-12-31",
  "invoice_date":     "2026-09-27",
  "partner_id":       89,
  "income_type":      "01",
  "payment_type":     "2",
  "payment_due_date": "2026-10-27",
  "payment_term":     "30 dias",
  "items": [
    {
      "name":       "Servicio de consultoría",
      "quantity":   1,
      "price_unit": 5000.00,
      "tax_ids":    [1]
    }
  ]
}

Ejemplo — Nota de crédito (E34)

POST /api/ecf/send
Authorization: ECF-5-abc123...

{
  "ncf":               "E340000000001",
  "invoice_date_due":  "2026-07-30",
  "partner_id":        89,
  "ncf_modificate":    "E320000000001",
  "modification_code": "1",
  "base_amount":       5000.00,
  "tax_ids":           [1]
}

Respuesta exitosa

{
  "message": "Documento creado correctamente",
  "code":    200,
  "data": {
    "invoice_id":        145,
    "invoice_name":      "INV/2026/00145",
    "partner_id":        89,
    "partner_name":      "Comercial Los Girasoles S.R.L.",
    "ncf":               "E310000000001",
    "origin_ncf":        null,
    "ecf_status":        "sent",
    "ecf_status_detail": "init",
    "status_url":        "/api/ecf/invoice/145/status",
    "fecha_firma":       "27-09-2026 10:15:30",
    "codigo_seguridad":  "Wr3u19",
    "qr_link":           "https://ecf.dgii.gov.do/...",
    "payment_type":      "2",
    "payment_due_date":  "2026-10-27",
    "payment_term":      "30 dias",
    "move_type":         "out_invoice",
    "amount_untaxed":    5000.00,
    "amount_tax":        900.00,
    "amount_total":      5900.00
  }
}

payment_due_date solo viene en ventas a crédito (null en contado/gratuito). El QR se entrega antes de la aprobación de la DGII: consulta status_url hasta ver success antes de dar la factura por aceptada.

Consulta el estado actual de una factura. Si el comprobante todavía está en cola (ecf_status_detail = init), lo envía a la DGII en ese momento y devuelve el resultado. Devuelve los mismos campos que /send (QR, fecha de firma, tipo de pago, etc.).

Parámetros de ruta

{
  "code": 200,
  "data": {
    "invoice_id":   145,
    "ncf":          "E320000000001",
    "ecf_status":        "success",
    "ecf_status_detail": "success",
    "amount_total":      5900.00,
    "message_dgii":      "Aceptado"
  }
}

Lista las facturas creadas por el conector con paginación y filtro opcional por estado.

Query params

GET /api/ecf/invoices?ecf_status=sent&limit=50

Fuerza una consulta en tiempo real a la DGII para actualizar el estado de la factura. Si todavía está en cola, primero la envía.

Descarga el XML sin firma del comprobante. La respuesta tiene Content-Type: application/xml.

GET /api/ecf/get/145/xml
# Response Content-Type: application/xml
# Body: <?xml version="1.0" ...><ECF>...</ECF>