Deplino Logo
Actualités
← Accueil

Acest API îi permite PMS-ului unui hotel (sau unui channel manager, unei platforme OTA) să conducă Channel Manager-ul Deplino din propriul sistem:

  • citește camerele (tipuri și camere fizice), disponibilitatea, rezervările, prețurile și restricțiile;
  • trimite rezervările făcute în afara Deplino, apoi le modifică sau le anulează;
  • închide și redeschide camere fizice (mentenanță, reparație, curățenie);
  • trimite prețurile și restricțiile pe zile, pe care Deplino le duce mai departe pe canale (Booking.com, Airbnb, Expedia etc.);
  • creează, modifică și șterge tipuri de cameră și planuri tarifare și redenumește camerele fizice (C1 → 101);
  • primește un webhook la fiecare rezervare și la fiecare schimbare de disponibilitate.

Disponibilitatea o calculează Deplino. Trimiți faptele (rezervări, camere închise), nu numărul de camere libere. Deplino le adună cu rezervările de pe canale și de pe site și trimite rezultatul pe canale. Așa nu se ajunge la două surse care se contrazic.

Nu livrăm cod de integrare: integratorul își scrie propriul client peste acest API, ca la Stripe. Totul e pe această pagină; căsuța de sus te duce direct la secțiunea căutată.

Cheia API se generează din contul de partener Deplino, tab Setări → API. Cere un abonament de conectivitate OTA activ.

Nu confunda cheia API PMS cu cheia de widget. Pagina de Setări are și o secțiune separată, „Widget-uri" (dp_a1b2c3..., fără _live/_test). Aceea e o cheie publică, vizibilă în sursa site-ului, care doar identifică widgetul de apel, calendar sau AI afișat pe site-ul partenerului. Nu poate scrie nimic. Cheia din acest document (dp_live_.../dp_test_...) e cea de integrare: scrie rezervări, prețuri și blocări și trebuie ținută secretă ca orice cheie API. Nu se pot folosi una în locul celeilalte.

Autentificare

Fiecare cerere trimite cheia în header-ul Authorization, ca token Bearer:

Authorization: Bearer dp_live_a1b2c3d4e5f6...
  • Cheia se trimite doar prin header, niciodată în query string sau în corpul cererii.
  • Deplino stochează doar hash-ul cheii. Cheia completă se afișează o singură dată, la generare. Dacă se pierde, generezi alta și o revoci pe cea veche.
  • O cheie e legată de un singur cont de partener. Nu există chei „master" pentru mai mulți parteneri.
  • O cheie poate fi revocată oricând din dashboard. O cerere cu o cheie revocată primește 401.
  • Fiecare răspuns include header-ul X-Deplino-Version: v1.
  • Toate datele sunt în formatul YYYY-MM-DD, pe ora României.

Mediu test și live

Prefixul cheii arată mediul ei:

  • dp_live_...: cheie de producție. Ce trimiți e real: blochează stoc, pleacă pe canale și declanșează webhook-ul.
  • dp_test_...: cheie de test. Orice scriere (sync, PATCH/anulare rezervare, blocări, tarife, restricții, camere, planuri tarifare) trece prin aceleași validări și dă aceleași erori ca pe live, dar nu scrie nimic: nimic în bază, nimic pe canale, niciun webhook. Răspunsul e marcat "test": true.

Citirile se comportă identic pe ambele medii: citesc datele reale ale partenerului, fără să le schimbe. Cheile, câte una pentru fiecare mediu, se generează din același ecran, alegând Live sau Test la creare. Cu cheia de test îți verifici integrarea cap-coadă fără să atingi nimic pe canale.

Mediul de test (test.deplino.ro)

CAUTA: sandbox, staging, test environment, test.deplino.ro, mediu de test

Cheia dp_test_ validează, dar nu scrie. Ca să vezi și efectul scrierilor (rezervarea care scade disponibilitatea, camera nouă care apare în calendar, planul care ajunge în Channel Manager), Deplino are un mediu de test separat, la https://test.deplino.ro:

  • e o copie a platformei, cu bază de date proprie: nimic de acolo nu atinge contul tău real;
  • Channel Manager-ul e legat de mediul de test al Channex, deci nu pleacă nimic pe Booking.com, Airbnb sau Expedia reale;
  • la cerere, îți creăm acolo un cont cu aceleași camere ca hotelul tău real, cu login în dashboard (ca să vezi rezultatul în calendar) și o cheie dp_live_ de test;
  • toate rutele sunt aceleași, cu adresa schimbată: https://test.deplino.ro/api/v1/pms/....

În mediul de test, cheia dp_live_ scrie pe bune (în baza de test). Cheile de pe test.deplino.ro nu merg pe deplino.ro și invers. Datele mediului de test se pot reseta fără anunț; nu le folosi ca arhivă.

Fluxul recomandat de integrare

  1. Mapare, o singură dată. Apelezi GET /produse (tipuri de cameră și camere fizice) și GET /planuri-tarifare (planurile fiecărui tip). În sistemul tău salvezi corespondențele tip_cameră_PMS ↔ produs_id, cameră_fizică_PMS ↔ (produs_id, index_unitate) și plan_PMS ↔ plan_tarifar_id.

  2. Verifici cu cheia dp_test_. Trimiți cererile reale ale integrării: toate validările rulează, nimic nu se scrie.

  3. Încarci starea inițială pe live. Trimiți rezervările viitoare prin POST /sync, cu external_id. Apoi camerele închise prin POST /blocari și prețurile și restricțiile pe orizontul tău (cel mult 500 de zile) prin PUT /tarife și PUT /restrictii.

  4. Din acel moment trimiți doar schimbările:

    • rezervare nouă → POST /sync;
    • rezervare modificată → PATCH /rezervari/{id};
    • rezervare anulată → POST /rezervari/{id}/anulare;
    • cameră închisă sau redeschisă → POST /blocari / DELETE /blocari/{id};
    • preț sau restricție → PUT /tarife / PUT /restrictii.

    Pentru prețuri și restricții, adună schimbările (de exemplu o dată la câteva secunde) în loc să trimiți o cerere la fiecare celulă.

  5. Asculți webhook-ul. Primești rezervările venite pe canale și pe site (rezervare_noua/modificata/anulata), schimbările de disponibilitate (disponibilitate_modificata) și eșecurile de trimitere pe canale (sync_canal_esuat).

  6. Reconciliezi periodic. De exemplu o dată pe noapte: GET /rezervari, GET /blocari, GET /tarife și GET /restrictii pe orizontul tău, comparate cu PMS-ul. Un webhook pierdut sau o cerere căzută se repară așa.

Maparea camerelor

Deplino nu cunoaște identificatorii interni ai PMS-ului tău, așa că primul pas e o mapare făcută de integrator:

  • Tipul de cameră (ex. „Dublă Deluxe") e un produs_id. Prețurile, restricțiile și rezervările se trimit pe el.
  • Camera fizică (ex. camera 204) e index_unitate: un număr de la 0 la stoc_total - 1 în interiorul tipului, cu numar_camera și etaj așa cum le-a scris hotelul în Deplino. Blocările se trimit pe el. Rezervările nu-l cer: Deplino alege singur o cameră fizică liberă.
  • Planul tarifar (ex. „Mic dejun inclus, nerambursabil") e plan_tarifar_id, din GET /planuri-tarifare. O cameră fără planuri proprii are doar prețul de bază (plan_tarifar_id: null).

Maparea pe canale nu se face prin API. Legătura dintre un tip de cameră sau un plan tarifar Deplino și listarea lui de pe Booking.com, Airbnb sau Expedia o face hotelul, din dashboard-ul Deplino, în Channel Manager. Un tip de cameră sau un plan creat prin API apare imediat în Channel Manager, dar nu se vinde pe un canal până când hotelul nu îl leagă acolo de camera și tariful canalului. Dacă hotelul adaugă un tip nou de cameră (din dashboard sau prin API), reiei pasul de mapare (nu există încă un webhook de „produs nou").

Codurile camerelor pe canale le poți citi. După ce hotelul a făcut legătura, fiecare tip de cameră din GET /produse și GET /camere/{id} are coduri_ota: pe ce canal e vândut și cu ce identificatori (ex. ID-ul camerei și al tarifului pe Booking.com). Dacă PMS-ul tău e deja legat de Booking.com, așa recunoști automat care cameră Deplino e care cameră a ta. Codurile se reîmprospătează o dată pe oră; o legătură făcută acum apare în cel mult o oră.

GET /api/v1/pms/produse

Produsele active ale partenerului, fiecare cu camerele fizice ale lui. Fără paginare.

Parametri: niciunul.

curl https://deplino.ro/api/v1/pms/produse \
  -H "Authorization: Bearer dp_live_..."

Răspuns 200:

{
  "produse": [
    {
      "produs_id": "3f2a1c9e-...-8b21",
      "nume_produs": "Cameră Dublă Deluxe",
      "tip": "camera",
      "stoc_total": 3,
      "unitati": [
        { "index_unitate": 0, "numar_camera": "201", "etaj": "2" },
        { "index_unitate": 1, "numar_camera": "202", "etaj": "2" },
        { "index_unitate": 2, "numar_camera": "305", "etaj": "3" }
      ],
      "coduri_ota": [
        { "canal": "booking", "canal_titlu": "Booking.com", "id_camera": "1234501", "id_tarif": "45678901", "plan_tarifar_id": null },
        { "canal": "airbnb", "canal_titlu": "Airbnb", "id_camera": "987654321", "id_tarif": null, "plan_tarifar_id": null }
      ]
    }
  ]
}

coduri_ota e o listă goală dacă tipul de cameră nu e legat de niciun canal. canal e unul din booking, airbnb, expedia, agoda, szallas, google, trip, hostelworld, h2b (un canal nou apare cu numele lui, cu litere mici). id_tarif e null pe canalele fără tarife separate (Airbnb). plan_tarifar_id arată planul Deplino vândut sub acel cod, null pentru prețul de bază. Aceeași cameră poate apărea de mai multe ori pe un canal, câte o dată pentru fiecare tarif.

unitati poate avea mai puține elemente decât stoc_total dacă hotelul nu și-a numerotat toate camerele în Deplino. Indexurile rămân totuși valide de la 0 la stoc_total - 1.

Erori: 401 cheie invalidă, lipsă sau revocată.

Camere: tipuri de cameră și camere fizice

Tipurile de cameră se pot crea, modifica și șterge prin API, iar camerele fizice se pot redenumi. Câmpurile unui tip de cameră:

Câmp Tip Sens
nume text, 2–120 caractere Numele tipului (ex. „Cameră Dublă Deluxe").
pret_baza număr, peste 0, cel mult 50.000 Prețul pe noapte când nu e pus alt preț pe zi.
stoc întreg, 1–200 Câte camere fizice are tipul.
capacitate întreg, 1–30 Câte persoane încap.
descriere text, cel mult 5000 caractere, sau null Opțional.

Un câmp necunoscut dă 400, ca o greșeală de scriere să nu treacă neobservată.

Fiecare schimbare făcută prin API rămâne în jurnalul Deplino: cererea primită și cum arăta camera sau planul înainte și după. Hotelul și echipa Deplino pot vedea exact ce a schimbat integrarea și când.

POST /api/v1/pms/camere

Tip de cameră nou, cu stoc camere fizice numite C1…Cn (le redenumești apoi, vezi mai jos). nume, pret_baza, stoc, capacitate sunt obligatorii. hotel_id e necesar doar dacă contul are mai multe hoteluri.

curl -X POST https://deplino.ro/api/v1/pms/camere \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "nume": "Cameră Dublă Deluxe", "pret_baza": 400, "stoc": 3, "capacitate": 2 }'

Răspuns 201:

{
  "success": true,
  "camera": {
    "produs_id": "3f2a1c9e-...-8b21",
    "hotel_id": "a81d...-77c0",
    "nume": "Cameră Dublă Deluxe",
    "pret_baza": 400,
    "stoc": 3,
    "capacitate": 2,
    "descriere": null,
    "conectata_channex": true,
    "unitati": [
      { "index_unitate": 0, "numar_camera": "C1", "etaj": null },
      { "index_unitate": 1, "numar_camera": "C2", "etaj": null },
      { "index_unitate": 2, "numar_camera": "C3", "etaj": null }
    ],
    "planuri_tarifare": [
      { "plan_tarifar_id": "9c1e...-cx", "id_local": "e3b7...-01", "nume": "Tarif Standard", "mese": "none", "politica_anulare": "flexible", "zile_anulare_gratuita": null, "diferenta_pret": 0, "activ": true }
    ]
  }
}

Dacă hotelul e conectat la Channel Manager, camera apare acolo înainte de răspuns (conectata_channex: true), cu un plan „Tarif Standard". Nu se vinde încă pe niciun canal: hotelul o leagă de camera de pe Booking.com etc. din dashboard (vezi „Maparea camerelor").

GET /api/v1/pms/camere/{id}

Tipul de cameră, în aceeași formă ca mai sus: câmpurile, camerele fizice și planurile tarifare.

PATCH /api/v1/pms/camere/{id}

Trimiți doar câmpurile pe care le schimbi (oricare din tabelul de sus, fără hotel_id).

curl -X PATCH https://deplino.ro/api/v1/pms/camere/3f2a1c9e-...-8b21 \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "stoc": 5, "pret_baza": 420 }'

Răspuns 200: { "success": true, "camera": { ... }, "sincronizare": { "ok": true, "eroare": null } }.

  • Când crește stoc, camerele fizice noi primesc nume C4, C5… Când scade, dispar ultimele (cele cu index_unitate cel mai mare).
  • Stocul nu scade sub ce e vândut: dacă o cameră fizică care ar dispărea are o rezervare viitoare sau în curs, primești 409 cu "motiv": "stoc_sub_rezervari" și nimic nu se schimbă. Muți întâi rezervarea pe altă cameră (PATCH /rezervari/{id}), apoi scazi stocul.
  • Pe o cameră conectată, numărul de camere și planurile pleacă în Channel Manager înainte de răspuns. sincronizare.ok: false înseamnă că schimbarea e salvată în Deplino, dar nu a ajuns acolo; o retrimiți.

DELETE /api/v1/pms/camere/{id}

Șterge tipul de cameră, cu camerele lui fizice. Refuzat cu 409 când are rezervări în istoric ("motiv": "are_rezervari"), ca să nu se piardă rezervările și facturarea lor.

Dacă tipul de cameră e conectat la Channel Manager, înainte de ștergere îl scoatem de pe canale: disponibilitate 0 pe următoarele 500 de zile, apoi planurile și tipul de cameră șterse din Channel Manager. Abia după aceea se șterge din Deplino. Dacă Channel Manager nu confirmă, primești 502 cu "motiv": "channex" și camera rămâne în Deplino; retrimiți cererea peste câteva minute, iar ștergerea continuă de unde a rămas.

Răspuns 200: { "success": true, "produs_id": "3f2a1c9e-...-8b21" }.

PATCH /api/v1/pms/camere/{id}/unitati

Redenumește camerele fizice (și, opțional, etajul), ca să se potrivească cu numerele din PMS. Numărul lor nu se schimbă aici: îl dă stoc.

curl -X PATCH https://deplino.ro/api/v1/pms/camere/3f2a1c9e-...-8b21/unitati \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "unitati": [
        { "index_unitate": 0, "numar_camera": "101", "etaj": "1" },
        { "index_unitate": 1, "numar_camera": "102" }
      ] }'

Răspuns 200: { "success": true, "schimbate": 2, "unitati": [ ... ] }.

  • index_unitate e de la 0 la stoc - 1; numar_camera are 1–20 caractere.
  • Numele sunt unice în tipul de cameră, fără să conteze majusculele. Două camere care își schimbă numele între ele (101 ↔ 102) merg în aceeași cerere.
  • Un nume deja folosit de altă cameră dă 409; un index în afara stocului dă 400.
  • Rezervările și blocările rămân pe camerele lor: ele țin de index_unitate, nu de nume.

GET /api/v1/pms/disponibilitate

Câte camere sunt libere pe un interval și, dacă niciuna, de ce. Folosește același calcul ca site-ul, calendarul și canalele, deci ce apare aici ca liber e liber peste tot.

Parametri (query string):

Parametru Obligatoriu Format Notă
produs_id da uuid trebuie să aparțină partenerului din cheie
check_in da YYYY-MM-DD poate fi o dată deja trecută
check_out da YYYY-MM-DD strict după check_in
curl "https://deplino.ro/api/v1/pms/disponibilitate?produs_id=3f2a1c9e-...&check_in=2026-10-01&check_out=2026-10-05" \
  -H "Authorization: Bearer dp_live_..."

Răspuns 200:

{
  "produs_id": "3f2a1c9e-...-8b21",
  "unitati_libere": 2,
  "total": 4,
  "motiv": null
}

motiv apare când unitati_libere e 0 sau intervalul e blocat integral. Valori posibile: stop_sell, sejur_minim, sejur_maxim, sosire_interzisa, plecare_interzisa, ocupat.

Erori:

  • 400 parametri lipsă sau invalizi, ori interval invalid;
  • 401 cheie invalidă;
  • 403 produsul nu aparține contului tău;
  • 404 produsul nu există.

GET /api/v1/pms/rezervari

Rezervările al căror sejur se suprapune cu fereastra cerută, din toate sursele (canale, site, recepție, API), inclusiv cele anulate, ca să știi ce s-a anulat pe partea Deplino.

Datele oaspetelui ies doar cu acordul hotelului. Implicit, rezervările vin fără date personale. Dacă hotelul bifează în dashboard, la Setări → Pentru dezvoltatori, că sistemul conectat lucrează pentru el și poate primi datele oaspeților, fiecare rezervare primește și oaspete și canal (vezi mai jos), atât aici cât și în webhook. Bifa o poate da sau retrage doar proprietarul contului; de la retragere, datele nu mai pleacă.

Parametri (query string):

Parametru Obligatoriu Format Notă
de_la da YYYY-MM-DD început fereastră
pana_la da YYYY-MM-DD sfârșit fereastră, cel mult 400 de zile după de_la
produs_id nu uuid filtrează pe un singur produs
curl "https://deplino.ro/api/v1/pms/rezervari?de_la=2026-10-01&pana_la=2026-10-31" \
  -H "Authorization: Bearer dp_live_..."

Răspuns 200 (cel mult 1000 de rânduri pe apel; dacă ai mai multe, împarte fereastra):

{
  "rezervari": [
    {
      "id": "9c31...-comanda",
      "produs_id": "3f2a1c9e-...-8b21",
      "check_in": "2026-10-03",
      "check_out": "2026-10-06",
      "status": "confirmata",
      "sursa": "api_extern",
      "total": 540,
      "oaspete": {
        "nume": "Ana Popescu",
        "email": "[email protected]",
        "telefon": "+40 712 345 678",
        "limba": "ro",
        "tara": "RO",
        "oras": "Cluj-Napoca",
        "judet": null,
        "adresa": null,
        "cereri_speciale": "Sosim după 22:00"
      },
      "canal": {
        "nume": "BookingCom",
        "cod_rezervare": "4512398765",
        "politica_anulare": "Gratuit până cu 3 zile înainte",
        "penalitati_anulare": null,
        "plata_incasata_de": "ota"
      }
    }
  ]
}

oaspete și canal apar doar cu bifa hotelului. Câmpurile necunoscute sunt null. La Booking.com, email e adresa de redirecționare dată de Booking, nu adresa personală a oaspetelui, iar nume e numele celui care a făcut rezervarea, care poate fi altcineva decât oaspetele. canal.cod_rezervare e numărul rezervării pe canal (cel din extranetul Booking.com), nu codul Deplino.

sursa arată de unde a venit rezervarea. Prin API poți modifica și anula doar rezervările cu sursa: "api_extern", adică cele trimise de tine prin POST /sync.

Erori: 400 parametri lipsă sau invalizi, ori fereastră peste 400 de zile · 401 cheie invalidă.

POST /api/v1/pms/sync

Trimite în Deplino o rezervare făcută în afara platformei (direct la hotel, pe alt canal neconectat la Deplino), ca să ocupe o cameră aici și pe canale. Deplino alege camera fizică și trimite noua disponibilitate pe canale în câteva secunde, grupat cu celelalte schimbări ale hotelului (vezi Loturi). Răspunsul are lot_id, pe care poți urmări trimiterea.

Apelul e idempotent prin external_id: dacă trimiți de două ori același external_id, primești rezervarea deja creată, fără să ocupe a doua cameră. E util la retry-uri sau după o pană de rețea.

Corp JSON:

Câmp Obligatoriu Notă
produs_id da tipul de cameră; trebuie să aparțină partenerului din cheie
check_in da YYYY-MM-DD, poate fi în trecut (sejur deja început)
check_out da YYYY-MM-DD, strict după check_in
total da numeric, prețul rezervării; Deplino nu îl recalculează
persoane nu implicit 2
platit nu boolean, implicit false
client nu obiect { nume, email, telefon }
external_id nu, dar recomandat id-ul rezervării în sistemul tău; face apelul idempotent
curl -X POST https://deplino.ro/api/v1/pms/sync \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "produs_id": "3f2a1c9e-...-8b21",
    "check_in": "2026-10-03",
    "check_out": "2026-10-06",
    "total": 540,
    "external_id": "pms-42177"
  }'

Răspuns 200 (mediu live). Păstrează id_rezervare: pe el modifici și anulezi.

{ "success": true, "message": "Sincronizare reușită", "id_rezervare": "9c31...-comanda", "lot_id": "7a2e...-lot" }

Răspuns 200 (cheie de test: nimic scris, nicio cameră ocupată):

{ "success": true, "message": "Sincronizare reușită (mediu test — nicio rezervare reală creată, stocul nu a fost afectat).", "id_rezervare": "b0e2...", "test": true }

Răspuns 200 la retrimiterea aceluiași external_id:

{ "success": true, "message": "Rezervarea era deja sincronizată.", "id_rezervare": "9c31...-comanda", "duplicat": true }

Erori:

  • 400 câmp lipsă sau invalid, interval invalid, ori total în afara plajei acceptate;
  • 401 cheie invalidă;
  • 403 produsul nu aparține contului tău;
  • 404 produsul nu există;
  • 409 suprarezervare: nu mai e nicio cameră liberă de tipul ăsta pe interval;
  • 500 eroare internă.

PATCH /api/v1/pms/rezervari/{id}

Modifică o rezervare trimisă de tine prin POST /sync. {id} e id_rezervare primit atunci. Trimiți doar câmpurile care se schimbă; restul rămân cum erau.

Corp JSON (cel puțin un câmp):

Câmp Format Notă
check_in YYYY-MM-DD poate fi în trecut (sejur deja început)
check_out YYYY-MM-DD strict după check_in
produs_id uuid mută rezervarea pe alt tip de cameră al tău
total număr ≥ 0 prețul nou
persoane întreg 1–50
platit boolean

Orice alt câmp primește 400 (de exemplu, datele clientului nu se schimbă prin PATCH).

Dacă se schimbă datele sau tipul, Deplino păstrează camera fizică atunci când e liberă pe noul interval. Altfel alege alta liberă. Pe canale pleacă, grupat, atât intervalul vechi, cât și cel nou, iar răspunsul are lot_id. Dacă schimbi doar total, persoane sau platit, nu e nimic de trimis pe canale și lot_id e null.

curl -X PATCH https://deplino.ro/api/v1/pms/rezervari/9c31...-comanda \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "check_out": "2026-10-07", "total": 720 }'

Răspuns 200:

{
  "success": true,
  "rezervare": {
    "id": "9c31...-comanda",
    "produs_id": "3f2a1c9e-...-8b21",
    "index_unitate": 0,
    "check_in": "2026-10-03",
    "check_out": "2026-10-07",
    "persoane": 2,
    "status": "confirmata",
    "platit": false,
    "sursa": "api_extern",
    "total": 720
  }
}

Dacă rezervarea are deja factură emisă, răspunsul are și avertisment. Factura nu se modifică singură: hotelul o corectează din Deplino.

Erori:

  • 400 câmp necunoscut, corp gol, valoare invalidă, interval invalid sau id care nu e uuid;
  • 401 cheie invalidă;
  • 403 noul produs_id nu e al tău;
  • 404 rezervarea nu există sau nu e a ta;
  • 409 una din situațiile:
    • rezervarea nu a venit prin API (e de pe un canal, de pe site sau din recepție);
    • rezervarea e anulată;
    • suprarezervare: nicio cameră liberă pe noul interval. Rezervarea rămâne cum era.

POST /api/v1/pms/rezervari/{id}/anulare

Anulează o rezervare trimisă de tine prin POST /sync. Camera se eliberează și noua disponibilitate pleacă pe canale grupat, în câteva secunde. Rezervarea rămâne în istoric, cu status: "anulata", și apare așa și în GET /rezervari.

Corp JSON (opțional): { "motiv": "Oaspetele a anulat" }, cel mult 300 de caractere.

curl -X POST https://deplino.ro/api/v1/pms/rezervari/9c31...-comanda/anulare \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "motiv": "Oaspetele a anulat" }'

Răspuns 200: { "success": true, "rezervare": { …, "status": "anulata" }, "lot_id": "…" }.

Apelul e sigur de repetat. O rezervare deja anulată întoarce tot 200, cu "deja_anulata": true, fără un al doilea webhook.

Erori: 400 id invalid · 401 cheie invalidă · 404 rezervarea nu există sau nu e a ta · 409 rezervarea nu a venit prin API.

Blocări: camere fizice închise

O blocare închide o cameră fizică (de exemplu camera 204, cu index_unitate din GET /produse) pe un interval de nopți: mentenanță, reparație, curățenie. Pe canale apare ca o cameră liberă în minus, trimisă grupat, în câteva secunde.

Ca să oprești vânzarea unui tip întreg de cameră, nu folosi blocări. Folosește stop_sell din PUT /restrictii.

GET /api/v1/pms/blocari

Parametri opționali: produs_id, de_la, pana_la (implicit, de azi încolo). Lista include și blocările puse de hotel din Deplino, nu doar cele trimise prin API.

{
  "blocari": [
    {
      "id": "b71e...-blocare",
      "produs_id": "3f2a1c9e-...-8b21",
      "index_unitate": 1,
      "de_la": "2026-10-10",
      "pana_la": "2026-10-12",
      "motiv": "reparatie",
      "nota": "Instalator",
      "creat_la": "2026-10-01T09:12:44.000Z"
    }
  ]
}

POST /api/v1/pms/blocari

Câmp Obligatoriu Notă
produs_id da tipul camerei
index_unitate da camera fizică, 0 … stoc_total - 1
de_la da prima noapte blocată
pana_la da ultima noapte blocată (inclusă), cel mult 365 de nopți
motiv nu mentinere (implicit), reparatie, curatenie
nota nu text liber

Zilele din trecut se ignoră: blocarea începe de azi și răspunsul are un avertisment.

Răspuns 201:

{
  "success": true,
  "blocare": { "id": "b71e...-blocare", "produs_id": "3f2a1c9e-...-8b21", "index_unitate": 1, "de_la": "2026-10-10", "pana_la": "2026-10-12", "motiv": "reparatie", "nota": null, "creat_la": "2026-10-01T09:12:44.000Z" },
  "avertisment": null,
  "lot_id": "7a2e...-lot"
}

Blocarea e salvată în Deplino. Trimiterea pe canale o urmărești pe lot_id, cu GET /loturi/{id}. Cu cheia de test, lot_id e null.

Erori:

  • 400 câmp lipsă sau invalid, index_unitate în afara plajei, interval invalid sau în trecut, ori peste 365 de nopți;
  • 403 produsul nu e al tău;
  • 409 camera are o rezervare în acel interval. Răspunsul include rezervari: [id…]: muți rezervarea pe altă cameră în PMS, apoi blochezi.

DELETE /api/v1/pms/blocari/{id}

Redeschide camera și trimite disponibilitatea pe canale, grupat. Răspuns 200: { "success": true, "id": "…", "lot_id": "…" }. lot_id e null dacă blocarea se terminase deja (nu e nimic de trimis) sau cu cheia de test. Merge și pe blocările puse de hotel din Deplino. Nu merge pe blocările automate care țin locul unei rezervări mutate (409).

Erori: 400 id invalid · 404 blocarea nu există sau nu e a ta · 409 blocare automată.

GET /api/v1/pms/planuri-tarifare

Pentru fiecare tip de cameră: prețul de bază și planurile tarifare, ca să-ți mapezi planurile pe plan_tarifar_id. Parametru opțional: produs_id.

{
  "camere": [
    {
      "produs_id": "3f2a1c9e-...-8b21",
      "nume_produs": "Cameră Dublă Deluxe",
      "pret_baza": 400,
      "conectat_channex": true,
      "planuri": [
        { "plan_tarifar_id": "9c1e...-cx", "id_local": "e3b7...-01", "nume": "Nerambursabil", "mese": "breakfast", "politica_anulare": "non_refundable", "zile_anulare_gratuita": null, "diferenta_pret": -40, "activ": true }
      ]
    }
  ]
}
  • id_local e identificatorul stabil al planului: nu se schimbă niciodată. plan_tarifar_id devine id-ul din Channel Manager după ce planul ajunge acolo, deci se poate schimba o dată, imediat după creare. Salvează id_local în maparea ta. Oriunde API-ul cere un plan_tarifar_id (tarife, rezervări, rutele de mai jos) îl primește pe oricare dintre ele.
  • diferenta_pret e diferența față de prețul de bază pe zilele fără un preț pus explicit pe acel plan.
  • zile_anulare_gratuita: cu câte zile înainte de sosire se poate anula gratuit, la politica_anulare: "flexible"; null = regula generală a hotelului.
  • conectat_channex: false înseamnă că acel tip nu e legat încă de canale. Prețurile se salvează în Deplino, dar nu pleacă nicăieri.
  • O cameră fără planuri proprii (planuri: []) are doar prețul de bază. Pe ea trimiți tarife cu plan_tarifar_id: null.

POST /api/v1/pms/camere/{id}/planuri-tarifare

CAUTA: create rate plan, add rate plan, update rate plan, delete rate plan, plan nou, sterge plan

Plan tarifar nou pe tipul de cameră {id}. Câmpuri:

Câmp Valori
nume (obligatoriu) 2–60 caractere, unic pe cameră
mese (obligatoriu) none, breakfast, half_board, full_board
diferenta_pret (obligatoriu) lei față de prețul de bază: 0, pozitiv sau negativ (cel mult ±10.000, fără să ducă prețul sub zero)
politica_anulare flexible (implicit) sau non_refundable
zile_anulare_gratuita întreg 1–365 sau null; ignorat la non_refundable
activ true (implicit) sau false
curl -X POST https://deplino.ro/api/v1/pms/camere/3f2a1c9e-...-8b21/planuri-tarifare \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "nume": "Nerambursabil", "mese": "breakfast", "diferenta_pret": -40, "politica_anulare": "non_refundable" }'

Răspuns 201: { "success": true, "plan": { ... }, "planuri": [ ... ], "sincronizare": { "ok": true, "eroare": null } }. Pe o cameră conectată, planul e creat în Channel Manager înainte de răspuns, iar plan.plan_tarifar_id e deja id-ul de acolo. Nu se vinde încă pe niciun canal: hotelul îl leagă de tariful de pe Booking.com etc. din dashboard. O cameră are cel mult 10 planuri.

PATCH /api/v1/pms/camere/{id}/planuri-tarifare/{plan_id}

Doar câmpurile trimise se schimbă. {plan_id} e id_local sau plan_tarifar_id. Legătura planului cu canalele rămâne neatinsă. Răspuns 200, cu aceeași formă ca la creare.

DELETE /api/v1/pms/camere/{id}/planuri-tarifare/{plan_id}

Șterge planul din Deplino și din Channel Manager (deci și de pe canalele pe care era legat). Rezervările făcute deja pe el rămân. Răspuns 200: { "success": true, "plan": { ... }, "planuri": [ ... ] }. Un plan legat de H2B se scoate doar din dashboard (409, "motiv": "legat_h2b").

Tarife (prețuri pe zile)

GET /api/v1/pms/tarife

Parametri: de_la, pana_la (obligatorii, cel mult 500 de zile) și produs_id (opțional). Întoarce doar zilele cu preț pus explicit. Zilele care lipsesc au prețul de bază (plus diferența planului) din GET /planuri-tarifare.

{
  "trunchiat": false,
  "tarife": [
    { "produs_id": "3f2a1c9e-...-8b21", "data": "2026-12-31", "plan_tarifar_id": null, "pret": 650 }
  ]
}

trunchiat: true înseamnă că ai depășit 1000 de rânduri. Restrânge intervalul sau filtrează pe produs_id.

PUT /api/v1/pms/tarife

curl -X PUT https://deplino.ro/api/v1/pms/tarife \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tarife": [
      { "produs_id": "3f2a1c9e-...-8b21", "plan_tarifar_id": null, "de_la": "2026-12-20", "pana_la": "2026-12-30", "pret": 520 },
      { "produs_id": "3f2a1c9e-...-8b21", "plan_tarifar_id": null, "de_la": "2026-12-31", "pana_la": "2026-12-31", "pret": 650 }
    ]
  }'
  • plan_tarifar_id: null (sau lipsă) setează prețul de bază pe acele zile; planurile îl urmează cu diferența lor. Cu un plan_tarifar_id (sau id_local-ul planului), setezi prețul exact al acelui plan.
  • pret e un număr ≥ 0, în moneda hotelului.
  • de_la și pana_la sunt incluse, de azi până la cel mult 500 de zile. Zilele din trecut ale unui interval se ignoră.
  • Dacă aceeași zi apare în două elemente, câștigă ultimul.
  • Limite pe cerere: cel mult 1000 de elemente și 50.000 de zile-cameră.

Răspuns 202: prețurile sunt salvate în Deplino, iar trimiterea pe canale urmează (vezi Loturi):

{ "success": true, "stare": "in_asteptare", "lot_id": "5d0c...-lot", "elemente": 2, "zile": 12, "de_la": "2026-12-20", "pana_la": "2026-12-31" }

Cu cheia de test: 200, "test": true, lot_id: null, nimic salvat.

Erori:

  • 400 listă goală sau prea mare, element invalid (mesajul spune care: „Elementul 3: …"), plan care nu e al camerei, produs care nu e cameră, interval în trecut sau peste 500 de zile;
  • 403 produs care nu e al tău;
  • 409 prețurile hotelului sunt gestionate din Deplino, nu din PMS (vezi „Prețuri gestionate din PMS"). Scrierea nu se face.

Dacă o cerere mare eșuează la jumătate, răspunsul de eroare are și zile_salvate și lot_id: ce s-a salvat pleacă pe canale. Retrimite cererea întreagă, pentru că o scriere repetată a acelorași valori nu strică nimic.

Restricții

Restricțiile sunt pe tipul de cameră și pe zi:

Câmp Implicit Sens
min_stay 1 sejur minim, întreg 1–365
max_stay 30 sejur maxim, întreg 1–730, ≥ min_stay
stop_sell false tipul nu se vinde în acea zi
cta false închis la sosire: nu se poate face check-in în acea zi
ctd false închis la plecare: nu se poate face check-out în acea zi

GET /api/v1/pms/restrictii

Parametri: de_la, pana_la (obligatorii, cel mult 500 de zile) și produs_id (opțional). Întoarce doar zilele cu restricții puse; zilele care lipsesc au valorile implicite. Camerele fizice închise nu apar aici, ci în GET /blocari.

{
  "trunchiat": false,
  "restrictii": [
    { "produs_id": "3f2a1c9e-...-8b21", "data": "2026-12-31", "min_stay": 2, "max_stay": 30, "stop_sell": false, "cta": false, "ctd": true }
  ]
}

PUT /api/v1/pms/restrictii

curl -X PUT https://deplino.ro/api/v1/pms/restrictii \
  -H "Authorization: Bearer dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "restrictii": [
      { "produs_id": "3f2a1c9e-...-8b21", "de_la": "2026-12-30", "pana_la": "2027-01-01", "min_stay": 2 },
      { "produs_id": "3f2a1c9e-...-8b21", "de_la": "2027-02-10", "pana_la": "2027-02-12", "stop_sell": true }
    ]
  }'

Fiecare element e starea completă a zilelor lui. Ce nu trimiți revine la valoarea implicită. În exemplu, 30 decembrie – 1 ianuarie devin min_stay: 2, iar stop_sell, cta și ctd devin false, chiar dacă erau true înainte. Trimite mereu toate restricțiile pe care le vrei pe acele zile, nu doar pe cea schimbată.

stop_sell, cta și ctd sunt boolean (true/false). Interval, limite, răspuns 202, test, erori și loturi: la fel ca la PUT /tarife. Restricțiile nu ating camerele fizice închise prin blocări.

Loturi: cum ajung schimbările pe canale

Canalele primesc un număr limitat de actualizări pe minut pentru fiecare hotel. De aceea orice scriere care schimbă ce se vede pe canale (POST /sync, PATCH /rezervari/{id}, anularea, POST/DELETE /blocari, PUT /tarife, PUT /restrictii) se salvează pe loc în Deplino și întoarce un lot_id, iar trimiterea pe canale se face grupat: toate loturile în așteptare ale hotelului pleacă împreună, în câteva secunde. Rezervările și blocările pleacă imediat, cât timp hotelul mai are loc în limita de pe minut. Prețurile și restricțiile pleacă cel mult o dată la 20 de secunde. Nu e nevoie să aștepți un lot ca să-l trimiți pe următorul.

Disponibilitatea o calculează mereu Deplino, din toate sursele, în momentul trimiterii. Deci un lot de rezervare trimite numărul real de camere libere, nu doar efectul acelei rezervări.

GET /api/v1/pms/loturi/{id}

{
  "lot": {
    "lot_id": "5d0c...-lot",
    "tip": "tarife",
    "de_la": "2026-12-20",
    "pana_la": "2026-12-31",
    "elemente": 2,
    "zile": 12,
    "stare": "trimis",
    "incercari": 0,
    "eroare": null,
    "creat_la": "2026-12-01T10:00:00.000Z",
    "trimis_la": "2026-12-01T10:00:11.000Z"
  }
}
stare Ce înseamnă
in_asteptare salvat în Deplino, încă netrimis pe canale (de obicei câteva secunde)
trimis canalele au confirmat
fara_channex hotelul nu e conectat la canale; schimbarea e doar în Deplino
eroare canalele au refuzat de 5 ori; primești și webhook-ul sync_canal_esuat

tip e unul din tarife, restrictii, rezervare, blocare.

Când trimite, Deplino citește valorile din momentul trimiterii. Dacă ai schimbat aceeași zi de două ori, pe canale pleacă ultima valoare.

Erori: 400 id invalid · 404 lotul nu există sau nu e al tău.

Prețuri gestionate din PMS

Când prețurile și restricțiile vin din PMS, hotelul le poate bloca în Deplino: calendarul, Channel Manager-ul și asistentul AI din Deplino nu le mai pot modifica (primesc un mesaj că se modifică din PMS). Altfel, o schimbare făcută din Deplino ar fi suprascrisă de următoarea trimitere din PMS, fără ca cineva să observe. Prin API scrierea merge oricum.

Comutatorul se pornește pe contul hotelului. Pentru moment îl pornește echipa Deplino, la cererea hotelului.

Blocările camerelor fizice și rezervările nu sunt afectate de comutator.

Mesaje, recenzii, comentarii și postări

Cu modulul „Mesaje” activ pe contul hotelului, integrarea poate citi și răspunde la tot ce vede hotelul în Inbox-ul Deplino: mesajele oaspeților de pe Booking.com, Airbnb și Expedia, recenziile de pe canale, mesajele și comentariile de pe Facebook și Instagram, și poate programa postări. Fără modul, toate rutele de mai jos răspund 403 cu "motiv": "modul_inactiv".

  • Textele trimise au cel mult 5000 de caractere. Pe Booking.com, Airbnb și Expedia spațiile de la capete se taie; pe Facebook și Instagram textul pleacă exact cum l-ai trimis.
  • Răspunsurile scrise prin API sunt răspunsuri ale omului, chiar dacă hotelul are activat și răspunsul automat cu AI (acela ține de abonamentul hotelului și lucrează separat).
  • Cu o cheie dp_test_ nimic nu pleacă spre Booking.com, Facebook sau Instagram: se fac toate verificările (existență, proprietate, fereastră, validări) și primești { "success": true, "test": true }.
  • Ca să afli de un mesaj nou fără să citești în buclă, folosește webhook-ul (evenimentele mesaj_primit, recenzie_primita, comentariu_primit).

GET /api/v1/pms/mesaje/ota

Conversațiile cu oaspeții de pe canale (cele mai noi 100, cele mai recente întâi).

{
  "conversatii": [
    {
      "id": "b1e2...-fir",
      "canal": "BookingCom",
      "titlu": "Ana Popescu",
      "comanda_id": "9c31...-comanda",
      "inchisa": false,
      "necitita": true,
      "ultim_mesaj_la": "2026-11-19T08:12:00.000Z",
      "ultim_mesaj_de": "oaspete",
      "previzualizare": "Bună, ajungem la 22. E ok?"
    }
  ]
}

comanda_id leagă conversația de rezervare (același id ca în GET /rezervari), când se poate.

GET /api/v1/pms/mesaje/ota/{id}

Mesajele unei conversații, în ordine: { "conversatie": { "id", "canal", "titlu", "inchisa" }, "mesaje": [{ "id", "de": "oaspete" | "proprietate", "text", "atasamente", "la" }] }.

POST /api/v1/pms/mesaje/ota/{id}

Răspunde în conversație. Corp: { "text": "Sigur, vă așteptăm." }. Răspuns 200: { "success": true }. 409 cu "motiv": "thread_inchis" dacă canalul a închis conversația.

PATCH /api/v1/pms/mesaje/ota/{id}

Corp: { "citita": true }. Marchează conversația citită și în Inbox-ul hotelului.

POST /api/v1/pms/rezervari/{id}/mesaj

Scrie primul mesaj către oaspete, pe o rezervare venită de pe un canal (fără să existe încă o conversație). Corp: { "text": "..." }. 409 cu "motiv": "fara_booking_ota" dacă rezervarea nu a venit de pe un canal (ex. rezervare directă).

GET /api/v1/pms/recenzii

{
  "recenzii": [
    {
      "id": "c4d5...-recenzie",
      "canal": "BookingCom",
      "nota": 9.2,
      "note_detaliate": [],
      "nume_oaspete": "Ion",
      "text": "Cameră curată, personal amabil.",
      "raspuns": null,
      "are_raspuns": false,
      "necitita": true,
      "primita_la": "2026-11-18T10:00:00.000Z",
      "raspuns_posibil_pana_la": "2026-11-28T10:00:00.000Z",
      "poate_raspunde": true
    }
  ]
}

note_detaliate sunt notele pe categorii, așa cum le dă canalul (listă goală dacă lipsesc). poate_raspunde e false dacă hotelul a răspuns deja sau a trecut termenul canalului.

POST /api/v1/pms/recenzii/{id}

Răspunsul public al hotelului. Corp: { "text": "Mulțumim!" }. Se poate răspunde o singură dată: 409 cu "motiv": "deja_raspuns" la a doua oară.

PATCH /api/v1/pms/recenzii/{id}

Corp: { "citita": true }.

GET /api/v1/pms/mesaje/social

Conversațiile de pe Facebook Messenger și Instagram Direct.

{
  "conversatii": [
    {
      "id": "e7f8...-fir",
      "platforma": "instagram",
      "nume_client": "Maria",
      "necitite": 2,
      "fereastra_deschisa": true,
      "fereastra_expira_la": "2026-11-20T09:40:00.000Z",
      "arhivata": false,
      "creat_la": "2026-11-12T16:02:00.000Z",
      "ultim_mesaj_la": "2026-11-19T09:40:00.000Z",
      "ultim_mesaj_de": "client",
      "previzualizare": "Aveți loc sâmbătă?"
    }
  ]
}

GET /api/v1/pms/mesaje/social/{id}

{ "conversatie": { ... }, "mesaje": [{ "id", "de": "client" | "proprietate", "tip", "text", "atasamente", "raspuns_de": "ai" | "om" | null, "la" }] }. conversatie are aceeași formă ca în listă (fără ultim_mesaj_*).

POST /api/v1/pms/mesaje/social/{id}

Corp: { "text": "...", "agent_uman": false }.

Facebook și Instagram permit răspunsul doar 24 de ore de la ultimul mesaj al clientului (fereastra_deschisa). Dacă răspunde un om, nu un robot, trimite "agent_uman": true și fereastra devine 7 zile. Folosește agent_uman doar pentru răspunsuri scrise de un om: regula e a Meta, iar folosirea ei pentru mesaje automate poate duce la blocarea paginii. Peste fereastră primești 409 cu "motiv": "fereastra_inchisa".

PATCH /api/v1/pms/mesaje/social/{id}

Corp: { "citita": true }.

GET /api/v1/pms/comentarii

Comentariile de la postările paginilor de Facebook și Instagram ale hotelului. Cu ?necitite=true, doar cele necitite.

{
  "comentarii": [
    {
      "id": "a9b0...-comentariu",
      "platforma": "facebook",
      "postare_id": "1234567890_987654321",
      "raspuns_la_comentariu": false,
      "autor": "Dan",
      "al_paginii": false,
      "text": "Superb loc!",
      "raspuns": null,
      "raspuns_de": null,
      "ascuns": false,
      "necitit": true,
      "la": "2026-11-19T07:30:00.000Z"
    }
  ]
}

al_paginii: true marchează comentariile scrise chiar de pagina hotelului. raspuns_la_comentariu: true înseamnă că e un răspuns la alt comentariu, nu direct la postare.

POST /api/v1/pms/comentarii/{id}

Răspunde public la comentariu. Corp: { "text": "Mulțumim!" }.

PATCH /api/v1/pms/comentarii/{id}

Corp: { "citit": true } și/sau { "ascuns": true } (ascunde comentariul pe pagină; false îl arată din nou).

GET /api/v1/pms/postari

Ultimele 50 de postări, cu starea pe fiecare platformă: { "postari": [{ "id", "text", "are_imagine", "programata_la", "stare", "creata_la", "platforme": [{ "platforma", "stare", "eroare", "publicata_la" }] }] }.

POST /api/v1/pms/postari

{
  "text": "Weekend de iarnă la noi: -15% la 2 nopți.",
  "platforme": ["facebook", "instagram"],
  "programata_la": "2026-11-25T09:00:00Z",
  "imagine_base64": "/9j/4AAQSkZJRgABAQ...",
  "imagine_tip": "image/jpeg"
}
  • Fără programata_la (sau cu o dată trecută), postarea pleacă imediat.
  • Imaginea vine în corp, ca base64 (image/jpeg, image/png sau image/webp, cel mult 10 MB). Nu primim linkuri de imagini. Tipul se stabilește din conținutul fișierului, nu din imagine_tip, iar fiecare imagine trece prin antivirus: 400 cu "motiv": "virus_detectat" dacă e respinsă, 503 cu "motiv": "scanare_indisponibila" dacă antivirusul nu răspunde (retrimite peste câteva minute).
  • Instagram cere o imagine.
  • 400 cu "motiv": "fara_conexiune" dacă hotelul nu și-a legat pagina pe acea platformă.

DELETE /api/v1/pms/postari/{id}

Șterge postarea (și de pe pagini, dacă a fost publicată).

POST /api/v1/pms/postari/{id}

Publică acum o postare programată. Fără corp.

Webhook de ieșire

Dacă partenerul are un URL de webhook activ (setat din dashboard, tab Setări → API), Deplino trimite un POST cu un eveniment JSON:

Eveniment Când
rezervare_noua rezervare nouă pentru un produs al partenerului (de pe canale, site, recepție sau API)
rezervare_modificata rezervare modificată
rezervare_anulata rezervare anulată
disponibilitate_modificata s-a schimbat disponibilitatea fără o rezervare: cameră închisă sau redeschisă, intervenție programată, număr de camere schimbat
sync_canal_esuat un lot (prețuri, restricții, rezervare sau blocare) a fost refuzat definitiv de canale
mesaj_primit mesaj nou de la un oaspete (Booking.com, Airbnb, Expedia) sau de la un client pe Facebook / Instagram (doar cu modulul „Mesaje”)
recenzie_primita recenzie nouă pe un canal (doar cu modulul „Mesaje”)
comentariu_primit comentariu nou la o postare de pe Facebook / Instagram (doar cu modulul „Mesaje”)

Fiecare eveniment are forma { tip, eveniment_id, timestamp, data }. Folosește eveniment_id ca să recunoști o livrare repetată.

Evenimentele de rezervare

{
  "tip": "rezervare_noua",
  "eveniment_id": "6b7d...-eveniment",
  "timestamp": "2026-10-01T14:22:03.000Z",
  "data": {
    "comanda_id": "9c31...-comanda",
    "produs_id": "3f2a1c9e-...-8b21",
    "check_in": "2026-10-03",
    "check_out": "2026-10-06",
    "total_plata": 540,
    "status": "confirmata"
  }
}

Payload-ul se reconstruiește din starea curentă a rezervării, nu dintr-o copie de la momentul evenimentului. O livrare repetată după câteva ore arată starea reală. Datele oaspetelui (oaspete, canal, aceeași formă ca la GET /rezervari) intră în data doar cu bifa hotelului din Setări → Pentru dezvoltatori. Primești și evenimentele rezervărilor trimise chiar de tine prin API. comanda_id e același cu id_rezervare, deci le recunoști.

disponibilitate_modificata

{
  "tip": "disponibilitate_modificata",
  "eveniment_id": "24b8...-eveniment",
  "timestamp": "2026-11-17T14:25:41.601Z",
  "data": { "produs_id": "3f2a1c9e-...-8b21", "de_la": "2026-11-02", "pana_la": "2026-11-04" }
}
  • de_la și pana_la sunt ambele incluse.
  • O schimbare pe mai multe zile vine ca un singur eveniment, nu câte unul pe zi.
  • La schimbarea numărului de camere al unui tip, intervalul e de azi până la +500 de zile.
  • Primești evenimentul și pentru blocările făcute chiar de tine prin API. E normal, disponibilitatea chiar s-a schimbat. Nu e un conflict.
  • Reacția recomandată: citești GET /disponibilitate și GET /blocari pe interval.
  • Rezervările nu declanșează acest eveniment; ele au evenimentele lor.

sync_canal_esuat

{
  "tip": "sync_canal_esuat",
  "eveniment_id": "a1f0...-eveniment",
  "timestamp": "2026-12-01T10:05:00.000Z",
  "data": {
    "loturi": ["5d0c...-lot"],
    "de_la": "2026-12-20",
    "pana_la": "2026-12-31",
    "eroare": "Canalele (Booking, Airbnb etc.) au refuzat actualizarea după 5 încercări. Schimbările sunt salvate la Deplino, dar pe canale e încă starea veche."
  }
}

Schimbările sunt salvate în Deplino, dar pe canale e încă starea veche. La prețuri și restricții, retrimite intervalul mai târziu (PUT /tarife sau PUT /restrictii). La rezervări și blocări nu trebuie să faci nimic: sincronizarea automată a hotelului retrimite disponibilitatea. Dacă eroarea se repetă, scrie-ne.

Evenimentele de mesaje

{
  "tip": "mesaj_primit",
  "eveniment_id": "f3c1...-eveniment",
  "timestamp": "2026-11-19T08:12:40.000Z",
  "data": {
    "id": "7a6b...-mesaj",
    "fir_id": "b1e2...-fir",
    "canal": "BookingCom",
    "sursa": "ota",
    "comanda_id": "9c31...-comanda",
    "primit_la": "2026-11-19T08:12:00.000Z"
  }
}
  • La mesaj_primit, sursa e ota (citești cu GET /mesaje/ota/{fir_id}) sau social (cu GET /mesaje/social/{fir_id}, iar canal e facebook sau instagram).
  • recenzie_primita: { id, canal, nota, primita_la } → GET /recenzii.
  • comentariu_primit: { id, canal, postare_id, primit_la } → GET /comentarii.
  • Textul nu e în payload, doar identificatorii: îl citești prin API, cu cheia ta.
  • Evenimentele de mesaje pleacă la cel mult 2 minute după ce mesajul a ajuns la Deplino. Comentariile scrise chiar de pagina hotelului nu generează eveniment.

La disponibilitate_modificata, sync_canal_esuat și evenimentele de mesaje, payload-ul e cel de la momentul evenimentului, și tot acela se retrimite.

Verificarea semnăturii

Fiecare cerere are un header X-Deplino-Signature de forma:

X-Deplino-Signature: t=1730469723,v1=5257a869e7...

t e un timestamp Unix (secunde), iar v1 e HMAC-SHA256(secret, "{t}.{corp_json}"), în hex. Secretul se vede o singură dată, la generare sau regenerare, din dashboard. Verifică semnătura înainte de a folosi conținutul și respinge orice cerere cu un t mai vechi de 5 minute (300s), ca protecție la replay.

Node.js:

import crypto from 'node:crypto';

function verificaWebhook(corpRaw, header, secret) {
  const [tPart, v1Part] = header.split(',');
  const t = Number(tPart.split('=')[1]);
  const semnaturaPrimita = v1Part.split('=')[1];

  if (Math.abs(Date.now() / 1000 - t) > 300) {
    throw new Error('Semnătură expirată (peste 5 minute).');
  }

  const semnaturaAsteptata = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${corpRaw}`)
    .digest('hex');

  const a = Buffer.from(semnaturaPrimita, 'hex');
  const b = Buffer.from(semnaturaAsteptata, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    throw new Error('Semnătură invalidă.');
  }
}

PHP:

<?php
function verificaWebhook(string $corpRaw, string $header, string $secret): void {
    [$tPart, $v1Part] = explode(',', $header, 2);
    $t = (int) substr($tPart, 2);
    $semnaturaPrimita = substr($v1Part, 3);

    if (abs(time() - $t) > 300) {
        throw new Exception('Semnătură expirată (peste 5 minute).');
    }

    $semnaturaAsteptata = hash_hmac('sha256', "{$t}.{$corpRaw}", $secret);

    if (!hash_equals($semnaturaAsteptata, $semnaturaPrimita)) {
        throw new Exception('Semnătură invalidă.');
    }
}

Retry

O livrare care nu primește un răspuns 2xx (sau eșuează din cauza rețelei ori a timeout-ului de 10s) se reîncearcă automat, cu pauze crescătoare: după 30s, 2 min, 10 min, apoi 1 oră. După a cincea încercare eșuată, livrarea e marcată definitiv eșuată și rămâne în jurnal. Se poate retrimite manual din dashboard oricând după aceea.

URL-ul trebuie să fie https://. Redirect-urile nu se urmăresc. Răspunde repede cu 2xx și procesează după, ca să nu atingi timeout-ul.

Rate-limits și anti-abuz

Limitele sunt per cheie, fiecare cu contorul ei separat:

Grup Limită
Citiri (toate GET) 60 de cereri pe minut
Scrieri punctuale (PATCH/anulare rezervare, blocări, camere, planuri tarifare, mesaje, recenzii, comentarii, postări) 60 de cereri pe minut
Prețuri și restricții (PUT /tarife, PUT /restrictii) 60 de cereri pe minut

Peste limită primești 429 cu header-ul Retry-After (în secunde).

  • POST /sync nu are o limită separată. E protejat de plafonul general anti-bot al platformei.
  • Pentru prețuri și restricții contează mai mult să trimiți puțin și grupat: o cerere cu multe elemente e mai bună decât multe cereri cu câte unul.
  • O cheie care primește 20 de răspunsuri 403 (produs care nu e al ei) în 5 minute e dezactivată automat, iar partenerul e anunțat pe email. Asta indică o cheie configurată greșit sau folosită pe alt cont.
  • Mai multe cereri 401 (chei invalide sau necunoscute) de pe aceeași adresă IP declanșează o alertă internă (semn de scanare), fără să afecteze cheile valide.

Coduri de eroare

Toate răspunsurile de eroare au forma { "error": "mesaj" }, în română. Multe adaugă motiv, un cod stabil pe care îl poți testa în program (ex. modul_inactiv). Unele adaugă câmpuri utile, de exemplu rezervari la o blocare refuzată sau zile_salvate și lot_id la o scriere parțială.

Cod Sens
200 / 201 Reușit.
202 Acceptat: salvat în Deplino, trimiterea pe canale urmează (PUT /tarife, PUT /restrictii).
400 Cerere invalidă: câmp lipsă sau necunoscut, format greșit, interval ori sumă în afara limitelor.
401 Cheie API lipsă, invalidă sau revocată.
403 Cheia e validă, dar produsul cerut nu aparține contului ei; sau modulul „Mesaje” nu e activ pe cont ("motiv": "modul_inactiv").
404 Resursa nu există sau nu e a ta (rezervare, blocare, lot, produs, conversație, recenzie, comentariu, postare).
409 Conflict: suprarezervare; cameră cu rezervare la blocare; rezervare care nu e din API sau e anulată; prețuri gestionate din Deplino; stoc sub camerele vândute (stoc_sub_rezervari); tip de cameră cu rezervări (are_rezervari) la ștergere; nume de cameră sau de plan deja folosit; la mesaje: conversație închisă (thread_inchis), recenzie deja răspunsă (deja_raspuns), rezervare fără canal (fara_booking_ota), fereastra Facebook / Instagram închisă (fereastra_inchisa).
429 Prea multe cereri; vezi rate-limits.
500 Eroare internă Deplino. Retrimite mai târziu; dacă persistă, scrie-ne.
502 Channel Manager nu a confirmat o operație (ex. ștergerea unei camere conectate, "motiv": "channex"). Nimic nu s-a schimbat în Deplino; retrimite mai târziu. La mesaje: canalul sau Facebook / Instagram a refuzat trimiterea.
503 Un serviciu de care depinde cererea nu răspunde acum (ex. antivirusul la imaginea unei postări, "motiv": "scanare_indisponibila"). Nimic nu s-a salvat; retrimite peste câteva minute.

Versionare

Toate rutele sunt sub /api/v1/. O schimbare incompatibilă (câmp eliminat, sens schimbat) vine pe o cale nouă, /api/v2/.... /api/v1/ nu se modifică retroactiv sub integratorii existenți. Câmpurile și endpointurile noi se pot adăuga în v1, deci clientul tău trebuie să ignore câmpurile pe care nu le cunoaște. Fiecare răspuns poartă header-ul X-Deplino-Version: v1, ca să verifici programatic versiunea.