v0.3.0

Quickstart

Dalla chiave API alla prima prenotazione confermata: catalogo, capacità, prezzi e booking in pochi minuti.

Apri
Apri in ClaudeApri in ChatGPT

Prima di iniziare

Tako è una piattaforma headless e multi-tenant per tour, attività, noleggi ed esperienze. Il gestionale pubblica catalogo, prezzi e disponibilità tramite /api/v1, gestisce le prenotazioni e collega i canali di vendita. Questa pagina porta da zero a una prenotazione confermata.

Base URL: https://api.takoconnect.com/api/v1

Sei un reseller che acquista disponibilità? Il flusso qui sotto riguarda il gestionale del fornitore. I canali usano credenziali di connessione separate, non intercambiabili con la chiave tenant.

Autenticazione

Ogni richiesta porta la chiave tenant come Bearer token. Non esiste un header X-Tenant-Id: il tenant deriva dalla chiave.

Ottieni la chiave API

  1. Accedi alla dashboard con il tuo tenant.
  2. In API keys crea una chiave dedicata al gestionale: il valore completo compare una sola volta.
  3. Assegna gli scope minimi. La chiave copre tutti i fornitori del tenant.
export TAKO_API_URL="https://api.takoconnect.com"
export TAKO_API_KEY="cm_live_…"   # mai nel codice sorgente

Verifica la connessione

curl "$TAKO_API_URL/api/v1/me" \
  -H "Authorization: Bearer $TAKO_API_KEY"
{
  "tenant": { "id": "tenant-id", "name": "Organizzazione", "defaultCurrency": "EUR", "status": "ACTIVE" },
  "scopes": ["catalog:read", "bookings:read"],
  "user": null
}

Dettagli su scope e rotazione in Autenticazione; contratto completo in GET /me.

Concetti chiave

RisorsaRuolo
SupplierFornitore che eroga l’esperienza; appartiene al tenant.
Product → Option → UnitEsperienza → variante prenotabile → categoria acquistabile.
ResourcePool fisico o umano di capacità, condivisibile tra opzioni dello stesso fornitore.
BookingPrenotazione con unitItems e snapshot di prezzo e consumo.

Step 1: Crea il catalogo

Crea fornitore, prodotto (in INACTIVE finché non è completo), opzione e unità. Salva l’id di ogni risposta.

curl -X POST "$TAKO_API_URL/api/v1/suppliers" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Operatore",
  "timezone": "Europe/Rome",
  "locale": "it-IT"
}'
curl -X POST "$TAKO_API_URL/api/v1/products" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "supplierId": "supplier-id",
  "name": "Tour in barca",
  "status": "INACTIVE"
}'
curl -X POST "$TAKO_API_URL/api/v1/products/{productId}/options" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Mattina",
  "durationMinutes": 60,
  "pricingPer": "UNIT"
}'
curl -X POST "$TAKO_API_URL/api/v1/options/{optionId}/units" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "ADULT",
  "name": "Adulto",
  "restrictions": {
    "paxCount": 1
  }
}'

Step 2: Capacità e calendario

Una risorsa definisce i posti; il collegamento all’opzione stabilisce quanti ne consuma; il periodo ricorrente materializza le partenze.

curl -X POST "$TAKO_API_URL/api/v1/resources" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "supplierId": "supplier-id",
  "name": "Posti tour",
  "quantity": 1,
  "capacityPerResource": 10
}'
curl -X POST "$TAKO_API_URL/api/v1/options/{optionId}/resource-requirements" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceId": "resource-id",
  "quantity": 1
}'
curl -X POST "$TAKO_API_URL/api/v1/options/{optionId}/availability-periods" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "startMonthDay": "04-01",
  "endMonthDay": "10-31",
  "weekdays": [
    1,
    2,
    3,
    4,
    5,
    6
  ],
  "startTimes": [
    "09:00",
    "15:00"
  ]
}'

Step 3: Prezzi

Importi interi nelle unità minori della valuta: 2500 = 25,00 EUR. Il PUT sostituisce tutti i periodi dell’opzione.

curl -X PUT "$TAKO_API_URL/api/v1/options/{optionId}/pricing-periods" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pricingPer": "UNIT",
  "periods": [
    {
      "startMonthDay": "01-01",
      "endMonthDay": "12-31",
      "weekdays": [
        0,
        1,
        2,
        3,
        4,
        5,
        6
      ],
      "startTimes": [
        "09:00",
        "15:00"
      ],
      "retailPrices": {
        "unit-id": 2500
      }
    }
  ]
}'

Poi attiva il prodotto con PATCH /products/{id} e {"status":"ACTIVE"}.

Step 4: Leggi la disponibilità

curl "$TAKO_API_URL/api/v1/availability?optionId={optionId}&from=2030-06-01T00:00:00Z&to=2030-06-30T23:59:59Z" \
  -H "Authorization: Bearer $TAKO_API_KEY"

Usa gli startAt restituiti per prenotare: l’UTC cambia con l’ora legale.

Step 5: Crea e conferma la prenotazione

curl -X POST "$TAKO_API_URL/api/v1/bookings" \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "optionId": "option-id",
  "startAt": "2030-06-15T07:00:00Z",
  "unitItems": [
    {
      "unitId": "unit-id",
      "quantity": 2
    }
  ],
  "customer": {
    "firstName": "Ada",
    "lastName": "Esempio",
    "emailAddress": "ada@example.com"
  },
  "idempotencyKey": "gestionale:supplier-42:ordine-123",
  "status": "ON_HOLD"
}'

La chiave idempotente è univoca nel tenant: un retry restituisce la stessa prenotazione. Conferma con:

curl -X POST "$TAKO_API_URL/api/v1/bookings/{bookingId}/confirm" \
  -H "Authorization: Bearer $TAKO_API_KEY"

Il totale autorevole è booking.pricingSnapshot.retail. Rileggi con GET dopo ogni transizione: restituisce lo stato persistito e l’updatedAt da usare nel prossimo PATCH.

Esempio eseguibile

Scarica integration-example.mjs: Node 22, nessuna dipendenza. Crea catalogo, risorse e prezzi; esegue riserva, retry idempotente, conferma, modifica e cancellazione verificando totale e capacità. Usalo solo nel tenant di test: ogni esecuzione crea nuovi dati.

TAKO_API_URL="https://api.takoconnect.com" TAKO_RUN_EXAMPLE=yes node integration-example.mjs

E adesso?