Documentación Técnica de la API de Dataico - Factura Electrónica Sector Salud

Referencia completa: API DOCS Documentación Técnica FE

Autenticación

La API utiliza los parámetros Dataico_account_id y Auth-token como método de autenticación para la transmisión de facturas electrónicas del sector salud.

Para obtener estas credenciales: en Dataico, ve a Opciones (parte superior) > Configuración.

Numeración

Para obtener los datos de autorización de tu numeración o consecutivo de facturación electrónica:

Ventas > Facturas > Numeraciones > [Editar]

En la pantalla de edición encontrarás el prefijo, número de resolución y el consecutivo actual.

Crear Factura Electrónica para el Sector Salud

Método: POST

Endpoint: https://api.dataico.com/direct/dataico_api/v2/invoices

Headers:

Content-Type: application/json
Auth-token: <token de la cuenta DATAICO>

Tipos de operación aceptados

El campo operation de la factura acepta los siete tipos de operación del sector salud:

SS_RECAUDO · SS_POS · SS_CUFE · SS_CUDE · SS_SNUM · SS_REPORTE · SS_SIN_APORTE

Los ejemplos JSON de abajo cubren cuatro de ellos; SS_POS, SS_CUDE y SS_SNUM usan la misma estructura de campos de salud que SS_CUFE.

Versión de las reglas de salud (`version`)

El objeto health acepta el campo version, con dos valores: API_SALUD_V1 y API_SALUD_V2. Envía "version": "API_SALUD_V2": es la versión que aplica las validaciones de contrato, póliza y cobertura que se describen abajo, y la que documenta el Swagger.

Si la petición no envía version, la API usa API_SALUD_V1, que no aplica esas reglas: Dataico no revisa que la factura lleve contrato o justificación, que contrato y póliza no vayan juntos ni que la cobertura sea distinta de PLAN_DE_BENEFICIOS.

"health": {
  "version": "API_SALUD_V2",
  "period_start_date": "01/09/2026",
  "period_end_date": "30/09/2026",
  "provider_code": "1234567890",
  "payment_modality": "PAGO_POR_EVENTO",
  "coverage": "PLAN_DE_BENEFICIOS_CONTRIBUTIVO",
  "contract_number": "<número del contrato>"
}

Contrato, póliza y factura sin contrato

Con API_SALUD_V2, en SS_CUFE, SS_CUDE, SS_POS, SS_SNUM y SS_REPORTE:

El objeto health lleva exactamente uno de estos dos campos, nunca ambos ni ninguno: contract_number o invoice_without_contract.
contract_number y policy_number no pueden ir juntos, ni en la factura ni en cada elemento de associated_users.
policy_number se usa solo en atenciones SOAT o de planes voluntarios de salud. Como no va con contract_number, una factura con póliza lleva invoice_without_contract con la justificación que corresponda.
contract_number es el número del contrato objeto de facturación. Deberá ser el CUCON (Código Único de Contrato) que asigna el SIIFA del Ministerio de Salud, según el cronograma de implementación del SIIFA.

En SS_SIN_APORTE el número de contrato es opcional y esta regla no aplica. SS_RECAUDO no exige número de contrato ni justificación.

Factura sin contrato. invoice_without_contract es un entero entre 1 y 6 con el código de justificación del catálogo SISPRO facturaSinContrato. Los seis códigos y su significado están descritos en el campo dentro del Swagger. Un valor fuera de ese rango se rechaza con el error invoice_without_contract must be a justification code between 1 and 6.

En el XML emitido, la justificación viaja en el bloque FACTURA_SIN_CONTRATO:

schemeName: salud_facturaSinContrato.gc
schemeID: el código en dos dígitos (01 a 06)
Texto del valor: la descripción literal del catálogo SISPRO, no el código, tal como la compara la validación oficial

La interfaz de Dataico no tiene campo para invoice_without_contract ni para policy_number en estas operaciones, así que una atención sin contrato o con póliza se factura por esta API.

Cobertura y modalidad de pago

Con API_SALUD_V2, en las mismas cinco operaciones, la cobertura PLAN_DE_BENEFICIOS se rechaza, también dentro de associated_users. Usa PLAN_DE_BENEFICIOS_CONTRIBUTIVO para el régimen contributivo o PLAN_DE_BENEFICIOS_SUBSIDIADO para el subsidiado.
En payment_modality no uses OTRA_MODALIDAD: la Resolución 948 de 2026 ya no contempla esa modalidad. Ver Modalidad de Pago en facturas Sector Salud.

Recibos Referencia (`receipt_documents`)

Si tu cliente lleva su propio control de recepción de mercancía (un albarán, un DAFI, una guía de remisión), puedes enviar esos identificadores en la solicitud de creación con el campo opcional receipt_documents, un arreglo de textos:

"receipt_documents": ["ALB-4471", "DAFI-9930"]

Puedes enviar tantos como necesites, y repetir el mismo identificador.
Si no envías el campo, el documento se crea sin referencias.
Cada entrada viaja al XML de la DIAN y aparece en el PDF, en el bloque de datos junto a la Orden de Compra.

Es el mismo campo Recibos Referencia que se llena desde la interfaz de Dataico. Ver ¿Cómo agregar Recibos Referencia a una factura o nota?.

Códigos CUPS en los ítems

La API no tiene un campo exclusivo para el código CUPS (Clasificación Única de Procedimientos en Salud), ni en items, ni en health, ni en associated_users. Cada procedimiento se envía como un ítem:

sku: el código CUPS del procedimiento.
description: el nombre del procedimiento.

"items": [
  {
    "sku": "890201",
    "description": "Consulta de primera vez por medicina general",
    "quantity": 1,
    "price": 45000
  }
]

Dataico no valida el código contra el catálogo CUPS: sku acepta cualquier texto no vacío, así que revisa el código antes de enviarlo.
En el XML de la DIAN, sku viaja como identificación estándar del ítem (StandardItemIdentification, con schemeID="999") y description como descripción del ítem.
Si en tu catálogo de productos no existe un producto con ese sku, la API lo crea con el código como Referencia. Las facturas siguientes con el mismo código se asocian a ese producto, y la descripción de cada línea es la que envías en cada solicitud.
Dataico no genera los RIPS. Los códigos CUPS que exigen los RIPS se reportan allí, por fuera de Dataico.

Desde la interfaz, el equivalente es crear un producto por procedimiento, con el código CUPS en Referencia y el nombre del procedimiento en Descripción.

Estructuras JSON por Tipo de Operación

Los ejemplos de abajo no incluyen version: agrégale "version": "API_SALUD_V2" al objeto health y usa la cobertura del régimen que corresponda.

Tipo de operación SS Recaudo:

Tipo de operación SS CUFE:

Tipo de operación SS Reporte:

Tipo de operación SS Sin Aporte:

Tipos de Operación Salud

Para más detalles sobre los tipos de operación, su aplicación y los campos requeridos, consulta Tipos de operación del sector salud en Dataico.