Avvio rapido

Da zero alla prima chiamata riuscita.

1. Get credentials

I client di integrazione vengono registrati da noi, non in autonomia. Scrivi a support@shiftavo.com indicando:

• per quale azienda è l’integrazione,

• cosa deve fare — concediamo solo gli scope necessari a coprirlo (vedi Scope).

Ricevi tre cose:

client_id	es. cust-acme-integration
client_secret	mostrato una sola volta, conservato con hash dalla nostra parte — non recuperabile, quindi salvalo subito
scope	es. shifts.read timesheets.read

Un set di credenziali appartiene a una sola azienda e non può raggiungerne un’altra, anche se tu appartieni a più aziende.

2. Get an access token

POST all’endpoint del token del provider di identità. Le credenziali vanno nel corpo del formulario:

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"
}

Importante

Memorizza in cache il token e riutilizzalo fino a poco prima della scadenza. È un requisito, non un’ottimizzazione: non chiamare l’endpoint del token una volta per richiesta.

3. Find out which host to call

L’access token è un JWT che porta un claim api_base con il nome dello shard della tua azienda:

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

Leggi l’host dal token invece di scriverlo nel codice: è ciò che ci permette di aggiungere o spostare shard senza che tu debba cambiare nulla. Decodifica il payload solo come indicazione di routing; non devi verificare il tuo stesso token.

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
}

Se ti tornano le tue sedi, allora credenziali, scope e vincolo con l’azienda sono tutti corretti.

La stessa cosa in 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()

Passi successivi

• Autenticazione — il flusso completo del token, compresa la scadenza e la gestione dei 401.

• Convenzioni — paginazione, errori, idempotenza. Leggilo prima di scrivere un client.

• Referenza API — ogni endpoint.