# Tako Docs

Piattaforma headless, API-first e multi-tenant per tour, attività, noleggi ed esperienze.
Base URL: https://api.takoconnect.com/api/v1. Autenticazione: Authorization: Bearer <chiave tenant>.

## Guide

- [Quickstart](https://docs.takoconnect.com/): Dalla chiave API alla prima prenotazione confermata: catalogo, capacità, prezzi e booking in pochi minuti.
- [Autenticazione](https://docs.takoconnect.com/authentication/): Chiavi tenant, scope, emissione e rotazione via API.
- [Convenzioni HTTP](https://docs.takoconnect.com/conventions/): Formati, date, PATCH, importi e paginazione validi per tutta l’API.
- [Catalogo](https://docs.takoconnect.com/catalog/): Fornitori, prodotti, opzioni, unità e foto.
- [Risorse e disponibilità](https://docs.takoconnect.com/availability/): Capacità autoritativa per risorsa, calendario ricorrente, override e blocchi.
- [Prezzi](https://docs.takoconnect.com/pricing/): Valuta del tenant, modalità di prezzo e periodi tariffari.
- [Prenotazioni](https://docs.takoconnect.com/bookings/): Creazione idempotente, stati, modifica concorrente e operazioni manuali.
- [Errori e retry](https://docs.takoconnect.com/errors/): Codici HTTP, formato degli errori e strategie di retry sicure.
- [Webhook e sincronizzazione](https://docs.takoconnect.com/sync/): Ricevi gli aggiornamenti delle prenotazioni, riallinea con il feed incrementale, controlla job e audit.
- [Collaudo](https://docs.takoconnect.com/checklist/): Cosa verificare prima di andare in produzione.

## API Reference

# Leggere tenant, scope e utente corrente

GET /api/v1/me

Con API key user è null. Nessuno scope aggiuntivo oltre all'autenticazione.

Autenticazione: Authorization: Bearer <chiave tenant>.

Risposta 200:
```json
{
  "tenant": {
    "id": "entity-id",
    "name": "name",
    "defaultCurrency": "EUR",
    "status": "ACTIVE"
  },
  "scopes": [
    "scopes"
  ],
  "user": {
    "id": "entity-id",
    "email": "email",
    "name": "name",
    "role": "ADMIN"
  }
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/me/me/

---

# Impostare la valuta del tenant

PATCH /api/v1/me

Codice valuta supportato a tre lettere maiuscole. 409 se esistono periodi di prezzo: rimuoverli prima. Impostarla prima di configurare i prezzi.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Body di esempio:
```json
{
  "defaultCurrency": "EUR"
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "name": "name",
  "defaultCurrency": "EUR",
  "status": "ACTIVE"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/me/update/

---

# Elencare le chiavi tenant

GET /api/v1/api-keys

Restituisce soltanto metadati; mai hash o chiavi in chiaro.

Scope richiesti: api-keys:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: api-keys:read.

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "name": "name",
    "prefix": "prefix",
    "scopes": [
      "scopes"
    ],
    "createdAt": "2030-06-15T08:00:00.000Z",
    "lastUsedAt": "2030-06-15T08:00:00.000Z",
    "expiresAt": "2030-06-15T08:00:00.000Z",
    "revokedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/api-keys/list/

---

# Creare una chiave tenant

POST /api/v1/api-keys

La chiave completa è restituita una sola volta. scopes omesso equivale a ["*"]. Non si possono assegnare scope superiori ai propri. La chiave copre tutto il tenant, non un singolo fornitore.

Scope richiesti: api-keys:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: api-keys:write.

Body di esempio:
```json
{
  "name": "Gestionale",
  "scopes": [
    "catalog:read",
    "availability:read",
    "bookings:read"
  ]
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "name": "name",
  "prefix": "prefix",
  "scopes": [
    "scopes"
  ],
  "createdAt": "2030-06-15T08:00:00.000Z",
  "lastUsedAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "revokedAt": "2030-06-15T08:00:00.000Z",
  "key": "key"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/api-keys/create/

---

# Eliminare una chiave tenant

DELETE /api/v1/api-keys/{id}

Eliminazione immediata. Una API key non può eliminare sé stessa. Ruotare creando e verificando prima una chiave sostitutiva.

Scope richiesti: api-keys:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: api-keys:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/api-keys/remove/

---

# Elencare i fornitori

GET /api/v1/suppliers

Senza limit restituisce un array. Con limit (1–100) restituisce {items,total}; offset parte da 0 ed è ignorato senza limit. Non è un cursore di sincronizzazione. Esclude i fornitori archiviati; ordine per nome.

Scope richiesti: suppliers:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: suppliers:read.

Query:
- limit? (integer)
- offset? (integer)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "name": "name",
    "reference": "tour-di-esempio",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z",
    "timezone": "timezone",
    "locale": "locale",
    "website": "website",
    "email": "email",
    "telephone": "telephone",
    "address": "address",
    "metadata": {},
    "deletedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/suppliers/list/

---

# Creare un fornitore

POST /api/v1/suppliers

reference opzionale, derivata dal nome e univoca nel tenant. Se esplicita e già usata: 409. locale predefinito it-IT. Usare un fuso IANA, per esempio Europe/Rome.

Scope richiesti: suppliers:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: suppliers:write.

Body di esempio:
```json
{
  "name": "Operatore",
  "timezone": "Europe/Rome",
  "locale": "it-IT"
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "timezone": "timezone",
  "locale": "locale",
  "website": "website",
  "email": "email",
  "telephone": "telephone",
  "address": "address",
  "metadata": {},
  "deletedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/suppliers/create/

---

# Leggere un fornitore

GET /api/v1/suppliers/{id}

Scope richiesti: suppliers:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: suppliers:read.

Parametri di percorso: id.

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "timezone": "timezone",
  "locale": "locale",
  "website": "website",
  "email": "email",
  "telephone": "telephone",
  "address": "address",
  "metadata": {},
  "deletedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/suppliers/get/

---

# Modificare un fornitore

PATCH /api/v1/suppliers/{id}

PATCH parziale. null rimuove website, email, telephone o address. Modifiche a lingua, fuso e contatti si propagano ai prodotti.

Scope richiesti: suppliers:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: suppliers:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "name": "Operatore aggiornato",
  "website": null
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "timezone": "timezone",
  "locale": "locale",
  "website": "website",
  "email": "email",
  "telephone": "telephone",
  "address": "address",
  "metadata": {},
  "deletedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/suppliers/update/

---

# Archiviare un fornitore

DELETE /api/v1/suppliers/{id}

409 finché esistono prodotti, risorse o connessioni attive. Il fornitore viene archiviato, non cancellato fisicamente.

Scope richiesti: suppliers:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: suppliers:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/suppliers/remove/

---

# Elencare il catalogo completo

GET /api/v1/products

Senza limit restituisce un array. Con limit (1–100) restituisce {items,total}; offset parte da 0 ed è ignorato senza limit. Non è un cursore di sincronizzazione. Ordine per nome. Include opzioni, unità non ritirate, risorse richieste, periodi attivi e prezzi; include anche prodotti non ACTIVE.

Scope richiesti: catalog:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:read.

Query:
- limit? (integer)
- offset? (integer)
- supplierId? (string)
- search? (string)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "name": "name",
    "reference": "tour-di-esempio",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z",
    "supplierId": "supplier-id",
    "shortDescription": "shortDescription",
    "description": "description",
    "features": [
      {
        "type": "type",
        "shortDescription": "shortDescription"
      }
    ],
    "depositPercentage": 0,
    "durationMinutesFrom": 0,
    "durationMinutesTo": 0,
    "timezone": "timezone",
    "locale": "locale",
    "availabilityType": "START_TIME",
    "status": "ACTIVE",
    "metadata": {},
    "options": [
      {
        "id": "entity-id",
        "tenantId": "tenant-id",
        "name": "name",
        "reference": "tour-di-esempio",
        "createdAt": "2030-06-15T08:00:00.000Z",
        "updatedAt": "2030-06-15T08:00:00.000Z",
        "productId": "product-id",
        "isDefault": true,
        "durationMinutes": 0,
        "sortOrder": 0,
        "pricingPer": "UNIT",
        "cancellationCutoffAmount": 0,
        "cancellationCutoffUnit": "cancellationCutoffUnit",
        "bookingCutoffMinutes": 0,
        "requiredContactFields": [
          "requiredContactFields"
        ],
        "restrictions": {},
        "metadata": {},
        "units": [
          {
            "id": "entity-id",
            "tenantId": "tenant-id",
            "name": "name",
            "reference": "tour-di-esempio",
            "createdAt": "2030-06-15T08:00:00.000Z",
            "updatedAt": "2030-06-15T08:00:00.000Z",
            "optionId": "option-id",
            "type": "ADULT",
            "requiredContactFields": [
              null
            ],
            "restrictions": {},
            "metadata": {},
            "deletedAt": "2030-06-15T08:00:00.000Z"
          }
        ],
        "resourceRequirements": [
          {
            "id": "entity-id",
            "tenantId": "tenant-id",
            "optionId": "option-id",
            "resourceId": "resource-id",
            "quantity": 0,
            "maxQuantity": 0
          }
        ],
        "availabilityPeriods": [
          {
            "id": "entity-id",
            "tenantId": "tenant-id",
            "optionId": "option-id",
            "startMonthDay": "startMonthDay",
            "endMonthDay": "endMonthDay",
            "weekdays": [
              null
            ],
            "startTimes": [
              null
            ],
            "label": "label",
            "createdAt": "2030-06-15T08:00:00.000Z",
            "updatedAt": "2030-06-15T08:00:00.000Z",
            "active": true,
            "pricingBasis": "pricingBasis",
            "currency": "EUR",
            "prices": {}
          }
        ],
        "pricingPeriods": [
          {
            "id": "entity-id",
            "tenantId": "tenant-id",
            "optionId": "option-id",
            "startMonthDay": "startMonthDay",
            "endMonthDay": "endMonthDay",
            "weekdays": [
              null
            ],
            "startTimes": [
              null
            ],
            "label": "label",
            "createdAt": "2030-06-15T08:00:00.000Z",
            "updatedAt": "2030-06-15T08:00:00.000Z",
            "color": "color",
            "retailPrices": {
              "unit-id": null
            },
            "retailPriceTiers": [
              null
            ]
          }
        ]
      }
    ],
    "photos": [
      {
        "id": "entity-id",
        "sortOrder": 0,
        "contentType": "contentType",
        "updatedAt": "2030-06-15T08:00:00.000Z"
      }
    ]
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/products/list-products/

---

# Creare un prodotto

POST /api/v1/products

status predefinito ACTIVE; per preparare il catalogo usare INACTIVE. reference derivata dal nome se omessa. metadata.directBooking=false abilita la richiesta di approvazione.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Body di esempio:
```json
{
  "supplierId": "supplier-id",
  "name": "Tour di esempio",
  "status": "INACTIVE"
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "supplierId": "supplier-id",
  "shortDescription": "shortDescription",
  "description": "description",
  "features": [
    {
      "type": "type",
      "shortDescription": "shortDescription"
    }
  ],
  "depositPercentage": 0,
  "durationMinutesFrom": 0,
  "durationMinutesTo": 0,
  "timezone": "timezone",
  "locale": "locale",
  "availabilityType": "START_TIME",
  "status": "ACTIVE",
  "metadata": {},
  "options": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "name": "name",
      "reference": "tour-di-esempio",
      "createdAt": "2030-06-15T08:00:00.000Z",
      "updatedAt": "2030-06-15T08:00:00.000Z",
      "productId": "product-id",
      "isDefault": true,
      "durationMinutes": 0,
      "sortOrder": 0,
      "pricingPer": "UNIT",
      "cancellationCutoffAmount": 0,
      "cancellationCutoffUnit": "cancellationCutoffUnit",
      "bookingCutoffMinutes": 0,
      "requiredContactFields": [
        "requiredContactFields"
      ],
      "restrictions": {},
      "metadata": {},
      "units": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "name": "name",
          "reference": "tour-di-esempio",
          "createdAt": "2030-06-15T08:00:00.000Z",
          "updatedAt": "2030-06-15T08:00:00.000Z",
          "optionId": "option-id",
          "type": "ADULT",
          "requiredContactFields": [
            "requiredContactFields"
          ],
          "restrictions": {},
          "metadata": {},
          "deletedAt": "2030-06-15T08:00:00.000Z"
        }
      ],
      "resourceRequirements": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "optionId": "option-id",
          "resourceId": "resource-id",
          "quantity": 0,
          "maxQuantity": 0
        }
      ],
      "availabilityPeriods": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "optionId": "option-id",
          "startMonthDay": "startMonthDay",
          "endMonthDay": "endMonthDay",
          "weekdays": [
            0
          ],
          "startTimes": [
            "startTimes"
          ],
          "label": "label",
          "createdAt": "2030-06-15T08:00:00.000Z",
          "updatedAt": "2030-06-15T08:00:00.000Z",
          "active": true,
          "pricingBasis": "pricingBasis",
          "currency": "EUR",
          "prices": {}
        }
      ],
      "pricingPeriods": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "optionId": "option-id",
          "startMonthDay": "startMonthDay",
          "endMonthDay": "endMonthDay",
          "weekdays": [
            0
          ],
          "startTimes": [
            "startTimes"
          ],
          "label": "label",
          "createdAt": "2030-06-15T08:00:00.000Z",
          "updatedAt": "2030-06-15T08:00:00.000Z",
          "color": "color",
          "retailPrices": {
            "unit-id": 0
          },
          "retailPriceTiers": [
            {
              "minQuantity": null,
              "maxQuantity": null,
              "retail": null
            }
          ]
        }
      ]
    }
  ],
  "photos": [
    {
      "id": "entity-id",
      "sortOrder": 0,
      "contentType": "contentType",
      "updatedAt": "2030-06-15T08:00:00.000Z"
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/products/create-product/

---

# Leggere un prodotto e le sue opzioni

GET /api/v1/products/{id}

Scope richiesti: catalog:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:read.

Parametri di percorso: id.

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "supplierId": "supplier-id",
  "shortDescription": "shortDescription",
  "description": "description",
  "features": [
    {
      "type": "type",
      "shortDescription": "shortDescription"
    }
  ],
  "depositPercentage": 0,
  "durationMinutesFrom": 0,
  "durationMinutesTo": 0,
  "timezone": "timezone",
  "locale": "locale",
  "availabilityType": "START_TIME",
  "status": "ACTIVE",
  "metadata": {},
  "options": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "name": "name",
      "reference": "tour-di-esempio",
      "createdAt": "2030-06-15T08:00:00.000Z",
      "updatedAt": "2030-06-15T08:00:00.000Z",
      "productId": "product-id",
      "isDefault": true,
      "durationMinutes": 0,
      "sortOrder": 0,
      "pricingPer": "UNIT",
      "cancellationCutoffAmount": 0,
      "cancellationCutoffUnit": "cancellationCutoffUnit",
      "bookingCutoffMinutes": 0,
      "requiredContactFields": [
        "requiredContactFields"
      ],
      "restrictions": {},
      "metadata": {},
      "units": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "name": "name",
          "reference": "tour-di-esempio",
          "createdAt": "2030-06-15T08:00:00.000Z",
          "updatedAt": "2030-06-15T08:00:00.000Z",
          "optionId": "option-id",
          "type": "ADULT",
          "requiredContactFields": [
            "requiredContactFields"
          ],
          "restrictions": {},
          "metadata": {},
          "deletedAt": "2030-06-15T08:00:00.000Z"
        }
      ],
      "resourceRequirements": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "optionId": "option-id",
          "resourceId": "resource-id",
          "quantity": 0,
          "maxQuantity": 0
        }
      ],
      "availabilityPeriods": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "optionId": "option-id",
          "startMonthDay": "startMonthDay",
          "endMonthDay": "endMonthDay",
          "weekdays": [
            0
          ],
          "startTimes": [
            "startTimes"
          ],
          "label": "label",
          "createdAt": "2030-06-15T08:00:00.000Z",
          "updatedAt": "2030-06-15T08:00:00.000Z",
          "active": true,
          "pricingBasis": "pricingBasis",
          "currency": "EUR",
          "prices": {}
        }
      ],
      "pricingPeriods": [
        {
          "id": "entity-id",
          "tenantId": "tenant-id",
          "optionId": "option-id",
          "startMonthDay": "startMonthDay",
          "endMonthDay": "endMonthDay",
          "weekdays": [
            0
          ],
          "startTimes": [
            "startTimes"
          ],
          "label": "label",
          "createdAt": "2030-06-15T08:00:00.000Z",
          "updatedAt": "2030-06-15T08:00:00.000Z",
          "color": "color",
          "retailPrices": {
            "unit-id": 0
          },
          "retailPriceTiers": [
            {
              "minQuantity": null,
              "maxQuantity": null,
              "retail": null
            }
          ]
        }
      ]
    }
  ],
  "photos": [
    {
      "id": "entity-id",
      "sortOrder": 0,
      "contentType": "contentType",
      "updatedAt": "2030-06-15T08:00:00.000Z"
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/products/get-product/

---

# Modificare un prodotto

PATCH /api/v1/products/{id}

Risposta senza relazioni: usare GET per rileggere opzioni e foto. Cambiare il nome senza reference rigenera lo slug. timezone/locale null ripristinano l'eredità dal fornitore.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "status": "ACTIVE"
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "supplierId": "supplier-id",
  "shortDescription": "shortDescription",
  "description": "description",
  "features": [
    {
      "type": "type",
      "shortDescription": "shortDescription"
    }
  ],
  "depositPercentage": 0,
  "durationMinutesFrom": 0,
  "durationMinutesTo": 0,
  "timezone": "timezone",
  "locale": "locale",
  "availabilityType": "START_TIME",
  "status": "ACTIVE",
  "metadata": {}
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/products/update-product/

---

# Eliminare un prodotto

DELETE /api/v1/products/{id}

409 con prenotazioni attive o altri riferimenti che impediscono l'eliminazione. Le relazioni di catalogo vengono eliminate a cascata.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/products/delete-product/

---

# Leggere opzione, unità, risorse e periodi

GET /api/v1/options/{id}

Scope richiesti: catalog:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:read.

Parametri di percorso: id.

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "productId": "product-id",
  "isDefault": true,
  "durationMinutes": 0,
  "sortOrder": 0,
  "pricingPer": "UNIT",
  "cancellationCutoffAmount": 0,
  "cancellationCutoffUnit": "cancellationCutoffUnit",
  "bookingCutoffMinutes": 0,
  "requiredContactFields": [
    "requiredContactFields"
  ],
  "restrictions": {},
  "metadata": {},
  "units": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "name": "name",
      "reference": "tour-di-esempio",
      "createdAt": "2030-06-15T08:00:00.000Z",
      "updatedAt": "2030-06-15T08:00:00.000Z",
      "optionId": "option-id",
      "type": "ADULT",
      "requiredContactFields": [
        "requiredContactFields"
      ],
      "restrictions": {},
      "metadata": {},
      "deletedAt": "2030-06-15T08:00:00.000Z"
    }
  ],
  "resourceRequirements": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "optionId": "option-id",
      "resourceId": "resource-id",
      "quantity": 0,
      "maxQuantity": 0
    }
  ],
  "availabilityPeriods": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "optionId": "option-id",
      "startMonthDay": "startMonthDay",
      "endMonthDay": "endMonthDay",
      "weekdays": [
        0
      ],
      "startTimes": [
        "startTimes"
      ],
      "label": "label",
      "createdAt": "2030-06-15T08:00:00.000Z",
      "updatedAt": "2030-06-15T08:00:00.000Z",
      "active": true,
      "pricingBasis": "pricingBasis",
      "currency": "EUR",
      "prices": {}
    }
  ],
  "pricingPeriods": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "optionId": "option-id",
      "startMonthDay": "startMonthDay",
      "endMonthDay": "endMonthDay",
      "weekdays": [
        0
      ],
      "startTimes": [
        "startTimes"
      ],
      "label": "label",
      "createdAt": "2030-06-15T08:00:00.000Z",
      "updatedAt": "2030-06-15T08:00:00.000Z",
      "color": "color",
      "retailPrices": {
        "unit-id": 0
      },
      "retailPriceTiers": [
        {
          "minQuantity": 0,
          "maxQuantity": 0,
          "retail": 0
        }
      ]
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/options/get-option/

---

# Modificare un'opzione

PATCH /api/v1/options/{id}

pricingPer si cambia con PUT pricing-periods. Impostare un'altra opzione predefinita prima di rimuovere isDefault dall'attuale. reference rigenerata quando cambia name.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "bookingCutoffMinutes": 60
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "productId": "product-id",
  "isDefault": true,
  "durationMinutes": 0,
  "sortOrder": 0,
  "pricingPer": "UNIT",
  "cancellationCutoffAmount": 0,
  "cancellationCutoffUnit": "cancellationCutoffUnit",
  "bookingCutoffMinutes": 0,
  "requiredContactFields": [
    "requiredContactFields"
  ],
  "restrictions": {},
  "metadata": {}
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/options/update-option/

---

# Eliminare un'opzione

DELETE /api/v1/options/{id}

409 con prenotazioni attive. Se era predefinita, viene selezionata un'altra opzione.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/options/delete-option/

---

# Creare un'opzione

POST /api/v1/products/{id}/options

La prima opzione è predefinita. durationMinutes predefinito 60, cutoff 0. reference generata dal nome. Le opzioni non hanno un campo status; lo stato vendibile è sul prodotto.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "name": "Mattina",
  "durationMinutes": 60,
  "pricingPer": "UNIT"
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "productId": "product-id",
  "isDefault": true,
  "durationMinutes": 0,
  "sortOrder": 0,
  "pricingPer": "UNIT",
  "cancellationCutoffAmount": 0,
  "cancellationCutoffUnit": "cancellationCutoffUnit",
  "bookingCutoffMinutes": 0,
  "requiredContactFields": [
    "requiredContactFields"
  ],
  "restrictions": {},
  "metadata": {}
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/options/create-option/

---

# Creare un'unità prenotabile

POST /api/v1/options/{id}/units

reference generata dal nome. Le tariffe UNIT/RESOURCE esistenti ricevono una voce a prezzo zero: aggiornare i prezzi prima di vendere. RESOURCE usa metadata.resourceId; restrictions.paxCount indica i posti per unità.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "type": "ADULT",
  "name": "Adulto",
  "restrictions": {
    "paxCount": 1
  }
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "optionId": "option-id",
  "type": "ADULT",
  "requiredContactFields": [
    "requiredContactFields"
  ],
  "restrictions": {},
  "metadata": {},
  "deletedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/units/create-unit/

---

# Modificare un'unità

PATCH /api/v1/units/{id}

minAge ≤ maxAge e minQuantity ≤ maxQuantity se presenti. restrictions e metadata sostituiscono gli oggetti, non vengono uniti ricorsivamente.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "name": "Adulto aggiornato"
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "name": "name",
  "reference": "tour-di-esempio",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "optionId": "option-id",
  "type": "ADULT",
  "requiredContactFields": [
    "requiredContactFields"
  ],
  "restrictions": {},
  "metadata": {},
  "deletedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/units/update-unit/

---

# Rimuovere un'unità dal catalogo

DELETE /api/v1/units/{id}

Con prenotazioni attive l'unità viene ritirata e resta nello storico; altrimenti viene eliminata. Le chiavi prezzo vengono aggiornate.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/units/delete-unit/

---

# Caricare una foto

POST /api/v1/products/{id}/photos

data è base64 senza prefisso data:. contentType: image/jpeg, image/png o image/webp. Massimo 14.000.000 caratteri base64 (circa 10 MB decodificati); limite corpo JSON: 15 MB.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "contentType": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aZ1sAAAAASUVORK5CYII="
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "sortOrder": 0,
  "contentType": "contentType",
  "updatedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/photos/add-photo/

---

# Riordinare tutte le foto

PUT /api/v1/products/{id}/photos

ids deve contenere esattamente tutti gli id delle foto del prodotto, senza duplicati.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "ids": [
    "photo-id"
  ]
}
```

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "sortOrder": 0,
    "contentType": "contentType",
    "updatedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/photos/reorder-photos/

---

# Sostituire una foto

PUT /api/v1/products/{id}/photos/{photoId}

Mantiene id e ordinamento. Stesso formato e limiti del caricamento.

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id, photoId.

Body di esempio:
```json
{
  "contentType": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aZ1sAAAAASUVORK5CYII="
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "sortOrder": 0,
  "contentType": "contentType",
  "updatedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/photos/replace-photo/

---

# Eliminare una foto

DELETE /api/v1/products/{id}/photos/{photoId}

Scope richiesti: catalog:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: catalog:write.

Parametri di percorso: id, photoId.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/photos/delete-photo/

---

# Scaricare una foto pubblica

GET /api/v1/products/{id}/photos/{photoId}

Non richiede autenticazione. Restituisce i byte dell'immagine, non JSON. Non caricare documenti riservati.

Autenticazione: nessuna.

Parametri di percorso: id, photoId.

Risposta 200:
```json
<binary image>
```

Errori: 400, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/photos/get-photo-file/

---

# Elencare le risorse

GET /api/v1/resources

Senza limit restituisce un array. Con limit (1–100) restituisce {items,total}; offset parte da 0 ed è ignorato senza limit. Non è un cursore di sincronizzazione. Ordine per nome.

Scope richiesti: resources:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:read.

Query:
- limit? (integer)
- offset? (integer)
- supplierId? (string)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "supplierId": "supplier-id",
    "name": "name",
    "quantity": 0,
    "capacityPerResource": 0,
    "metadata": {},
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/list/

---

# Creare una risorsa

POST /api/v1/resources

Capacità totale in posti = quantity × capacityPerResource. La risorsa appartiene a un solo fornitore.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Body di esempio:
```json
{
  "supplierId": "supplier-id",
  "name": "Posti tour",
  "quantity": 1,
  "capacityPerResource": 10
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "supplierId": "supplier-id",
  "name": "name",
  "quantity": 0,
  "capacityPerResource": 0,
  "metadata": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/create/

---

# Leggere una risorsa e i collegamenti

GET /api/v1/resources/{id}

Scope richiesti: resources:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:read.

Parametri di percorso: id.

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "supplierId": "supplier-id",
  "name": "name",
  "quantity": 0,
  "capacityPerResource": 0,
  "metadata": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "requirements": [
    {
      "id": "entity-id",
      "tenantId": "tenant-id",
      "optionId": "option-id",
      "resourceId": "resource-id",
      "quantity": 0,
      "maxQuantity": 0
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/get/

---

# Modificare una risorsa

PATCH /api/v1/resources/{id}

Cambiare quantity o capacityPerResource aggiorna la capacità di tutti gli slot, sovrascrivendo anche gli override. 409 se la nuova capacità è inferiore al riservato.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "quantity": 2
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "supplierId": "supplier-id",
  "name": "name",
  "quantity": 0,
  "capacityPerResource": 0,
  "metadata": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/update/

---

# Eliminare una risorsa

DELETE /api/v1/resources/{id}

409 se inventario o opzioni la referenziano. Non esiste un endpoint di cancellazione degli slot inventario.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/remove/

---

# Elencare i periodi di disponibilità attivi

GET /api/v1/options/{id}/availability-periods

Ordine per startMonthDay. Non usare i campi legacy prices/currency per leggere le tariffe.

Scope richiesti: availability:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: availability:read.

Parametri di percorso: id.

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "optionId": "option-id",
    "startMonthDay": "startMonthDay",
    "endMonthDay": "endMonthDay",
    "weekdays": [
      0
    ],
    "startTimes": [
      "startTimes"
    ],
    "label": "label",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z",
    "active": true,
    "pricingBasis": "pricingBasis",
    "currency": "EUR",
    "prices": {}
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/availability-periods/

---

# Elencare i blocchi che intersecano l'intervallo

GET /api/v1/availability-blocks

from ≤ to. Intersezione: startAt < to e endAt > from. Ordine per startAt.

Scope richiesti: availability:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: availability:read.

Query:
- from (datetime)
- to (datetime)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "productId": "product-id",
    "startAt": "2030-06-15T08:00:00.000Z",
    "endAt": "2030-06-15T08:00:00.000Z",
    "createdAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/resources/availability-blocks/

---

# Collegare o aggiornare una risorsa dell'opzione

POST /api/v1/options/{id}/resource-requirements

Risorsa e opzione devono appartenere allo stesso fornitore. Upsert per (optionId,resourceId). quantity predefinito 1; maxQuantity omesso/null usa tutto il pool. Omettere i valori li ripristina ai default anche in aggiornamento.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "resourceId": "resource-id",
  "quantity": 1,
  "maxQuantity": null
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "optionId": "option-id",
  "resourceId": "resource-id",
  "quantity": 0,
  "maxQuantity": 0
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/resource-requirements/add-requirement/

---

# Scollegare una risorsa dall'opzione

DELETE /api/v1/options/{optionId}/resource-requirements/{resourceId}

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: optionId, resourceId.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/resource-requirements/remove-requirement/

---

# Impostare la capacità degli slot

POST /api/v1/resources/{id}/inventory

Upsert per (resourceId,startAt). Specificare capacity (posti totali) oppure quantity (numero risorse), mai entrambi; senza entrambi ripristina la capacità del pool. Non modifica reserved. endAt, se presente, deve essere dopo startAt. 409 sotto il riservato. Non inviare la disponibilità residua come capacità totale.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "slots": [
    {
      "startAt": "2030-06-15T08:00:00Z",
      "capacity": 10
    }
  ]
}
```

Risposta 201:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "resourceId": "resource-id",
    "startAt": "2030-06-15T08:00:00.000Z",
    "endAt": "2030-06-15T08:00:00.000Z",
    "capacity": 0,
    "reserved": 0,
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/inventory/upsert-inventory/

---

# Leggere gli slot inventario

GET /api/v1/resources/{id}/inventory

from ≤ to; estremi inclusivi sulla partenza, ordine startAt. Non è un preventivo di disponibilità vendibile.

Scope richiesti: resources:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:read.

Parametri di percorso: id.

Query:
- from (datetime)
- to (datetime)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "resourceId": "resource-id",
    "startAt": "2030-06-15T08:00:00.000Z",
    "endAt": "2030-06-15T08:00:00.000Z",
    "capacity": 0,
    "reserved": 0,
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/inventory/inventory/

---

# Aggiungere disponibilità ricorrente

POST /api/v1/options/{id}/availability-periods

Ricorrenza annuale nel fuso del prodotto, altrimenti del fornitore. Date MM-DD inclusive, anche a cavallo d'anno; weekdays: 0 domenica–6 sabato; startTimes: HH:mm. Serve almeno una risorsa collegata. Non configura i prezzi: completare pricing-periods prima di vendere.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "startMonthDay": "01-01",
  "endMonthDay": "12-31",
  "weekdays": [
    0,
    1,
    2,
    3,
    4,
    5,
    6
  ],
  "startTimes": [
    "10:00"
  ]
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "optionId": "option-id",
  "startMonthDay": "startMonthDay",
  "endMonthDay": "endMonthDay",
  "weekdays": [
    0
  ],
  "startTimes": [
    "startTimes"
  ],
  "label": "label",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "active": true,
  "pricingBasis": "pricingBasis",
  "currency": "EUR",
  "prices": {}
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/availability-periods/create-availability-period/

---

# Disattivare un periodo di disponibilità

DELETE /api/v1/options/{optionId}/availability-periods/{periodId}

Il periodo resta nello storico con active=false; le prenotazioni esistenti non vengono annullate.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: optionId, periodId.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/availability-periods/remove-availability-period/

---

# Bloccare le nuove prenotazioni di un prodotto

POST /api/v1/availability-blocks

startAt < endAt. Blocca partenze in [startAt,endAt); non cancella prenotazioni esistenti.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Body di esempio:
```json
{
  "productId": "product-id",
  "startAt": "2030-06-15T00:00:00Z",
  "endAt": "2030-06-16T00:00:00Z"
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "productId": "product-id",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "createdAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/availability-blocks/create-availability-block/

---

# Rimuovere un blocco

DELETE /api/v1/availability-blocks/{id}

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/availability-blocks/remove-availability-block/

---

# Leggere i periodi di prezzo

GET /api/v1/options/{id}/pricing-periods

Ordine per startMonthDay e createdAt. Valuta da GET /me.

Scope richiesti: availability:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: availability:read.

Parametri di percorso: id.

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "optionId": "option-id",
    "startMonthDay": "startMonthDay",
    "endMonthDay": "endMonthDay",
    "weekdays": [
      0
    ],
    "startTimes": [
      "startTimes"
    ],
    "label": "label",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z",
    "color": "color",
    "retailPrices": {
      "unit-id": 0
    },
    "retailPriceTiers": [
      {
        "minQuantity": 0,
        "maxQuantity": 0,
        "retail": 0
      }
    ]
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/pricing-periods/pricing-periods/

---

# Sostituire modalità e intero calendario prezzi

PUT /api/v1/options/{id}/pricing-periods

Ricorrenza annuale nel fuso del prodotto, altrimenti del fornitore. Date MM-DD inclusive, anche a cavallo d'anno; weekdays: 0 domenica–6 sabato; startTimes: HH:mm. Serve almeno una risorsa collegata. Operazione atomica e sostitutiva. UNIT/RESOURCE: una chiave per ogni unitId; BOOKING: sola chiave booking. Importi interi nelle unità minori. I periodi devono coprire la disponibilità ricorrente; nelle sovrapposizioni vince il prezzo massimo per chiave. Le fasce retailPriceTiers sono solo BOOKING: minQuantity ≤ maxQuantity; in sovrapposizione vince il prezzo massimo, senza fascia applicabile la quotazione fallisce. Gli id dei periodi vengono rigenerati.

Scope richiesti: resources:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: resources:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "pricingPer": "UNIT",
  "periods": [
    {
      "startMonthDay": "01-01",
      "endMonthDay": "12-31",
      "weekdays": [
        0,
        1,
        2,
        3,
        4,
        5,
        6
      ],
      "startTimes": [
        "10:00"
      ],
      "retailPrices": {
        "unit-id": 2500
      }
    }
  ]
}
```

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "optionId": "option-id",
    "startMonthDay": "startMonthDay",
    "endMonthDay": "endMonthDay",
    "weekdays": [
      0
    ],
    "startTimes": [
      "startTimes"
    ],
    "label": "label",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z",
    "color": "color",
    "retailPrices": {
      "unit-id": 0
    },
    "retailPriceTiers": [
      {
        "minQuantity": 0,
        "maxQuantity": 0,
        "retail": 0
      }
    ]
  }
]
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/pricing-periods/replace-pricing-periods/

---

# Calcolare la disponibilità operativa

GET /api/v1/availability

Intervallo inclusivo sulle partenze UTC. Può materializzare l'inventario ricorrente. Nessuna quotazione prezzi: leggere pricing-periods; il totale autorevole della prenotazione è pricingSnapshot. Questa API management ignora il booking cutoff nel flag available, ma POST bookings con startAt lo applica. Non riserva capacità.

Scope richiesti: availability:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: availability:read.

Query:
- optionId (string)
- from (datetime)
- to (datetime)

Risposta 200:
```json
[
  {
    "optionId": "option-id",
    "startAt": "2030-06-15T08:00:00.000Z",
    "endAt": "2030-06-15T08:00:00.000Z",
    "cutoffAt": "2030-06-15T08:00:00.000Z",
    "maxUnits": 0,
    "manual": true,
    "available": true,
    "capacity": 0,
    "vacancies": 0,
    "resources": [
      {
        "resourceId": "resource-id",
        "vacancies": 0
      }
    ]
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/availability/get/

---

# Elencare le prenotazioni

GET /api/v1/bookings

Senza limit restituisce un array. Con limit (1–100) restituisce {items,total}; offset parte da 0 ed è ignorato senza limit. Non è un cursore di sincronizzazione. Ordine createdAt decrescente. from/to filtrano startAt, non updatedAt. search cerca nome/email cliente. source è api/v1 o il codice del canale/provider (anche per prenotazioni OCTO). Con updatedSince la risposta è {items,nextCursor}, ordinata per updatedAt/id; usa nextCursor fino a null.

Scope richiesti: bookings:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:read.

Query:
- status? (enum) valori: ON_HOLD, PENDING, CONFIRMED, CANCELLED, REJECTED, EXPIRED
- from? (datetime)
- to? (datetime)
- supplierId? (string)
- source? (string)
- search? (string)
- updatedSince? (datetime)
- cursor? (string)
- limit? (integer)
- offset? (integer)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "uuid": "uu-id",
    "supplierId": "supplier-id",
    "sourceChannelConnectionId": "source-channel-connection-id",
    "productId": "product-id",
    "optionId": "option-id",
    "source": "source",
    "externalId": "external-id",
    "status": "ON_HOLD",
    "startAt": "2030-06-15T08:00:00.000Z",
    "endAt": "2030-06-15T08:00:00.000Z",
    "expiresAt": "2030-06-15T08:00:00.000Z",
    "customer": {},
    "notes": "notes",
    "cancellationReason": "cancellationReason",
    "idempotencyKey": "idempotencyKey",
    "pricingSnapshot": {
      "schemaVersion": 1,
      "pricingPer": "UNIT",
      "currency": "EUR",
      "currencyPrecision": 0,
      "retail": 0,
      "unitPricing": [
        {
          "unitId": "unit-id",
          "quantity": 0,
          "retail": 0,
          "unitRetail": 0,
          "name": "name",
          "type": "type",
          "paxCount": 0
        }
      ]
    },
    "resourceUsageSnapshot": {
      "schemaVersion": 1,
      "items": [
        {
          "resourceId": "resource-id",
          "name": "name",
          "capacityPlaces": 0,
          "resourceQuantity": 0
        }
      ]
    },
    "participants": {},
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z",
    "unitItems": [
      {
        "id": "entity-id",
        "bookingId": "booking-id",
        "unitId": "unit-id",
        "quantity": 0,
        "metadata": {}
      }
    ]
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/list/

---

# Creare una prenotazione

POST /api/v1/bookings

Esattamente uno tra startAt (UTC) e customStart (ora locale nel fuso del prodotto/fornitore). Almeno un'unità valida e quantità positive. idempotencyKey è nel JSON, univoca per tenant: il riuso restituisce la prenotazione esistente senza confrontare il payload, anche con risposta 201. Omettere status per rispettare metadata.directBooking: CONFIRMED normalmente, PENDING se false; ON_HOLD crea una riserva. customStart crea una partenza manuale e supera il booking cutoff; fornire retailPrices se manca una tariffa. expandCapacity=true autorizza un aumento della capacità. backdated richiede una sessione utente, con API key restituisce 403. endAt omesso può tornare null; il consumo usa la durata dell'opzione.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Body di esempio:
```json
{
  "optionId": "option-id",
  "startAt": "2030-06-15T08:00:00Z",
  "unitItems": [
    {
      "unitId": "unit-id",
      "quantity": 2
    }
  ],
  "status": "ON_HOLD",
  "idempotencyKey": "gestionale:supplier:ordine-123",
  "customer": {
    "firstName": "Ada",
    "lastName": "Esempio",
    "emailAddress": "ada@example.com"
  }
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/create/

---

# Leggere una prenotazione

GET /api/v1/bookings/{id}

Usare l'id interno, non uuid. Rileggere prima di PATCH per ottenere expectedUpdatedAt corrente.

Scope richiesti: bookings:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:read.

Parametri di percorso: id.

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/get/

---

# Modificare quantità, partenza o prezzi

PATCH /api/v1/bookings/{id}

expectedUpdatedAt obbligatorio, da GET. Serve almeno uno tra startAt, customStart, unitItems, resourceItems, retailPrices, participants; startAt e customStart sono alternativi. unitItems sostituisce l'intera composizione. Stati ammessi: ON_HOLD non scaduto, PENDING, CONFIRMED. 409 per modifica concorrente, capacità insufficiente o canale di origine senza sottoscrizione BOOKING_UPDATE. L'API management supera i cutoff di prenotazione e cancellazione. Ricalcola prezzo e consumo atomicamente. Non consente di cambiare optionId, customer o notes.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "expectedUpdatedAt": "2030-06-01T12:00:00.000Z",
  "unitItems": [
    {
      "unitId": "unit-id",
      "quantity": 3
    }
  ]
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/update/

---

# Confermare una riserva ON_HOLD

POST /api/v1/bookings/{id}/confirm

Passa a CONFIRMED oppure PENDING se il prodotto richiede approvazione. Non è idempotente: una seconda conferma può dare 409. Dopo un timeout rileggere GET; rileggere anche prima del successivo PATCH.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/confirm/

---

# Approvare una prenotazione PENDING

POST /api/v1/bookings/{id}/approve

Passa da PENDING a CONFIRMED; altri stati producono 409. Dopo un timeout rileggere GET prima di ritentare.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/approve/

---

# Rifiutare una prenotazione e liberare capacità

POST /api/v1/bookings/{id}/reject

Imposta REJECTED su una prenotazione attiva, con reason opzionale. Questa operazione management non applica il cancellation cutoff. Ripetere su uno stato finale produce 409; dopo un timeout rileggere GET.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "reason": "Richiesta non approvata dal fornitore"
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/reject/

---

# Cancellare una prenotazione e liberare capacità

POST /api/v1/bookings/{id}/cancel

Imposta CANCELLED. Questa operazione management non applica il cancellation cutoff. Ripetere su CANCELLED o altri stati finali produce 409; dopo un timeout rileggere GET. Nessun rimborso o pagamento viene eseguito.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "uuid": "uu-id",
  "supplierId": "supplier-id",
  "sourceChannelConnectionId": "source-channel-connection-id",
  "productId": "product-id",
  "optionId": "option-id",
  "source": "source",
  "externalId": "external-id",
  "status": "ON_HOLD",
  "startAt": "2030-06-15T08:00:00.000Z",
  "endAt": "2030-06-15T08:00:00.000Z",
  "expiresAt": "2030-06-15T08:00:00.000Z",
  "customer": {},
  "notes": "notes",
  "cancellationReason": "cancellationReason",
  "idempotencyKey": "idempotencyKey",
  "pricingSnapshot": {
    "schemaVersion": 1,
    "pricingPer": "UNIT",
    "currency": "EUR",
    "currencyPrecision": 0,
    "retail": 0,
    "unitPricing": [
      {
        "unitId": "unit-id",
        "quantity": 0,
        "retail": 0,
        "unitRetail": 0,
        "name": "name",
        "type": "type",
        "paxCount": 0
      }
    ]
  },
  "resourceUsageSnapshot": {
    "schemaVersion": 1,
    "items": [
      {
        "resourceId": "resource-id",
        "name": "name",
        "capacityPlaces": 0,
        "resourceQuantity": 0
      }
    ]
  },
  "participants": {},
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z",
  "unitItems": [
    {
      "id": "entity-id",
      "bookingId": "booking-id",
      "unitId": "unit-id",
      "quantity": 0,
      "metadata": {}
    }
  ]
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/bookings/cancel/

---

# Elencare i webhook del gestionale

GET /api/v1/webhooks/subscriptions

Restituisce i webhook tenant-wide o del fornitore risolto dalla chiave. Gli header non vengono restituiti.

Scope richiesti: bookings:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:read.

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "supplierId": "supplier-id",
    "url": "url",
    "notificationTypes": [
      "notificationTypes"
    ],
    "status": "ACTIVE",
    "consecutiveFailures": 0,
    "disabledReason": "disabledReason",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "updatedAt": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/webhooks/list/

---

# Sottoscrivere gli aggiornamenti prenotazione

POST /api/v1/webhooks/subscriptions

Invia BOOKING_UPDATE per creazioni, conferme, modifiche e cancellazioni. supplierId omesso significa tutti i fornitori del tenant.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Body di esempio:
```json
{
  "url": "https://gestionale.example/webhooks/tako",
  "supplierId": "supplier-id",
  "headers": {
    "Authorization": "Bearer receiver-secret"
  }
}
```

Risposta 201:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "supplierId": "supplier-id",
  "url": "url",
  "notificationTypes": [
    "notificationTypes"
  ],
  "status": "ACTIVE",
  "consecutiveFailures": 0,
  "disabledReason": "disabledReason",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/webhooks/create/

---

# Modificare o riattivare un webhook

PATCH /api/v1/webhooks/subscriptions/{id}

ACTIVE azzera il contatore errori; gli header presenti sostituiscono quelli correnti.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Body di esempio:
```json
{
  "status": "ACTIVE"
}
```

Risposta 200:
```json
{
  "id": "entity-id",
  "tenantId": "tenant-id",
  "supplierId": "supplier-id",
  "url": "url",
  "notificationTypes": [
    "notificationTypes"
  ],
  "status": "ACTIVE",
  "consecutiveFailures": 0,
  "disabledReason": "disabledReason",
  "createdAt": "2030-06-15T08:00:00.000Z",
  "updatedAt": "2030-06-15T08:00:00.000Z"
}
```

Errori: 400, 401, 403, 404, 409, 413, 500.

Pagina: https://docs.takoconnect.com/api-reference/webhooks/update/

---

# Eliminare un webhook gestionale

DELETE /api/v1/webhooks/subscriptions/{id}

La rimozione è immediata.

Scope richiesti: bookings:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: bookings:write.

Parametri di percorso: id.

Risposta 200:
```json
{
  "deleted": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/webhooks/remove/

---

# Leggere gli ultimi job di sincronizzazione

GET /api/v1/sync-jobs

Massimo 200, createdAt decrescente; tentativi ordinati per numero. Non è una lista completa paginabile.

Scope richiesti: sync:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: sync:read.

Query:
- status? (enum) valori: PENDING, RUNNING, RETRYING, SUCCEEDED, FAILED
- provider? (string)
- supplierId? (string)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "supplierId": "supplier-id",
    "channelConnectionId": "channel-connection-id",
    "provider": "provider",
    "type": "type",
    "entityId": "entity-id",
    "dedupKey": "dedupKey",
    "status": "PENDING",
    "correlationId": "correlation-id",
    "createdAt": "2030-06-15T08:00:00.000Z",
    "startedAt": "2030-06-15T08:00:00.000Z",
    "completedAt": "2030-06-15T08:00:00.000Z",
    "attempts": [
      {
        "id": "entity-id",
        "syncJobId": "sync-job-id",
        "attempt": 0,
        "status": "status",
        "errorCode": "errorCode",
        "errorMessage": "errorMessage",
        "requestMetadata": {},
        "responseMetadata": {},
        "createdAt": "2030-06-15T08:00:00.000Z"
      }
    ]
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/sync-jobs/list/

---

# Accodare un nuovo tentativo per un job FAILED

POST /api/v1/sync-jobs/{id}/retry

Clona l'evento di origine. 201 significa accodato, non consegnato. 400 se il job non è FAILED o l'evento non è più disponibile. Non è idempotente.

Scope richiesti: sync:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: sync:write.

Parametri di percorso: id.

Risposta 201:
```json
{
  "retried": true,
  "outboxEventId": "outbox-event-id"
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/sync-jobs/retry/

---

# Rielaborare un evento Viator ricevuto o fallito

POST /api/v1/webhook-events/{id}/retry

Solo provider VIATOR, stato RECEIVED/FAILED e tipo BookingRequest/BookingCancellationRequest. Non è un endpoint per sottoscrivere webhook.

Scope richiesti: sync:write.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: sync:write.

Parametri di percorso: id.

Risposta 201:
```json
{
  "retried": true
}
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/webhook-events/retry/

---

# Leggere gli ultimi eventi di audit

GET /api/v1/audit-logs

Massimo 200, timestamp decrescente. Filtri entityType/entityId; nessun cursore di sincronizzazione.

Scope richiesti: audit:read.

Autenticazione: Authorization: Bearer <chiave tenant>. Scope: audit:read.

Query:
- entityType? (string)
- entityId? (string)

Risposta 200:
```json
[
  {
    "id": "entity-id",
    "tenantId": "tenant-id",
    "actorType": "USER",
    "actorId": "actor-id",
    "source": "source",
    "entityType": "entityType",
    "entityId": "entity-id",
    "action": "action",
    "before": {},
    "after": {},
    "timestamp": "2030-06-15T08:00:00.000Z"
  }
]
```

Errori: 400, 401, 403, 404, 409, 500.

Pagina: https://docs.takoconnect.com/api-reference/audit-logs/list/

---