> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronizare

> Păstrează o copie a ce ți se publică: liste și cursoare, updated_since, versiuni, tombstone-uri, ciclul de viață comun tuturor resurselor și disponibilitatea.

<Warning>
  **Preview: nimic nu este servit încă.** Pagina descrie contractul API-ului de distribuție (versiunea `1.0.0`). Încearcă-l pe un mock al contractului ([Testare](/ro/distribution-api/testing)).
</Warning>

Canalul tău își ține propria copie a ce îi publică gazdele și o aduce la zi întrebând ce s-a schimbat. Webhook-urile îți spun mai repede, dar sursa sunt listele și jurnalul de evenimente: orice ai ratat rămâne acolo 35 de zile.

## Liste

`GET /locations`, `/owners`, `/properties`, `/amenities` și `/webhooks` răspund cu o pagină:

```json theme={null}
{
  "data": [ … ],
  "next_cursor": "…"
}
```

* `limit` este între 1 și 500, implicit 100; peste 500 este refuzat.
* Pentru pagina următoare trimite înapoi `next_cursor` ca `cursor`. Este opac și legat de interogarea care l-a produs. Pe ultima pagină este `null`.
* `/locations`, `/owners` și `/properties` filtrează după `status`, de exemplu `status=active,inactive`, iar `/properties` și după `location_id` și `owner_id`.
* O singură resursă se citește cu `GET /locations/{location_id}`, `/owners/{owner_id}`, `/properties/{property_id}`.
* O citire poartă un `ETag` (toate, mai puțin `GET /availability`); trimite-l înapoi ca `If-None-Match`, iar un răspuns neschimbat este `304 Not Modified`, peste tot în afară de jurnalele de livrări ale webhook-urilor (`/webhooks/{webhook_id}/deliveries`).

Proprietățile își numesc `location_id` și `owner_id`, așa că citește locațiile și proprietarii înaintea proprietăților care trimit la ei.

## Prima copie, apoi doar schimbările

<Steps>
  <Step title="Citește totul o dată">
    Listează fiecare resursă fără `updated_since`, urmând `next_cursor` până la capăt. Păstrează fiecare resursă cu `version`-ul ei și reține cel mai mare `updated_at` primit.
  </Step>

  <Step title="Cere ce s-a schimbat de atunci">
    Listează din nou cu `updated_since` egal cu acel cel mai mare `updated_at`. Limita este **inclusivă**, deci nu ai nevoie de suprapunere: ce s-a schimbat chiar în acea secundă vine din nou, iar versiunea îți spune dacă îl ai deja.
  </Step>

  <Step title="Aplică după versiune">
    Aplică o resursă doar când `version`-ul ei este mai mare decât cel pe care îl ai și ignoră-l pe unul mai mic. Versiunea crește la fiecare schimbare vizibilă canalului tău, dar nu este un contor: nu te aștepta la valori consecutive.
  </Step>

  <Step title="Ia-o de la capăt când fereastra a trecut">
    Un `updated_since` mai vechi decât fereastra de păstrare, de 35 de zile, primește `410` cu `sync-window-expired`. Resincronizează de la zero: citește totul o dată, ca la primul pas.
  </Step>
</Steps>

## Un singur ciclu de viață pentru toate resursele

Locațiile, proprietarii, proprietățile, facilitățile și endpoint-urile de webhook au același `status`, cu același înțeles peste tot:

| `status` | Înseamnă |
| - | - |
| `active` | Publicat pentru tine și în vigoare. |
| `inactive` | Publicat, dar nu în vigoare acum: o proprietate care nu se poate vinde momentan, o locație sau un proprietar ale cărui proprietăți publicate sunt toate inactive, un endpoint de webhook suspendat. Poate redeveni activ. |
| `withdrawn` | Nepublicat pentru tine acum. Poate reveni cu același id și o versiune mai mare. |
| `deleted` | Definitiv. Id-ul nu mai este folosit niciodată. |

O resursă `withdrawn` sau `deleted` este un **tombstone**, la toate resursele, și nu se trimite nimic altceva:

```json theme={null}
{ "id": "prp_1qnykkykp69yv8d59hxk5410m9", "status": "withdrawn", "version": 42, "updated_at": "2026-10-16T09:30:00Z" }
```

Tombstone-urile apar într-o listă doar când trimiți `updated_since`; fără el există doar resurse `active` și `inactive`. O resursă citită după id răspunde cu tombstone-ul ei. Tratează toate cele patru valori la fiecare resursă, inclusiv una pe care acea resursă nu o atinge azi.

## Disponibilitate și prețuri

Disponibilitatea se citește pe proprietate și pe noapte, în datele proprietății.

* `GET /properties/{property_id}/availability?from=2026-12-20&to=2026-12-27` răspunde cu nopțile unei proprietăți dintr-o fereastră: `to` este exclusiv, fereastra are cel mult 365 de nopți și stă în orizontul publicat. Un `from` dinaintea zilei de azi a proprietății este servit de azi, iar răspunsul spune ce fereastră a servit. O fereastră dincolo de orizont primește `400` cu `window-beyond-horizon` și `horizon_end`-ul proprietății. O proprietate retrasă sau ștearsă primește `404`.
* `GET /availability?updated_since=…&from=…&to=…` răspunde cu nopțile care s-au schimbat, grupate pe proprietăți active sau inactive. O pagină se termină la `limit` proprietăți sau la 5.000 de nopți, care vine prima, așa că nopțile unei proprietăți pot continua pe pagina următoare sub același `property_id`: aplică-le după dată. O pagină costă `max(1, ceil(nights / 1000))` unități din limita ta de cereri.

Fiecare noapte are `units_available` (0 înseamnă complet ocupat), `min_stay` și `max_stay` pentru o sosire în acea noapte, `closed_to_arrival`, `closed_to_departure` și câte un tarif pentru fiecare plan tarifar. `price` este prețul pentru `base_occupancy` oaspeți, așa cum îl plătește oaspetele (cu TVA, cu adaosul aplicat), și este `null` când tariful este `closed`; `extra_guest_price` este prețul pentru încă un adult, `0` când e gratuit, `null` când prețul îi acoperă pe toți.

## Jurnalul de evenimente

`GET /events` este jurnalul tău, în ordinea în care au fost înregistrate, al schimbărilor, păstrat 35 de zile. Reține `last_event_id` de pe fiecare pagină și trimite-l înapoi ca `since`; `next_cursor` este `null` când ai ajuns la zi. Fără `since`, jurnalul începe cu cel mai vechi eveniment păstrat. Apar doar tipurile de evenimente acoperite de permisiunile cheii tale: `availability.updated` cere `read:ari`.

Un `since` mai vechi decât jurnalul păstrat primește `410` cu `event-cursor-expired` și `latest_event_id`: resincronizează cu `updated_since`, apoi continuă jurnalul de la `latest_event_id`.

Un eveniment numește o resursă și versiunea ei sau, pentru `availability.updated`, o proprietate și un interval de nopți (`from`, `to` exclusiv), fără versiune: citește din nou acel interval. Tipurile de evenimente sunt `location.created`, `location.updated`, `location.deleted`, `owner.created`, `owner.updated`, `owner.deleted`, `property.created`, `property.updated`, `property.deleted`, `property.distributed`, `property.withdrawn` și `availability.updated`, și se pot adăuga altele.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.