е-Фактура API

Автентикација

Секое барање (освен добивањето OAuth токен, јавната листа на изданија на Bridge и проверката на статус) носи заглавие Authorization: Bearer.

API клучеви

Создавајте клучеви во конзолата, со одредени дозволи (scope) и опционално ограничени на подгрупа од вашите компании-клиенти. Клучот изгледа вака:

mfk_test_7hqk2m9vslgp4wz3c1yxfb0e
mfk_live_9k2pqxlt5m0wnzvcb1y47rghf

Делот test/live ја одредува околината — sandbox клучевите можат да пристапат само до документи со environment: "sandbox", live клучевите само до продукциски документи. Клучевите се прикажуваат само еднаш, при создавање; на серверот се чува само хеш. Ротирајте клуч од конзолата: стариот продолжува да работи до 7 дена, за да можете безбедно да ги префрлите вашите системи на новиот.

Authorization: Bearer mfk_test_7hqk2m9vslgp4wz3c1yxfb0e

OAuth 2.0 client credentials (за софтверски куќи)

Софтверските куќи (vendor) кои работат во име на повеќе компании-клиенти можат да користат OAuth 2.0 client-credentials (RFC 6749 §4.4) наместо статичен клуч:

POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=mfc_...&client_secret=...&scope=einvoices:read einvoices:write

Ова враќа краткотраен (15-минутен) bearer токен чии дозволи се пресекот на она што сте го побарале и она што му е дозволено на клиентот. Ова е единствениот endpoint чие тело со грешка е обично OAuth 2.0 JSON, а не application/problem+json — видете Грешки.

Дозволи (scope)

Scope	Дозволува
`einvoices:read` / `einvoices:write`	Читање / издавање, сторно и корекција на е-фактури
`inbox:read` / `inbox:write`	Читање / прифаќање и одбивање влезни документи
`archive:read`	Читање архивирани артефакти и барање извози
`companies:read` / `companies:write`	Читање / создавање и ажурирање компании-клиенти, читање потрошувачка
`webhooks:manage`	Управување со webhook endpoint-и, настани и испораки
`signing:agent`	Инлајн потпишување во Режим Б (само SDK-агенти)

Клучеви за повеќе компании

Клуч или токен што има пристап до повеќе од една компанија-клиент мора да испраќа X-Company-Id на секое барање; клуч ограничен на само една компанија може да го изостави.

Околини

Клучевите mfk_test_... (и sandbox OAuth клиентите) секогаш комуницираат само со тест системот на УЈП или со симулаторот на Merot — видете Sandbox. Продукциските клучеви бараат production_allowed на сметката, што пак бара активен платен план.