[API FE CRI] Actualización en el control de numeraciones durante la emisión

Comunicación para usuarios e integradores

Fecha de entrada en vigencia: <fecha>

Hemos incorporado un nuevo control para evitar que una misma numeración consecutiva sea utilizada más de una vez por la misma compañía durante la emisión de documentos electrónicos.

El control aplica a:

• facturas electrónicas
• tiquetes electrónicos
• notas de crédito
• notas de débito
• facturas electrónicas de exportación
• facturas electrónicas de compra

¿Qué cambia?

Al solicitar la emisión de un documento, el sistema verificará la combinación de:

identificación de la compañía + numeración consecutiva

Si esa combinación ya está siendo procesada o ya fue utilizada, la nueva solicitud será rechazada con una respuesta HTTP 400 y un código específico.

Este comportamiento permite identificar claramente si existe una operación en curso o un documento previo asociado con la misma numeración.

Situaciones que se evitan

La actualización reduce los siguientes casos:

• emisión duplicada por solicitudes simultáneas
• reutilización accidental de una numeración ya consumida
• creación de más de un documento por reintentos concurrentes
• reenvíos automáticos que intentan crear nuevamente el mismo comprobante
• diferencias entre documentos originadas por utilizar la misma numeración con claves distintas
• intentos repetidos después de que Hacienda ya recibió o reconoció el documento

Respuestas que se busca mitigar

El control busca detectar el uso repetido antes de que genere respuestas posteriores como:

• códigos de Hacienda -99 o 99 indicando que la numeración consecutiva ya existe
• mensajes indicando que la numeración ya está asociada con otra clave
• respuestas con el texto El comprobante [clave] ya fue recibido anteriormente.
• resultados inciertos provocados por enviar simultáneamente el mismo documento más de una vez

Estas respuestas todavía pueden presentarse en casos externos, reintentos antiguos o solicitudes que ya se encontraban en curso. Cuando el sistema identifique evidencia de que Hacienda ya recibió el comprobante o conoce la numeración, conservará esa condición para impedir un nuevo uso.

Nuevas respuestas de emisión

AP3017: numeración en proceso

Esta respuesta indica que ya existe una solicitud activa para la misma identificación de compañía y numeración consecutiva.

HTTP: 400 Bad Request

{
  "message": "Bad request",
  "errors": [
    {
      "code": "AP3017",
      "message": "numeration is already in process"
    }
  ]
}

Acción recomendada

• No enviar solicitudes concurrentes con la misma numeración.
• Esperar el resultado de la solicitud original.
• Consultar el estado del documento original antes de intentar otra acción.
• Si el estado no puede determinarse, seguir el mecanismo habitual de consulta o soporte en lugar de crear un documento nuevo.

AP3018: numeración ya utilizada

Esta respuesta indica que la numeración ya está asociada con un documento consumido y no puede volver a utilizarse para una emisión diferente.

HTTP: 400 Bad Request

Respuesta base:

Cuando el identificador del documento existente está disponible, el mensaje puede incluirlo:

{
  "message": "Bad request",
  "errors": [
    {
      "code": "AP3018",
      "message": "numeration was already used by idDocument:<document-id>"
    }
  ]
}

Acción recomendada

• No reintentar la emisión como un documento diferente usando la misma numeración.
• Si la solicitud era un reintento del documento original, consultar ese documento en lugar de crear otro.
• Utilizar idDocument para localizar el documento existente cuando el dato esté presente.
• Si realmente se necesita emitir un documento distinto, asignar una numeración nueva según la secuencia autorizada de la compañía.
• Contactar soporte si no es posible identificar el documento existente o si se considera que la numeración no debería estar consumida.

Diferencia entre AP3017 y AP3018

Recomendaciones para integradores

Evitar concurrencia por numeración

No ejecutar en paralelo dos solicitudes que compartan:

identificación de compañía + numeración consecutiva

La aplicación cliente debe mantener una sola operación activa para esa combinación.

Tratar los reintentos como idempotentes

Antes de reintentar una solicitud por timeout, desconexión o respuesta incierta:

1. Consultar si el documento original fue registrado.
2. Consultar su estado actual.
3. Evitar crear un segundo documento con los mismos datos y numeración.

No depender solamente del HTTP 400

Otros errores de validación también pueden responder HTTP 400. La acción correcta debe decidirse usando:

errors[].code

Comportamiento esperado por escenario

Ejemplo de manejo en una integración

const error = response.errors?.[0];

if (error?.code === 'AP3017') {
  // No crear otro documento. Consultar la operación que ya está en curso.
  await consultarDocumentoOriginal();
}

if (error?.code === 'AP3018') {
  // No reutilizar la numeración. Buscar el documento ya existente.
  const existingDocumentId = extraerIdDocument(error.message);
  await consultarDocumentoExistente(existingDocumentId);
}

El ejemplo es ilustrativo. Cada integración debe mantener su estrategia de consulta, trazabilidad y reintentos.