Сървърът Zanzibar VFMS REST API позволява на други програми, например ERP или хотелска система, да издават фискални бележки в Занзибар чрез виртуалната фискална система (VFMS) на данъчната служба на Занзибар (ZRA). API е съвместим с Incotex Invoice Monitoring, така че програма, направена за него, работи и с IncoPOS. Всеки фискален документ се записва и като продажба в IncoPOS. Списъкът със сървъри е в Сървъри, а полетата, които има всеки сървър, са в Добавяне, редакция и изтриване на сървъри.
Какво ви трябва
- Устройство Zanzibar VFMS в Устройства на това работно място, с данните за вход в ZRA на звеното за продажби. Продажбите минават през него.
- За хотелските заявки: integration ID и token на звеното за настаняване и на звеното за хотелски услуги, от ZRA.
- Лиценз на това работно място. Прозорецът показва „Изисква Basic или по-добър лиценз“.
- Свободен порт на това работно място, отворен в защитната му стена.
Настройте сървъра
- Отворете Редакция → Администриране → Сървъри… и натиснете Нов.
- Изберете Zanzibar VFMS REST API в Тип на сървъра:. Порт: получава 8089, а Базов път: получава /.
- Въведете Потребител: и Парола: и изберете Използвайте HTTPS за криптирани връзки.
- За хотел натиснете бутона до ZRA credentials: и въведете двете звена, вижте Данни за вход в ZRA.
- Натиснете Запис. Разрешете порта в защитната стена, когато IncoPOS попита.
| Поле | Какво прави |
|---|---|
| Порт: | Портът на API. Не може да го използва друг разрешен сървър на работното място. |
| Базов път: | Началото на всеки адрес на API. Описанието на API се отваря на базовия път, последван от swagger. |
| Потребител:, Парола: | Входът, който програмите изпращат с всяка заявка. Потребител: е задължително. С празна Парола: API приема заявки без вход. |
| Използвайте HTTPS | API приема само криптирани връзки. Сертификат: показва сертификата на сървъра. Настройката е същата като в Tanzania VFD REST API. |
| ZRA credentials: | Бутонът показва integration ID на хотелските звена или (не е конфигуриран) и отваря ZRA Credentials. |
Данни за вход в ZRA
Прозорецът ZRA Credentials съдържа входа в ZRA на двете хотелски звена и офлайн бележките. Запис ги запазва за това работно място веднага, без да записва сървъра.
| Поле | Какво прави |
|---|---|
| Hotel accommodation unit: Integration ID:, Token: | Входът в ZRA за заявките за настаняване, например настаняване, гости, стаи и напускане. |
| Hotel services unit: Integration ID:, Token: | Входът в ZRA за хотелските услуги. |
| Enable offline receipts (experimental) | Когато ZRA не е достъпна, продажбата веднага получава местен номер на бележка и се изпраща в ZRA по-късно. |
| Offline tax rate (%): | Данъчната ставка на офлайн бележките, по подразбиране 15. |
| Offline receipt prefix: | Началото на номерата на офлайн бележките, по подразбиране OFF. |
Заявката може да носи и свои integration ID и token, които тогава заместват тези от прозореца.
Как работи
API приема продажби (POST zanz/sale, с ?btob или ?institution за фирмени и институционални клиенти), хотелски заявки (POST zanz/hotel), записания резултат на продажба (GET zanz/sale/{referenceNumber}), стоките, които ZRA не облага (GET zanz/non-tax-items), и проверка на състоянието (GET api/health). Описанието на типа сървър в прозореца ги изброява всички.
Всяка продажба се записва в обекта по подразбиране на IncoPOS и се фискализира чрез устройството Zanzibar VFMS, една по една. Референтен номер, изпратен отново, връща записания резултат или подписва записаната продажба, ако тя не е била фискализирана. Напускането и услугите в хотела също се записват като продажби.
| Случай | Отговор на API |
|---|---|
| ZRA не отговаря навреме | Продажбата се записва с неизвестно състояние. Отговорът казва да не се опитва отново със същия референтен номер. |
| ZRA не е достъпна | Грешка, а с включени офлайн бележки местна бележка. Офлайн бележките се изпращат в ZRA във фонов режим, отново на всеки 2 минути, докато ZRA не е достъпна. |
| ZRA вече има референтния номер или отказва продажбата | Грешка с отговора на ZRA. |
| Няма лиценз | „The server is not licensed“. |
| Няма устройство Zanzibar VFMS | „No Zanzibar VFMS device is configured as the sales data controller on the server“. |
| Няма данни за вход за хотелско звено | „The ZRA credentials for this unit are not configured“. |
Отстраняване на проблеми
| Проблем | Решение |
|---|---|
| „Потребителското име не може да бъде празно!“ | Въведете Потребител:. |
| „Please enter a valid offline tax rate.“ | Въведете число в Offline tax rate (%):. |
| „Сървърът ‘…’ не успя да стартира поради отказан достъп.“ | Windows не позволява на IncoPOS да слуша на порта. Натиснете Копиране на команда (Копиране на команди с HTTPS), изпълнете командите в Command Prompt, отворен като администратор, след това запишете сървъра отново или рестартирайте IncoPOS. |
| „Сървърът ‘…’ работи, но защитната стена може да блокира входящите връзки на порт …“ | Другите компютри не достигат до API. Натиснете Копиране на команда и изпълнете командата като администратор или разрешете порта в Windows Defender Firewall. |