Праќање документ

POST

/api/integration/v1/outbound

Submits one UBL 2.1 document for delivery.

The response does not wait for processing: status 10 means “received by us”. Repeating the call with the same X-Idempotency-Key and the same body within one hour returns the same docUid with HTTP 200 instead of creating a second document.

Примерот важи само за demo околината.

Request

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: <X-Idempotency-Key>" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

Секој повик носи X-Api-Key со клуч што го има опфатот IntegrationApi, и X-Software-Id со името и верзијата на твојот софтвер. Како се бара клуч стои во Автентикација.

Parameters

Сите параметри (2)

Parameter	In	Type	Presence	Description
`X-Software-Id`	`header`	string	`always`	Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.
`X-Idempotency-Key`	`header`	string	`always`	Client-chosen key that makes the submission repeatable. The same key with the same body within one hour returns the same docUid instead of creating a second document; the same key with a different body is rejected with EARH-2010. Missing means EARH-2013.

Request Body

One UBL 2.1 document as raw XML. Exactly one document per request — a payload carrying more is rejected with EARH-2011. The bytes are stored as received and are returned unchanged by GET outbound/{docUid}/file?format=ubl.

Тип: application/xml. Работен пример што поминува таков каков е: invoice-ubl21.xml — што содржи и што смееш да замениш стои на Формати.

Error codes

EARH-1001 · EARH-1002 · EARH-1003 · EARH-1004 · EARH-1005 · EARH-1006 · EARH-1007 · EARH-2001 · EARH-2002 · EARH-2003 · EARH-2004 · EARH-2005 · EARH-2006 · EARH-2010 · EARH-2011 · EARH-2012 · EARH-2013 · EARH-9001

Целосниот список шифри, со што значат и што да се направи, е во Каталог на грешки.

Responses

200

The same key and body were already submitted; the original docUid is returned and alreadyExisted is true.

{
  "docUid": "eah_o_01M0ZZB88FT117S27PM8ZEK9RY",
  "status": 10,
  "receivedAt": "2026-08-26T23:24:26+02:00",
  "alreadyExisted": true
}

Сите полиња во телото (4)

Field	Type	Presence
`docUid`	string	`nullable`
`status`	integer · int32	`always`
`receivedAt`	string · date-time	`always`
`alreadyExisted`	boolean	`always`

201

The document was accepted and now carries a docUid.

{
  "docUid": "eah_o_01M0ZZB88FT117S27PM8ZEK9RY",
  "status": 10,
  "receivedAt": "2026-08-26T23:24:17+02:00",
  "alreadyExisted": false
}

Сите полиња во телото (4)

Field	Type	Presence
`docUid`	string	`nullable`
`status`	integer · int32	`always`
`receivedAt`	string · date-time	`always`
`alreadyExisted`	boolean	`always`

400

The submission cannot be processed — EARH-1007 (a tenant value in the body), EARH-2001 (not well-formed XML), EARH-2002 (not UBL 2.1), EARH-2003 (no recipient), EARH-2004 (malformed recipient tax number), EARH-2005 (no document type), EARH-2006 (no amount), EARH-2011 (more than one document), EARH-2013 (the X-Idempotency-Key header is missing).

{
  "type": "https://earhiva.mk/errors/EARH-1007",
  "title": "Request body must not contain a tenant-identifying field.",
  "status": 400,
  "code": "EARH-1007"
}

Сите полиња во телото (6)

Field	Type	Presence	Description
`type`	string	`nullable`	Address of this code in the error catalogue (RFC 7807).
`title`	string	`nullable`	Short, stable English summary of the error — the same string that appears in your log.
`status`	integer · int32	`always`	HTTP status code, repeated in the body (RFC 7807).
`detail`	string	`nullable`	What went wrong in this particular call, when there is more to say than the title.
`code`	string	`nullable`	The `EARH-xxxx` code. This is the contract: match on it, not on the text.
`eventId`	string	`nullable`	Only on `EARH-9000`. Quote it when reporting the problem — the same reference we record in our log.

401

The API key is missing, unknown, expired or revoked — EARH-1001, EARH-1002, EARH-1003. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.

403

The caller’s address is outside the allowed list, or the key does not carry the IntegrationApi scope — EARH-1004, EARH-1005. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.

409

EARH-2010 — the same idempotency key was already used with different content; EARH-9001 — outbound over the API is not enabled for this tenant.

{
  "type": "https://earhiva.mk/errors/EARH-2010",
  "title": "This idempotency key was already used with different content.",
  "status": 409,
  "code": "EARH-2010"
}

Сите полиња во телото (6)

Field	Type	Presence	Description
`type`	string	`nullable`	Address of this code in the error catalogue (RFC 7807).
`title`	string	`nullable`	Short, stable English summary of the error — the same string that appears in your log.
`status`	integer · int32	`always`	HTTP status code, repeated in the body (RFC 7807).
`detail`	string	`nullable`	What went wrong in this particular call, when there is more to say than the title.
`code`	string	`nullable`	The `EARH-xxxx` code. This is the contract: match on it, not on the text.
`eventId`	string	`nullable`	Only on `EARH-9000`. Quote it when reporting the problem — the same reference we record in our log.

413

EARH-2012 — the document exceeds the working size limit; the response names the allowed one.

{
  "type": "https://earhiva.mk/errors/EARH-2012",
  "title": "Document exceeds the configured size limit.",
  "status": 413,
  "code": "EARH-2012"
}

Сите полиња во телото (6)

Field	Type	Presence	Description
`type`	string	`nullable`	Address of this code in the error catalogue (RFC 7807).
`title`	string	`nullable`	Short, stable English summary of the error — the same string that appears in your log.
`status`	integer · int32	`always`	HTTP status code, repeated in the body (RFC 7807).
`detail`	string	`nullable`	What went wrong in this particular call, when there is more to say than the title.
`code`	string	`nullable`	The `EARH-xxxx` code. This is the contract: match on it, not on the text.
`eventId`	string	`nullable`	Only on `EARH-9000`. Quote it when reporting the problem — the same reference we record in our log.

429

The traffic limit for this key has been reached — EARH-1006. The response carries Retry-After. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.

500

Unexpected error on our side — EARH-9000. The body carries eventId; quote it when reporting the problem. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.