Avvio in 5 minuti

Alla fine di questa pagina avrai fatto due chiamate vere: una per ottenere un token, una per leggere dei dati. Tutto con curl, senza installare niente.

Verifica che il servizio risponda

Questa chiamata non vuole il token. Se non risponde, inutile proseguire.

curl https://os1.omnitools.it/api/health

Risposta attesa: HTTP 200.

Procurati le credenziali

Servono tre cose, e te le diamo noi: utente, password e il codice dell'azienda su cui vuoi lavorare (per esempio DEMO).

Oggi l'accesso e' con un utente, non con una chiave applicativa.

Chiedi un utente dedicato all'integrazione, non quello di una persona: se quella persona cambia password o lascia l'azienda, l'integrazione si ferma senza preavviso.

Ottieni il token

# sostituisci utente, password e azienda
curl -X POST https://os1.omnitools.it/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"UTENTE","password":"PASSWORD","company":"DEMO"}'

Se le credenziali sono giuste torna un oggetto fatto cosi':

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": { ... },
  "company": "DEMO",
  "exercise": "2026"
}

Quello che serve e' access_token. L'azienda che hai chiesto resta dentro il token: non dovrai ripeterla a ogni chiamata.

Usa il token

TOKEN="incolla-qui-access_token"

curl https://os1.omnitools.it/api/lookup/clienti \
  -H "Authorization: Bearer $TOKEN"

Se arriva l'elenco dei clienti, l'integrazione e' in piedi: da qui in poi e' solo questione di quale rotta chiamare.

Lo stesso in Python

import requests

BASE = "https://os1.omnitools.it"

r = requests.post(f"{BASE}/api/auth/login", json={
    "username": "UTENTE",
    "password": "PASSWORD",
    "company": "DEMO",
}, timeout=30)
r.raise_for_status()
token = r.json()["access_token"]

sessione = requests.Session()
sessione.headers["Authorization"] = f"Bearer {token}"

clienti = sessione.get(f"{BASE}/api/lookup/clienti", timeout=30).json()
print(clienti)

Il token scade

Quando scade, le chiamate cominciano a rispondere 401. Non serve rifare il login: c'e' POST /api/auth/refresh, a cui si passa il refresh_token ricevuto all'inizio.

Un consiglio che fa risparmiare tempo.

Non chiedere un token nuovo a ogni chiamata. Tienilo da parte, usalo finche' funziona, e rinnovalo quando arriva il primo 401. Un login per chiamata funziona in prova e poi diventa lento appena i documenti sono tanti.

E adesso

Le quattro parole da conoscere per non sbagliare azienda o permessi stanno in Concetti. L'elenco completo delle rotte, con tutti i campi, sta nel Riferimento. Cosa fare quando qualcosa risponde male sta in Errori.