Avvio rapido

Da una chiave di staging a una chiamata funzionante, in pochi minuti.

Ti serve una credenziale PMS di staging. Se non ce l’hai ancora, richiedi l’accesso.

​

1. Imposta due variabili d’ambiente

export TATALLO_BASE_URL="https://staging.api.tatallo.com"
export TATALLO_API_KEY="tat_stg_sk_<credential-id>_<secret>"   # your staging key

Ogni esempio di queste guide legge queste due variabili. Per passare poi alla produzione, imposta TATALLO_BASE_URL su https://api.tatallo.com e usa la chiave di produzione.

​

2. Controlla la chiave

curl -s "$TATALLO_BASE_URL/v1/me" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

Vedi quale chiave hai usato, il tuo PMS, l’ambiente e gli scope:

{
  "credential_id": "5d4e040b-61c1-44a4-a4ca-9a751dc05133",
  "pms_name": "Test PMS",
  "environment": "staging",
  "scopes": [
    "properties:read"
  ]
}

credential_id è l’ID della chiave stessa, quindi il tuo può differire dall’esempio. environment deve valere staging, e scopes deve includere properties:read.

​

3. Elenca le proprietà

curl -s "$TATALLO_BASE_URL/v1/properties" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

In staging ottieni le proprietà di prova collegate al tuo PMS, esattamente queste:

{
  "data": [
    {
      "id": "6cfa992d-1805-4de6-892c-23785031aba0",
      "name": "Fixture Loft Kreuzberg",
      "timezone": "Europe/Berlin",
      "status": "active",
      "country": "Germany",
      "city": "Berlin",
      "max_guests": 2,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "934f807c-39d6-45de-b107-d5c9e03cb041",
      "name": "Fixture House Alfama",
      "timezone": "Europe/Lisbon",
      "status": "inactive",
      "country": "Portugal",
      "city": "Lisbon",
      "max_guests": 6,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
      "name": "Fixture Apartment Trastevere",
      "timezone": "Europe/Rome",
      "status": "active",
      "country": "Italy",
      "city": "Rome",
      "max_guests": 4,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    }
  ],
  "page": {
    "next_cursor": null
  }
}

page.next_cursor è null, quindi l’elenco è completo. Se le proprietà sono più di quelle che stanno in una pagina, segui il cursore: vedi Scoperta delle proprietà in staging.

​

4. Leggi una proprietà

curl -s "$TATALLO_BASE_URL/v1/properties/bef2859f-2444-47ec-b5f4-f1e6701f087f" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

{
  "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
  "name": "Fixture Apartment Trastevere",
  "timezone": "Europe/Rome",
  "status": "active",
  "country": "Italy",
  "city": "Rome",
  "max_guests": 4,
  "currency": "EUR",
  "updated_at": "2026-10-01T09:00:00.000Z"
}

Salva l’id di ogni proprietà nella tua tabella di corrispondenza: non cambia mai. Il significato di ogni campo: Proprietà.

​

Risoluzione dei problemi

Ogni errore ha la stessa forma, { "error": { "code", "message", "request_id" } }. Decidi in base a code.

​

401 unauthorized

La chiave manca, è malformata, appartiene all’altro ambiente, è scaduta oppure è stata revocata. Controlla che TATALLO_API_KEY inizi con tat_stg_sk_ quando TATALLO_BASE_URL punta allo staging, che l’header sia esattamente Authorization: Bearer <key> e che nulla sia stato tagliato nel copiarla. Vedi Autenticazione.

​

403 insufficient_scope

La chiave è valida, ma non ha properties:read. GET /v1/me ne mostra gli scope. Chiedi a [e-mail] una chiave con lo scope che ti serve.

​

404 property_not_found

La proprietà non è collegata al tuo PMS, oppure non esiste. Tatallo risponde allo stesso modo nei due casi, di proposito. Elenca prima le tue proprietà e usa i loro id. Vedi perché una proprietà non collegata è un 404.

​

429 rate_limited

Più di 60 richieste in un minuto con questa chiave. Attendi il numero di secondi indicato nell’header Retry-After, poi riprova.

Quando scrivi al supporto, cita l’header X-Request-Id della risposta che è fallita.