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.
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.
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
| Permiso | Qué deja hacer |
|---|---|
| contacts:read | Ver clientes y proveedores |
| contacts:write | Crear y editar contactos |
| products:read | Ver productos, servicios y listas de precios |
| products:write | Crear y editar productos |
| inventory:read | Ver bodegas y existencias |
| invoices:read | Ver facturas y notas crédito |
| invoices:write | Crear facturas de venta |
| credit_notes:write | Crear notas crédito (devoluciones) |
| payments:read | Ver pagos recibidos |
| payments:write | Registrar pagos de facturas |
| webhooks:manage | Crear 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.
| Kickstart | 300 por minuto |
| Boost | 600 por minuto |
| Supreme | 1.200 por minuto |
| Empresa de pruebas | 60 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.
{
"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…"
}