е-Фактура API

Postman колекција

Колекцијата има по едно барање за секоја операција од јавното API, готова околина Merot sandbox и папка Get started што го следи водичот Целосно поставување од почеток до крај. Се генерира од јавниот OpenAPI опис, па секогаш се совпаѓа со API референцата: по секое ново издание преземете ја повторно и увезете ја одново.

Преземете ја колекцијата Преземете ја sandbox околината

Увоз и поставување

1. Во Postman изберете Import и спуштете ги двете датотеки, или користете Import од врска со адресите подолу.
2. Изберете ја околината Merot sandbox во изборникот за околина горе десно. Postman ги чува идентификаторите што колекцијата ги зачувува за вас (видете подолу) во избраната околина, па изберете ја пред да испратите какво било барање.
3. Отворете ја околината и залепете го вашиот sandbox клуч во apiKey. Започнува со mfk_test_; го добивате со регистрација на сметка за програмер. Вредноста е означена како тајна, па Postman по default ја изостава од извозите и споделените прегледи.
4. Оставете го companyId празно. Create a company и List companies го пополнуваат самите. Ако вашиот клуч достигнува повеќе компании, поставете го сами на компанијата со која работите.

Адреси на датотеките:

https://developer.merot.com/postman/merot-efaktura-api.postman_collection.json
https://developer.merot.com/postman/merot-sandbox.postman_environment.json

Околината намерно нема продукциска верзија: продукциските клучеви сè уште не се достапни. baseUrl е https://api.efaktura.merot.com, истиот хост за sandbox и за продукција. Клучот одредува до која околина стигате.

Што има во колекцијата

• Get started: создавање компанија, создавање потписник, поврзување на потписникот со компанијата, наоѓање на сертификатот што го врзал Merot Bridge, негово активирање, издавање тест фактура, преземање на нејзиниот статус и преглед на влезното сандаче. Секој чекор го зачувува идентификаторот што го враќа (companyId, signerId, certificateId, einvoiceId), па за следниот не ви треба копирање. Чекорите 4 до 6 бараат инсталиран и спарен Merot Bridge, исто како во водичот, а чекорот 6 чека да го прифатите потврдувањето на потпишувањето во Bridge.
• Vendors: get an OAuth access token (последното барање во Get started): client-credentials грантот за софтверски куќи (vendor). Ставете clientId и clientSecret во околината и испратете го; токенот се зачувува како accessToken и автоматски се користи како bearer додека apiKey е празен. Токените траат 15 минути, па испратете го барањето повторно кога ќе истече.
• Една папка по ресурс: OAuth, Companies, Signers and certificates, E-invoices, Inbox, Webhooks and events, Archive, Sandbox, Bridge and signing и Usage and health. Незадолжителните параметри на барањето се наведени, но исклучени; штиклирајте ги оние што ви требаат.

Секое барање испраќа Authorization: Bearer {{apiKey}} (поставено еднаш на колекцијата) и Merot-Version: {{merotVersion}}. Барањата што работат врз една компанија испраќаат и X-Company-Id: {{companyId}}; заглавието се изоставува додека companyId е празно. Износите во примерите се децимален износ како текстуална вредност (string), на пример "10000.00", никогаш како JSON број.

Idempotency-Key

Секое пишување, освен POST /v1/oauth/token, бара Idempotency-Key. Колекцијата го прави тоа наместо вас: скрипта пред барањето става нов UUID v4 во заглавието пред секое пишување. Никогаш не треба да внесувате ваков клуч.

Повторувањата се справуваат онака како што API-то го очекува. Ако пишувањето заврши со мрежна грешка, истек на времето, 429 или 5xx, а вие го испратите истото барање со исто тело повторно, колекцијата го користи истиот клуч, па серверот го третира како повторување на првиот обид. Ако го промените телото, или претходниот обид добил конечен одговор (кој било статус под 500, освен 429), следното испраќање добива нов клуч.

Повторно генерирање

Колекцијата и околината се генерираат од јавниот OpenAPI опис со скрипта во репозиториумот на овој сајт, не се пишуваат рачно. За да ги обновите по промена на API-то:

npm run postman:sync    # ја копира најновата спецификација
npm run postman:build   # ги препишува public/postman/*.json

Тест го прекинува градењето на сајтот ако вградените датотеки се разликуваат од OpenAPI снимката, ако распоредот на папките повеќе не ја покрива секоја операција, или ако се појави тајна.