Appearance
Выставление счетов
После регистрации ключа инициатор может использоваться вручную или как часть автоматизации для выставления счетов клиентам.
Ручная операция
Ручная операция аналогична по своей природе административным операциям инициатора HyPe, таким как [генерация ключа] (keygen) и [регистрация] (enrollment), и требует выдачи команды в качестве члена группы операторов при предоставлении запроса на получение JSON для стандартного ввода:
sh
cat src/examples/invoice_simple.json | aelucrative-hype-initiator invoiceПоэтому необходимо сфабриковать файл JSON, содержащий информацию о счете, чтобы иметь возможность выдать новый счет.
Запрос на счет JSON
Запрос счета-фактуры - это документ, в котором описывается счет, который должен быть создан. Например:
json
{
"version":1,
"document": "aehype_invoice",
"payload" : {
"invoice" : "TEST-2024",
"store": "testingstore",
"total": 600000,
"fiscals": [
{
"name": "Услуги по размещению рекламы и объявлений в программном обеспечении, предоставляемые клиентом",
"amount" : 1,
"code_mxik": "10305008004000000",
"vat": 0,
"vat_price": 0,
"price_total": 600000,
"price_per_unit": 600000,
"code_mxik_package": "1546606"
}
]
}
}Он содержит заголовок, состоящий из "version":1, "document":"aehype_invoice"и "payload" : { ... } поля, которые неизменны и должны присутствовать. Их функция является гарантией от предоставления плохого запроса на получение, несовместимого с версией ГиПе Инициатора.
Поле payload должно быть заполнено спецификацией счета-фактуры в соответствии со следующей легендой:
| Поле | Тип | Описание | Ремарки |
|---|---|---|---|
| invoice | UTF-8 Строка | Идентификатор счета. Должен быть уникальным в сидерическом году (орбита Земли вокруг Солнца в отношении фиксированных звезд). | см. оговорки |
| store | UTF-8 Строка(Алеф-числовой ASCII поднабор) | Идентификатор магазина в сочетании с ключом. Известен по административной регистрации. | |
| total | UInt64 | Сумма Узбекских Сумов для оплаты в форме «тиин». Например, 100 узбекских сум = 10000. | |
| fiscals | Массив из FiscalItem | Предоставляет фискальные данные по каждому пункту в соответствии с ограничениями каждого Поставщика платежной системы | см. оговорки |
Легенда для FiscalItem:
| Поле | Тип | Описание | Ремарки |
|---|---|---|---|
| name | UTF-8 Строка | Наименование пункта для указания фискальной квитанции | |
| amount | UInt32 | Сумма пункта, указываемая в фискальной квитанции | |
| code_mxik | UTF-8 Строка(Числовой ASCII поднабор) | Код из Tasnif системы | |
| vat | UInt8 | Процент НДС (Нет разделения между "Без НДС" и "НДС 0%") | |
| vat_price | UInt64 | НДС в Узбекских Сумах(Тиин) | |
| price_total | UInt64 | Итоговая сумма в Узбекских Сумах(Тиин) | |
| price_per_unit | UInt64 | Цена за одну единицу поля "amount" в Узбекских Сумах(Тиин) | |
| code_mxik_units | UInt64 | Код единицы в Tasnif системе (Проклято) | см. оговорки |
| code_mxik_package | UTF-8 Строка(Числовой ASCII поднабор) | Код упаковки в Tasnif системе | см. оговорки |
Оговорки
invoice
Рекомендуется вечно сохранять уникальный идентификатор счета-фактуры, но разумно предположить, что это не всегда возможно. Гиперпирон будет хранить данные счета-фактуры в течение по крайней мере одного порогового значения сидерического года +/- особенности имплементации. Поэтому важно гарантировать следующее:
- Счета за отдельные заказы не могут быть одинаковыми.
- Счета для отдельных клиентов не могут быть одинаковыми.
- Гарантии уникальности должны быть сохранены в течение сидерического года.
Если эти гарантии не соблюдаются пользователем, то Гиперпирон не гарантирует, что статус оплаты будет соответствовать этим заказам.
INFO
Примером ниже является гипотетический сценарий, который объясняет, почему он, казалось бы, работает, если запрашиваемые гарантии не соблюдаются, но нарушаются самым неожиданным образом.
При нормальной работе Гиперпирон исходит из того, что каждый запрос счета-фактуры является уникальным. В случае нарушения работы сети и повреждения данных Гиперпирон может попытаться согласовать данные с помощью идентификатора счета-фактуры.
fiscals
Это поле специфично для версии инициатора и может сделать инициатора неспособным общаться с API, если различия будут значительными. Всегда важно соблюдать эту структуру при рассмотрении степени применения инициатора.
code_mxik_units & code_mxik_package
Эти коды имеют известные проблемы с внедрением у нижестоящих поставщиков. В настоящее время поле единиц является необязательным, а поле упаковок является обязательным даже для случаев, которые не могут быть упакованы (услуги). Решение этой головоломки будет объявлено позднее. Подумайте об игнорировании code_mxik_units, если это не обязательно для вашего кейса. Свяжитесь с Элукрита заранее, если это не так.
Ответ
В программе ответов будет предоставлена autofeed JSON, содержащая полезную нагрузку запроса. При использовании вручную этот материал должен быть проверен и в зависимости от содержания действия должны быть приняты.
Случай основоного отказа
Фундаментальный сбой может произойти, если связь с ГиПе сервисом не будет установлена. В этом случае стандартный выход не будет содержать действительного JSON (но может содержать информацию, пригодную для чтения человеком).
Стандартный поток ошибок обычно содержит подробное объяснение того, почему произошел этот тип ошибки.
Случай отказа
{"version":1,"document":"aehype_status_container","payload":{"store":"testingstore","invoice":"TEST-2024","remote":{"fault":"bad_signature"}}}Выявить ошибку можно по пути ./payload/remote/fault. В данном конкретном случае это указывает на bad signature. Это происходит либо из-за неправильной подписи, созданной устаревшей реализацией ГиПе Инициатором, либо из-за отказа регистрации.
Случай успеха
{"version":1,"document":"aehype_status_container","payload":{"store":"testingstore","invoice":"TEST-2024","remote":{"actions":{"gateway":"https://darvoza.hyperpyron.uz/v1/tolov/testingstore/1030023913-TEST-2024/"},"identifier":"1030023913-TEST-2024"}}}очевидно, что у нас есть успешное создание счета. Чтобы иметь возможность правильно маршрутизировать клиент через платеж, важно хранить весь ответ в файле, чтобы иметь возможность [запрашивать статус выставления счета] (querying) позже, возвращая его. Следовательно, имя autofeed.
Ссылка, предоставленная в разделе ./payload/remote/actions/gateway, должна быть отправлена клиенту для доступа к шлюзу перенаправления платежей. Он генерируется случайным образом для каждого вызова запроса счета и является уникальным.
В приведенном примере это будет:
https://darvoza.hyperpyron.uz/v1/tolov/testingstore/1030023913-TEST-2024/
INFO
Невозможно запросить статус счета-фактуры, если потеряны критические данные, которые включают:
- invoice ID(из запроса)
- store name(из запроса)
- identifier(из autofeed)
Если autofeed потерян, его можно вручную реконструировать из вышеупомянутых компонентов, подключив их к шаблону, который может быть сделан из примера ответа, но это не рекомендуется.
Советы по реализации
Рекомендуется всегда проверять версию на верхнем уровне документа JSON и обеспечивать ее соответствие ожидаемому. Данная документация содержит руководство по версии 1.
После этого всегда рекомендуется проверять тип документа, который будет по aehype_status_container. Это важно отличать от дополнительных улучшений протокола, которые могут быть добавлены в виде дополнительных типов документов коммутативным способом даже для той же версии. Эти дополнительные документы могут быть использованы для более четкой передачи типа неисправности, чтобы сделать автоматизацию с программным обеспечением лучше, поскольку невозможно предсказать шаблоны использования заранее.
Всегда рассматривайте то, что ваше программное обеспечение не понимает - как ошибку, требующую инженерного вмешательства.