Novedades
Contáctanos
Start typing to search…
Back to All
Improved

Actualización en Eventos Electrónicos y Validaciones de Esquemas

17 days ago by Alegra

Se han implementado mejoras y nuevas funcionalidades en el API para la emisión y gestión de eventos electrónicos, así como el fortalecimiento de las validaciones en los esquemas de documentos electrónicos. Los cambios están orientados a simplificar el proceso de emisión de eventos, mejorar la integridad de los datos y garantizar un mayor cumplimiento con los estándares establecidos por la DIAN.

Las principales mejoras incluyen un nuevo endpoint que permite crear eventos electrónicos utilizando únicamente el CUFE de la factura, con extracción automática de información del emisor y receptor desde la DIAN. Adicionalmente, se han implementado validaciones numéricas más estrictas en todos los esquemas de documentos electrónicos (Facturas Electrónicas, Documentos Equivalentes POS y Documentos Soporte NAS) para prevenir errores y asegurar la consistencia de los datos enviados a la entidad gubernamental.

Nuevas Funcionalidades

Nuevo endpoint para crear eventos desde CUFE

Se ha implementado un nuevo endpoint que permite crear eventos electrónicos asociados a una factura utilizando únicamente su CUFE (Código Único de Factura Electrónica). Este endpoint simplifica significativamente el proceso de emisión de eventos al extraer automáticamente la información del emisor y receptor desde el XML de la factura consultado en la DIAN.

Endpoint: POST /events/from-cufe

Características principales:

  • Extracción automática de datos: La información del emisor (SenderParty) y receptor (ReceiverParty) se obtiene automáticamente del XML de la factura consultado en la DIAN, eliminando la necesidad de proporcionar estos datos manualmente.

  • Soporte para todos los tipos de eventos: Admite la emisión de los siguientes eventos:

    • 030 - Acuse de recibo: Requiere información del generador (issuerParty)
    • 031 - Reclamo: Requiere código de reclamo (claimCode) según tabla DIAN
    • 032 - Recibo del bien o la prestación del servicio: Requiere información del generador (issuerParty)
    • 033 - Aceptación expresa: Opcionalmente puede incluir notas adicionales
    • 034 - Aceptación tácita: Solo requiere el CUFE y número del evento

  • Validaciones mejoradas:

    • Validación de existencia del evento en la DIAN para prevenir duplicados
    • Validación del número de identificación de la empresa
    • Validación de formato del CUFE proporcionado

  • Campos requeridos mínimos:

    • type: Código del tipo de evento
    • number: Número del evento (puede ser alfanumérico)
    • uuid: CUFE de la factura a la que se asociará el evento

Ejemplo de uso:

{
  "type": "034",
  "number": "TA001",
  "uuid": "eb79739f6be3dc3fbeafasdsac331a72320a372469fd5270147c73c389ace6ad133c05d86a1ec9ff250bebc3e2ccc"
}

Mejoras en Eventos Electrónicos

Campo notes agregado a eventos

Se ha agregado el campo notes a todos los esquemas de eventos para permitir incluir información adicional en los eventos electrónicos.

Características:

  • Tipo: Array de strings
  • Longitud máxima por nota: 10,000 caracteres
  • Campo opcional
  • Campo oficial DIAN <Note>

Ejemplo:

{
  "type": "031",
  "number": "RJ001",
  "uuid": "...",
  "claimCode": "01",
  "notes": ["Factura con inconsistencias en los totales", "Se requiere revisión del documento"]
}

Campo taxCode agregado a ReceiverParty

Se ha agregado el campo taxCode al esquema ReceiverParty en los eventos electrónicos.

Características:

  • Tipo: String
  • Valores permitidos: "01" (IVA), "04" (INC), "ZA" (IVA e INC), "ZZ" (No aplica)
  • Valor por defecto: "ZZ" (No aplica)
  • Campo requerido
  • Campo oficial DIAN

Campo regimeCode removido de ReceiverParty

El campo regimeCode ha sido removido del esquema ReceiverParty para simplificar la estructura de datos y cumplir con los estándares de la DIAN.

Mejoras en IssuerParty

Se han realizado mejoras en el esquema IssuerParty:

  • Actualización de descripciones de campos
  • Reordenamiento de campos para mayor claridad
  • Campos requeridos actualizados: identificationType, identificationNumber, firstName, familyName

Inclusión de URL del XML en respuestas de eventos no aceptados

Cuando un evento no es aceptado por la DIAN, la respuesta ahora incluye la URL del archivo XML generado, facilitando el acceso al documento para revisión o depuración.

Cambio en respuesta:

Antes:

{
  "event": { ... }
}

Ahora:

{
  "event": { ... },
  "files": {
    "xml": "https://..."
  }
}

Este cambio aplica tanto para el endpoint /events como para el nuevo endpoint /events/from-cufe.

Mejoras en Validaciones

Validaciones numéricas en esquemas

Se han agregado validaciones de rango (minimum y maximum) a campos numéricos en los esquemas de documentos electrónicos para garantizar la integridad de los datos y cumplir con los estándares de la DIAN.

Campos actualizados:

En esquemas de Facturas Electrónicas (FE):

  • TotalAmounts:

    • grossTotal: minimum: 0
    • taxableTotal: minimum: 0
    • taxTotal: minimum: 0
    • discountTotal: minimum: 0
    • chargeTotal: minimum: 0
    • advanceTotal: minimum: 0
    • payableTotal: minimum: 0

  • Item:

    • discount: minimum: 0, maximum: 100
    • charge: minimum: 0, maximum: 100
    • subtotal: minimum: 0
    • taxAmount: minimum: 0

  • Tax:

    • taxAmount: minimum: 0
    • taxPercentage: minimum: 0, maximum: 100
    • taxableAmount: minimum: 0

En esquemas de Documentos Equivalentes POS:

  • TotalAmounts: Todos los campos con minimum: 0
  • Withholding:
    • taxPercentage: minimum: 0, maximum: 100
    • taxableAmount: minimum: 0
    • taxAmount: minimum: 0

En esquemas de Documentos Soporte NAS:

  • TotalAmounts: Todos los campos con minimum: 0

Impacto:

  • Los valores negativos en totales y montos de impuestos ahora son rechazados automáticamente
  • Los porcentajes de descuento y cargo están limitados al rango 0-100
  • Los porcentajes de impuestos están limitados al rango 0-100
  • Mejora la consistencia de datos y reduce errores en el procesamiento

Compatibilidad

  • Retrocompatibilidad: Todos los cambios son retrocompatibles con versiones anteriores de la API
  • Validaciones: Las nuevas validaciones solo rechazan valores inválidos que anteriormente podrían causar errores en la DIAN
  • Endpoints existentes: Los endpoints existentes mantienen su funcionalidad sin cambios
  • Campos opcionales: Los nuevos campos (notes, taxCode con valor por defecto) no afectan las peticiones existentes

Notas Importantes

  • Los valores negativos en campos numéricos ahora serán rechazados con un error de validación
  • Los porcentajes deben estar en el rango 0-100
  • El nuevo endpoint /events/from-cufe requiere que la factura exista en la DIAN y esté disponible para consulta
  • La información del emisor y receptor se obtiene automáticamente del XML de la factura, pero puede ser sobrescrita si se proporciona en el cuerpo de la petición
  • El campo regimeCode ya no debe enviarse en ReceiverParty - será rechazado si se incluye
  • El campo taxCode en ReceiverParty tiene un valor por defecto de "ZZ" si no se proporciona