Quick Start

Оваа страница води од нула до испратен документ во пет чекора. Секој чекор носи готов пример: копирај го целиот и замени ги двата Placeholder-а — <ВАШИОТ КЛУЧ> со клучот што си го добил, и <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА> со ознаката на твојот софтвер. Ништо друго не се менува.

Основната адреса на demo околината е https://sandbox.api.earhiva.mk и таа стои во секој пример подолу.

1. Побарај клуч за demo околината

Клучот за demo околината се бара од нас — не се создава сам од екран. Барањето се праќа по е-пошта на support@earhiva.mk, со наслов Барање за клуч кон demo околината.

Клучот што ќе го добиеш носи опфат IntegrationApi — без него секој повик кон адресите под api/integration/v1 се одбива, дури и кога клучот е валиден.

Барањето носи два одделни списока податоци: за тебе како интегратор, и за клиентот од чие име ќе се праќаат тест податоци кон УЈП. Demo клучот е врзан за конкретен даночен обврзник, па без вториот список не може да се изврши. Копирај го овој текст и пополни ги двата:

Барање за клуч кон demo околината на eArhiva

Податоци за интеграторот
  име на компанијата:
  лице за контакт:
  е-пошта:
  телефон:
  име на апликацијата што ќе го користи API:

Податоци за клиентот
  име на компанијата:
  ЕДБ:
  лице за контакт:
  е-пошта:
  телефон:

2. Провери дека клучот важи

GET /api/integration/v1/ping не допира ниту еден документ — само кажува дали клучот е примен. Тоа е најевтиниот начин да се раздели „клучот не важи” од „документот е погрешен” пред да се прати што било.

Двете заглавија се задолжителни во секој повик: X-Api-Key го носи клучот, а X-Software-Id го именува твојот софтвер. Второто е слободен текст — впиши го името и верзијата на својата апликација, пр. SmetkovodstvoPro/2.4. Таа вредност не влијае на правата на клучот; служи за да те препознаеме во логовите кога ќе се јавиш со прашање.

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"
}

3. Прати документ

Документот се праќа како UBL 2.1 XML во телото на POST /api/integration/v1/outbound. Заглавието X-Idempotency-Key е задолжително: тоа е твојата ознака за оваа испорака, по која повторен повик со иста содржина враќа 200 наместо да создаде втор документ.

Преземи го работниот пример invoice-ubl21.xml, сними го како invoice.xml во папката од која ја извршуваш командата, и изврши ја непроменета. Тој поминува таков каков е — што содржи и што во него смееш да замениш со свое, стои подоцна на страницата Формати, кога ќе праќаш свој документ.

curl -i -X POST "https://sandbox.api.earhiva.mk/api/integration/v1/outbound" \
  -H "X-Api-Key: <ВАШИОТ КЛУЧ>" \
  -H "X-Software-Id: <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА>" \
  -H "X-Idempotency-Key: quick-start-001" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

4. Земи го идентификаторот

При успех одговорот е 201 и во телото стои docUid — идентификаторот на документот кај нас. Тој е единственото што ти треба за сè понатаму: статус, преземање на фајл, историја, откажување.

⛔ Копирај ја вредноста на docUid од твојот одговор и чувај ја. Секоја команда од тука натаму, почнувајќи од чекорот 5, ја носи на местото на Placeholder-от <docUid>. Вредноста подолу е пример од еден таков одговор — твојата ќе биде поинаква и само таа работи со твојот документ.

{
  "docUid": "eah_o_01K3F9YB2M7Q4XVZ8NDHRPTC5E",
  "status": 10,
  "receivedAt": "2026-08-25T10:16:41.088+02:00",
  "alreadyExisted": false
}

Статус 10 значи дека документот е примен и заведен кај нас. Одговорот не чека обработка — таа почнува потоа, и се следи со чекорот 5.

Ако истата ознака X-Idempotency-Key се повтори со иста содржина, се враќа 200 со истиот docUid и alreadyExisted: true. Тоа не е грешка — тоа е заштитата од двојно праќање.

5. Провери го статусот

GET /api/integration/v1/outbound/{docUid} го враќа тековниот статус на документот. Во командата подолу замени го <docUid> со вредноста што ја копира во чекорот 4:

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

{
  "docUid": "eah_o_01K3F9YB2M7Q4XVZ8NDHRPTC5E",
  "status": 20,
  "failureCode": null,
  "failureMessage": null,
  "createdAt": "2026-08-25T10:16:41.088+02:00",
  "partnerEdb": "4030000000000",
  "documentNumber": "0001/2026",
  "amount": 1180.00,
  "currency": "MKD",
  "ujp": null
}

⚠️ Веднаш по праќањето документот е во статус 10 и полињата за партнер, број, износ и валута може да бидат null — тие се пополнуваат кога обработката ќе го прочита документот. Празно поле таму не значи дека нешто паднало; тоа се гледа единствено од status и од failureCode.

Секоја вредност на status, што значи и кон што може да премине, стои на страницата Статуси.