Démarrage rapide

Démarrage rapide#

De zéro à un premier appel réussi.

1. Get credentials#

Les clients d’intégration sont enregistrés par nous, pas en libre-service. Écris à support@shiftavo.com en précisant :

  • pour quelle entreprise l’intégration est prévue,

  • ce qu’elle doit faire — nous n’accordons que les scopes que cela couvre (voir Scopes).

Tu reçois trois choses :

client_id

p. ex. cust-acme-integration

client_secret

affiché une seule fois, stocké haché de notre côté — irrécupérable, enregistre-le donc immédiatement

scopes

p. ex. shifts.read timesheets.read

Un jeu d’identifiants appartient à exactement une entreprise et ne peut pas en atteindre une autre, même si tu appartiens à plusieurs.

2. Get an access token#

POST vers le point de terminaison de jeton du fournisseur d’identité. Les identifiants vont dans le corps du formulaire :

curl -X POST https://auth.shiftavo.com/identity/o/api/token \
  -d grant_type=client_credentials \
  -d client_id=cust-acme-integration \
  -d client_secret=$CLIENT_SECRET \
  -d scope=shifts.read

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "shifts.read"
}

Important

Mets le jeton en cache et réutilise-le jusqu’à peu avant son expiration. C’est une exigence, pas une optimisation — n’appelle pas le point de terminaison du jeton à chaque requête.

3. Find out which host to call#

Le jeton d’accès est un JWT portant un claim api_base qui nomme le shard de ton entreprise :

{ "api_base": "https://app.shiftavo.com", "tenant_id": "0194d1c0-…", "…": "…" }

Lis l’hôte depuis le jeton plutôt que de le coder en dur — c’est ce qui nous permet d’ajouter ou de déplacer des shards sans que tu changes quoi que ce soit. Décode la charge utile comme simple indication de routage ; tu n’as pas besoin de vérifier ton propre jeton.

4. Make a call#

curl "$API_BASE/api/public/v1/locations/?page_size=100" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "object": "list",
  "data": [
    { "object": "location", "id": "0194d1c0-…", "name": "Bar — Hamptons" }
  ],
  "has_more": false,
  "next": null
}

Si tes propres sites reviennent, les identifiants, les scopes et le rattachement à l’entreprise sont tous corrects.

La même chose en Python#

import requests

AUTH = "https://auth.shiftavo.com"

token = requests.post(
    f"{AUTH}/identity/o/api/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "shifts.read",
    },
    timeout=30,
).json()

# `api_base` is a routing hint from the token — decode, don't verify.
import base64, json
payload = token["access_token"].split(".")[1]
api_base = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))["api_base"]

shifts = requests.get(
    f"{api_base}/api/public/v1/shifts/",
    headers={"Authorization": f"Bearer {token['access_token']}"},
    timeout=30,
).json()

Suite#