Una API di prenotazione compatta e con ambiti limitati.

Endpoint

Autorizzazione, envelope e tracciamento delle richieste

GET /api/partner/v1/catalog?locale=en&limit=2 HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential
Accept-Language: en
Origin: https://partner.example

HTTP/1.1 200 OK
Cache-Control: private, no-store
Referrer-Policy: no-referrer
X-Request-Id: <request_id>
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: <remaining>
X-RateLimit-Reset: <unix_seconds>

{
  "data": { "services": [], "next_cursor": null },
  "meta": { "request_id": "<request_id>", "version": "v1" }
}

Politica di ambiti e credenziali

Crea prenotazione

POST /api/partner/v1/bookings HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential
Idempotency-Key: 7b1d9ed1-7f34-4ddf-9e01-example
Content-Type: application/json

{
  "service_id": "<published_service_id>",
  "location_id": "<optional_allowed_location_id>",
  "date": "2026-09-21",
  "start_time": "10:00",
  "external_reference": "partner-order-1042",
  "customer": {
    "name": "Test customer",
    "phone": "+15550001111",
    "consent_to_contact": true
  }
}

Struttura attuale della prenotazione

• Partner API v1 crea un servizio per prenotazione. Il campo documentato service_id è singolare; i campi inventati service_ids o composition_mode vengono rifiutati.
• La prenotazione composta sequenziale o parallela è disponibile tramite il widget firmato Feny e il flusso proprietario, dove il motore canonico convalida combinazioni, capacità del personale e regole correnti.
• Non esporre credenziali Partner API nel browser. Usa id e versione pubblici del widget per gli embed e mantieni le chiamate API su un server attendibile.

Paginazione e letture limitate

GET /api/partner/v1/catalog?locale=en&limit=25&cursor=<next_cursor> HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential

{
  "data": {
    "services": ["..."],
    "next_cursor": "<opaque_cursor_or_null>"
  },
  "meta": { "request_id": "<request_id>", "version": "v1" }
}

Regole di paginazione

• Le letture di catalogo e specialisti accettano limit da 1 a 50 (predefinito 25). La disponibilità accetta da 1 a 96 (predefinito 48).
• Invia next_cursor esattamente come restituito. È opaco e non deve essere decodificato, costruito, condiviso tra query non correlate o usato dopo una modifica dei filtri.
• Il next_cursor della disponibilità rappresenta l’inizio dell’ultimo slot restituito per quella query. Un next_cursor nullo indica che non esiste una pagina successiva.
• La disponibilità è una lettura corrente, non una prenotazione. Rileggila e lascia che la creazione esegua il controllo finale della capacità sul server.

Azioni idempotenti sulla prenotazione

POST /api/partner/v1/bookings/<pbr_reference>/actions/cancel HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential
Idempotency-Key: 11111111-2222-4333-8444-example
Content-Type: application/json

{ "expected_version": 3 }

Politica di idempotenza e versione

• Usa una Idempotency-Key di 16–128 caratteri per ogni scrittura logica. Dopo un risultato incerto ripeti la richiesta esatta; usa una nuova chiave per una nuova operazione.
• Non riutilizzare mai una chiave di idempotenza con input modificato. L’API restituisce 409 idempotency_key_reused invece di scegliere quale richiesta sia autorevole.
• Recupera la prenotazione prima di annullare o riprogrammare e invia l’ultima versione come expected_version. Una versione obsoleta può restituire 409 booking_version_conflict.
• Non inserire dati cliente, credenziali o altri valori sensibili in Idempotency-Key o external_reference.

Errori e tentativi