Lydira API
EN

Aktarım yolları

Gemi turu

Kabinleriyle gemi turu rezervasyonları.

Gemisi, tarihleri ve kabinleriyle bir gemi turu rezervasyonu.

Bu sayfada

Şu kapsamlardan birini taşıyan anahtar erişir:importimport_issue

Cruise rezervasyonlarıcruises

POST/api/v1/imports/cruises

Bir kez oluşturulur: aynı external_id ile tekrar gönderim kopya açmaz, atlanır.

Uç noktalar

  • validatePOST /api/v1/imports/cruises/validate
  • importPOST /api/v1/imports/cruises
  • feedGET /api/v1/imports/cruises/records
  • read_backGET /api/v1/imports/cruises/records/{external_id}

Yeni bir satırda bulunmalı

embark_ondisembark_on

Fatura bilgisiyle örnek istek (cari anahtarı olmadan)

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/imports/cruises/validate' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "source_system": "crm",
  "rows": [
    {
      "external_id": "CRUISE-1001-B",
      "ship_name": "MSC Fantasia",
      "embark_on": "2026-03-14",
      "disembark_on": "2026-03-18",
      "cabin_count": 2,
      "guest_count": 2,
      "currency": "EUR",
      "supplier_external_id": "SUPPLIER-1001",
      "status": "draft",
      "notes": "Imported from the source system.",
      "rate_basis": "net",
      "margin_mode": "percent",
      "option_date": "2026-03-20T18:00",
      "transaction_date": "2026-03-14",
      "invoice_date": "2026-03-18",
      "cost_lines": [
        {
          "kind": "cabin_fare",
          "amount": "1250.00",
          "label": "Imported line",
          "currency": "EUR",
          "vat_rate": "20",
          "tax_inclusive": true,
          "quantity": 1
        }
      ],
      "sell_lines": [
        {
          "kind": "package_price",
          "amount": "1250.00",
          "label": "Imported line",
          "currency": "EUR",
          "vat_rate": "20",
          "tax_inclusive": true,
          "quantity": 1
        }
      ],
      "travelers": [
        {
          "first_name": "Ada",
          "last_name": "Lovelace",
          "nationality": "TR",
          "national_id": "10000000146",
          "passport_number": "U01234567",
          "passport_country": "TR",
          "passport_expiry": "2031-06-30",
          "date_of_birth": "1988-04-21",
          "gender": "MRS",
          "frequent_flyer_number": "TK123456789"
        }
      ],
      "cabin_category": "balcony",
      "bill_to_legal_name": "Lovelace Seyahat A.Ş.",
      "bill_to_tax_number": "1234567890",
      "bill_to_tax_office": "Beşiktaş",
      "bill_to_address_line": "Nispetiye Cad. No:12",
      "bill_to_city": "İstanbul",
      "bill_to_country": "TR"
    }
  ]
}'
Alanlar(43)
  • external_idstring
  • ship_namestring
  • embark_ondatezorunlu
  • disembark_ondatezorunlu
  • cabin_countinteger
  • guest_countinteger
  • currencycurrency
  • customer_external_idreference
  • supplier_external_idreference
  • custom_fieldsobject

    the account's own fields on the booking, by key

  • statusenum

    Şunlardan biri:draftoptionconfirmedsailingcompletedcancelled

  • notesstring
  • rate_basisenum

    net ⇒ cost typed / sell derived; commissionable ⇒ the reverse

    Şunlardan biri:netcommissionable

  • margin_modeenum

    percent ⇒ the margin was typed as a %; amount ⇒ as a flat figure

    Şunlardan biri:percentamount

  • option_datedate
  • transaction_datedate

    işlem tarihi — the FX anchor for every cost line

  • invoice_datedate
  • cost_linesobject[]

    cost-side pricing lines for the "cruise" pricing context

    Her öğe

    • kindstringzorunlu

      Uygulamanın kullandığı değerler:cabin_fareport_taxesgratuitiesshore_excursiondrinks_packagewifi_packagespecialty_diningservice_feesupplier_refundinsurance_premium

    • amountmoneyzorunlu
    • labelstring
    • currencycurrency
    • vat_ratedecimal

      percent (20 ⇒ 20% KDV); omit to take the kind's default

    • tax_inclusiveboolean

      true ⇒ the amount includes VAT. A hotel stay or a charter takes one VAT mode: the lines' flags decide it, lines stating both are refused, and every line follows the booking's mode afterwards

    • quantityinteger
  • sell_linesobject[]

    sell-side pricing lines for the "cruise" pricing context

    Her öğe

    • kindstringzorunlu

      Uygulamanın kullandığı değerler:package_pricemarkupservice_feesupplier_commissioncancellation_feeinsurance_premiumdiscountrefund_allowancecabin_fareport_taxesgratuitiesshore_excursiondrinks_packagewifi_packagespecialty_diningsupplier_refund

    • amountmoneyzorunlu
    • labelstring
    • currencycurrency
    • vat_ratedecimal

      percent (20 ⇒ 20% KDV); omit to take the kind's default

    • tax_inclusiveboolean

      true ⇒ the amount includes VAT. A hotel stay or a charter takes one VAT mode: the lines' flags decide it, lines stating both are refused, and every line follows the booking's mode afterwards

    • quantityinteger
  • markupmoney

    the agency's hidden markup on the whole booking, in its currency: split across the guests by their cost (by their sell when the booking carries no cost) and folded into each guest's fare on the invoice

  • markup_percentdecimal

    the markup as a percentage of the booking's cost; wins over markup

  • discountmoney

    the whole booking's discount (iskonto), a positive figure: split across the guests by what each owes, after the markup and the service fee

  • discount_percentdecimal

    the discount as a percentage of everything the booking sells, the markup and the service fee included; wins over discount

  • service_feemoney

    the agency's fee for the whole booking, in its currency; split across the guests like the booking form's. Sent, the account's service-fee rules write nothing

  • service_fee_percentdecimal

    the fee as a percentage (0-100) of the booking's sale before fee and discount, instead of service_fee; split like it

  • service_fee_vat_ratedecimal

    the fee's VAT, percent (0 ⇒ exempt); omit it and the law decides, else the seller's standard rate

  • service_fee_waivedboolean

    true: the account's service-fee rules write no fee on this booking

  • travelersobject[]PII

    guests; auto-saved to the customer's traveller directory

    Her öğe

    • first_namestringPII
    • last_namestringPII
    • nationalitystring
    • national_idstringPII
    • passport_numberstringPII
    • passport_countrystring
    • passport_expirydate
    • date_of_birthdatePII
    • genderstring

      Uygulamanın kullandığı değerler:MRMRSMISSMSTR

    • frequent_flyer_numberstring
    • custom_fieldsobject

      the account's own fields on the guest, by key

  • cabin_categorystring

    Hesabınızın cruise_cabin_category listesi; başlangıç değerleri:insideoceanviewbalconymini_suitesuitespasolo

  • bill_to_typeenum

    omit to infer: a legal name or a 10-digit tax number ⇒ corporate

    Şunlardan biri:corporateindividual

  • bill_to_legal_namestring
  • bill_to_tax_numbertax_numberPII

    VKN for a corporate payer, TCKN for an individual; matched digits-only

  • bill_to_tax_officestring
  • bill_to_passport_numberstringPII

    individual only; used when there is no TCKN

  • bill_to_first_namestringPII
  • bill_to_last_namestringPII
  • bill_to_emailemailPII

    stored on a NEW cari; never used to match

  • bill_to_phonephonePII

    stored on a NEW cari; never used to match

  • bill_to_address_linestringPII
  • bill_to_districtstringPII
  • bill_to_citystringPII
  • bill_to_zipstringPII
  • bill_to_countrystring

    ISO-2 code, e.g. TR

Referanslar

  • customer_external_id → customers · eşleşme external_id, email · bulunamazsa skip
  • supplier_external_id → suppliers · eşleşme external_id, code · bulunamazsa skip

Hesabınızın ek alanları (custom_fields)

Her acente Ayarlar → Ek alanlar'dan kendi alanlarını ekler: proje kodu, seyahat nedeni, sicil numarası gibi. Alanlar hesaptan hesaba değiştiği için bu sayfa onları listeleyemez. Entegrasyonunuz bunları API'den öğrenir.

GET /api/v1/imports/entities/{key} yanıtındaki custom_fields, anahtarınızın bağlı olduğu hesabın bu kayıt türündeki alanlarını verir: kaydın kendisi için record, her yolcu ya da misafir için traveler. Her alan satırda gönderilecek key'i, type'ını, zorunlu olup olmadığını (required), hangi carilere uygulandığını (applies_to) ve seçmeli bir alansa options listesini taşır. Eşlemeyi kurarken okuyun; acente bir alanı değiştirdiğini söylediğinde yeniden okuyun. Bu, hesabın canlı listesidir.

İstek · hesabın alanları

curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/imports/entities/cruises' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'
Yanıt · custom_fields (kesit)
200
{
  "key": "cruises",
  "custom_fields": {
    "record": [
      {
        "key": "project_code",
        "label": "Project code",
        "type": "text",
        "required": "always",
        "applies_to": "all"
      },
      {
        "key": "trip_reason",
        "label": "Trip reason",
        "type": "select",
        "required": "listed_customers",
        "applies_to": "listed_customers",
        "options": [
          {
            "value": "meeting",
            "label": "Meeting"
          },
          {
            "value": "fair",
            "label": "Trade fair"
          }
        ],
        "customers": [
          {
            "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
            "external_id": "CUST-17",
            "required": true
          }
        ]
      }
    ],
    "traveler": [
      {
        "key": "employee_no",
        "label": "Employee no",
        "type": "text",
        "required": "never",
        "applies_to": "all",
        "pii": true
      }
    ]
  }
}

Her tip ne alır

tipsatırdaki değer
text"PRJ-2026-001"
long_text"Fair delegation, second group"
number12.5
date"2026-03-14"
booleantrue
select"meeting"
multi_select["meeting", "fair"]

number takes a number or a numeric string; date an ISO date; select one option value (or its label); multi_select a list of them.

required ve applies_to

  • requiredneveralwayslisted_customers

    listed_customers: required only for the customers marked required in customers.

  • applies_toalllisted_customers

    listed_customers: the field is accepted only on those customers' records.

Değerleri key'e göre tek bir JSON nesnesi olarak gönderin. Bilinmeyen bir anahtar, yanlış tipte bir değer ya da eksik bir zorunlu alan satırı düşürür ve hatada anahtarın adı geçer. Güncellemede (on_conflict: update) nesne anahtar anahtar birleşir: göndermediğiniz anahtar korunur, null gönderdiğiniz silinir. Acentenin müşteri belgelerine bastığı bir alan, kayıt faturalandıktan sonra değişmez.

Yolcu alanları her yolcunun kendi custom_fields nesnesine yazılır.

Aynı biçimde geri gelirler: geri okumada ve webhook gövdesinde detail.custom_fields altında (biletin her yolcusunda da). Kişisel veri olarak işaretli alan yalnızca rolü kişisel veriyi okuyabilen bir anahtara döner; webhook'ta hiç yer almaz.

Geri okuma

Acente kaydı işledikten sonra (onaylar, biletleri numaralar, faturalar) GET /api/v1/imports/{entity}/records/{external_id} bunu döner; her webhook da aynı gövdeyi taşır. detail, gönderiminizden sonra yalnız acentenin ekleyebildiği bilgileri taşır.

GET /api/v1/imports/cruises/records/CRUISE-1001
200
{
  "entity": "cruises",
  "external_id": "CRUISE-1001",
  "source_system": "crm",
  "type": "CruiseBooking",
  "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
  "created_at": "2026-03-14T09:30:00Z",
  "updated_at": "2026-03-15T11:05:00Z",
  "status": "confirmed",
  "locked": true,
  "lock_reason": "invoiced",
  "currency": "EUR",
  "totals": {
    "cost": "1100.0",
    "sell": "1250.0"
  },
  "invoices": [
    {
      "id": "4b8e1f60-7c2d-4e9a-b3f5-0a6d2c9e8b71",
      "number": "LYD2026000000117",
      "status": "issued",
      "currency": "EUR",
      "total": "1250.0",
      "balance": "1250.0"
    }
  ],
  "detail": {
    "voucher_number": "VCH-2026-000412",
    "supplier_confirmation_no": "CNF-77821",
    "supplier": "Lovelace Travel Partners",
    "custom_fields": {
      "project_code": "PRJ-2026-001",
      "trip_reason": "meeting"
    },
    "ship_name": "MSC Fantasia",
    "embark_on": "2026-03-14",
    "disembark_on": "2026-03-18",
    "cabins": [
      {
        "cabin_number": "10214",
        "category": "balcony",
        "deck": "10",
        "booked_pax": 2,
        "capacity": 2
      }
    ]
  }
}

İstek · deneme, tüm alanlar

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/imports/cruises/validate' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "source_system": "crm",
  "rows": [
    {
      "external_id": "CRUISE-1001",
      "ship_name": "MSC Fantasia",
      "embark_on": "2026-03-14",
      "disembark_on": "2026-03-18",
      "cabin_count": 2,
      "guest_count": 2,
      "currency": "EUR",
      "customer_external_id": "CUSTOMER-1001",
      "supplier_external_id": "SUPPLIER-1001",
      "custom_fields": {
        "project_code": "PRJ-2026-001",
        "trip_reason": "meeting"
      },
      "status": "draft",
      "notes": "Imported from the source system.",
      "rate_basis": "net",
      "margin_mode": "percent",
      "option_date": "2026-03-20T18:00",
      "transaction_date": "2026-03-14",
      "invoice_date": "2026-03-18",
      "cost_lines": [
        {
          "kind": "cabin_fare",
          "amount": "1250.00",
          "label": "Imported line",
          "currency": "EUR",
          "vat_rate": "20",
          "tax_inclusive": true,
          "quantity": 1
        }
      ],
      "sell_lines": [
        {
          "kind": "package_price",
          "amount": "1250.00",
          "label": "Imported line",
          "currency": "EUR",
          "vat_rate": "20",
          "tax_inclusive": true,
          "quantity": 1
        }
      ],
      "markup": "1250.00",
      "markup_percent": "10",
      "discount": "1250.00",
      "discount_percent": "5",
      "service_fee": "1250.00",
      "service_fee_vat_rate": "20",
      "service_fee_waived": true,
      "travelers": [
        {
          "first_name": "Ada",
          "last_name": "Lovelace",
          "nationality": "TR",
          "national_id": "10000000146",
          "passport_number": "U01234567",
          "passport_country": "TR",
          "passport_expiry": "2031-06-30",
          "date_of_birth": "1988-04-21",
          "gender": "MRS",
          "frequent_flyer_number": "TK123456789",
          "custom_fields": {
            "employee_no": "E-10442"
          }
        }
      ],
      "cabin_category": "balcony"
    }
  ]
}'
Yanıt
200
{
  "import": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "entity": "cruises",
    "source_system": "crm",
    "status": "ready",
    "company_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "stats": {
      "total": 1,
      "will_create": 1,
      "will_update": 0,
      "created": 0,
      "updated": 0,
      "skipped": 0,
      "invalid": 0,
      "failed": 0,
      "not_selected": 0
    },
    "error": null,
    "created_at": "2026-03-14T09:30:00Z",
    "links": {
      "self": "/api/v1/imports/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "rows": "/api/v1/imports/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/rows"
    },
    "mode": "validate",
    "async": false,
    "on_conflict": "skip",
    "pricing": "apply_rules"
  },
  "ignored_fields": [],
  "results": [
    {
      "row": 1,
      "external_id": "CRUISE-1001",
      "status": "will_create",
      "payer": {
        "outcome": "external_id",
        "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18"
      }
    }
  ]
}

Akış

  1. Deneyin. POST …/validate aynı yolu koşar ve hiçbir şey yazmaz.
  2. Gönderin. Aynı gövde, /validate olmadan. Bozuk satır tek başına düşer ve alanını söyler.
  3. Geri okuyun. GET /api/v1/imports/{entity}/records/{external_id} kendi kimliğinizle cevap verir.
  4. Dinleyin. Acente kaydı değiştirdiğinde webhook haber verir.

Kurallar →Webhook'lar →