POS Posting API за производители на каси
STRYK POS Posting API книжи ставки од твојата каса на сметки за соби на пријавени гости. Референцата ги прикажува пријавата, книжењето, сторнирањето и webhook-ите.
Contents
Преглед
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 | Вкупна проверка од дозвола, преостанат лимит и затворена сметка. Провери ја непосредно пред книжењето. |
postingBlockReason | no_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-Id | ID на webhook-от, не на испораката |
Заглавие X-STRYK-Signature | sha256= и 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-ови. Таму повторно прочитај ја состојбата.
Листа за прифаќање со тест-хотел и вистински тест-престој со пријава:
- Провери
/pingи доделувањето на гост и соба, исто и кај резервации со повеќе соби. - Провери данок, валута и ограничувањето на клучот на оутлет.
- Точно повторување без двојно книжење, изменета содржина со 409, изгубен одговор со усогласување.
- Batch сите или ниедна, заклучување и лимит, сторно и повторно сторно.
- Збирови на фактура при одјава и одбивање на сторното по преземањето.
- Потпишан webhook, невалиден потпис, дупла и заменета испорака.
- Приказ на грешка, промена на клуч и усогласување од персоналот.
Техничка референца
Целосниот опис е достапен како 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} | Сторнирај една отворена ставка |