Скокни до содржината
Reference, STRYK POS

POS Posting API за производители на каси

STRYK POS Posting API книжи ставки од твојата каса на сметки за соби на пријавени гости. Референцата ги прикажува пријавата, книжењето, сторнирањето и webhook-ите.

Last updated: Developers
Contents
  1. Преглед
  2. Клучеви и безбедност
  3. Сметка за соба и износи
  4. Книжење и повторување
  5. Сторно и фактура
  6. Webhook-ови и прифаќање
  7. Техничка референца

Преглед

API е интерфејс од сервер до сервер за ставки на пријавени престои. Хотелот ја поврзува твојата каса во Поставки под POS: Поврзување на каса. Таму касата добива клуч и Адреса за касата.

ПодатокВредност
Основна адресаhttps://app.staystryk.com/api/v1/pos/public
ПријаваBearer клуч на хотелот во заглавието Authorization
УсловХотелот има активен додаток STRYK POS
Без додатокСекој повик одговара со 403 и кодот module_disabled. STRYK не книжи ставка.
Ограничување на повици100 барања на секои 60 секунди по клуч. Потоа STRYK одговара со 429.
Верзија на описот1.3.0

Клучеви и безбедност

  • Клучот започнува со pos_live_. Хотелот го гледа само еднаш при создавањето.
  • Испраќај го само на серверот преку HTTPS во заглавието: Authorization: Bearer <vollständiger Schlüssel>. Никогаш како параметар во адресата.
  • Клучот припаѓа на точно еден хотел и по избор на еден оутлет. Хотелот создава по еден клуч за секоја врска.
  • 401 значи: STRYK не можеше да го провери клучот. Провери ја конфигурацијата и оперативниот статус. Не менувај го клучот автоматски.
  • Новиот клуч е нов опсег на идемпотентност. Тој не ги наоѓа и не ги сторнира ставките на стариот клуч. Заврши ги отворените налози и усогласи ги, пред хотелот да го повлече стариот клуч.
  • Ако клучот е изгубен или компромитиран, хотелот го повлекува со Повлечи клуч и ги расчистува несигурните постапки во STRYK, пред твојата каса да испрати замена.

Сметка за соба и износи

Метод и патекаНамена
GET /pingПроверува само дали клучот се прифаќа.
GET /accountsГи наведува моментално пријавените сметки за соби, вклучително и блокираните.
GET /room-lookup?room=105Ја поврзува соба со пријавениот престој. 404 без соодветен гост, 409 кај двосмислена соба.

Сметката за соба ги содржи овие полиња:

ПолеЗначење
bookingId, bookingNumber, guestName, roomNumberПрестој и соба
allowPostingХотелот дозволил книжење ставки за престојот. Само тоа не е доволно.
allowChargeВкупна проверка од дозвола, преостанат лимит и затворена сметка. Провери ја непосредно пред книжењето.
postingBlockReasonno_post, credit_limit_reached, account_closed или празно
openChargesCount, openChargesTotal, stayChargesTotalОтворени ставки и збир на несторнираните ставки
creditLimit, remainingCredit, currencyЛимит, преостанат лимит и валута на хотелот

Прикажи го гостот и собата за потврда и испрати bookingId заедно со room. Не ја чувај листата на сметки трајно како адресар на гости. Износите се JSON броеви во валута на хотелот. Заокружувањето е HALF_UP: количината на три, износите на две децимали.

Книжење и повторување

Метод и патекаНамена
POST /chargesКнижи ставка на сметка за соба. Одговор 201 со ставката.
POST /charges/batchКнижи од 1 до 50 ставки заедно. Сите нови ставки се книжат или ниедна. Одговорот ги следи редоследот на барањето.
GET /charges/{externalRef}Враќа трајна состојба на ставка, исто така cancelled и transferred.

Полиња на книжење:

ПолеЗадолжителноЗначење
bookingId, roomбарем едноСоба како текст со букви, не како број. Ако се дадени двете, мора да се совпаѓаат.
descriptionда1 до 500 знаци
unitPriceдаБруто цена по единица, поголема од 0, највеќе 99999.99
externalRefдаЕдинствен клуч за документ или ставка, од 1 до 255 знаци, на пример receipt-123-item-1
quantityне0,001 до 9999, стандардно 1
unitненајвеќе 20 знаци, стандардно Стк.
taxRateнеАктивна даночна стапка на хотелот. Ако не се наведе, важи стандардот на оутлетот, а потоа централниот.
currencyнеМора да биде валутата на хотелот
outletIdнеКај клуч со оутлет важи тој оутлет. Друга вредност дава 403.
chargedAtнеВреме на услугата, стандардно сега, највеќе 5 минути во иднина
notes, posRefнеБелешка (1000 знаци), референца на документ за рецепцијата (100 знаци)

Вкупниот износ од количина и единечна цена е поголем од 0 и највеќе 99999999.99.

externalRef е непроменливиот клуч за идемпотентност на хотелот и клучот. Точно повторување го враќа оригиналната ставка со idempotentReplay=true. Изменета содржина или сторниран клуч дава 409.

По тајм-аут или 5xx прво читај GET /charges/{externalRef}. Само при потврден 404 испрати го истото барање непроменето со истиот клуч повторно. Зачувај ги барањата пред испраќање и никогаш не менувај chargedAt, цена, данок или референца. Ако одговорот покажува duplicateWarning, ставката е веќе книжена. Усогласи ја во STRYK и не испраќај повторно.

СтатусЗначење
400Неважечки податоци, поправи ги.
401Клучот не може да се провери
403Опсегот не е дозволен, на пример погрешен оутлет
404Сметката или ставката не постои
409Деловен конфликт. Провери го кодот, не повторувај слепо.
429Ограничување на повици, почекај најмалку 60 секунди
5xxПрво усогласи, па повторувај со ограничен backoff

Кодовите на одговорот за грешка се меѓу другото pos_currency_mismatch, pos_external_ref_conflict, pos_external_ref_cancelled, pos_room_required, pos_guest_not_inhouse, pos_posting_blocked, pos_credit_limit_exceeded, pos_charge_already_invoiced и pos_account_closed. Не прави разлика според германскиот текст. requestId му помага на поддршката.

Сторно и фактура

DELETE /charges/{externalRef} сторнира отворена ставка на твојот клуч. Во телото по избор стои reason (највеќе 500 знаци). Повторување го враќа веќе сторнираната ставка.

  • Статусот на ставка е open, cancelled или transferred.
  • Ставката останува open додека одјавата не ја создаде фактурата. Тогаш STRYK ги презема отворените ставки во позиции на фактура и статусот се менува во transferred.
  • Презета ставка дава 409 со pos_charge_already_invoiced. Хотелот ја поправа во книговодството: Коригирај фактура.
  • Сторното ништо не брише и ништо не враќа. Сторнираната ставка останува следлива.

API книжи позитивни ставки. Плаќањата што се завршуваат на касата не ги испраќај дополнително на собата. При поделено плаќање испрати само отворениот дел на собата со правилно распределен данок. Попустите одземи од бруто цената пред книжењето.

Webhook-ови и прифаќање

Хотелот создава webhook-ови во Поставки под POS: Создај webhook-ови.

ПодатокВредност
Настаниcharge.posted, charge.cancelled, при тестирање ping
Заглавие X-STRYK-EventИме на настанот
Заглавие X-STRYK-Webhook-IdID на webhook-от, не на испораката
Заглавие X-STRYK-Signaturesha256= и HMAC-SHA-256 од непроменетите бајти на барањето. Само со конфигурирана тајна.
Телоevent, hotelId, timestamp, data со chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency и оутлетот
Одговор2xx по трајно прифаќање во рок од 10 секунди. STRYK не ги следи пренасочувањата.
ПовторувањеПо 30 секунди, 5 минути, 30 минути и 2 часа, до зачуваната граница

Провери го потписот над непроменетото тело, пред да го прочиташ како JSON. Зачувај ги event и data.chargeId трајно за да ги препознаваш повторувањата. Испораките може да пристигнат двапати или со друг редослед: стар charge.posted не ја пребришува charge.cancelled. За пријавување, одјавување и пренесување на фактура нема webhook-ови. Таму повторно прочитај ја состојбата.

Листа за прифаќање со тест-хотел и вистински тест-престој со пријава:

  1. Провери /ping и доделувањето на гост и соба, исто и кај резервации со повеќе соби.
  2. Провери данок, валута и ограничувањето на клучот на оутлет.
  3. Точно повторување без двојно книжење, изменета содржина со 409, изгубен одговор со усогласување.
  4. Batch сите или ниедна, заклучување и лимит, сторно и повторно сторно.
  5. Збирови на фактура при одјава и одбивање на сторното по преземањето.
  6. Потпишан webhook, невалиден потпис, дупла и заменета испорака.
  7. Приказ на грешка, промена на клуч и усогласување од персоналот.

Техничка референца

Целосниот опис е достапен како OpenAPI датотека на англиски, како YAML на /developers/pos/openapi.yaml и како JSON на /developers/pos/openapi.json на веб-страницата на STRYK. Во хотелот Техничка документација во делот За техничарот на касата во Поставки под POS води до оваа страница.

МетодПатекаКраток опис
GET/pingПровери врска
GET/accountsНаведи пријавени сметки за соби
GET/room-lookupНајди престој за соба
POST/chargesКнижи една ставка
POST/charges/batchКнижи до 50 ставки заедно
GET/charges/{externalRef}Прочитај состојба на ставка
DELETE/charges/{externalRef}Сторнирај една отворена ставка
Контакт