е-Фактура API

Идемпотентност

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

Idempotency-Key: 8f14e45f-ceea-467f-b0e8-c1f9dc1e6f8f

• Повторување со истиот клуч и исто тело на барањето го враќа оригиналниот одговор (со Idempotent-Replayed: true), без да ја изврши работата двапати.
• Истиот клуч со различно тело е 409 idempotency_conflict.
• Клучевите се паметат 24 часа.

По истекот на 24 часа — clientReference

За издавање е-фактури конкретно, clientReference во POST /v1/einvoices дава идемпотентност што трае подолго од 24-часовниот прозорец на Idempotency-Key: повторување со истата clientReference и исто тело секогаш го враќа постојниот документ (200, не 202), неограничено долго. Различно тело со истата clientReference е 409 client_reference_conflict. Токму ова го прави безбедно да се повторува издавањето фактура од ред за чекање или cron задача, дури и по неколку дена, без ризик за дупликат при поднесувањето до УЈП.

Што е природно идемпотентно

GET барањата, POST /v1/einvoices/validate (никогаш не поднесува ништо) и барањата за освежување на статус не бараат клуч за идемпотентност воопшто — немаат несакани споредни ефекти што можат да се дуплираат.