Download a received document

GET

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

Downloads one representation of an inbound document.

original is always available — the file exactly as it arrived. ubl and pdf are served only if the document arrived in that shape; a representation is never produced on demand.

The example applies to the demo environment only.

Request

curl -i -X GET "https://sandbox.api.earhiva.mk/api/integration/v1/inbound/<docUid>/file" \
  -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 (3)

Parameter	In	Type	Presence	Description
`docUid`	`path`	string	`always`	Identifier of the document.
`format`	`query`	string	`optional`	One of `original`, `ubl`, `pdf`.
`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 · EARH-3002 · EARH-9003

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

Responses

200

The stored bytes of the requested representation.

string format: binary

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; EARH-3002 — the document exists but did not arrive in that shape. original keeps working in that case.

{
  "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.

409

EARH-9003 — the record says the content was stored, but it is not retrievable. Not the same as EARH-3002: that one means the shape never arrived, this one means it did and its content was lost. Repeating will not help until we fix it — everything else about the document still reads normally.

{
  "type": "https://earhiva.mk/errors/EARH-9003",
  "title": "The stored content of this document is not retrievable.",
  "status": 409,
  "code": "EARH-9003"
}

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.