One received document by identifier

GET

/api/integration/v1/inbound/{docUid}

Returns one inbound document by its identifier.

The example applies to the demo environment only.

Request

curl -i -X GET "https://sandbox.api.earhiva.mk/api/integration/v1/inbound/<docUid>" \
  -H "X-Api-Key: <YOUR KEY>" \
  -H "X-Software-Id: <NAME AND VERSION OF YOUR APPLICATION>"

Every call carries X-Api-Key with a key that has the IntegrationApi scope, and X-Software-Id with the name and version of your software. How to request a key is on Authentication.

Parameters

All parameters (2)

Parameter	In	Type	Presence	Description
docUid	path	string	always	Identifier of the document, as it appears in the list.
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.

Error codes

EARH-1001 · EARH-1002 · EARH-1003 · EARH-1004 · EARH-1005 · EARH-1006 · EARH-1008 · EARH-1010 · EARH-1011 · EARH-3001

The full list of codes, what each means and what to do, is in the Error catalogue.

Responses

200

The document, including ackedAt when it was acknowledged.

{
  "docUid": "eah_i_01M0ZZB88FT117S27PM8ZEK9RY",
  "receivedAt": "2026-08-26T09:12:04",
  "senderName": "Partner DOOEL Skopje",
  "senderEdb": "4080012600123",
  "ackedAt": null,
  "documentNumber": "2026-000318",
  "amount": 4720,
  "currency": "MKD"
}

All fields in the body (11)

Field	Type	Presence	Description
docUid	string	always	Identifier of the document. Use it to fetch a file or to acknowledge the document.
receivedAt	string · date-time	always	Time the document arrived.
senderName	string	nullable	Name of the sender, read from the received document.
senderEdb	string	nullable	Tax number of the sender, read from the received document.
ackedAt	string · date-time	nullable	Time of the FIRST acknowledgement, or null while the document has not been acknowledged. A repeated acknowledgement does not move it.
documentNumber	string	nullable	Document number, read from the received document.
amount	number · double	nullable	Total amount, read from the received document.
currency	string	nullable	Currency of amount, as a three-letter code.
status	integer · int32	always	Current state of the document: 110 received, 120 being processed, 140 approved, 150 rejected. The code never changes meaning and does not depend on the response language.
rejectionReason	string	nullable	Why the document was rejected. Filled in only when status is 150; null otherwise.
decisionDeadline	string · date	nullable	Calendar date by which the document has to be approved or rejected, or null when no deadline is set for it. It is a date, not a moment: the field carries no time and no zone, so it never depends on the reader’s clock. Past that date the tax authority accepts the document on its own, so a caller that is still deciding has to read this to know how long it has left.

400

The X-Software-Id header is missing — EARH-1008.

{
  "type": "https://earhiva.mk/errors/EARH-1008",
  "title": "X-Software-Id header is missing.",
  "status": 400,
  "code": "EARH-1008"
}

All fields in the body (6)

Field	Type	Presence	Description
type	string	always	Address of this code in the error catalogue (RFC 7807).
title	string	always	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. Absent when the title already says everything.
code	string	always	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 — it is the same reference we record in our log, so one number identifies the event on both sides.

401

The API key is missing, unknown, expired or revoked — EARH-1001, EARH-1002, EARH-1003. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.

403

The caller’s address is outside the allowed list, the key does not carry the IntegrationApi scope, the organization’s plan does not include integration access, or the key has been switched off by its owner — EARH-1004, EARH-1005, EARH-1010, EARH-1011. The last two are returned on every call and carry no Retry-After: waiting does not change the state. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.

404

EARH-3001 — no such document. An unknown identifier and a document belonging to another tenant give an identical answer.

{
  "type": "https://earhiva.mk/errors/EARH-3001",
  "title": "Document not found.",
  "status": 404,
  "code": "EARH-3001"
}

All fields in the body (6)

Field	Type	Presence	Description
type	string	always	Address of this code in the error catalogue (RFC 7807).
title	string	always	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. Absent when the title already says everything.
code	string	always	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 — it is the same reference we record in our log, so one number identifies the event on both sides.

429

The traffic limit for this key has been reached — EARH-1006. The response carries Retry-After. The limit is counted per key, and its size comes from the organization’s plan. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.

500

Unexpected error on our side — EARH-9000. The body carries eventId; quote it when reporting the problem. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.