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

1. Што е клучот

Клучот е низа знаци што ја добиваш од нас, врзана за еден даночен обврзник и за твојот софтвер. Тој не се создава од екран и не се генерира од профил.

Секој клуч носи еден или повеќе опфати. За интеграцискиот API потребен е опфатот IntegrationApi — тој е тоа што му дозволува на клучот да ги повикува адресите под api/integration/v1. Клуч без него е валиден клуч, но секој повик кон интеграцискиот API се одбива со EARH-1005 и статус 403.

2. Две задолжителни заглавија

Секое барање кон интеграцискиот API носи и двете заглавија подолу. Ниту едно од нив не е незадолжително и ниту едно не се заменува со друго.

Заглавие	Што носи	Кога недостасува
`X-Api-Key`	клучот што си го добил	`EARH-1001` · `401`
`X-Software-Id`	ознака на софтверот што повикува — име и верзија, слободен текст, пр. `SmetkovodstvoPro/2.4`	`EARH-1008` · `400`

X-Software-Id не влијае на правата на клучот. Тој служи за да можеме да го препознаеме твојот софтвер во логовите кога ќе се јавиш со прашање.

3. Работен пример

GET /api/integration/v1/ping не допира ниту еден документ — само кажува дали клучот е примен. Копирај ја командата целата и замени ги двата Placeholder-а — клучот и ознаката на својот софтвер:

curl -i -X GET "https://sandbox.api.earhiva.mk/api/integration/v1/ping" \
  -H "X-Api-Key: <ВАШИОТ КЛУЧ>" \
  -H "X-Software-Id: <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА>"

При успех се враќа 200 и тело:

{
  "ok": true,
  "keyValid": true,
  "serverTime": "2026-08-25T10:14:03.412+02:00"
}

keyValid: true значи дека клучот е примен, дека важи и дека го носи опфатот IntegrationApi. Од тука натаму секој повик оди со истите две заглавија.

4. Што уште може да тргне наопаку

Освен отсутните заглавија и отсутниот опфат, клучот може да биде одбиен и во овие три случаи:

Шифра	HTTP	Што значи
`EARH-1002`	`401`	клучот му поминал рокот и мора да се обнови
`EARH-1003`	`401`	клучот е повлечен и повеќе не важи
`EARH-1004`	`403`	барањето доаѓа од адреса што не е на дозволената листа за тој клуч

Секоја шифра во каталогот на грешки носи и што точно да се направи со неа.