Saltar al contenido

Primeros pasos

Empezar

De cero a tu primera factura de prueba en cuatro pasos. Copia los ejemplos tal cual y córrelos desde tu servidor.

La URL base de la API es https://app.conta360.co/api/v1. No la confundas con la de esta documentación (api.conta360.co).

Antes de empezar#

  1. El administrador de la empresa entra a Configuración → Integraciones en Conta360 y crea una integración.
  2. Copia el client_id y el client_secret. El secreto se muestra una sola vez.
  3. Guárdalos en el servidor de tu sistema, como variables de entorno.

¿Todavía no tienes una empresa real? Pide a soporte una credencial de prueba del Restaurante Demo.

El administrador decide qué puede hacer la integración (los alcances), desde qué IP, cuántas peticiones por minuto y hasta qué fecha. Lo ves en detalle en Autenticación y alcances.

1. Pide un token#

bash
curl -X POST https://app.conta360.co/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"c360_live_…","client_secret":"sk_…"}'
json
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600, "scope": "productos.read facturas.write" }

Las demás llamadas llevan el encabezado Authorization: Bearer <access_token>.

bash
curl https://app.conta360.co/api/v1/productos?per_page=100 -H "Authorization: Bearer $TOKEN"
json
{
  "data": [
    {
      "id": "3f1c…",
      "codigo": "P-0001",
      "nombre": "Bandeja paisa",
      "precio": "38000.00",
      "unidad": "94",
      "impuesto": { "codigo": "04", "tarifa": "8.00" },
      "excluido_de_impuesto": false,
      "activo": true
    }
  ],
  "meta": { "page": 1, "per_page": 100, "total": 9, "total_pages": 1 }
}

Sincronízalo al abrir caja y cada tanto. Los precios e impuestos de la factura siempre salen de Conta360: si tu sistema manda otro precio, la API lo rechaza (salvo que el administrador le haya dado el alcance facturas.precio).

3. Emite tu primera factura#

Para tu primera prueba usa una credencial del Restaurante Demo (su client_id empieza por c360_test_): la factura se valida en el ambiente de pruebas de la DIAN, sin validez fiscal. Los ejemplos usan su catálogo. Si además agregas "borrador": true, el documento se guarda en Conta360 sin enviarlo a la DIAN.

bash
curl -X POST https://app.conta360.co/api/v1/facturas \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-00184" \
  -d '{
    "pedido": "Mesa 7 · 184",
    "borrador": true,
    "cliente": { "tipo_documento": "13", "identificacion": "1098765432", "nombres": "Ana Gómez", "correo": "ana@correo.com" },
    "items": [
      { "codigo": "P-0001", "cantidad": 2 },
      { "codigo": "P-0002", "cantidad": 1, "nota": "sin cebolla" }
    ],
    "pagos": [{ "forma": "1", "metodo": "49" }]
  }'

Fíjate en el encabezado Idempotency-Key: es obligatorio y debe ser estable por pedido. Si tu sistema reintenta, la DIAN no recibe la factura dos veces.

Cuando quites borrador, la respuesta 201 trae el número, el CUFE, el QR y el enlace público. Lo ves completo en Emitir facturas.

Siguiente paso#

Buscar en la documentación