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

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.

URL de autorización
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=S256

Si 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.

La vuelta
https://tu-app.example/callback
  ?code=a360_oac_…
  &state=valor_aleatorio_por_intento
  &iss=https://api.ally360.co

3. Cambia el código por tokens

Canje
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
Respuesta
{
  "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.

Renovación
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.

Revocación
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

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

Los metadatos del servidor están en https://api.ally360.co/.well-known/oauth-authorization-server.

¿Tienes dudas?