API dokumentacija · GetFast 24/7

Apžvalga

GetFast 24/7 prekybininko API leidžia jūsų e. parduotuvei parduoti prekes, kurios jau guli paštomatuose: parodyti, kur prekę galima atsiimti arba ar ją galima pristatyti per valandą, rezervuoti konkretų vienetą atsiskaitymo metu ir patvirtinti apmokėjimą. Atsiėmimo PIN kodą pirkėjui parodome mes — per API jis niekada negrąžinamas.

Visi galiniai taškai prasideda šiuo adresu:

Bazinis adresas

https://getfast24.lt/api/v1

Užklausų ir atsakymų turinys — JSON (UTF-8), laukų vardai snake_case. Nežinomi užklausos laukai ignoruojami.
Pinigų sumos — sveikieji skaičiai centais (39900 = 399,00 €).
Laikas — ISO 8601 UTC, pvz. 2026-11-11T17:00:00.000Z. Nesamos reikšmės grąžinamos kaip null.
Identifikatoriai — UUID. Užsakymą galima nurodyti ir jo numeriu (GF-000123), paštomatą — ir jo kodu (ZT01).
Visi atsakymai turi antraštę Cache-Control: no-store.
Užklausos turinys — iki 64 KB.

Autentifikavimas

Kiekviena užklausa turi turėti antraštę Authorization: Bearer <API raktas>. Raktą susikurkite prekybininko portale, skiltyje Integracija. Rakto forma — gfk_, 8 simbolių priešdėlis, _ ir 40 simbolių slaptoji dalis. Visas raktas parodomas tik vieną kartą sukūrimo metu; mes saugome tik jo maišos reikšmę.

Raktas priklauso vienam prekybininkui: per jį matomos ir keičiamos tik to prekybininko prekės, atsargos ir užsakymai. Kito prekybininko užsakymo identifikatorius grąžina 404 not_found.

Pavyzdys

export GETFAST_API_KEY="gfk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

curl -s "https://getfast24.lt/api/v1/products" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Jei antraštės nėra, raktas neteisingos formos, nežinomas, atšauktas arba prekybininko paskyra išjungta, grąžinama 401 unauthorized su antrašte WWW-Authenticate: Bearer.

Raktą laikykite tik serveryje

Niekada nedėkite rakto į naršyklės ar mobiliosios programėlės kodą. Jei raktas galėjo nutekėti, portale jį atšaukite ir sukurkite naują — atšauktas raktas nustoja veikti iškart.

Rekomenduojama integracijos eiga

1
Prekės puslapyje — prieinamumas
Kvieskite GET /availability su prekės SKU. Jei žinote pirkėjo vietą (adreso koordinates), perduokite lat ir lng: paštomatai bus surikiuoti nuo artimiausio, o laukas delivery pasakys, ar galimas pristatymas per valandą ir kiek jis kainuoja. Jei sąrašas pickup tuščias ir delivery yra null, GetFast 24/7 pasirinkimo nerodykite.
2
Atsiskaitymo pradžioje — rezervacija
Kai pirkėjas pasirenka paštomatą arba pristatymą ir spaudžia „Pirkti“, kvieskite POST /orders. Užsakymas sukuriamas būsenoje reserved ir 15 min. laiko konkretų vienetą — kitas pirkėjas jo nebenupirks. Pirkėjui imkite total_cents (prekės kaina + pristatymo mokestis). Į external_ref įrašykite savo užsakymo numerį — jis grįš visuose atsakymuose ir webhook pranešimuose.
Kaina imama iš jūsų katalogo GetFast 24/7 portale užsakymo sukūrimo akimirką. POST /orders nėra idempotentiškas: pakartota užklausa sukurs dar vieną rezervaciją, todėl po tinklo klaidos pirmiausia patikrinkite GET /orders?status=reserved.
3
Gavus pinigus — apmokėjimo patvirtinimas
Kai jūsų mokėjimų sistema patvirtina, kad pinigai gauti, kvieskite POST /orders/{id}/pay. Kvietimą saugu kartoti — antras kartas nieko nepakeičia. Jei rezervacija jau baigėsi, gausite 409 reservation_expired: sukurkite naują užsakymą arba grąžinkite pinigus.
4
Pirkėjui — sekimo nuoroda
Užsakymo patvirtinimo puslapyje ir laiške parodykite tracking_url. Tame puslapyje pirkėjas mato būseną, atsiėmimo PIN ir QR kodą (atsiėmimui) arba pristatymo PIN, kurį pasako kurjeriui (pristatymui). Tą pačią nuorodą jam siunčiame ir SMS žinute (kūrimo aplinkoje žinutės tik įrašomos — žr. Tik kūrimo aplinkai). PIN kodų per API negrąžiname — jų savo sistemoje nesaugokite ir nerodykite.
5
Jei pirkėjas nesumoka — atšaukimas
Nutrūkus mokėjimui kvieskite POST /orders/{id}/cancel — vienetas iškart grįš į pardavimą. Nieko nedarant, rezervacija pasibaigs pati.
6
Būsenos sekimas
Įjunkite webhook ir atnaujinkite savo užsakymą gavę order.status_changed. Jei webhook nenaudojate, periodiškai klauskite GET /orders/{id}.

Pristatymas per valandą

Pristatymas siūlomas, kai paštomatas su šia preke yra ne toliau kaip 20 km (tiesia linija) nuo pirkėjo adreso. Mokestis priklauso nuo atstumo: nuo 5,99 € (iki 5 km), 9,99 € (5–10 km), 14,99 € (10–20 km) (pigiausias — 5,99 €); jį iš pirkėjo surenkate jūs, o mes įtraukiame į mėnesio išklotinę. Adreso koordinates turi pateikti jūsų sistema — adresų paieškos API neteikia.

Išparduota? Užsakymas iš anksto

Kurjeriai papildo visus paštomatus 11:00 ir 20:00 (Vilniaus laiku); prekės paštomate maždaug po 20 min. Kai prekės nėra, GET /availability grąžina restock: { next_round_at, ready_at }. Sukūrę užsakymą su allow_backorder: true galite parduoti jau dabar: apmokėtas jis laukia būsenoje awaiting_stock, o kai papildymas atveža prekę, gausite įprastą order.status_changed webhook (ready_for_pickup / awaiting_courier). Prekybininko sandėlio atsargos demonstracijoje laikomos neribotomis.

Kas atsitinka paštomate

Prekes į paštomatą sudeda kurjeris pagal papildymo užduotį (ją užsakote portale, skiltyje „Papildymas“). Viena prekė užima vienas dureles. Vienetas tampa parduodamas, kai paštomatas patvirtina, kad prekė viduje, ir tik tada atsiranda GET /availability atsakyme.

Užsakymo gyvavimo ciklas

Užsakymas visada prasideda būsenoje reserved ir toliau juda priklausomai nuo gavimo būdo (fulfillment): pickup — pirkėjas atsiima pats, delivery — kurjeris išima prekę iš paštomato ir atveža per valandą.

Atsiėmimas (pickup)

reserved → [awaiting_stock →] ready_for_pickup → completed

Pristatymas (delivery)

reserved → [awaiting_stock →] awaiting_courier → courier_assigned → out_for_delivery → completed

reservedLaukia apmokėjimoUžsakymas sukurtas, konkretus vienetas laikomas pirkėjui (užsakymui iš anksto — be vieneto), laukiama apmokėjimo patvirtinimo.Toliau: ready_for_pickup, awaiting_courier arba awaiting_stock (pay), cancelled (cancel), expired (baigėsi laikas)
awaiting_stockLaukia papildymoUžsakymas iš anksto apmokėtas, prekės paštomate dar nėra. Ją atveža artimiausias papildymo ratas (ready_estimate); vos vienetas atsiduria paštomate, jis priskiriamas seniausiam apmokėtam užsakymui.Toliau: ready_for_pickup arba awaiting_courier (prekė atkeliavo), cancelled (operatorius)
ready_for_pickupParuošta atsiimtiAtsiėmimas: apmokėta, pirkėjas gali atsiimti prekę paštomate su PIN arba QR kodu.Toliau: completed (pirkėjas atsiėmė)
awaiting_courierLaukia kurjerioPristatymas: apmokėta, laukiama, kol užduotį priims kurjeris.Toliau: courier_assigned
courier_assignedKurjeris priskirtasPristatymas: kurjeris priėmė užduotį ir vyksta prie paštomato. Jei kurjeris užduoties atsisako, užsakymas grįžta į awaiting_courier.Toliau: out_for_delivery, awaiting_courier
out_for_deliveryVežama pirkėjuiPristatymas: kurjeris paėmė prekę iš paštomato ir veža pirkėjui.Toliau: completed (pirkėjas patvirtino pristatymo PIN)
completedĮvykdytaPirkėjas prekę gavo. Galutinė būsena.
expiredRezervacija baigėsiApmokėjimas nepatvirtintas iki reserved_until; vienetas grįžo į pardavimą. Galutinė būsena.
cancelledAtšauktaAtšaukta: jūsų (prieš apmokėjimą) arba operatoriaus. Galutinė būsena.

Rezervacija galioja 15 min. nuo sukūrimo (laukas reserved_until). Nepatvirtinus apmokėjimo, užsakymas tampa expired, o vienetas grįžta į pardavimą.
Jūs galite atšaukti tik neapmokėtą (reserved) užsakymą. Apmokėtą užsakymą atšaukia tik GetFast 24/7 operatorius — jei pirkėjas jau matė kodą, prekę iš paštomato turi paimti kurjeris.
Numatytas apmokėto atsiėmimo užsakymo terminas — 48 val. nuo apmokėjimo. Parduodami tik tie vienetai, kurių paštomato kodas galios ilgiau už šį terminą. Terminui praėjus užsakymas pats neatšaukiamas — sprendžia operatorius.
Kiekvienas būsenos pasikeitimas (ir pats sukūrimas) išsiunčiamas jūsų sistemai kaip webhook įvykis order.status_changed, jei esate nurodę adresą.

Portale šios būsenos vadinamos taip: reserved — „Laukia apmokėjimo“, awaiting_stock — „Laukia papildymo“, ready_for_pickup — „Paruošta atsiimti“, awaiting_courier — „Laukia kurjerio“, courier_assigned — „Kurjeris priskirtas“, out_for_delivery — „Vežama pirkėjui“, completed — „Įvykdyta“, expired — „Rezervacija baigėsi“, cancelled — „Atšaukta“.

Prekės, paštomatai ir prieinamumas

GET`/api/v1/products`

Jūsų aktyvios prekės ir kiek jų vienetų šiuo metu parduodama.

Parametrų nėra. Grąžinamos tik aktyvios prekės (iki 200), surikiuotos pagal pavadinimą. Prekes kuriate ir keičiate portale, skiltyje „Prekės“ — per API katalogas tik skaitomas.

Prekės laukai

idstring (UUID): Prekės identifikatorius.
skustring: Jūsų prekės kodas — juo prekę nurodote kituose kvietimuose.
name, descriptionstring: Pavadinimas ir aprašymas iš jūsų katalogo.
price_centsinteger: Kaina centais. Ši kaina bus įrašyta į naują užsakymą.
size"S" | "M" | "L": Paštomato durelių dydis, kurio reikia prekei.
activeboolean: Visada true — išjungtos prekės negrąžinamos.
image_urlstring (URL) | null: Absoliutus prekės nuotraukos adresas (JPEG, PNG arba WebP) arba null, jei nuotraukos nėra. Nuotrauką įkeliate portale, prekės kortelėje. Adresas keičiasi, kai įkeliama nauja nuotrauka, todėl jį galima ilgai laikyti podėlyje.
image_altstring | null: Alternatyvusis nuotraukos tekstas (alt) — jūsų įrašytas arba prekės pavadinimas; null, jei nuotraukos nėra.
availableinteger: Vienetai, kuriuos galima užsakyti dabar (visuose veikiančiuose paštomatuose kartu): ne rezervuoti, ne parduoti ir su kodu, kuris galios visą atsiėmimo terminą — ta pati taisyklė kaip GET /availability.

Užklausa

curl -s "https://getfast24.lt/api/v1/products" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "products": [
    {
      "id": "0b6f2f0e-8a1c-4f2b-b3a5-6d4c2e1f0a9b",
      "sku": "TEL-X1-128",
      "name": "Išmanusis telefonas X1 128 GB",
      "description": "6,5 colio ekranas, 128 GB atmintis, dvi SIM kortelės.",
      "price_cents": 39900,
      "size": "S",
      "active": true,
      "image_url": "http://localhost:3247/products/tel-x1-128.png",
      "image_alt": "Išmanusis telefonas X1 128 GB",
      "available": 3
    }
  ]
}

GET`/api/v1/lockers`

Veikiančių paštomatų vieša informacija.

Parametrų nėra. Grąžinami tik veikiantys paštomatai, surikiuoti pagal kodą. Tinka žemėlapiui ar paštomatų sąrašui jūsų parduotuvėje.

Paštomato laukai

idstring (UUID): Paštomato identifikatorius. Lauke locker_id galima naudoti jį arba code.
codestring: Trumpas kodas, pvz. ZT01.
name, address, citystring: Pavadinimas ir adresas pirkėjui.
lat, lngnumber: Koordinatės (WGS84).

Užklausa

curl -s "https://getfast24.lt/api/v1/lockers" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "lockers": [
    {
      "id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
      "code": "ZT01",
      "name": "Žirmūnų tiltas",
      "address": "Sporto g. 16A",
      "city": "Vilnius",
      "lat": 54.6950807,
      "lng": 25.2981194
    },
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "code": "VG01",
      "name": "Vingis",
      "address": "Geležinio Vilko g. 2A",
      "city": "Vilnius",
      "lat": 54.6710025,
      "lng": 25.2366353
    }
  ]
}

GET`/api/v1/stock`

Jūsų atsargos: kiekvienos prekės kiekiai kiekviename paštomate.

Parametrų nėra. Viena eilutė — viena prekės ir paštomato pora, kurioje yra bent vienas vienetas (atvykstantis, parduodamas, rezervuotas arba parduotas ir dar neatsiimtas). Skirta atsargų apskaitai; pirkėjui rodykite GET /availability.

Eilutės laukai

sku, product_namestring: Prekė.
product_image_urlstring (URL) | null: Prekės nuotrauka, kaip GET /products lauke image_url.
locker_id, locker_codestring: Paštomatas.
availableinteger: Vienetai šiame paštomate, kuriuos galima užsakyti dabar (kaip GET /availability).
reservedinteger: Vienetai, laikomi neapmokėtiems užsakymams.
sold_awaiting_pickupinteger: Parduoti vienetai, kurie dar guli paštomate (laukia pirkėjo arba kurjerio).
incominginteger: Vienetai papildymo užduotyse: laukia kurjerio arba šiuo metu kraunami.

Užklausa

curl -s "https://getfast24.lt/api/v1/stock" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "stock": [
    {
      "sku": "TEL-X1-128",
      "product_name": "Išmanusis telefonas X1 128 GB",
      "product_image_url": "http://localhost:3247/products/tel-x1-128.png",
      "locker_id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
      "locker_code": "ZT01",
      "available": 2,
      "reserved": 0,
      "sold_awaiting_pickup": 1,
      "incoming": 0
    },
    {
      "sku": "TEL-X1-128",
      "product_name": "Išmanusis telefonas X1 128 GB",
      "product_image_url": "http://localhost:3247/products/tel-x1-128.png",
      "locker_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "locker_code": "VG01",
      "available": 1,
      "reserved": 0,
      "sold_awaiting_pickup": 0,
      "incoming": 2
    }
  ]
}

GET`/api/v1/availability`

Kur prekę galima atsiimti ir ar galimas pristatymas per valandą.

Užklausos parametrai (query)

skustring, 1–64 simboliaiprivaloma: Jūsų prekės kodas.
latnumber, −90…90· neprivaloma: Pirkėjo vietos platuma. Nurodoma tik kartu su lng.
lngnumber, −180…180· neprivaloma: Pirkėjo vietos ilguma. Nurodoma tik kartu su lat.

Atsakymo laukai

skustring: Užklaustas SKU.
productobject: name, price_cents ir image_url (absoliutus nuotraukos adresas arba null).
pickuparray: Veikiantys paštomatai, kuriuose yra bent vienas parduodamas vienetas. Su koordinatėmis — nuo artimiausio; be jų — pagal kodą. Gali būti tuščias.
pickup[].locker_id, code, name, address, lat, lngstring / number: Paštomatas.
pickup[].distance_kmnumber | null: Atstumas tiesia linija nuo pirkėjo, 2 ženklų po kablelio tikslumu; null, jei koordinatės nenurodytos.
pickup[].availableinteger: Kiek vienetų galima nupirkti šiame paštomate.
deliveryobject | null: null, jei koordinatės nenurodytos arba 20 km spinduliu (tiesia linija) nuo pirkėjo nėra paštomato su šia preke.
delivery.availabletrue: Visada true, kai objektas grąžinamas.
delivery.fee_centsinteger: Pristatymo mokestis centais šiuo adresu — pagal atstumą nuo artimiausio paštomato su preke (nuo 5,99 € (iki 5 km), 9,99 € (5–10 km), 14,99 € (10–20 km)).
delivery.distance_kmnumber: Atstumas tiesia linija nuo to paštomato iki adreso.
delivery.tiersarray: [{ max_km, fee_cents }] — kainos ribos, didėjančia tvarka.
delivery.legsarray: Kurjerio etapai [{ locker_id, locker_code, distance_km, fee_cents, eta_minutes }]: vienas paštomatas — vienas kurjeris. Vienam SKU visada vienas etapas; mūsų parduotuvės krepšelis iš kelių paštomatų turi kelis.
delivery.eta_minutesinteger: Numatoma pristatymo trukmė minutėmis (60).
delivery.from_locker_idstring (UUID): Artimiausias paštomatas su preke — iš jo kurjeris paimtų prekę.
delivery_radius_kmnumber: Pigiausio pristatymo spindulys kilometrais (pirma kainos riba) — pvz., žemėlapio apskritimui.
delivery_max_kmnumber: Toliausias atstumas, kuriuo pristatome (paskutinė kainos riba).
delivery_tiersarray: Tos pačios kainos ribos kaip delivery.tiers — grąžinamos ir tada, kai delivery yra null.
restockobject | null: Tik kai prekės nėra nė viename paštomate: next_round_at (kito papildymo rato pradžia) ir ready_at (kada prekė bus paštomate). Tada galima kurti užsakymą su allow_backorder: true.

Skaičiuojami tik vienetai, kurie tikrai yra paštomate ir kurių kodas galios visą atsiėmimo terminą (48 val.). Kvietimo metu taip pat užbaigiamos pasibaigusios rezervacijos, todėl skaičiai visada aktualūs.

Galimos klaidos

404not_foundTokio SKU jūsų kataloge nėra arba prekė išjungta.
422validation_errorNėra sku, koordinatės už ribų arba nurodyta tik viena iš jų.

Užklausa

curl -s "https://getfast24.lt/api/v1/availability?sku=TEL-X1-128&lat=54.6872&lng=25.2797" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "sku": "TEL-X1-128",
  "product": {
    "name": "Išmanusis telefonas X1 128 GB",
    "price_cents": 39900,
    "image_url": "http://localhost:3247/products/tel-x1-128.png"
  },
  "pickup": [
    {
      "locker_id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
      "code": "ZT01",
      "name": "Žirmūnų tiltas",
      "address": "Sporto g. 16A",
      "lat": 54.6950807,
      "lng": 25.2981194,
      "distance_km": 1.47,
      "available": 2
    },
    {
      "locker_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "code": "VG01",
      "name": "Vingis",
      "address": "Geležinio Vilko g. 2A",
      "lat": 54.6710025,
      "lng": 25.2366353,
      "distance_km": 3.3,
      "available": 1
    }
  ],
  "delivery": {
    "available": true,
    "fee_cents": 599,
    "eta_minutes": 60,
    "from_locker_id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
    "distance_km": 1.47,
    "tiers": [
      {
        "max_km": 5,
        "fee_cents": 599
      },
      {
        "max_km": 10,
        "fee_cents": 999
      },
      {
        "max_km": 20,
        "fee_cents": 1499
      }
    ],
    "legs": [
      {
        "locker_id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
        "locker_code": "ZT01",
        "distance_km": 1.47,
        "fee_cents": 599,
        "eta_minutes": 60
      }
    ]
  },
  "delivery_radius_km": 5,
  "delivery_max_km": 20,
  "delivery_tiers": [
    {
      "max_km": 5,
      "fee_cents": 599
    },
    {
      "max_km": 10,
      "fee_cents": 999
    },
    {
      "max_km": 20,
      "fee_cents": 1499
    }
  ],
  "restock": null
}

Užsakymai

POST`/api/v1/orders`

Sukuria užsakymą ir rezervuoja vieną konkretų prekės vienetą.

Užklausos turinys (JSON)

skustring, 1–64 simboliaiprivaloma: Jūsų prekės kodas. Prekė turi būti aktyvi.
fulfillment"pickup" | "delivery"privaloma: Atsiėmimas paštomate arba pristatymas per valandą.
locker_idstring· neprivaloma: Paštomato UUID arba kodas. Privaloma atsiėmimui. Pristatymui neprivaloma: nenurodžius parenkamas artimiausias paštomatas su preke; nurodžius — prekė imama būtent iš jo.
customer.first_name, customer.last_namestring, iki 60 simbolių· neprivaloma: Pirkėjo vardas ir pavardė (sąskaitai). Būtinas first_name arba name.
customer.namestring, iki 120 simbolių· neprivaloma: Senesnis būdas — vardas ir pavardė viename lauke. Vis dar priimamas: pirmas žodis tampa first_name, likę — last_name.
customer.phonestringprivaloma: Telefonas: 6–20 simbolių — skaitmenys, tarpai, skliaustai ir brūkšneliai, gali prasidėti +. Šiuo numeriu siunčiama sekimo nuoroda.
customer.emailstring· neprivaloma: El. paštas (neprivalomas, tikrinama forma).
customer.companyobject· neprivaloma: Jei perkama įmonės vardu: name (būtina), code (būtina, Lietuvos juridinio asmens kodas — lygiai 9 skaitmenys), vat_code (neprivaloma, LT + 9 arba 12 skaitmenų), address (būtina, registracijos adresas). Neteisingi kodai — 422 validation_error.
deliveryobject· neprivaloma: Privaloma pristatymui: address (3–300 simbolių), lat (−90…90) ir lng (−180…180).
external_refstring, 1–120 simbolių· neprivaloma: Jūsų užsakymo numeris ar kita nuoroda. Unikalumas netikrinamas.
allow_backorderboolean· neprivaloma: Jei true ir prekės paštomate (pristatymui — 20 km spinduliu) nėra, sukuriamas užsakymas iš anksto: be vieneto, su ready_estimate. Apmokėtas jis tampa awaiting_stock; artimiausias papildymo ratas atveža prekę, ir užsakymas pats tęsiasi kaip įprastas (ready_for_pickup arba awaiting_courier). Numatyta — false (tada 409 out_of_stock).

Sėkmės atveju grąžinama 201 ir užsakymas būsenoje reserved; rezervacija galioja 15 min. (reserved_until). Parenkamas vienetas, kurio paštomato kodas baigs galioti anksčiausiai. Pristatymo užsakymui pridedamas mokestis pagal atstumą nuo paštomato iki adreso (delivery_fee_cents): nuo 5,99 € (iki 5 km), 9,99 € (5–10 km), 14,99 € (10–20 km).

Pristatymo užsakymo turinys

{
  "sku": "TEL-X1-128",
  "fulfillment": "delivery",
  "customer": {
    "first_name": "Ona",
    "last_name": "Pirkėja",
    "phone": "+37060000000",
    "company": {
      "name": "UAB „Pavyzdys“",
      "code": "300000002",
      "vat_code": "LT100000000002",
      "address": "Gedimino pr. 9, LT-01103 Vilnius"
    }
  },
  "delivery": {
    "address": "Gedimino pr. 9, Vilnius",
    "lat": 54.6872,
    "lng": 25.2797
  },
  "external_ref": "ESHOP-10046"
}

Galimos klaidos

404not_foundSKU nežinomas arba prekė išjungta; nurodytas paštomatas nerastas.
409out_of_stockPaštomate (arba pristatymo spindulyje esančiuose paštomatuose) nebėra laisvo vieneto.
409delivery_unavailableAdresas toliau nei 20 km nuo nurodyto paštomato arba tokiu spinduliu nėra paštomato su šia preke (ir nenurodytas allow_backorder).
409invalid_stateNurodytas paštomatas šiuo metu neveikia.
422validation_errorTrūksta laukų ar jie neteisingi; atsiėmimui nenurodytas locker_id; pristatymui nenurodytas delivery.

Užklausa

curl -s -X POST "https://getfast24.lt/api/v1/orders" \
  -H "Authorization: Bearer $GETFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sku": "TEL-X1-128",
  "fulfillment": "pickup",
  "locker_id": "ZT01",
  "customer": {
    "first_name": "Ona",
    "last_name": "Pirkėja",
    "phone": "+37060000000",
    "email": "ona@example.com"
  },
  "external_ref": "ESHOP-10045"
}'

Atsakymas 201

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "number": "GF-000123",
  "status": "reserved",
  "fulfillment": "pickup",
  "sku": "TEL-X1-128",
  "product": {
    "name": "Išmanusis telefonas X1 128 GB",
    "price_cents": 39900,
    "image_url": "https://getfast24.lt/products/tel-x1-128.png"
  },
  "locker": {
    "id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
    "code": "ZT01",
    "name": "Žirmūnų tiltas",
    "address": "Sporto g. 16A"
  },
  "customer": {
    "name": "Ona Pirkėja",
    "first_name": "Ona",
    "last_name": "Pirkėja",
    "phone": "+37060000000",
    "email": "ona@example.com",
    "company": null
  },
  "delivery": null,
  "price_cents": 39900,
  "delivery_fee_cents": 0,
  "total_cents": 39900,
  "backorder": false,
  "ready_estimate": null,
  "delivery_leg": null,
  "external_ref": "ESHOP-10045",
  "reserved_until": "2026-11-11T17:15:00.000Z",
  "tracking_url": "https://getfast24.lt/o/3f9a1c0b7e2d4a6f8b1c2d3e",
  "created_at": "2026-11-11T17:00:00.000Z",
  "paid_at": null,
  "ready_at": null,
  "picked_at": null,
  "delivered_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "invoice": null
}

POST`/api/v1/orders/{id}/pay`

Patvirtinate, kad surinkote pinigus. Užsakymas pradedamas vykdyti.

Kelio parametras

{id}stringprivaloma: Užsakymo id (UUID) arba numeris, pvz. GF-000123.

Turinio nereikia. Atsiėmimo užsakymas tampa ready_for_pickup, pristatymo — awaiting_courier (kurjeriams sukuriama pristatymo užduotis). Pirkėjui išsiunčiama SMS su tracking_url. Kvietimas idempotentiškas: jau apmokėtam užsakymui grąžinama 200 ir dabartinė jo būsena, nieko nekeičiant.

Galimos klaidos

404not_foundUžsakymas nerastas (arba priklauso kitam prekybininkui).
409reservation_expiredRezervacijos laikas baigėsi (užsakymas expired). Kurkite naują užsakymą.
409invalid_stateUžsakymas atšauktas arba rezervuotas vienetas nebepasiekiamas.

Užklausa

curl -s -X POST "https://getfast24.lt/api/v1/orders/GF-000123/pay" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "number": "GF-000123",
  "status": "ready_for_pickup",
  "fulfillment": "pickup",
  "sku": "TEL-X1-128",
  "product": {
    "name": "Išmanusis telefonas X1 128 GB",
    "price_cents": 39900,
    "image_url": "https://getfast24.lt/products/tel-x1-128.png"
  },
  "locker": {
    "id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
    "code": "ZT01",
    "name": "Žirmūnų tiltas",
    "address": "Sporto g. 16A"
  },
  "customer": {
    "name": "Ona Pirkėja",
    "first_name": "Ona",
    "last_name": "Pirkėja",
    "phone": "+37060000000",
    "email": "ona@example.com",
    "company": null
  },
  "delivery": null,
  "price_cents": 39900,
  "delivery_fee_cents": 0,
  "total_cents": 39900,
  "backorder": false,
  "ready_estimate": null,
  "delivery_leg": null,
  "external_ref": "ESHOP-10045",
  "reserved_until": null,
  "tracking_url": "https://getfast24.lt/o/3f9a1c0b7e2d4a6f8b1c2d3e",
  "created_at": "2026-11-11T17:00:00.000Z",
  "paid_at": "2026-11-11T17:02:10.000Z",
  "ready_at": "2026-11-11T17:02:10.000Z",
  "picked_at": null,
  "delivered_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "invoice": null
}

POST`/api/v1/orders/{id}/cancel`

Atšaukia neapmokėtą užsakymą; vienetas grįžta į pardavimą.

Parametrai

{id}stringprivaloma: Užsakymo id (UUID) arba numeris, pvz. GF-000123.
reasonstring, iki 300 simbolių· neprivaloma: Užklausos turinyje (JSON). Neprivaloma — turinį galima praleisti; tada įrašoma „Atšaukė pardavėjas“.

Veikia tik būsenoje reserved. Jau atšauktam užsakymui grąžinama 200 ir tas pats užsakymas. Apmokėtą užsakymą atšaukti gali tik GetFast 24/7 operatorius.

Galimos klaidos

404not_foundUžsakymas nerastas (arba priklauso kitam prekybininkui).
409invalid_stateUžsakymas jau apmokėtas, įvykdytas arba jo rezervacija baigėsi. details.status rodo dabartinę būseną.
422validation_errorPer ilga reason arba netaisyklingas JSON.

Užklausa

curl -s -X POST "https://getfast24.lt/api/v1/orders/GF-000123/cancel" \
  -H "Authorization: Bearer $GETFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Pirkėjas persigalvojo"
}'

Atsakymas 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "number": "GF-000123",
  "status": "cancelled",
  "fulfillment": "pickup",
  "sku": "TEL-X1-128",
  "product": {
    "name": "Išmanusis telefonas X1 128 GB",
    "price_cents": 39900,
    "image_url": "https://getfast24.lt/products/tel-x1-128.png"
  },
  "locker": {
    "id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
    "code": "ZT01",
    "name": "Žirmūnų tiltas",
    "address": "Sporto g. 16A"
  },
  "customer": {
    "name": "Ona Pirkėja",
    "first_name": "Ona",
    "last_name": "Pirkėja",
    "phone": "+37060000000",
    "email": "ona@example.com",
    "company": null
  },
  "delivery": null,
  "price_cents": 39900,
  "delivery_fee_cents": 0,
  "total_cents": 39900,
  "backorder": false,
  "ready_estimate": null,
  "delivery_leg": null,
  "external_ref": "ESHOP-10045",
  "reserved_until": null,
  "tracking_url": "https://getfast24.lt/o/3f9a1c0b7e2d4a6f8b1c2d3e",
  "created_at": "2026-11-11T17:00:00.000Z",
  "paid_at": null,
  "ready_at": null,
  "picked_at": null,
  "delivered_at": null,
  "cancelled_at": "2026-11-11T17:05:00.000Z",
  "cancel_reason": "Pirkėjas persigalvojo",
  "invoice": null
}

GET`/api/v1/orders/{id}`

Vienas užsakymas pagal id arba numerį.

Kelio parametras

{id}stringprivaloma: Užsakymo id (UUID) arba numeris, pvz. GF-000123.

Galimos klaidos

404not_foundUžsakymas nerastas (arba priklauso kitam prekybininkui).

Užklausa

curl -s "https://getfast24.lt/api/v1/orders/GF-000123" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "number": "GF-000123",
  "status": "ready_for_pickup",
  "fulfillment": "pickup",
  "sku": "TEL-X1-128",
  "product": {
    "name": "Išmanusis telefonas X1 128 GB",
    "price_cents": 39900,
    "image_url": "https://getfast24.lt/products/tel-x1-128.png"
  },
  "locker": {
    "id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
    "code": "ZT01",
    "name": "Žirmūnų tiltas",
    "address": "Sporto g. 16A"
  },
  "customer": {
    "name": "Ona Pirkėja",
    "first_name": "Ona",
    "last_name": "Pirkėja",
    "phone": "+37060000000",
    "email": "ona@example.com",
    "company": null
  },
  "delivery": null,
  "price_cents": 39900,
  "delivery_fee_cents": 0,
  "total_cents": 39900,
  "backorder": false,
  "ready_estimate": null,
  "delivery_leg": null,
  "external_ref": "ESHOP-10045",
  "reserved_until": null,
  "tracking_url": "https://getfast24.lt/o/3f9a1c0b7e2d4a6f8b1c2d3e",
  "created_at": "2026-11-11T17:00:00.000Z",
  "paid_at": "2026-11-11T17:02:10.000Z",
  "ready_at": "2026-11-11T17:02:10.000Z",
  "picked_at": null,
  "delivered_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "invoice": null
}

GET`/api/v1/orders`

Jūsų užsakymų sąrašas, naujausi pirmi.

Užklausos parametrai (query)

statusstring· neprivaloma: Viena būsena iš gyvavimo ciklo. Nenurodžius — visos.
limitinteger, 1–200· neprivaloma: Kiek užsakymų viename puslapyje. Numatyta 50.
pageinteger, nuo 1· neprivaloma: Puslapio numeris. Numatyta 1.

Atsakymo laukai

ordersarray: Užsakymo objektai.
totalinteger: Kiek užsakymų atitinka filtrą iš viso.
page, limitinteger: Pritaikytas puslapis ir jo dydis.

Galimos klaidos

422validation_errorNežinoma status reikšmė, limit ar page už ribų.

Užklausa

curl -s "https://getfast24.lt/api/v1/orders?status=ready_for_pickup&limit=50&page=1" \
  -H "Authorization: Bearer $GETFAST_API_KEY"

Atsakymas 200

{
  "orders": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "number": "GF-000123",
      "status": "ready_for_pickup",
      "fulfillment": "pickup",
      "sku": "TEL-X1-128",
      "product": {
        "name": "Išmanusis telefonas X1 128 GB",
        "price_cents": 39900,
        "image_url": "https://getfast24.lt/products/tel-x1-128.png"
      },
      "locker": {
        "id": "2f1b0c7e-5a43-4c1d-9b8e-3d2a1f0e9c8b",
        "code": "ZT01",
        "name": "Žirmūnų tiltas",
        "address": "Sporto g. 16A"
      },
      "customer": {
        "name": "Ona Pirkėja",
        "first_name": "Ona",
        "last_name": "Pirkėja",
        "phone": "+37060000000",
        "email": "ona@example.com",
        "company": null
      },
      "delivery": null,
      "price_cents": 39900,
      "delivery_fee_cents": 0,
      "total_cents": 39900,
      "backorder": false,
      "ready_estimate": null,
      "delivery_leg": null,
      "external_ref": "ESHOP-10045",
      "reserved_until": null,
      "tracking_url": "https://getfast24.lt/o/3f9a1c0b7e2d4a6f8b1c2d3e",
      "created_at": "2026-11-11T17:00:00.000Z",
      "paid_at": "2026-11-11T17:02:10.000Z",
      "ready_at": "2026-11-11T17:02:10.000Z",
      "picked_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "cancel_reason": null,
      "invoice": null
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Užsakymo objektas

Visi užsakymų galiniai taškai grąžina tą patį objektą.

Laukai

idstring (UUID): Užsakymo identifikatorius.
numberstring: Žmogui skaitomas numeris, pvz. GF-000123.
statusstring: Būsena — žr. gyvavimo ciklą.
fulfillment"pickup" | "delivery": Gavimo būdas.
skustring: Prekės kodas.
productobject: name, price_cents (kaina užsakymo sukūrimo metu) ir image_url (dabartinė prekės nuotrauka arba null).
lockerobject: id, code, name, address — paštomatas, kuriame guli rezervuotas vienetas.
customerobject: name (vardas ir pavardė kartu), first_name, last_name, phone, email (gali būti null) ir company — { name, code, vat_code, address } arba null. Seniems užsakymams, sukurtiems tik su name, vardas ir pavardė išskaidyti automatiškai.
deliveryobject | null: Pristatymui — address, lat, lng; atsiėmimui — null.
price_centsinteger: Prekės kaina centais.
delivery_fee_centsinteger: Pristatymo mokestis centais; atsiėmimui — 0.
total_centsinteger: Suma, kurią turi sumokėti pirkėjas: price_cents + delivery_fee_cents.
backorderboolean: Užsakymas iš anksto (allow_backorder): sukurtas be vieneto, apmokėtas pereina į awaiting_stock ir laukia papildymo rato.
ready_estimatestring | null: Užsakymui iš anksto — kada prekė numatoma paštomate (artimiausio papildymo rato pabaiga); kitiems — null.
delivery_leginteger | null: Mūsų parduotuvės krepšeliams su pristatymu — kurjerio etapo numeris (vienas paštomatas — vienas kurjeris). API užsakymams — null.
external_refstring | null: Jūsų nuoroda, perduota kuriant užsakymą.
reserved_untilstring | null: Iki kada galioja rezervacija. Tik būsenoje reserved, kitur — null.
tracking_urlstring: Pirkėjo sekimo puslapio adresas. Grąžinamas visada; PIN ir QR kodas jame atsiranda apmokėjus.
created_atstring: Sukūrimo laikas.
paid_atstring | null: Kada patvirtintas apmokėjimas.
ready_atstring | null: Kada užsakymas tapo paruoštas atsiimti (tik atsiėmimui).
picked_atstring | null: Kada prekė išimta iš paštomato — pirkėjo (atsiėmimas) arba kurjerio (pristatymas).
delivered_atstring | null: Kada pirkėjas patvirtino pristatymą (tik pristatymui).
cancelled_at, cancel_reasonstring | null: Atšaukimo laikas ir priežastis.
invoiceobject | null: GetFast 24/7 parduotuvės užsakymams — sąskaita faktūra, kurią apmokėjimo metu išrašėme jūsų vardu (jūsų rekvizitai ir serija): number (pvz. DEL-000123), issued_at, net_cents, vat_cents, total_cents ir portal_url (HTML ir PDF prekybininko portale, reikia prisijungti). Užsakymams, sukurtiems per jūsų API, — null: pinigus surenkate ir sąskaitą išrašote jūs.

Webhook pranešimai

Jei portale, skiltyje Integracija, nurodote webhook adresą, apie kiekvieną užsakymo būsenos pasikeitimą (ir apie užsakymo sukūrimą) jūsų sistemai siunčiame POST užklausą. Adresas turi būti https://, be naudotojo vardo ir slaptažodžio. Įvykiai, įvykę tuo metu, kai adresas nenurodytas, nekaupiami ir vėliau nesiunčiami.

Užklausa

POST <jūsų webhook adresas>

{
  "id": "c2f4a8d0-1b3e-4c5a-9d7f-6e8b0a2c4d6f",
  "event": "order.status_changed",
  "created_at": "2026-11-11T17:02:10.412Z",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "number": "GF-000123",
    "status": "ready_for_pickup",
    "previous_status": "reserved",
    "fulfillment": "pickup",
    "external_ref": "ESHOP-10045",
    "tracking_url": "https://getfast24.lt/o/3f9a1c0b7e2d4a6f8b1c2d3e"
  }
}

Turinio laukai

idstring (UUID): Pranešimo identifikatorius. Kartojant siuntimą jis nesikeičia — pagal jį atmeskite pasikartojimus.
eventstring: order.status_changed arba ping (bandomasis įvykis iš portalo).
created_atstring: Kada įvykis įvyko (ISO 8601 UTC).
data.id, data.numberstring: Užsakymo identifikatorius ir numeris.
data.statusstring: Nauja užsakymo būsena.
data.previous_statusstring | null: Ankstesnė būsena; null, kai pranešama apie užsakymo sukūrimą.
data.fulfillment"pickup" | "delivery": Gavimo būdas.
data.external_refstring | null: Jūsų nuoroda iš užsakymo.
data.tracking_urlstring: Pirkėjo sekimo puslapio adresas.

Antraštės: Content-Type: application/json, User-Agent: GetFast247-Webhooks/1 ir parašas X-GetFast-Signature. Bandomojo įvykio turinys:

Įvykis ping

{
  "id": "5d0e9b3a-7c1f-4e2a-8b6d-0f1a2b3c4d5e",
  "event": "ping",
  "created_at": "2026-11-11T17:10:00.000Z",
  "data": {
    "message": "GetFast 24/7 webhook test",
    "sent_by": "merchant"
  }
}

Atsakymas ir kartojimas

Atsakykite bet kuria 2xx būsena per 5 sekundes. Nukreipimų (3xx) nesekame — jie laikomi nesėkme.
Nepavykus bandome iš viso iki 5 kartų. Pauzės po nesėkmių — ne trumpesnės kaip 30 s, 60 s, 120 s, 240 s; pakartotinius siuntimus vykdo foninė užduotis, paleidžiama kas 60 s, todėl reali pauzė gali būti tiek ilgesnė. Po 5-ojo nesėkmingo bandymo pranešimas nebesiunčiamas.
Tas pats pranešimas gali ateiti daugiau nei kartą, o eiliškumas negarantuojamas — apdorojimas turi būti idempotentiškas (pagal id), o esant abejonei tikrąją būseną rodo GET /orders/{id}.
Paskutinius siuntimus, bandymų skaičių ir klaidą matote portale, skiltyje „Integracija“. Ten pat galite išsiųsti bandomąjį įvykį.

Parašo tikrinimas

Pirmą kartą išsaugojus adresą sugeneruojamas parašo raktas (whsec_…), parodomas vieną kartą; portale jį galima pakeisti nauju. Kiekviena užklausa turi antraštę

X-GetFast-Signature: t=<unix laikas sekundėmis>,v1=<parašas>

kur parašas — šešioliktainis HMAC-SHA256, apskaičiuotas jūsų raktu nuo eilutės <t>.<neapdorotas užklausos turinys>. Tikrindami:

imkite neapdorotą turinį (baitus), o ne iš naujo suformuotą JSON;
apskaičiuokite parašą ir palyginkite pastovaus laiko funkcija;
atmeskite užklausas, kurių t skiriasi nuo dabarties daugiau nei 5 min. — taip apsisaugosite nuo pakartotinio seno pranešimo panaudojimo (šią ribą taikote jūs; pakartotinis siuntimas visada pasirašomas nauju laiku).

Node.js — verify-getfast-signature.mjs

import crypto from 'node:crypto';

const TOLERANCE_SECONDS = 300;

// rawBody — užklausos turinys tiksliai toks, koks gautas (prieš JSON.parse).
export function verifyGetFastSignature(rawBody, header, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(String(header ?? '').split(',').map((part) => part.trim().split('=')));
  if (!/^\d+$/.test(parts.t ?? '') || typeof parts.v1 !== 'string') return false;
  if (Math.abs(nowSeconds - Number(parts.t)) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const given = Buffer.from(parts.v1, 'utf8');
  const wanted = Buffer.from(expected, 'utf8');
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

Node.js — priėmimo pavyzdys

import http from 'node:http';
import { verifyGetFastSignature } from './verify-getfast-signature.mjs';

const secret = process.env.GETFAST_WEBHOOK_SECRET; // whsec_…
const seen = new Set(); // produkcijoje — duomenų bazės lentelė su unikaliu id

http.createServer((request, response) => {
  const chunks = [];
  request.on('data', (chunk) => chunks.push(chunk));
  request.on('end', () => {
    const rawBody = Buffer.concat(chunks).toString('utf8');
    if (!verifyGetFastSignature(rawBody, request.headers['x-getfast-signature'], secret)) {
      response.writeHead(401).end();
      return;
    }
    const event = JSON.parse(rawBody);
    if (!seen.has(event.id)) {
      seen.add(event.id);
      if (event.event === 'order.status_changed') {
        // atnaujinkite užsakymą savo sistemoje pagal event.data.external_ref / event.data.status
      }
    }
    response.writeHead(204).end(); // 2xx per 5 s, kitaip bandysime dar kartą
  });
}).listen(Number(process.env.PORT ?? 4000));

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_getfast_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
    """raw_body — užklausos turinys baitais, tiksliai toks, koks gautas."""
    parts = dict(part.strip().split("=", 1) for part in (header or "").split(",") if "=" in part)
    timestamp, signature = parts.get("t", ""), parts.get("v1", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

PHP

<?php

const GETFAST_TOLERANCE_SECONDS = 300;

// $rawBody = file_get_contents("php://input");
// $header  = $_SERVER["HTTP_X_GETFAST_SIGNATURE"] ?? null;
function verify_getfast_signature(string $rawBody, ?string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(",", $header ?? "") as $part) {
        $pair = explode("=", trim($part), 2);
        if (count($pair) === 2) {
            $parts[$pair[0]] = $pair[1];
        }
    }
    $timestamp = $parts["t"] ?? "";
    $signature = $parts["v1"] ?? "";
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > GETFAST_TOLERANCE_SECONDS) {
        return false;
    }
    $expected = hash_hmac("sha256", $timestamp . "." . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

Pakeitus parašo raktą

Naujas raktas pradeda galioti iškart — juo pasirašomi ir dar neišsiųsti ar kartojami pranešimai. Pirmiausia atnaujinkite raktą savo sistemoje, tada tikrinkite bandomuoju įvykiu.

Klaidos

Nepavykusi užklausa grąžina 4xx arba 5xx būseną ir vienodos formos JSON: mašininį kodą code, lietuvišką pranešimą message (jį galima rodyti darbuotojui) ir kartais papildomą objektą details. Programoje remkitės code ir HTTP būsena, ne pranešimo tekstu. Atskirų laukų klaidų tekstai (details.issues[].message) gali būti ir anglų kalba.

Klaidos forma (422)

{
  "error": {
    "code": "validation_error",
    "message": "Neteisingi užsakymo duomenys.",
    "details": {
      "issues": [
        {
          "path": "customer.phone",
          "message": "Neteisingas telefono numeris."
        }
      ]
    }
  }
}

Galimos klaidos

401unauthorizedNėra rakto, jis neteisingas, atšauktas arba prekybininkas išjungtas.
404not_foundPrekė (nežinomas arba išjungtas SKU), paštomatas arba užsakymas nerastas.
409out_of_stockKuriant užsakymą pasirinktame paštomate nebėra laisvo šios prekės vieneto.
409delivery_unavailablePristatymo adresas per toli nuo paštomato su šia preke.
409reservation_expiredBandoma apmokėti užsakymą, kurio rezervacijos laikas jau baigėsi.
409invalid_stateVeiksmas negalimas dabartinėje būsenoje: pvz. atšaukiamas jau apmokėtas užsakymas, apmokamas atšauktas užsakymas, paštomatas šiuo metu neveikia. details.status rodo dabartinę užsakymo būseną, kai ji žinoma.
422validation_errorNeteisingi parametrai arba turinys (taip pat ir netaisyklingas JSON). details.issues — sąrašas { path, message } su lauko keliu, pvz. customer.phone.
429rate_limitedViršytas užklausų limitas. Žr. Užklausų limitas.
500internal_errorNetikėta serverio klaida. Užklausą galima pakartoti vėliau.

Pavyzdys: prekės nebėra (409)

{
  "error": {
    "code": "out_of_stock",
    "message": "Šios prekės pasirinktame paštomate nebėra."
  }
}

Klaidų žodyne yra ir daugiau kodų (forbidden 403, conflict 409, lokkio_unavailable ir not_configured 503). Šiuo metu v1 galiniai taškai jų negrąžina, bet nežinomą kodą klientas turėtų apdoroti pagal HTTP būseną.

Kreipiantis į neegzistuojantį kelią arba nepalaikomu HTTP metodu, atsako pati karkaso sistema (404 arba 405) — toks atsakymas nėra aukščiau aprašytos JSON formos.

Užklausų limitas

Vienam API raktui leidžiama 20 užklausų per sekundę (slenkantis 1 s langas). Viršijus limitą grąžinama 429 rate_limited, antraštė Retry-After (sekundėmis, ne mažiau kaip 1) ir details.retry_after_ms — po kiek milisekundžių verta bandyti vėl. Atmestos užklausos į limitą neįskaičiuojamos.

Atsakymas 429

{
  "error": {
    "code": "rate_limited",
    "message": "Per daug užklausų: limitas 20 per sekundę vienam raktui.",
    "details": {
      "retry_after_ms": 640
    }
  }
}

Prieinamumo atsakymą prekės puslapiui verta trumpam (kelioms sekundėms) pasidėti savo pusėje — taip limito nepasieksite net per akcijas.

Tik kūrimo aplinkai

Ši dokumentacija rodoma iš įdiegimo, kurio adresas https://getfast24.lt. Žemiau — kas joje veikia kitaip, nei veiktų produkcijoje.

Mokėjimų nėra. API pinigų neapdoroja: POST /orders/{id}/pay yra jūsų patvirtinimas, kad pinigus surinkote patys. Demo parduotuvėje (/shop) mokėjimas imituojamas.
SMS nesiunčiamos. Žinutės pirkėjui tik įrašomos; jas galima peržiūrėti testavimo centre ir užsakymo puslapyje portale.
Webhook į http:// adresus leidžiami tik ne produkcijoje; produkcijoje — tik https://.
Užklausų limitas laikomas atmintyje (vienam procesui) ir nusinulina perkrovus programą.
Demo raktas ir paštomatai. Demo parduotuvė naudoja šį API per HTTP su demo prekybininko raktu (DEMO_SHOP_API_KEY faile .env.local) — tai pavyzdinė integracija. Paštomatai yra virtualūs.
Vidiniai adresai /api/internal/sync ir /api/lokkio/webhook nėra prekybininko API dalis — jūsų integracijai jų nereikia.