Desarrolladores
OAuth para aplicaciones
Conecta tu aplicación a las empresas de tus usuarios sin pedirles una clave: cada persona autoriza qué puede hacer tu app y puede desconectarla cuando quiera.
Cuándo usar OAuth
Si tu integración es para tu propia empresa, una clave de API es más simple. Si construyes una aplicación que muchas empresas van a conectar, usa OAuth: cada persona autoriza a tu app desde Ally360, elige la empresa y ve exactamente qué podrá hacer. El token actúa en su nombre y nunca puede más que ella.
1. Registra tu aplicación
Escríbenos con el nombre de tu app, sus direcciones de regreso y los permisos que necesita. Te damos un client_id y, si tu app tiene servidor, un secreto que se muestra una sola vez. Las direcciones de regreso deben ser https; las apps de escritorio pueden usar http://127.0.0.1 con cualquier puerto.
2. Envía a la persona a autorizar
PKCE con S256 es obligatorio, también para apps con secreto. Genera un verificador aleatorio por intento, envía su hash como code_challenge y guarda el state para compararlo a la vuelta.
https://app.ally360.co/oauth/authorize
?response_type=code
&client_id=a360c_tu_app
&redirect_uri=https%3A%2F%2Ftu-app.example%2Fcallback
&scope=contacts%3Aread%20invoices%3Aread
&state=valor_aleatorio_por_intento
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256Si la persona acepta, vuelve a tu dirección con un código que vale un minuto y un solo uso. Comprueba que iss sea el de Ally360. Si cancela, llega error=access_denied.
https://tu-app.example/callback
?code=a360_oac_…
&state=valor_aleatorio_por_intento
&iss=https://api.ally360.co3. Cambia el código por tokens
curl -X POST https://api.ally360.co/oauth/token \
-u "a360c_tu_app:a360_ocs_tu_secreto" \
-d grant_type=authorization_code \
-d code=a360_oac_… \
-d redirect_uri=https://tu-app.example/callback \
-d code_verifier=el_verificador_que_generaste{
"access_token": "a360_oat_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "a360_ort_…",
"scope": "contacts:read invoices:read"
}Usa el access_token en la API como cualquier clave: Authorization: Bearer a360_oat_…. Vale una hora. Los límites de peticiones son los del plan de la empresa, contados por cada autorización.
4. Renueva sin volver a pedir permiso
Cada renovación entrega un token de renovación nuevo y el anterior deja de servir. Si alguien presenta uno ya usado, Ally360 lo toma como una filtración y desconecta tu app de esa empresa. Un reintento de red dentro de los 30 segundos siguientes sí se acepta.
curl -X POST https://api.ally360.co/oauth/token \
-u "a360c_tu_app:a360_ocs_tu_secreto" \
-d grant_type=refresh_token \
-d refresh_token=a360_ort_…5. Desconecta
Revocar el token de renovación desconecta tu app de la empresa y borra los webhooks que creó. La persona también puede desconectarla desde Configuración › Integraciones.
curl -X POST https://api.ally360.co/oauth/revoke \
-u "a360c_tu_app:a360_ocs_tu_secreto" \
-d token=a360_ort_…Permisos que puedes pedir
| 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 |
Los metadatos del servidor están en https://api.ally360.co/.well-known/oauth-authorization-server.