AutoBill - Autofacturación DIAN para tu sistema POS

Introducción

AutoBill expone endpoints REST para recibir tickets de venta, generar códigos QR y completar el flujo de autofacturación electrónica.

Base URL

https://api.autobill.lat/v1

Sandbox

https://sandbox-api.autobill.lat/v1

Todos los requests de administración usan autenticación por header con token privado y, para operaciones de escritura, se recomienda idempotencia.

Autenticación

Incluye tu llave privada en el header de cada request.

Header requerido

http

x-api-key: ab_xxx
Content-Type: application/json

Request de ejemplo

bash

curl https://api.autobill.lat/v1/tickets \
  -X POST \
  -H "x-api-key: ab_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: pos-001" \
  -d '{ ... }'

Endpoints

Referencia y prueba interactiva para los endpoints principales.

POST/tickets

Crear ticket POS

Registra una venta y retorna token/URL del QR para autofacturación.

Parámetros

Parámetro	Tipo	Requerido	Descripción
ticket_number	`string`	Sí	Identificador único del ticket Validación: 1-80 caracteres
issued_at	`ISO 8601`	Sí	Fecha y hora de emisión Validación: formato datetime
currency	`string`	No	Moneda de la operación Validación: default COP
subtotal	`number`	Sí	Subtotal sin impuestos Validación: >= 0
tax_total	`number`	Sí	Total de impuestos Validación: >= 0
grand_total	`number`	Sí	Total final Validación: >= 0
items	`array`	Sí	Lista de líneas de venta Validación: 1-300 elementos

Respuesta exitosa

{
  "success": true,
  "data": {
    "ticket_id": "cmn8bf08u0008gao8i8v991iz",
    "ticket_number": "POS-SBX-0002",
    "qr_url": "http://localhost:3000/qr/98280dd73e34182dfbaf8229e226cf59",
    "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "duplicated": false
  }
}

Respuesta de error

{
  "success": false,
  "error": "Error en los datos enviados",
  "details": {
    "items": "Se requieren entre 1 y 300 items"
  }
}

Probar endpoint

POST/tickets

API Key

Para sandbox usa una clave con prefijo 'sk_test_'.

Payload (JSON)

POST/qr/{qr_token}/invoice

Solicitar factura desde QR

Recibe datos del cliente final para emitir factura electrónica del ticket asociado al token QR.

Parámetros

Parámetro	Tipo	Requerido	Descripción
document	`string`	Sí	Documento del cliente Validación: 5-30 caracteres
business_name	`string`	Sí	Nombre o razón social Validación: 3-180 caracteres
email	`string`	Sí	Correo de envío de factura Validación: email válido

Respuesta exitosa

{
  "success": true,
  "data": {
    "invoice_id": "cln2a3b4c5d6e7f8",
    "ticket_number": "POS-20260326-001",
    "status": "sent",
    "duplicated": false
  }
}

Probar endpoint

POST/qr/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9/invoice

Payload (JSON)

Webhooks

Recibe notificaciones asíncronas cuando cambie el estado de la factura. Recomendado para evitar polling constante.

Registrar webhook

POST /webhooks

bash

curl https://api.autobill.lat/v1/webhooks \
  -X POST \
  -H "x-api-key: ab_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: webhook-001" \
  -d '{
    "url": "https://pos.tudominio.com/webhooks/autobill",
    "events": ["invoice.stamped"],
    "secret": "whsec_123456789"
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "id": "wh_01j2k3l4m5n6",
    "url": "https://pos.tudominio.com/webhooks/autobill",
    "events": ["invoice.stamped"],
    "active": true,
    "created_at": "2026-03-27T03:10:00.000Z"
  }
}

Request enviado cuando la factura se timbra ante DIAN

AutoBill hará un POST a tu endpoint con el evento invoice.stamped.

Headers que recibes

http

POST /webhooks/autobill HTTP/1.1
Content-Type: application/json
x-autobill-signature: t=1711510000,v1=4f2bc3c3...
x-autobill-event: invoice.stamped

Body del webhook

json

{
  "id": "evt_01j2k3l4m5n6",
  "type": "invoice.stamped",
  "created_at": "2026-03-27T03:12:45.000Z",
  "data": {
    "ticket_id": "cmn8bf08u0008gao8i8v991iz",
    "ticket_number": "POS-SBX-0002",
    "invoice_id": "inv_01j2k3l4m5",
    "dian_status": "APPROVED",
    "dian_uuid": "cufe_9e4c5b...",
    "stamped_at": "2026-03-27T03:12:40.000Z",
    "customer": {
      "document": "12345678",
      "email": "cliente@correo.com"
    },
    "totals": {
      "currency": "COP",
      "subtotal": 500000,
      "tax_total": 22800,
      "grand_total": 522800
    }
  }
}

Verificación recomendada: valida la firma de x-autobill-signature usando tu secret antes de procesar el evento.

Modelos comunes de POS

Payloads base para escenarios de integración frecuentes.

Payload de ticket

json

{
  "ticket_number": "RES-20260326-1823",
  "issued_at": "2026-03-26T18:23:01Z",
  "currency": "COP",
  "subtotal": 54000,
  "tax_total": 10260,
  "grand_total": 64260,
  "items": [
    { "sku": "HAM-001", "description": "Hamburguesa", "quantity": 2, "unit_price": 18000, "tax_amount": 6840, "total_amount": 42840 },
    { "sku": "BEB-002", "description": "Bebida", "quantity": 2, "unit_price": 5000, "tax_amount": 950, "total_amount": 10950 }
  ]
}

Manejo de errores

Formato estándar y códigos HTTP de referencia.

Código	Significado	Acción sugerida
200/201	Operación exitosa	Consumir respuesta normalmente
400	Payload inválido	Corregir validaciones
401	Token inválido o ausente	Verificar header x-api-key
409	Duplicidad detectada	Revisar x-idempotency y ticket_number
500	Error interno	Reintentar con backoff exponencial

Formato de error

json

{
  "success": false,
  "error": "Error en los datos enviados",
  "details": {
    "field": "mensaje de validación"
  }
}

Siguiente paso

Si ya validaste requests en sandbox, configura tu entorno de producción y aplica rotación de llaves privadas.

Contactar soporte Ver quick start

Documentación API

Introducción

Autenticación

Endpoints

Crear ticket POS

Parámetros

Respuesta exitosa

Respuesta de error

Probar endpoint

Solicitar factura desde QR

Parámetros

Respuesta exitosa

Probar endpoint

Webhooks

Registrar webhook

Request enviado cuando la factura se timbra ante DIAN

Modelos comunes de POS

Manejo de errores

Siguiente paso