Emisión & Recepción de Comprobantes e-CF

El endpoint POST /fe/recepcion/ecf es el canal central para la emisión de Comprobantes Fiscales Electrónicos (e-CF). Recibe el documento en formato JSON, realiza validaciones sintácticas y tributarias, construye el XML estándar de la DGII, estampa la Firma Digital XMLDSig en memoria con el certificado X.509 de la empresa y lo transmite al Web Service de la DGII.

🚀 1. Emisión e-CF en Formato JSON (POST /fe/recepcion/ecf)

Encabezados Requeridos (Headers HTTP)

• Authorization: Bearer <token_jwt>
• Content-Type: application/json

📥 Contrato Detallado de la Respuesta JSON

Al emitir un comprobante, la API devuelve un objeto JSON estructurado con el dictamen de la DGII y los elementos de auditoría y representación impresa. A continuación se detalla el propósito de cada campo:

Ejemplo de Respuesta Exitosa (200 OK - Aceptado)

{
  "trackId": "7bf136a7-0df7-4b71-9878-8314ba6cfbfb",
  "encf": "E310000000001",
  "estado": "Aceptado",
  "codigo": "1",
  "secuenciaUtilizada": true,
  "securityCode": "UbX4HU",
  "digitalSignatureDate": "2026-08-17T12:08:37.51789",
  "fechaRecepcion": "17-08-2026 12:08:40",
  "url": "https://ecf.dgii.gov.do/testecf/ConsultaTimbre?RncEmisor=131592511&RncComprador=130301931&ENCF=E310000000001&FechaEmision=17-08-2026&MontoTotal=11,800.00&FechaFirma=17-08-2026 12:08:37&CodigoSeguridad=UbX4HU",
  "mensajes": [
    {
      "codigo": 1,
      "valor": "Comprobante recibido y aceptado exitosamente por la DGII."
    }
  ]
}

🔍 Significado Detallado de Cada Campo de la Respuesta

1. trackId (Identificador de Rastreo DGII)

• Tipo: string (UUID/GUID) o alfanumérico único.
• Qué es: Es el número de seguimiento oficial generado y asignado por la DGII para cada transacción recibida.
• Para qué sirve: Permite realizar consultas de estado posteriores mediante los servicios de la DGII o ante la mesa de ayuda tributaria en caso de discrepancias.

2. estado (Dictamen Tributario Oficial de la DGII)

• Tipo: string.
• Valores Posibles:
  • "Aceptado": El comprobante cumple con todas las reglas tributarias, aritméticas y de estructura de la DGII. Es 100% válido legalmente.
  • "Aceptado Condicional": El comprobante fue aceptado fiscalmente pero contiene advertencias informativas menores.
  • "Rechazado": El comprobante no fue aprobado por la DGII debido a inconsistencias fiscales (ej. RNC inexistente, balance superado, descuadre de ITBIS).
  • "En Proceso": El documento fue recibido por la DGII y se encuentra en la cola de validación asíncrona.
• Regla de Validación: La aplicación integradora debe ramificar su lógica de negocio evaluando el campo estado, nunca asumiendo éxito por códigos numéricos arbitrarios.

3. codigo (Código de Respuesta de la Operación)

• Tipo: string.
• Valores Estándar:
  • "1": Aceptado por la DGII.
  • "2": Rechazado por la DGII.
  • "4": Aceptado Condicional.
  • "0" / "200": Reenvío Idempotente. Confirma que el e-NCF ya fue aceptado previamente por la DGII en una transmisión anterior.

4. secuenciaUtilizada (Consumo de la Secuencia Fiscal)

• Tipo: boolean (true / false).
• Qué es: Indica si la secuencia numérica correlativa asignada (E310000000001) fue consumida en la DGII.
• Comportamiento:
  • true: La DGII dio por utilizada la secuencia. Si fue aceptado, el e-NCF queda asignado a la transacción. Si fue rechazado con secuencia consumida, esa numeración queda inutilizada tributariamente y el sistema debe avanzar obligatoriamente al siguiente número (E310000000002).
  • false: La transacción falló en una validación previa a la afectación de secuencias en la DGII. La secuencia no fue consumida ante el fisco y puede corregirse y reenviarse con la misma numeración.

5. securityCode (Código de Seguridad para Representación Impresa)

• Tipo: string de 6 caracteres alfanuméricos (ej. "UbX4HU").
• Qué es: Primeros seis (6) caracteres alfanuméricos derivados del hash criptográfico del valor de la firma digital (SignatureValue).
• Uso obligatorio: Debe imprimirse visiblemente en la factura física o PDF debajo del Código QR.

6. digitalSignatureDate (Marca Temporal de la Firma Criptográfica)

• Tipo: string en formato ISO 8601 con zona horaria oficial (ej. "2026-08-17T12:08:37.51789").
• Qué es: Fecha y hora exacta (GMT-4) en la que el motor criptográfico firmó el XML con el certificado digital X.509.

7. url (Enlace de Consulta del Timbre Fiscal QR)

• Tipo: string con formato URL oficial de la DGII.
• Uso: Esta cadena es exactamente el contenido a codificar en el Código QR del comprobante (mínimo 22x22 mm).

8. reenviado (Detección de Reintentos e Idempotencia)

• Tipo: boolean (true / false).
• Qué es: Bandera que indica si la petición recibida corresponde a una retransmisión de un comprobante con un e-NCF previamente procesado.
• Comportamiento de Reenvío Exitoso (reenviado: true): Si el sistema cliente reenvía un e-NCF que ya fue aceptado con anterioridad, la API no retransmite duplicados a la DGII y devuelve la confirmación idempotente:

  {
    "trackId": "7bf136a7-0df7-4b71-9878-8314ba6cfbfb",
    "encf": "E310000000001",
    "estado": "Aceptado",
    "codigo": "0",
    "reenviado": true,
    "secuenciaUtilizada": true,
    "mensajes": [
      {
        "codigo": 0,
        "valor": "El e-NCF E310000000001 ya fue enviado y aceptado anteriormente por la DGII. No se reenvía para evitar duplicados."
      }
    ]
  }

9. mensajes (Diagnóstico y Mensajes de Validación)

• Tipo: Array<{ codigo: number, valor: string }>.
• Qué es: Lista de mensajes descriptivos y códigos numéricos generados por la DGII o por la API.

🔒 Aclaración Técnica: Generación de Firma en Memoria Previa al Envío a DGII

Una duda frecuente entre los integradores es: ¿Por qué una respuesta con estado: "Rechazado" puede incluir securityCode, digitalSignatureDate y url?

[Tu Sistema / ERP]
       │  (1. Envía Payload JSON)
       ▼
[API Medasoft e-CF]
       │  (2. Validación local de estructura y esquemas)
       │  (3. Construcción del documento XML <ECF>)
       │  (4. FIRMA EN MEMORIA con Certificado X.509)
       │      ├─ Se genera SignatureValue
       │      ├─ Se calcula securityCode (6 dígitos)
       │      ├─ Se fija digitalSignatureDate (GMT-4)
       │      └─ Se construye la URL oficial del Timbre QR
       │  (5. Transmisión segura HTTPS al Web Service DGII)
       ▼
[Servidores de la DGII]
       │  (6. Evaluación de reglas tributarias, RNCs, vigencia y cuadraturas)
       │  (7. Emisión del Dictamen: Aceptado / Rechazado)
       ▼
[Respuesta JSON al Cliente]

Explicación del Comportamiento:

1. La firma criptográfica es un acto del emisor, no de la DGII: Conforme a la Ley 126-02 y la Ley 32-23, el emisor debe firmar y sellar digitalmente el documento XML antes de presentarlo ante la autoridad tributaria.
2. Generación previa del timbre: Dado que el XML ya está firmado al momento de transmitirse, los datos del timbre (securityCode, digitalSignatureDate y url) ya existen y forman parte de la evidencia digital de la petición.
3. El dictamen de la DGII ocurre después de la firma: La DGII recibe el documento firmado y procede a verificar si las reglas de negocio se cumplen. Si una regla falla (ejemplo: un RNC suspendido o un total que no cuadra), la DGII emite un dictamen de Rechazo.
4. Regla de Oro para el Integrador:

   ⚠️ REGLA CRÍTICA: La presencia de securityCode o url en la respuesta NO significa que el comprobante sea válido. El único y exclusivo indicador de validez fiscal es que la propiedad estado tenga el valor "Aceptado" o "Aceptado Condicional". Si estado es "Rechazado", el comprobante carece de validez tributaria.

🔄 2. Recepción B2B XML (POST /fe/recepcion/api/ecf)

Endpoint B2B para recibir archivos XML de e-CF transmitidos por otros contribuyentes y generar automáticamente la respuesta de Acuse de Recibo (ARECF) firmada digitalmente:

curl -X POST "https://medasoftfe.com/fe/recepcion/api/ecf" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "xml=@factura_proveedor.xml"