Referencia de la API

Integre la facturación electrónica DGII en su sistema usando nuestra API REST.

Base URL

Autenticación

Todas las peticiones requieren un API Key en el header X-API-Key. Genere su API Key desde la sección API Keys del dashboard de cada empresa.

Importante: Cada empresa tiene su propia API Key. Solo se permite 1 API Key activa por empresa. La API Key identifica automaticamente a la empresa en cada peticion — no necesita enviar el ID de empresa.
curl -X POST /api/v1/ecf/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ecf_live_su_api_key_aqui" \
  -d '{ "ECF": { ... } }'

Ambiente

El ambiente se configura en la sección Configuración > Empresa. Los documentos se envían al ambiente configurado y se filtran automáticamente.

TesteCF

Desarrollo / Pruebas

CerteCF

Certificación DGII

eCF

Producción

Campos que no hace falta enviar

Estos campos de IdDocson opcionales. Si no los envía, se completan con los valores por defecto de su empresa (Configuración > Modificar Empresa), y solo en los tipos de e-CF donde el campo existe. Si los envía, se respeta su valor.

VersionSiempre 1.0.
TipoIngresosEl tipo de ingreso elegido en la empresa (por defecto 01).
IndicadorMontoGravado0 o 1 según la empresa; solo si el comprobante tiene montos gravados.
IndicadorEnvioDiferido1 solo si la empresa lo tiene activado; si no, el campo no va.
IndicadorServicioTodoIncluido1 solo si la empresa lo tiene activado; si no, el campo no va.

Webhooks

Registre una URL en Configuración > Webhooks y le avisamos cuando un comprobante pendiente recibe su estado de la DGII. Enviamos un POST cuyo cuerpo es el mismo JSON que devuelve POST /api/v1/ecf/send, con las cabeceras que usted configure (su API key, un Authorization, etc.).

POST https://su-servidor.com/webhooks/ecf
Content-Type: application/json; charset=utf-8
User-Agent: IMECF-Webhook/1.0
X-IMECF-Event: ecf.estado          (o "prueba" al pulsar Probar)
X-IMECF-Delivery: <id unico del aviso>
X-API-Key: <la que usted configuro>

{ "id": "...", "encf": "E310000000001", "estado": "Aceptado", "trackId": "...", "receptor": { ... }, ... }
  • Responda con un 2xx en menos de 10 segundos. Si no, lo intentamos hasta 3 veces.
  • Use X-IMECF-Delivery para descartar avisos duplicados.
  • El botón Probar envía un comprobante de ejemplo a su URL y le muestra la respuesta de su servidor.
  • La URL debe ser pública; no se siguen redirecciones.

Secuencias eNCF

La plataforma gestiona las secuencias de eNCF automáticamente. Cuando envía un documento sin el campo eNCF, se genera el próximo número disponible.

Nota:Configure sus secuencias desde el dashboard (Documentos ECF > Secuencias) con los rangos autorizados por la DGII antes de enviar documentos.

Endpoints

POST/api/v1/ecf/send

Enviar un documento ECF a la DGII

Envia un documento ECF. Los campos eNCF, FechaVencimientoSecuencia, Emisor, FechaEmision y FechaHoraFirma se generan automaticamente.

Request Body

{
  "ECF": {
    "Encabezado": {
      "IdDoc": {
        "TipoeCF": "31",
        "TipoPago": "1",
        "TablaFormasPago": {
          "FormaDePago": [{ "FormaPago": 1, "MontoPago": "590.00" }]
        }
      },
      "Comprador": {
        "RNCComprador": "40223982170",
        "RazonSocialComprador": "CLIENTE SRL"
      },
      "Totales": {
        "MontoGravadoTotal": "500.00",
        "MontoGravadoI1": "500.00",
        "ITBIS1": "18",
        "TotalITBIS": "90.00",
        "TotalITBIS1": "90.00",
        "MontoTotal": "590.00"
      }
    },
    "DetallesItems": {
      "Item": {
        "NumeroLinea": "1",
        "IndicadorFacturacion": "1",
        "NombreItem": "Producto",
        "IndicadorBienoServicio": "1",
        "CantidadItem": "1",
        "UnidadMedida": "43",
        "PrecioUnitarioItem": "500.00",
        "MontoItem": "500.00"
      }
    }
  }
}

Response

{
  "id": "d3d47071-5782-4325-be7e-106c88ddbf14",
  "encf": "E310000000015",
  "tipoEcf": "E31",
  "estado": "Aceptado",
  "trackId": "b79bbde7-124e-4739-b3ce-e44aa23adc06",
  "codigoSeguridad": "cUdYgj",
  "dgiiUrl": "https://ecf.dgii.gov.do/testecf/consultatimbre?...",
  "xmlUrl": "https://api.tudominio.com/api/v1/ecf/{id}/xml",
  "enviado": true,
  "secuenciaUtilizada": true,
  "ambiente": "TesteCF",
  "source": "api",
  "errorMessage": null,
  "createdAt": "2026-05-27T10:56:59.164Z",
  "updatedAt": "2026-05-27T10:57:01.306Z"
}
GET/api/v1/ecf/{id}/status

Consultar estado de un documento por ID

Retorna todos los datos del documento incluyendo el estado actual, trackId, request/response JSON completo.

Response

// Misma estructura que la respuesta de POST /send
GET/api/v1/ecf/by-encf/{encf}

Consultar documento por eNCF

Busca un documento por su numero eNCF (ej: E310000000015). La API Key identifica la empresa automaticamente.

Response

// Misma estructura que la respuesta de POST /send
GET/api/v1/ecf/{id}/track

Consultar trackId en la DGII y actualizar estado

Consulta el estado real del documento en la DGII usando el trackId. Actualiza el estado del documento y retorna la respuesta completa.

Response

// Misma estructura que la respuesta de POST /send (con estado actualizado)
GET/api/v1/ecf/{id}/xml

Descargar XML firmado del documento

Retorna el XML firmado digitalmente tal como fue enviado a la DGII. Content-Type: application/xml.

GET/api/v1/ecf

Listar documentos ECF con filtros y paginacion

Lista paginada. Filtros: tipoEcf, estado, search, fechaDesde, fechaHasta, page, limit (default 10, max 100). Si no envia ambiente, usa el de la empresa.

Response

{
  "data": [ { ... }, { ... } ],
  "total": 45,
  "page": 1,
  "limit": 10
}
POST/api/v1/ecf/batch

Envio masivo (maximo 50 documentos)

Envia hasta 50 documentos en una sola peticion. Cada documento se procesa individualmente.

Response

{
  "results": [
    { "encf": "E310000000016", "status": "sent", "id": "uuid..." },
    { "encf": "E310000000017", "status": "error", "error": "..." }
  ],
  "total": 2
}
POST/{rnc}/fe/recepcion/api/ecf

Recibir documento ECF (recepcion)

Recibe un documento ECF en formato XML reenviado desde su sistema. Acepta Content-Type: application/xml o multipart/form-data (campo "xml"). Requiere X-API-Key.

Response

{
  "message": "Documento recibido exitosamente.",
  "id": "d3d47071-5782-4325-be7e-106c88ddbf14",
  "encf": "E310000000001",
  "tipoEcf": "E31"
}
POST/{rnc}/fe/aprobacioncomercial/api/ecf

Recibir aprobacion comercial (ACECF)

Recibe una aprobacion comercial (ACECF) en formato XML reenviada desde su sistema. Acepta Content-Type: application/xml o multipart/form-data (campo "xml"). Requiere X-API-Key.

Response

{
  "message": "Aprobacion comercial recibida exitosamente.",
  "id": "d3d47071-5782-4325-be7e-106c88ddbf14",
  "encf": "E310000000001"
}
GET/api/v1/dgii/rnc?value={rnc_o_cedula}

Buscar contribuyente por RNC o Cédula en la DGII

Busca información de un contribuyente en la DGII por su RNC (9 dígitos) o Cédula (11 dígitos). Primero busca en el registro de contribuyentes, si no encuentra busca en ciudadanos. Requiere suscripción Pro.

Response

{
  "success": true,
  "nombre": "EMPRESA EJEMPLO SRL",
  "nombreComercial": "EJEMPLO COMERCIAL",
  "cedulaRnc": "130862346",
  "categoria": "",
  "regimen": "NORMAL",
  "estado": "ACTIVO",
  "actividad": "ACTIVIDADES DE CONSULTORÍA",
  "adminLocal": "ADM. LOCAL SANTO DOMINGO",
  "facturadorElectronico": "Sí"
}
GET/api/v1/dgii/jce?cedula={cedula}

Validar cédula en la Junta Central Electoral (JCE)

Valida si una cédula dominicana (11 dígitos) existe en la Junta Central Electoral. Retorna los datos de la persona si existe. No requiere suscripción Pro.

Response

// Si la cédula existe:
{
  "found": true,
  "cedula": "40212344309",
  "nombre": "CESAR MIGUEL MORONTA GUILLEN",
  "primerNombre": "CESAR",
  "segundoNombre": "MIGUEL",
  "primerApellido": "MORONTA",
  "segundoApellido": "GUILLEN",
  "sexo": "MALE",
  "fechaNacimiento": "2004-09-18T00:00:00.000000Z",
  "lugarNacimiento": "HATO DEL YAQUE, SANTIAGO, R.D.",
  "foto": "https://api.ursoft.com.do/people/.../photo?..."
}

// Si no existe:
{
  "found": false,
  "cedula": "40212344309",
  "message": "Cédula no encontrada en la JCE."
}
POST/api/v1/ecf/bulk

Enviar varios e-CF en un lote (hasta 500)

Guarda el lote y pone sus comprobantes en una cola: se envian a la DGII de uno en uno, en orden, y cada uno una sola vez. La llamada no espera a la DGII. Con modo "pendiente" (por defecto) el lote entra en la cola en el envio nocturno (11:00 PM) o cuando usted lo procese. Con modo "inmediato" entra en la cola al recibirlo: con hasta 15 comprobantes la respuesta espera los resultados; con mas, responde enseguida. Cada resultado se notifica por webhook en cuanto ese comprobante termina.

Response

// HTTP 202
{
  "id": "uuid-del-lote",
  "estado": "PENDIENTE",        // PENDIENTE | PROCESANDO | COMPLETADO
  "ambiente": "eCF",
  "total": 2,
  "pendientes": 2,
  "procesados": 0,
  "errores": 0,
  "mensaje": "Lote de 2 comprobantes guardado como pendiente. Se enviará en el envío nocturno (11:00 PM), o puede procesarlo antes: desde el panel, en Lotes, o con POST /api/v1/ecf/bulk/{id}/procesar.",
  "documentos": [
    { "posicion": 1, "referencia": "FAC-1001", "estado": "PENDIENTE", "encf": null, "error": null, "documento": null },
    { "posicion": 2, "referencia": "FAC-1002", "estado": "PENDIENTE", "encf": null, "error": null, "documento": null }
  ]
}

// Otros mensajes:
// modo "inmediato", hasta 15:
//   "Lote de 2 comprobantes recibido: se está enviando a la DGII."
// modo "inmediato", mas de 15:
//   "Lote de 40 comprobantes recibido: quedó en cola y se está enviando a la DGII de uno en uno, en orden. ..."
POST/api/v1/ecf/bulk/{id}/procesar

Enviar ahora un lote pendiente

Para no esperar al envio nocturno. Pone el lote en la cola y responde enseguida; los comprobantes salen de uno en uno y cada resultado llega por webhook. Tambien se puede hacer desde el panel, en Lotes. Si el lote ya se esta enviando o ya termino, no hace nada.

GET/api/v1/ecf/bulk/{id}

Consultar un lote y el resultado de cada comprobante

Devuelve el avance del lote y cada comprobante. Cuando un comprobante ya existe, "documento" trae el mismo objeto que devuelve POST /api/v1/ecf/send. Un lote COMPLETADO puede tener errores: revise el campo "errores".

Response

{
  "id": "uuid-del-lote",
  "estado": "COMPLETADO",
  "total": 2, "pendientes": 0, "procesados": 1, "errores": 1,
  "documentos": [
    {
      "posicion": 1, "referencia": "FAC-1001",
      "estado": "PROCESADO",      // PENDIENTE | PROCESANDO | PROCESADO | ERROR
      "encf": "E310000000015", "error": null,
      "documento": { "id": "...", "encf": "E310000000015", "estado": "Aceptado", "trackId": "...", ... }
    },
    {
      "posicion": 2, "referencia": "FAC-1002",
      "estado": "ERROR",
      "encf": null,
      "error": "La secuencia para E31 esta agotada (10,000 de 10,000). ...",
      "documento": null
    }
  ]
}
GET/api/v1/ecf/directorio/{rnc}

Consultar el directorio de receptores electronicos de la DGII

Devuelve las URL de recepcion, aprobacion comercial y autenticacion que un RNC tiene registradas en la DGII, en el ambiente de su empresa. Responde 404 si ese RNC no es receptor electronico.

Response

{
  "nombre": "CLIENTE SRL",
  "rnc": "131880681",
  "urlRecepcion": "https://ecf.cliente.do/fe/recepcion/api/ecf",
  "urlAceptacion": "https://ecf.cliente.do/fe/aprobacioncomercial/api/ecf",
  "urlOpcional": "https://ecf.cliente.do/fe/autenticacion/api/semilla"
}
POST/api/v1/ecf/{id}/enviar-receptor

Entregar el comprobante al receptor (el comprador)

Busca al comprador en el directorio de la DGII y le entrega el XML firmado en ese momento. Solo para comprobantes aceptados. Devuelve el documento con el resultado en el objeto receptor. Si activa "Enviar los comprobantes a los receptores" en la empresa, esto ocurre solo, en segundo plano.

Response

{
  "id": "uuid-del-documento",
  "encf": "E310000000001",
  "estado": "Aceptado",
  "receptor": {
    "estado": "ENTREGADO",   // ENTREGADO | FALLIDO | SIN_RECEPTOR | NO_APLICA
    "url": "https://ecf.cliente.do/fe/recepcion/api/ecf",
    "intentos": 1,
    "error": null,
    "enviadoAt": "2026-11-18T14:00:05.000Z"
  }
}

TrackId y Estados

Despues de enviar un documento, recibira un trackId en la respuesta. Este identificador le permite consultar el estado real del documento en la DGII usando el endpointGET /api/v1/ecf/{id}/track.

Estados del sistema:

PENDIENTE_ENVIO_AL_SERVICIO_DGIIDocumento registrado en el sistema, esperando envio a la DGII
EN_PROCESOEnviado a la DGII pero no devolvio estado definitivo (fallback del sistema)
ERROR_AL_ENVIAR_A_DGIIError de comunicacion con la DGII (red, timeout, certificado). Puede reintentarse

Estados de la DGII (tal como los devuelve la DGII):

AceptadoDocumento aceptado por la DGII. Tiene validez fiscal
Aceptado CondicionalAceptado con observaciones. Tiene validez fiscal
RechazadoRechazado por la DGII. Debe corregirse y reenviarse
En ProcesoLa DGII confirma que esta procesando el documento
No encontradoTrackId no encontrado en la DGII
Los estados del sistema usan UPPER_SNAKE_CASE y son asignados internamente. Los estados de la DGII se almacenan tal cual los devuelve la API en PascalCase.

Flujo del Proceso

Al enviar un documento, el sistema registra cada paso en el campo responseJson como un array de eventos con timestamp.

1
AUTENTICACION_EXITOSAAutenticacion con DGII

Se autentica con los servicios de la DGII usando el certificado digital P12

2
DOCUMENTO_FIRMADOFirma del XML

El XML del e-CF se firma digitalmente con el certificado de la empresa

3
RESPUESTA_DGIIRespuesta de la DGII

Se recibe la respuesta con el trackId y estado inicial

4
TRACK_STATUSConsulta de TrackId

Se consulta el estado final del documento usando el trackId

5
REFRESH_STATUSActualizacion manual

Consulta manual posterior via GET /api/v1/ecf/{id}/track

Ejemplo de responseJson

[
  { "timestamp": "2026-05-27T10:57:00Z", "status": "AUTENTICACION_EXITOSA" },
  { "timestamp": "2026-05-27T10:57:00Z", "status": "DOCUMENTO_FIRMADO" },
  { "timestamp": "2026-05-27T10:57:01Z", "status": "RESPUESTA_DGII", "data": { "trackId": "...", "error": null } },
  { "timestamp": "2026-05-27T10:57:01Z", "status": "TRACK_STATUS", "data": { "estado": "Aceptado", "secuenciaUtilizada": true } }
]

Certificado Digital (.p12)

Para enviar documentos a la DGII, debe subir su certificado digital .p12 desde Configuración > Certificados. El certificado se usa para firmar digitalmente cada documento antes de enviarlo a la DGII. La contraseña se almacena encriptada con AES-256-GCM.

Recepcion de Documentos

Para recibir documentos ECF y aprobaciones comerciales que otras empresas le envian a traves de la DGII, configure su sistema para reenviar los XML a nuestra plataforma.

  1. 1Registre su URL de recepcion en la DGII (ej: https://su-sistema.com/fe/recepcion/api/ecf). Esta es la URL de su sistema donde la DGII le notificara.
  2. 2Registre su URL de aprobacion comercial en la DGII (ej: https://su-sistema.com/fe/aprobacioncomercial/api/ecf).
  3. 3Cuando la DGII envie un XML a su URL, reenvielo tal cual a nuestro endpoint con su API Key:

Reenvio de e-CF

curl -X POST /{su-rnc}/fe/recepcion/api/ecf \
  -H "Content-Type: application/xml" \
  -H "X-API-Key: ecf_live_su_api_key_aqui" \
  -d '<?xml version="1.0"?>
<ECF>
  <Encabezado>
    <IdDoc>
      <TipoeCF>31</TipoeCF>
      <eNCF>E310000000001</eNCF>
    </IdDoc>
    <Emisor>
      <RNCEmisor>123456789</RNCEmisor>
      <RazonSocialEmisor>EMPRESA EJEMPLO</RazonSocialEmisor>
    </Emisor>
    <Totales>
      <MontoTotal>1000.00</MontoTotal>
    </Totales>
  </Encabezado>
</ECF>'

Reenvio de Aprobacion Comercial

curl -X POST /{su-rnc}/fe/aprobacioncomercial/api/ecf \
  -H "Content-Type: application/xml" \
  -H "X-API-Key: ecf_live_su_api_key_aqui" \
  -d '<?xml version="1.0"?>
<ACECF>
  <DetalleAprobacionComercial>
    <RNCEmisor>123456789</RNCEmisor>
    <eNCF>E310000000001</eNCF>
    <FechaEmision>29-05-2026</FechaEmision>
    <MontoTotal>1000.00</MontoTotal>
    <RNCComprador>{su-rnc}</RNCComprador>
    <Estado>1</Estado>
  </DetalleAprobacionComercial>
</ACECF>'
4El documento aparecera automaticamente en la seccion ECF Recibidos de su dashboard.
Nota: Tambien puede consultar los documentos recibidos via API usandoGET /api/v1/ecf/received con su API Key.

Flujo Completo

  1. 1Registre su empresa con RNC, datos y ambiente (TesteCF para pruebas)
  2. 2Suba su certificado digital .p12 emitido por la DGII
  3. 3Configure las secuencias eNCF con los rangos autorizados por la DGII
  4. 4Active su suscripción ($30/mes)
  5. 5Genere un API Key desde el dashboard
  6. 6Envíe documentos via POST /api/v1/ecf/send con su API Key
  7. 7Consulte el trackId para verificar la aceptación en la DGII