[API FE CRI] Actualización de validaciones y documentación para comprobantes v4.4

Fecha de entrada en vigencia: Por confirmar (El cambio esta disponible en el ambiente de sandbox, pronto daremos actualizaciones confirmando su vigencia en producción).

Actualizamos las validaciones, los mensajes de error y la documentación Swagger/OpenAPI de la API de Costa Rica para comprobantes electrónicos v4.4.

Esta actualización permite identificar con mayor claridad los datos requeridos durante la emisión, consultar el catálogo CAByS correspondiente a la versión v4.4 y recibir respuestas de error más breves y accionables.

Aplica a los siguientes documentos:

• 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?

1. Código de tarifa requerido para IVA de cálculo especial

El campo itemDetails[].taxes[].feeCode también será obligatorio cuando el código de impuesto sea 07 —IVA de cálculo especial— en una línea normal del documento.

La obligatoriedad para el código 01 —IVA— se mantiene.

En los surtidos, cada componente declara su propia tarifa mediante itemDetails[].assortmentDetails[].taxes[].feeCode, según el impuesto correspondiente.

Para las facturas electrónicas de compra, feeCode es obligatorio para los códigos 01 y 07, sin la excepción de surtidos.

Acción recomendada

Revisar las solicitudes que utilicen el impuesto 07 e incluir el código de tarifa correspondiente cuando sea requerido.

Ejemplo ilustrativo de un impuesto con código de tarifa:

{
  "code": "07",
  "feeCode": "08",
  "fee": "13",
  "amount": "130.00"
}

Los valores de tarifa y monto deben corresponder a la operación que se está documentando.

2. Otros cargos: omitir el campo cuando no existan

La documentación ahora indica expresamente que otherCharges, cuando se envía, debe contener entre 1 y 15 elementos.

La API ya rechazaba los arreglos vacíos. Esta actualización incorpora esa condición en el contrato Swagger/OpenAPI mediante minItems: 1.

Una solicitud con:

{
  "otherCharges": []
}

produce una respuesta HTTP 400 con el código AP0083.

Acción recomendada

Si el documento no tiene otros cargos, omitir la propiedad otherCharges de la solicitud en lugar de enviar un arreglo vacío.

3. Catálogo CAByS correspondiente a v4.4

La documentación de itemDetails[].code aclara que el valor debe ser un código CAByS válido del catálogo vigente del Banco Central de Costa Rica.

Tener 13 dígitos no es suficiente: el código debe existir en el catálogo aplicable.

Además, el endpoint de consulta devolverá únicamente los códigos del catálogo utilizado para comprobantes v4.4.

Producción:

GET https://api.alanube.co/cri/v1/hacienda/cabys

Sandbox:

GET https://sandbox-api.alanube.co/cri/v1/hacienda/cabys

Acción recomendada

Actualizar los catálogos almacenados en la integración y verificar que los códigos enviados correspondan a v4.4. No asumir que un código utilizado en versiones anteriores sigue siendo válido.

4. Mensajes de error más breves para códigos inválidos

Las respuestas por códigos CAByS o actividades económicas inválidas dejarán de incluir el catálogo completo de valores permitidos.

En su lugar, el mensaje identificará el valor rechazado e indicará el endpoint donde consultar el catálogo correspondiente.

Los enlaces incluidos en los mensajes corresponderán al ambiente utilizado: producción o sandbox.

Acción recomendada

Usar errors[].code para identificar el tipo de error y consultar el catálogo indicado para corregir el dato. Evitar depender del texto completo del mensaje o extraer valores permitidos desde la respuesta de error.

5. Ejemplos de emisión actualizados

Los ejemplos de Swagger/OpenAPI se ajustaron para:

• Incluir feeCode en los impuestos con código 01.
• Omitir otherCharges cuando no existen otros cargos.
• Aclarar las condiciones de uso de feeCode y de los códigos CAByS.

Recomendaciones para integradores

Antes de emitir comprobantes v4.4:

1. Verificar que los impuestos 01 y 07 incluyan feeCode cuando corresponda.
2. Revisar la excepción del impuesto 07 en la línea principal de un surtido.
3. Omitir otherCharges si no existen cargos adicionales.
4. Actualizar el catálogo CAByS desde el endpoint de consulta.
5. Identificar los errores mediante errors[].code y consultar los catálogos desde sus endpoints.