Retención electrónica 2.0 por API: qué cambia y cómo migrar desde la 1.0

Si emites comprobantes de retención desde tu sistema, conviene migrar a la retención 2.0: es el esquema que pide el ATS y lleva la información completa del documento sustento.

Qué cambia

• Retención 1.0: cada retención indica su documento sustento de forma resumida (tipo, número y fecha).
• Retención 2.0: además de las retenciones, incluye el documento sustento completo (la factura del proveedor) con su código de sustento tributario, número de autorización, fechas, el detalle con su tarifa de IVA y la forma de pago.

El endpoint

• Retención 2.0 (recomendada): POST /plataforma/api/v2/retencionats/emision
• Retención 1.0: POST /plataforma/api/v2/retencion/emision — obsoleta, pero sigue funcionando para las integraciones existentes.

Ambas usan la api_key del punto de emisión, en el cuerpo JSON o en la cabecera X-Api-Key.

El bloque «sustento»

La gran diferencia en el JSON es el objeto sustento:

"sustento": {
  "codigo_sustento_tributario": "01",
  "codigo_documento_sustento": "01",
  "numero_documento_sustento": "001001000000123",
  "numero_autorizacion": "...",
  "fecha_documento_sustento": "2026/07/10",
  "fecha_registro_contable": "2026/07/13",
  "items": [ { "codigo_principal": "SERV-001", "descripcion": "Mantenimiento", "tipo_iva": 4, "cantidad": 1, "precio_unitario": 1000.00 } ]
}

En lugar de items también puedes enviar gastos con los subtotales por tarifa. Las retenciones ya no repiten el documento sustento: lo toman de este bloque.

Pasos para migrar

1. Cambia el endpoint a retencionats/emision.
2. Arma el bloque sustento con los datos de la factura del proveedor que ya tienes en tu sistema de compras.
3. Quita de cada retención los campos del documento sustento.
4. Prueba en el ambiente de pruebas con la api_key de un punto de pruebas.

Con los SDK

Los SDK oficiales tienen el método retencion20(): en PHP (Azur\Sdk\Emision) y en JavaScript (EmisionClasica).

Encuentra el ejemplo completo en la guía de la API (pestaña Retención 2.0) y todos los campos en la referencia.

Migra hoy: crea tu cuenta gratis y prueba en el ambiente de pruebas.