Estamos implementando validaciones asincrónicas para notas de crédito y débito, mejorando la consistencia y seguridad al procesar documentos referenciados. Release date: 30-09-2025

Validación asíncrona de documento referenciado

Verifica que la factura referenciada haya sido aceptada por la DGII antes de procesar la nota.

Antes de enviar la nota (débito o crédito) a la DGII verificamos si en nuestro registros tenemos dicha factura, si la tenemos validamos en que esta esté aceptada o rechazada por la DGII o si aun está en progreso, estos son los flujos según el estado del documento referenciado:

En proceso: si el documento aun está en proceso la nota tambien queda pendiente hasta tener un estado final en el documento
Aceptado: en caso de que el documento refenciado este acepado por la DGII (legalStatus = ACCEPTED|ACCEPTED_WITH_OBSERVATIONS) la nota se envia a la DGII

Rechazado: en caso de que el documento referenciado se encuentre rechazado por la DGII (legalStatus = REJECTED) la nota no se envia a la DGII y queda con un estado fallido (status = FAILED) con el codigo de error AP3012.
Ejemplo de nota rechazada:

{
    "id": "XXXXXXXXXXXXXXXXXXXXXXX",
    "stampDate": "2025-09-27T00:00:00.000Z",
    "status": "FAILED",
    "legalStatus": null,
    "companyIdentification": "123456789",
    "trackId": null,
    "documentNumber": "E340000000001",
    "sequenceConsumed": false,
    "signatureDate": "27-07-2025 00:00:00",
    "securityCode": "ASDFGH",
    "error": {
        "code": "AP3012",
        "message": "Document referenced is rejected or failed"
    }
}

Validación asíncrona de totales de notas crédito

Garantiza que las notas de crédito no generen saldos negativos en la factura referenciada.

Antes de enviar una nota de crédito a la DGII, calculamos el monto restante permitido sobre la factura referenciada teniendo en cuenta:

El total de la factura.
La suma de todas las notas débito aceptadas que afectan a la factura.
La suma de todas las notas crédito aceptadas que afectan a la factura.

El calculo seria el siguente: Total de la factura + (suma de notas débito aceptadas) - (suma de notas crédito aceptadas)

Notas de crédito de modificación de totales

La nota de crédito de modificación de totales (modificationCode = 3) solo puede enviarse si su total no excede el monto restante disponible. Si el total de la nota supera este límite, la nota queda con estado fallido (status = FAILED) y se asigna el código de error AP3013.

Ejemplo de nota de crédito con monto inválido:

{
    "id": "YYYYYYYYYYYYYYYYYYYYYYY",
    "stampDate": "2025-09-27T00:00:00.000Z",
    "status": "FAILED",
    "legalStatus": null,
    "companyIdentification": "123456789",
    "trackId": null,
    "documentNumber": "E340000000002",
    "sequenceConsumed": false,
    "signatureDate": "27-07-2025 00:00:00",
    "securityCode": "QWERTY",
    "error": {
        "code": "AP3013",
        "message": "The remainder of the sum of all transactions in the referenced document is less than the value of the credit note"
    }
}

Notas de crédito de anulación total

La nota de crédito de modificación de totales (modificationCode = 1) solo puede enviarse si su total es igual el monto restante disponible. Si el total de la nota es diferente al total restante, la nota queda con estado fallido (status = FAILED) y se asigna el código de error AP3014.

{
    "id": "YYYYYYYYYYYYYYYYYYYYYYY",
    "stampDate": "2025-09-27T00:00:00.000Z",
    "status": "FAILED",
    "legalStatus": null,
    "companyIdentification": "123456789",
    "trackId": null,
    "documentNumber": "E340000000002",
    "sequenceConsumed": false,
    "signatureDate": "27-07-2025 00:00:00",
    "securityCode": "QWERTY",
    "error": {
        "code": "AP3014",
        "message": "The total value of a cancellation note must be the same as the total sum of all transactions of the referenced document."
    }
}

Notas de crédito de tipo modificación de texto

Las notas de crédito con modificationCode = 2 (corrección de texto del comprobante fiscal) no pueden afectar los totales de la factura.

Si se intenta enviar una nota de este tipo con un total distinto de 0, se responderá con un status 400 y el siguente body con el error code AP3016:

{
    "errors": [
        {
            "code": "AP3015",
            "message": "Credit notes with modification code equal to 2 must have a total amount of 0"
        }
    ]
}

Detección de consecutivos en proceso

Mejora la validación de consecutivos duplicados incluyendo documentos que están siendo procesados.

Con esta validación ahora se evita que se generen múltiples documentos con el mismo consecutivo cuando existen emisiones concurrentes.
Si se intenta emitir un documento con un consecutivo que ya está en proceso, la API responderá con un status 400 y el siguiente error:

{
    "errors": [
        {
            "code": "AP3011",
            "message": "ENCF document is in process with id: XXXXXXXXXXXXXXXXXXXXX"
        }
    ]
}

De esta forma se garantiza un mayor control en la emisión concurrente de documentos y se evitan duplicados de consecutivos.

Resumen de cambios y consideraciones para integradores

Con esta versión se introducen validaciones asincrónicas que afectan directamente el flujo de envío de notas de crédito y débito. Los puntos clave a tener en cuenta son:

Notas pueden quedar en estado pendiente
- Si el documento referenciado aún está en proceso en la DGII, la nota quedará en estado PENDING hasta tener un resultado final.
- Esto implica que tu integración debe estar preparada para reintentos o para consultar periódicamente el estado del documento.
Errores de validación en notas de crédito
- AP3011 → Documento con consecutivo ya está en proceso.
- AP3012 → Documento referenciado rechazado.
- AP3013 → El monto de la nota de crédito excede el total restante permitido.
- AP3014 → Nota de crédito de tipo cancelación no coincide exactamente con el monto restante.
- AP3015 → Nota de crédito con modificationCode = 2 tiene un total distinto de 0.
Estados y flujos adicionales a mapear
- status = PENDING: notas esperando validación de documento referenciado.
- status = FAILED: notas rechazadas por reglas de negocio internas antes de enviarse a la DGII.
- Nuevos códigos de error específicos (AP3012, AP3012, AP3013, AP3014, AP3016) que deben ser contemplados en el manejo de respuestas de la API.

✅ Recomendación: revisa tu integración para:

Manejar correctamente estados PENDING y FAILED.
Mapear los nuevos códigos de error (AP3011, AP3012, AP3013, AP3014, AP3016).
Adaptar tus procesos de conciliación y reintentos para contemplar notas en validación asincrónica.