NuevoAlly IA ya responde con las cifras de tu negocioPruébala →

Desarrolladores

API pública de Ally360

Conecta tu tienda en línea o tu propio sistema con Ally360: claves por empresa, contactos, productos, existencias, facturas, pagos y webhooks firmados.

1. Crea una clave

En Ally360 ve a Configuración › Desarrolladores y crea una clave con los permisos que necesita tu integración. La clave completa se muestra una sola vez. Cada clave puede, como máximo, lo que hoy puede la persona que la creó: si esa persona pierde un permiso, la clave también.

Comprueba la clave
curl https://api.ally360.co/v1/me \
  -H "Authorization: Bearer a360_live_tu_clave"

2. Prueba sin riesgo

Desde la misma pantalla puedes crear tu empresa de pruebas. Sus claves empiezan por a360_test_, no necesitan plan y nada de lo que hagas en ella llega a la DIAN. Con POST /v1/sandbox/events simulas un evento, como la aceptación de una factura por la DIAN, para probar tus webhooks.

3. Crea documentos sin duplicarlos

Crear facturas, pagos y productos exige la cabecera Idempotency-Key con un UUID por intento: si repites la misma petición, recibes la misma respuesta y no se crea un segundo documento.

Crear una factura abierta
curl -X POST https://api.ally360.co/v1/invoices \
  -H "Authorization: Bearer a360_live_tu_clave" \
  -H "Idempotency-Key: 4f1c0c55-2a8e-4f0e-9a36-6f2b1b8d2c11" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<id del contacto>",
    "status": "open",
    "prices_include_tax": true,
    "lines": [{ "product_id": "<id del producto>", "quantity": "2", "unit_price": "59500" }]
  }'

Con prices_include_tax el precio unitario es el que paga el cliente (el de tu tienda) y Ally360 calcula la base con los impuestos de cada producto. Sin él, el precio es la base y los impuestos se suman.

Un producto que nace con initial_stock necesita unit_cost y opening_origin: sin costo ni origen, la existencia no se puede contabilizar y la API responde 422.

Permisos de las claves

PermisoQué deja hacer
contacts:readVer clientes y proveedores
contacts:writeCrear y editar contactos
products:readVer productos, servicios y listas de precios
products:writeCrear y editar productos
inventory:readVer bodegas y existencias
invoices:readVer facturas y notas crédito
invoices:writeCrear facturas de venta
credit_notes:writeCrear notas crédito (devoluciones)
payments:readVer pagos recibidos
payments:writeRegistrar pagos de facturas
webhooks:manageCrear y borrar webhooks

Límites

Peticiones por minuto y clave. Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; al pasarte recibes 429 con Retry-After. El plan gratuito no incluye API.

Kickstart300 por minuto
Boost600 por minuto
Supreme1.200 por minuto
Empresa de pruebas60 por minuto

Errores y paginación

Los errores siguen el formato RFC 7807 (application/problem+json). Las listas se paginan con cursor: pide la siguiente página con ?cursor= y el next_cursor de la respuesta, y usa updated_since para sincronizar sólo lo que cambió. Los importes llegan como texto decimal.

Un error
{
  "type": "https://ally360.co/desarrolladores/errores#api_scope_missing",
  "title": "La clave no tiene el permiso necesario: invoices:write.",
  "status": 403,
  "code": "API_SCOPE_MISSING",
  "request_id": "b0d6…"
}
¿Tienes dudas?