[API FE DOM] Mejora de la documentación y unificación del formato de errores

🆕 Unificación del formato de errores y mejora en la documentación

Fecha

Disponible en sandbox Fecha tentativa de despliegue en producción: 3 de febrero de 2026

Tipo de cambio

Cambio de contrato / Mejora de documentación

📝 Descripción

A partir de esta versión se unifica y estandariza el formato de respuesta de errores de la API, con el objetivo de:

• Eliminar inconsistencias en las respuestas de error.
• Facilitar el manejo de errores por parte de integradores.
• Mejorar la trazabilidad y documentación de cada error mediante códigos únicos.

Este cambio viene acompañado de una mejora en la documentación, incorporando un diccionario de errores organizado por categorías.

⚠️

Importante Estos cambios se encuentran disponibles únicamente en el ambiente de sandbox, con el objetivo de que los integradores puedan adaptar y validar sus implementaciones con anticipación.

🔴 Comportamiento anterior

Anteriormente, las respuestas de error podían variar entre distintos formatos, por ejemplo:

{ "code": 400, "message": ["error message"] }

{ "code": 400, "errors": ["error message"] }

{ "errors": ["error message"] }

Esta falta de uniformidad dificultaba el parseo automático y el manejo consistente de errores.

✅ Nuevo formato unificado de errores

A partir de este cambio, todas las respuestas de error seguirán el siguiente formato:

{
  "code": 400,
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Error description in English",
      "field": "fieldName"
    }
  ]
}

📌 Detalle de los campos

• code (number) Código HTTP de la respuesta.

• errors (array) Lista de errores detectados durante el procesamiento de la request.

Cada objeto dentro de errors contiene:

• code (string) Identificador único del error.

• message (string) Descripción del error en inglés, orientada al diagnóstico técnico.

• field (string, opcional) Campo asociado al error, cuando aplica. Puede no enviarse si el error no está vinculado a un campo específico.

📚 Diccionario de errores

La documentación incorpora un diccionario de errores, organizado por categorías, entre ellas:

• Validaciones asincrónicas de compañías
• Validaciones sincrónicas de compañías
• Usuarios
• DGII
• Documentos
• Sets de prueba
• Acuses de recibo
• Validaciones de tipos
• Validaciones de esquemas
• Validaciones comunes
• Identificación de documento
• Documentos de referencia
• Moneda
• Descuentos o recargos
• Errores generales
• Configuración

ℹ️

Nota La lista de errores documentada no es exhaustiva. Pueden incorporarse nuevos errores y categorías en el futuro sin requerir cambios en el formato de respuesta.

⚠️ Impacto para integradores

• Este cambio modifica el contrato de respuesta de errores.

• Los formatos anteriores quedan deprecados.

• Se recomienda:

  • Adaptar el manejo de errores para consumir el array errors.
  • Utilizar el code de cada error como referencia principal.
  • Realizar las validaciones necesarias en sandbox antes del pase a producción.

🚀 Despliegue a producción

• Fecha tentativa de despliegue: 3 de febrero de 2026.
• En caso de que esta fecha se modifique, se comunicará oportunamente a los integradores.

📌 Estado

Activo en sandbox – Pendiente de despliegue a producción.