OASF en Colombia: qué son, cómo elegirlos y cómo integrar su API en software de nómina

Por Ing. Carlos Méndez | 2 de septiembre de 2026

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.

El desarrollador tiene el XML de nómina generado y firmado. El siguiente paso es enviarlo. Pero la API del OASF contratado por el cliente acepta SOAP, la del próximo cliente acepta REST con OAuth, y un tercero requiere el XML en base64 dentro de un JSON. Los OASF no tienen un formato común. Lo que parece un paso simple — transmitir el documento — se convierte en tres integraciones diferentes que el ISV tiene que mantener.

Esta guía cubre todo lo que un equipo técnico necesita entender sobre los OASF: qué rol cumplen, cómo verificar la lista oficial de habilitados, qué criterios usar para elegir uno, cómo es la estructura típica de su API, y qué errores aparecen con más frecuencia durante la integración.

¿Qué es un OASF y qué rol cumple en la nómina electrónica?

Un OASF (Operador Autorizado de Facturación por Suscripción) es una entidad habilitada por la DIAN para recibir documentos electrónicos de nómina de los empleadores, validarlos previamente y transmitirlos a la entidad fiscal. Actuar como intermediario certificado: el empleador no envía sus documentos directamente a la DIAN, sino al OASF, que los valida, los registra y los retransmite. La DIAN devuelve al OASF la ApplicationResponse, que el OASF a su vez entrega al empleador (o a su software).

La diferencia con un Proveedor Tecnológico (PT) de facturación electrónica es importante: el PT actúa como intermediario para facturas, notas crédito y débito de venta; el OASF actúa como intermediario para documentos de nómina (NIDD y NANE). Son sistemas independientes con habilitaciones separadas. Un mismo proveedor puede ser PT y OASF, pero son roles diferenciados en la regulación.

Para un ISV, el OASF es un proveedor externo cuya API debe integrar. El ISV no valida los documentos — el OASF lo hace. Pero el ISV es responsable de generar el XML correcto, calcular el CUNE válido, aplicar la firma digital y manejar adecuadamente las respuestas de error que el OASF retorna.

Cómo verificar la lista oficial de OASF habilitados por la DIAN

La DIAN publica y actualiza la lista de OASF habilitados en su portal oficial. Para acceder a la lista vigente, el integrador debe consultar directamente el sitio de la DIAN en la sección de facturación electrónica y nómina electrónica. La lista incluye el nombre del operador, el NIT y el estado de habilitación. Un OASF puede ser suspendido o retirado — es recomendable validar el estado antes de iniciar una integración.

Adicionalmente, algunos OASF operan bajo acuerdos de sub-operador: el empleador contrata un servicio que internamente usa un OASF habilitado. En estos casos, el integrador debe verificar que el servicio contratado tenga acuerdo vigente con un OASF activo, no solo que el servicio exista. La cadena de responsabilidad es: software de nómina → proveedor de API → OASF habilitado → DIAN.

Criterios técnicos para elegir un OASF

Elegir un OASF implica evaluar tanto la capacidad técnica como la calidad de la DX (Developer Experience) de su API. Los criterios que más impactan la productividad del equipo integrador son los siguientes:

Tipo de API y protocolo

Los OASF en Colombia usan diferentes protocolos. Algunos ofrecen una API REST moderna con JSON y autenticación OAuth 2.0 o API Key. Otros mantienen interfaces SOAP/WSDL heredadas. Algunos aceptan el XML directamente; otros lo esperan encapsulado en base64 dentro de un campo JSON o dentro de un mensaje SOAP. La elección del protocolo impacta directamente el tiempo de integración y el costo de mantenimiento.

Sandbox con validaciones reales

El sandbox debe simular el comportamiento completo de la DIAN, incluyendo rechazos por esquema inválido, CUNE incorrecto, firma vencida y errores de reglas de negocio. Un sandbox que retorna éxito para cualquier documento no permite probar los escenarios más críticos. Antes de firmar con un OASF, el equipo técnico debe verificar que el sandbox responda con códigos de error reales.

Calidad de la documentación

La documentación debe incluir ejemplos completos de request y response para cada endpoint — no solo la descripción de los campos. Debe estar actualizada con la versión vigente del XSD de la DIAN. Si la documentación del OASF usa versiones de esquema desactualizadas, es una señal de alerta sobre la madurez del operador.

Capacidad de envío masivo y reintentos

Para ISVs con clientes de gran plantilla, la API del OASF debe soportar envíos en lote. Algunos OASF tienen límites de tasa (rate limits) que no están documentados hasta que se violan en producción. Verificar antes: ¿cuántos documentos por minuto admite el OASF? ¿Tiene cola automática de reintentos cuando la DIAN está en ventana de mantenimiento?

Estructura típica de la API de un OASF: request y response

No existe un estándar de API entre OASF. Sin embargo, la mayoría de los operadores modernos siguen un patrón común en su implementación REST. A continuación, la estructura típica de una llamada de envío de NIDD:

// Request típico a la API REST de un OASF
POST /api/v1/nomina/documentos
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "nit_empleador": "900123456",
  "ambiente": "2",
  "documento_xml_base64": "PD94bWwgdmVyc2lvbi...",
  "tipo_documento": "102",
  "numero_documento": "NE-2026-001234"
}

// Response exitosa
{
  "codigo": "0",
  "descripcion": "Documento recibido y transmitido a la DIAN",
  "cune": "abc123...sha384hash...",
  "estado_dian": "APROBADO",
  "application_response_base64": "PD94bWwgdmVyc2lvbi...",
  "fecha_transmision": "2026-09-02T10:15:00Z"
}

El campo más importante de la respuesta es el ApplicationResponse codificado, que contiene el XML de validación de la DIAN. El integrador debe decodificarlo, parsearlo y almacenarlo junto al CUNE del documento para auditoría. Algunos OASF omiten el ApplicationResponse en la respuesta REST y lo envían por webhook — el ISV debe contemplar ambos patrones.

Errores comunes al integrar un OASF por primera vez

La mayoría de los problemas en la primera integración con un OASF no provienen del XML de nómina sino de la capa de transporte. Los errores más frecuentes son:

Token de autenticación expirado sin manejo en el código: los tokens OAuth del OASF tienen tiempo de vida variable. Si el integrador no implementa renovación automática del token, los envíos fallan silenciosamente en producción con código 401.

Confusión entre ambiente sandbox y producción: el NIT del empleador en sandbox generalmente es diferente al de producción, y el OASF usa URLs base distintas. Enviar al endpoint de sandbox con NIT de producción genera rechazos que no son errores del XML.

Timeout sin reintentos: si la DIAN tarda más de lo esperado, el OASF puede retornar timeout. El integrador que no implementa polling o webhook recibe un error transiente y marca el documento como fallido cuando en realidad puede estar en proceso.

Base64 con saltos de línea: algunos stacks generan base64 con saltos de línea cada 76 caracteres (RFC 2045). Algunos OASF esperan base64 sin saltos. El error resultante es un XML corrompido que la DIAN rechaza.

Soporte a múltiples OASF en un mismo software: estrategia de abstracción

Un ISV que atiende clientes en distintas empresas se encontrará con que cada cliente tiene su OASF preferido o contratado. Implementar una integración directa con cada OASF es insostenible a medida que crece el portafolio. La estrategia recomendada es una capa de abstracción que separa la lógica de generación del XML (responsabilidad del ISV) de la lógica de transporte al OASF (responsabilidad del adaptador).

El patrón recomendado es un adaptador por OASF que expone una interfaz común: enviarDocumento(xml, credenciales) → ResultadoTransmision. El núcleo del software trabaja solo con esta interfaz. Los adaptadores manejan las particularidades de cada operador. Cuando el cliente cambia de OASF, solo se agrega o activa el adaptador correspondiente, sin tocar la lógica de generación.

Preguntas frecuentes sobre OASF en Colombia

¿Cuál es la diferencia entre un OASF y un PT en Colombia?

Un PT (Proveedor Tecnológico) es el intermediario habilitado por la DIAN para transmitir facturas electrónicas de venta. Un OASF es el intermediario habilitado para transmitir documentos de nómina electrónica. Son figuras regulatorias distintas con habilitaciones independientes. Un mismo proveedor puede tener ambas habilitaciones, pero operar como PT no le autoriza automáticamente a operar como OASF.

¿Cómo puedo saber si el OASF de mi cliente sigue habilitado?

La única fuente de verdad es la lista oficial publicada por la DIAN. Consultar el portal oficial y verificar que el operador aparezca con estado habilitado activo. Algunos OASFs han sido suspendidos temporalmente por incumplimiento de requisitos técnicos. Un sistema de monitoreo en el software que verifique periódicamente el estado del OASF activo puede prevenir interrupciones no anticipadas.

¿Qué diferencia hay entre el sandbox del OASF y el ambiente de pruebas de la DIAN?

El sandbox del OASF puede ser independiente del ambiente de pruebas de la DIAN (ambiente 2). Algunos OASF tienen un sandbox interno que simula las respuestas DIAN sin conectarse realmente al ambiente de pruebas fiscal. Otros OASF conectan su sandbox directamente al ambiente de pruebas DIAN. La diferencia es relevante: en el primer caso, las simulaciones pueden divergir del comportamiento real de la DIAN; en el segundo, se prueban los escenarios reales.

¿Es posible cambiar de OASF sin perder el historial de documentos?

Sí, pero el historial de ApplicationResponses almacenado por el OASF anterior no migra automáticamente. La DIAN tiene su propio registro de los documentos transmitidos asociados al NIT del empleador, independientemente del OASF. Para el integrador, lo crítico es que el software haya almacenado los CUNEs y los ApplicationResponses de cada documento procesado — ese historial pertenece al empleador y no debe depender del OASF.

Sobre el autor

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.