El permiso de la gestora

Cada gestora da permiso a tu software desde Qbox. Es OAuth 2.0 con código de autorización y PKCE (RFC 6749 y RFC 7636).

El recorrido

1. La conexión empieza en tu software o en Qbox. Desde Qbox, en «Conecta tu software», la gestora elige el tuyo y la llevamos a tu connectUrl, la que pongas en tu área. Allí entra en tu software, que sabe quién es.
2. Tu software la manda a pedir permiso a https://app.findqbox.com/oauth/authorize, con response_type=code, client_id, redirect_uri (una de las de tu área), scope, state y code_challenge con code_challenge_method=S256.
3. La gestora da permiso en Qbox. Ve lo que podrá hacer tu software y lo que no, elige adónde le llegan las solicitudes y acepta las condiciones de Qbox para los centros.
4. Volvemos a tu redirect_uri con code y state. El código vale 5 minutos y una sola vez.
5. Tu servidor lo cambia por los tokens, con tus credenciales.

curl -X POST https://api.findqbox.com/connect/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://tu-software.example.com/qbox/vuelta \
  -d code_verifier=$CODE_VERIFIER

Los permisos

• facilities.write: publicar los centros de la gestora y ponerlos al día.
• leads.read: recibir sus solicitudes.

Renovar el token

El access_token dura una hora. Para renovarlo, grant_type=refresh_token con el refresh_token. Cada vez llega uno nuevo y el anterior deja de valer; uno que no se usa en 90 días caduca. Si alguien usa uno que ya se cambió, anulamos todos los tokens de ese permiso por seguridad, y la gestora tiene que volver a darlo.

El token de tu software

Con tus credenciales solas (grant_type=client_credentials) tienes el token de tu software. No ve ningún centro: sirve para ver tus conexiones (GET /connections) y mandarte un aviso de prueba (POST /webhooks/test).

Si la gestora retira el permiso

Lo hace en Qbox cuando quiera. Te llega el aviso connection.revoked, sus tokens responden 403 connection_revoked y sus centros dejan de ponerse al día: siguen en el portal como los que se dan de alta en Qbox, con «Solicitar información».

En producción, las direcciones de vuelta son siempre https://. En pruebas también vale http://localhost.