Actualización Documento Equivalente

Este documento describe las mejoras y ajustes implementados en el API para la emisión de documentos equivalentes POS y NAS. Los cambios incluyen nuevas validaciones, elementos obligatorios, reordenamiento de campos y mejoras en la estructura de objetos para garantizar mayor compatibilidad con los requerimientos de la DIAN.

Cambios implementados

1. Objeto payments ahora obligatorio

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: El objeto payments se ha convertido en obligatorio para todas las emisiones. Además, se actualizaron los textos para paymentForm y paymentDueDate.

Cambios:

El objeto payments es ahora obligatorio
Actualización de textos descriptivos para mejor claridad
Nuevas validaciones implementadas

Antes:

{
  "payments": { // Opcional
    "paymentForm": "1",
    "paymentDueDate": "2024-12-31"
  }
}

Después:

{
  "payments": { // OBLIGATORIO
    "paymentForm": "1",
    "paymentDueDate": "2024-12-31"
  }
}

Validaciones:

El objeto payments debe estar presente en todas las peticiones
paymentForm debe contener un código válido de forma de pago
paymentDueDate debe tener formato de fecha válido (YYYY-MM-DD)

2. Nuevo elemento sellersItemIdentification en items

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Se agregó un nuevo elemento opcional sellersItemIdentification dentro del objeto items.

Estructura:

{
  "items": [
    {
      "sellersItemIdentification": { // NUEVO - Opcional
        "id": "SKU123",
        "extendedId": "EXT-SKU-123"
      }
    }
  ]
}

Elementos del objeto:

id (string, opcional): Identificador del producto por parte del vendedor
extendedId (string, opcional): Identificador extendido del producto

Campo oficial DIAN: <SellersItemIdentification>

Validaciones:

Ninguna validación especial requerida (elemento completamente opcional)

3. Eliminación del elemento note de la documentación

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Se elimina el elemento note de la documentación para cumplir con la normativa.

4. Ajustes en el objeto taxes dentro de items

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Reordenamiento de elementos y actualización de validaciones en el objeto taxes.

Nuevo orden de elementos:

taxCode
taxPercentage
taxableAmount
taxAmount
unitCode

Cambios importantes:

Actualización de la lista de códigos de impuestos válidos
Nuevas validaciones para coherencia matemática
Textos descriptivos mejorados

Validaciones:

taxAmount debe ser el resultado de: (taxPercentage × taxableAmount) / 100
taxCode debe estar en la lista actualizada de códigos válidos
Validación de coherencia entre todos los campos numéricos

Códigos de impuestos actualizados:

Código	Nombre
01	IVA
02	IC
03	ICA
04	INC
08	IC Porcentual
20	FtoHorticultura
21	Timbre
22	INC Bolsas
23	INCarbono
24	INCombustibles
25	Sobretasa Combustibles
26	Sordicom
30	IC Datos
32	ICL
33	INPP
34	IBUA
35	ICUI
36	ADV
ZZ	Nombre de la figura tributaria

5. Ajustes en el objeto withholdings dentro de items

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Eliminación y reordenamiento de elementos en el objeto withholdings.

Elementos eliminados:

unitCode (ya no se incluye)

Nuevo orden de elementos:

taxCode
taxPercentage
taxableAmount
taxAmount

Validaciones:

taxAmount = (taxPercentage × taxableAmount) / 100
taxCode debe ser válido para retenciones
Validación matemática obligatoria entre campos relacionados

6. Modificaciones en el objeto totalAmounts

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Ajustes en textos, eliminación de elementos de la documentación y cambios en obligatoriedad.

Cambios principales:

advanceTotal: Eliminado de la documentación para cumplir con la normativa
grandTotal: Cambiado a opcional
totalToPay: Cambiado a opcional
Textos descriptivos actualizados

Estructura actualizada:

{
  "totalAmounts": {
    "taxInclusiveAmount": "1190.00", // Obligatorio
    "taxExclusiveAmount": "1000.00", // Obligatorio
    "grandTotal": "1190.00", // Ahora opcional
    "totalToPay": "1190.00" // Ahora opcional
    // advanceTotal eliminado de la documentación
  }
}

Validaciones:

Coherencia matemática entre todos los totales
taxInclusiveAmount y taxExclusiveAmount siguen siendo obligatorios

7. Mejoras en el objeto discountsAndCharges

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Reordenamiento de elementos, nuevo campo reasonCode y cambios en el comportamiento del campo reason.

Nuevo orden de elementos:

isCharge
reasonCode (NUEVO)
baseAmount
percentageAmount
amount
reason

Nuevo campo reasonCode:

{
  "discountsAndCharges": [
    {
      "isCharge": false,
      "reasonCode": "01", // NUEVO - Obligatorio cuando isCharge = false
      "baseAmount": "1000.00",
      "percentageAmount": "10.00",
      "amount": "100.00",
      "reason": "Descuento por volumen" // Ahora opcional
    }
  ]
}

Campo reasonCode:

Obligatorio cuando isCharge = false (es un descuento)
Opcional cuando isCharge = true (es un cargo)
Valores permitidos: "00" (Descuento no condicionado), "01" (Descuento condicionado)
Valor por defecto: "01"

Campo reason actualizado:

Ahora es opcional
Si no se envía, se asigna automáticamente:
- "Cargo" cuando isCharge = true
- "Descuento" cuando isCharge = false

Campo oficial DIAN: <AdditionalAccountID>

Validaciones:

reasonCode solo acepta valores "00" o "01"
percentageAmount no debe ser mayor a 100
Si isCharge = false y no se envía reasonCode, se envía "01" a la DIAN automáticamente

8. Nuevo array withholdings a nivel de documento

Aplica a: Documento Equivalente únicamente

Descripción: Se agregó un nuevo array opcional withholdingTaxTotal a nivel del documento principal.

Estructura:

{
  "withholdingTaxTotal": [ // NUEVO - Array opcional
    {
      "taxCode": "05",
      "taxPercentage": "10.00",
      "taxableAmount": "1000.00",
      "taxAmount": "100.00"
    }
  ],
  "totalAmounts": {
    // ... resto del objeto
  }
}

Descripción del array:

Si el emisor es autorretenedor, puede usar este objeto para reportar autorretenciones totales a nivel general del documento (como ReteIVA o ReteFuente). Para reportarlas por línea, use el objeto withholdings dentro de items.

⚠️ Si se incluye información en ambos niveles, la DIAN sumará los valores.

Elementos de cada objeto:

taxCode (string, requerido): Código del impuesto
taxPercentage (string, requerido): Porcentaje de retención
taxableAmount (string, requerido): Base gravable
taxAmount (string, requerido): Valor de la retención

Campo oficial DIAN: <WithholdingTaxTotal>

Validaciones:

taxCode solo acepta códigos: 05, 06, 07
taxAmount = (taxPercentage × taxableAmount) / 100
Validación matemática obligatoria

9. Corrección en name y tradeName para visualización DIAN

Aplica a: Documento Equivalente y su Nota de Ajuste

Descripción: Ajuste en la generación del XML para corregir la visualización en el PDF generado por la DIAN.

Comportamiento actualizado:

Si el usuario envía tradeName en el objeto customer, se replica esa información en el elemento Name del grupo PartyName en el XML
Si no se envía tradeName, se replica la información de name

Ejemplo:

{
  "customer": {
    "name": "EMPRESA ABC S.A.S",
    "tradeName": "ABC Store" // Si se envía, este será el que aparezca en DIAN
  }
}

XML generado:

<PartyName>
  <Name>ABC Store</Name> <!-- Usa tradeName si está disponible -->
</PartyName>

Validaciones:

Si se proporciona tradeName, debe ser una cadena no vacía
La lógica de prioridad funciona automáticamente sin configuración adicional

Consideraciones importantes

Migración

Para implementar estos cambios:

Actualizar objetos obligatorios: Asegúrese de incluir el objeto payments en todas las peticiones
Verificar cálculos: Implemente las validaciones matemáticas requeridas
Probar integraciones: Ejecute pruebas completas para verificar compatibilidad

Soporte

Si tiene preguntas sobre estos cambios o necesita asistencia con la implementación, por favor contacte al equipo de soporte técnico a través de los canales habituales.