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

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

Autenticación

Cada petición lleva el encabezado Auth-token. Ahí puedes enviar cualquiera de estas dos credenciales:

Una llave API creada por tu empresa en Opciones > Configuración, botón Llaves API. Es la opción recomendada para integraciones nuevas. Ver ¿Cómo crear y revocar llaves API en Dataico?.
El Auth Token de la cuenta, que aparece en Opciones (parte superior) > Configuración.

Además, el cuerpo de la factura debe traer el campo dataico_account_id con el Dataico Account Id de la cuenta, que también aparece en Opciones > Configuración. Debe ser exactamente la cuenta a la que pertenece la credencial del Auth-token (o la empresa hija, si eres aliado y usas el encabezado x-on-behalf-of). Si no coincide, la API responde Debe enviar un dataico account id válido (debe ser un uuid como a7ec34ae-f30b-40e8-b3a8-93bfc4c37d70).

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 de la numeración encontrarás el prefijo, número de resolución y el consecutivo actual.

Si tu resolución todavía no aparece en Dataico, puedes traerla de la DIAN por API (ver Vincular resoluciones de la DIAN por API).

Ambiente (`env`) y numeración flexible

Dos campos de la factura deciden cómo se procesa:

env es obligatorio y solo acepta PRUEBAS o PRODUCCION. Con PRUEBAS la API solo busca las numeraciones de pruebas de la habilitación ante la DIAN (resolución 18760000001); con PRODUCCION, solo las de producción. Si envías otro valor, la API responde Ambiente debe ser PRUEBAS o PRODUCCION.
numbering.flexible define qué tan estricto es el consecutivo. Por defecto es true: basta con que el número esté dentro del rango de la resolución y no exista todavía. Con false, el número debe ser exactamente el siguiente de la numeración.

Crear Factura Electrónica

Método: POST

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

Headers:

Content-Type: application/json
Auth-token: <tu llave API o el Auth Token de la cuenta>

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?.

Estructuras JSON disponibles

Vincular resoluciones de la DIAN por API

Este endpoint consulta en la DIAN las resoluciones autorizadas al software de facturación de tu empresa y las crea o asocia como numeraciones en Dataico. Sirve, por ejemplo, cuando acabas de solicitar una resolución nueva y quieres usarla desde tu integración sin entrar a la interfaz.

Método: POST

Endpoint: https://api.dataico.com/direct/dataico_api/v2/numberings/sync_dian/invoice

Para resoluciones de Documento Soporte, usa support-doc en lugar de invoice: https://api.dataico.com/direct/dataico_api/v2/numberings/sync_dian/support-doc

Headers:

Content-Type: application/json
Auth-token: <tu llave API o el Auth Token de la cuenta>

No necesita cuerpo.

Respuesta de ejemplo:

{
  "numberings": [
    {
      "prefix": "<prefijo>",
      "dian_resolutions": [
        {
          "number": "<número de resolución>",
          "start": 1,
          "end": 1000,
          "technical_key": "<clave técnica>",
          "start_date": "<dd/MM/yyyy>",
          "end_date": "<dd/MM/yyyy>",
          "code": "SDJ-001",
          "code_msg": "<mensaje>"
        }
      ]
    }
  ]
}

Cada resolución trae un code (SDJ-001 o SDJ-002) y un code_msg que indica si la resolución ya existía en tu cuenta o si se acaba de agregar. Si usas otro valor en lugar de invoice o support-doc, la API responde con un error que te indica los dos módulos válidos.

Listar tus numeraciones

Para ver las numeraciones que ya tiene la cuenta:

Método: GET

Endpoint: https://api.dataico.com/direct/dataico_api/v2/numberings/{modulo}

Donde {modulo} es invoice, credit-note, debit-note o support-doc. La respuesta tiene la misma forma que la de vincular resoluciones.