📘 Documentație API Dal Travel

API pentru integrarea ofertelor de călătorie

Prezentare generală

API-ul Dal Travel oferă acces programatic la baza de date cu oferte disponibile pe platforma Dal Travel. Acesta expune două endpoint-uri publice, fără autentificare, care returnează liste paginate în format JSON: feed-ul complet de oferte și feed-ul pentru locuri disponibile.

Specificații OpenAPI

API-ul DAL Travel este documentat folosind standardul OpenAPI 3.0.3, oferind specificații complete pentru integrare și testare.

Fișiere disponibile

• OpenAPI YAML: https://rezervari.daltravel.ro/api_docs/openapi.yaml
• OpenAPI JSON: https://rezervari.daltravel.ro/api_docs/openapi.json

Caracteristici OpenAPI

• Schema completă: Toate câmpurile documentate cu tipuri de date corecte
• Exemple: Exemple pentru fiecare câmp și endpoint
• Validări: Restricții min/max pentru parametri
• Enum-uri: Valorile fixe pentru zone și status
• Format date: Format ISO 8601 pentru datele de timp
• Referințe: Relații între schema-uri
• Răspunsuri de eroare: Documentație completă pentru toate codurile de eroare

Endpoint principal

https://rezervari.daltravel.ro/feed

Metodă: GET
Autentificare: Nu este necesară (endpoint public)
Format răspuns: JSON
Rate Limiting: Nu este aplicat (endpoint public)

Endpoint locuri disponibile

https://rezervari.daltravel.ro/feed/locuri-libere

Metodă: GET
Autentificare: Nu este necesară (endpoint public)
Format răspuns: JSON
Descriere: Returnează aceleași oferte paginate, dar cu informația agregată de disponibilitate prin câmpul locuriDisponibile în plecariActive[].

Parametri de interogare (Query Parameters)

Exemple de cerere:

# Cerere de bază
GET https://rezervari.daltravel.ro/feed

# Cu parametri de paginare
GET https://rezervari.daltravel.ro/feed?page=2&limit=15

# Feed locuri disponibile
GET https://rezervari.daltravel.ro/feed/locuri-libere?page=1&limit=20

## Structura răspunsului (JSON)

### Răspuns de bază
```json
{
  "offers": [
    {
      "plecariActive": [
        {
          "title": "Exemplu de titlu pentru ofertă de călătorie",
          "locuriDisponibile": 25,
          "partajeCountByGender": {
            "masculin": 12,
            "feminin": 13
          },
          "name": null,
          "deleted": null,
          "pdfUrl": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_brochura.pdf",
          "listPhotoUrl": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_imagine_lista.webp",
          "id": 1234567,
          "status": "active",
          "cancelDays1": 120,
          "cancelPercent1": 5,
          "cancelDays2": 90,
          "cancelPercent2": 10,
          "cancelDays3": 60,
          "cancelPercent3": 50,
          "cancelDays4": 30,
          "cancelPercent4": 100,
          "tagline": "Exemplu de tagline pentru ofertă",
          "orase": null,
          "introducere": "Text de introducere pentru ofertă...",
          "sub_intro": "Sub-introducere pentru ofertă...",
          "va_invitam": "Text de invitație...",
          "info_traseu": "Informații despre traseu...",
          "info_insotitor": "Însoțitor român și ghizi locali",
          "info_tarif": "\u003Cp\u003E\u003Cstrong\u003E1200 EURO / loc în cameră dublă; Supliment single: 300 EURO\u003C/strong\u003E\u003C/p\u003E",
          "obiective_natura": "Exemplu de obiective de natură, Parcul Natural, Rezervația Naturală",
          "obiective_arta": "Exemplu de obiective de artă...",
          "obiective_traditii": null,
          "obiective_distractii": null,
          "start_date": "2024-06-15T00:00:00+03:00",
          "end_date": "2024-06-25T00:00:00+03:00",
          "tarif_dubla_text": "1200 EURO",
          "tarif_euro": 1200,
          "reducere_euro": 50,
          "tarif_usd": 1300,
          "reducere_usd": 25,
          "tarif_ron": 6000,
          "reducere_ron": 250,
          "tarif_a_treia_text": "1000 EURO",
          "discount_a_treia_euro": 200,
          "discount_a_treia_usd": 220,
          "discount_a_treia_ron": 1000,
          "tarif_copil_extra_text": "800 EURO",
          "discount_copil_extra_euro": 400,
          "discount_copil_extra_usd": 440,
          "discount_copil_extra_ron": 2000,
          "supliment_single_text": "300 EURO",
          "supliment_single_euro": 300,
          "supliment_single_usd": 330,
          "supliment_single_ron": 1500,
          "tarif_grup_minim": "Informații despre tarifele pentru grupuri minime...",
          "nr_minim_turisti": 30,
          "taxeAeroportIntercontinentale": "Taxe aeroport intercontinentale: 150 EUR",
          "taxeAeroportLocale": "Taxe aeroport locale: 50 EUR",
          "tarif_observatii": "Observații despre tarife: prețurile pot varia în funcție de sezon",
          "nr_zile": "10",
          "sfaturi": "Sfaturi pentru turiști: aduceți haine potrivite pentru vreme, documente de identitate valide",
          "incluse": "Servicii incluse în preț...",
          "neincluse": "Servicii neincluse în preț...",
          "conditii": "Condiții generale...",
          "acte": "- paşaportul sau cartea de identitate în curs de valabilitate",
          "observatii": "Observații generale...",
          "days": [
            {
              "id": 12345,
              "nr_zi": 1,
              "titlu": "Ziua 1 - Plecare din București",
              "masa": null,
              "cazare": "Hotel Exemplu 4* (sau similar 4*)",
              "zbor": null,
              "transport": "Avion, autocar",
              "obiective": "Obiectiv turistic 1\r\nObiectiv turistic 2\r\nObiectiv turistic 3\r\nObiectiv turistic 4\r\nObiectiv turistic 5",
              "optionale": null,
              "descriere": "Descrierea zilei...",
              "pictures": [
                {
                  "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_zi_imagine.webp"
                }
              ]
            },
            {
              "id": 12346,
              "nr_zi": 2,
              "titlu": "Ziua 2 - Vizitare oraș de destinație",
              "masa": "Mic dejun",
              "cazare": "Hotel Exemplu 4* (sau similar 4*)",
              "zbor": null,
              "transport": "Autocar",
              "obiective": "Centrul istoric\r\nMuzeul local\r\nPiața centrală",
              "optionale": null,
              "descriere": "Descrierea zilei...",
              "pictures": [
                {
                  "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_zi_imagine.webp"
                }
              ]
            }
          ],
          "brief_transport": "Avion\r\nAutocar\r\nFerry-boat",
          "brief_cazare": "2 nopți în orașul A\r\n2 nopți în orașul B\r\n2 nopți în orașul C\r\n2 nopți în orașul D\r\n2 nopți în orașul E",
          "brief_mese": "Mic dejun: 8",
          "brief_ghizi": "Însoțitor DAL Travel\r\nGhizi locali",
          "brief_marime_grup": "30",
          "pdf": "exemplu_brochura_oferta.pdf",
          "coords": [
            {
              "coords": "(44.4268, 26.1025)",
              "descriere": "",
              "nr": 0,
              "ordine": 1
            },
            {
              "coords": "(48.8566, 2.3522)",
              "descriere": "",
              "nr": 1,
              "ordine": 2
            },
            {
              "coords": "(41.9028, 12.4964)",
              "descriere": "",
              "nr": 2,
              "ordine": 3
            },
            {
              "coords": "(40.4168, -3.7038)",
              "descriere": "",
              "nr": 3,
              "ordine": 4
            },
            {
              "coords": "(50.0755, 14.4378)",
              "descriere": "",
              "nr": 4,
              "ordine": 5
            }
          ],
          "optionals": [
            {
              "id": 1,
              "name": "Excursie opțională",
              "tarif_euro": 50,
              "tarif_usd": 55,
              "tarif_ron": 250,
              "deplasare": false,
              "must": false,
              "available": true
            }
          ]
        }
      ],
      "imageUrl": "",
      "id": 1234,
      "name": "Exemplu de ofertă de călătorie",
      "zone": "europa",
      "pictures": [
        {
          "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_imagine1.webp"
        },
        {
          "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_imagine2.webp"
        },
        {
          "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_imagine3.webp"
        },
        {
          "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_imagine4.webp"
        },
        {
          "url": "https://rezervari.daltravel.ro/uploads/pictures/exemplu_imagine5.webp"
        }
      ],
      "coords": [
        {
          "coords": "(44.4268, 26.1025)",
          "descriere": "București",
          "nr": 0,
          "ordine": 1
        },
        {
          "coords": "(48.8566, 2.3522)",
          "descriere": "Paris",
          "nr": 1,
          "ordine": 2
        }
      ],
      "continents": [
        {
          "name": "Europa"
        }
      ],
      "countries": [
        {
          "name": "Franța"
        },
        {
          "name": "Italia"
        },
        {
          "name": "Spania"
        },
        {
          "name": "Germania"
        },
        {
          "name": "Austria"
        }
      ],
      "cities": [
        {
          "name": "Paris"
        },
        {
          "name": "Roma"
        },
        {
          "name": "Madrid"
        }
      ]
    }
  ],
  "currentPage": 1,
  "lastPage": 5
}

Descriere detaliată a câmpurilor

Câmpuri la nivel de răspuns principal

Câmpuri la nivel de ofertă (offers[])

Câmpuri în countries[]

Câmpuri în continents[]

Câmpuri în cities[]

Câmpuri în pictures[]

Câmpuri în plecariActive[] (plecări active)

Câmpuri în optionals[] (opțiuni plecare)

Câmpuri în partajeCountByGender

Câmpuri în days[] (zilele itinerarului)

Câmpuri în coords[] (coordonate geografice)

Notă: Câmpul coords poate apărea la două nivele:

• La nivelul ofertei (offers[].coords[]) - coordonatele generale ale destinațiilor
• La nivelul plecării (offers[].plecariActive[].coords[]) - coordonatele specifice pentru traseul plecării

Exemple de utilizare

1. Obținerea tuturor ofertelor (prima pagină)

curl "https://rezervari.daltravel.ro/feed"

2. Obținerea a 20 de oferte de pe pagina 2

curl "https://rezervari.daltravel.ro/feed?page=2&limit=20"

Limitări și restricții

Rate Limiting

• Nu există limitări de rate pentru endpoint-ul public
• Se recomandă utilizarea responsabilă, pentru a nu supraîncărca serverul. Nu este necesara o sincronizare mai frecventa de 24 de ore.

Limitări de paginare

• limit poate fi între 1 și 50 de oferte per pagină
• page începe de la 1 (nu de la 0)
• Dacă se solicită o pagină inexistentă, se returnează o listă goală

Formatul datelor

• Toate datele sunt returnate în format JSON
• Datele de tip string pot conține HTML (ex: info_tarif)
• Coordonatele sunt în format "(latitudine, longitudine)"
• Datele de timp sunt în format ISO 8601 cu timezone

Observații importante

Câmpuri care pot fi null

• Majoritatea câmpurilor opționale pot avea valoarea null
• Se recomandă verificarea valorilor înainte de utilizare
• Câmpurile obligatorii nu sunt niciodată null

Actualizarea datelor

• Datele sunt actualizate în timp real
• Se recomandă cache-ul local pentru performanță optimă
• Intervalul de actualizare recomandat: 1-6 ore

Coduri de eroare posibile

Suport și contact

Pentru întrebări tehnice sau probleme cu API-ul, contactați echipa de dezvoltare Dal Travel.

Endpoint-ul este destinat utilizării publice pentru integrarea ofertelor DalTravel în aplicații externe.