Decide on a received document

POST

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

Accepts or rejects an inbound document.

Read decisionDeadline first: once that day has passed the tax authority accepts the document on its own, and a decision sent afterwards is refused. A rejection needs both a reason code from codelists/reject-reasons and a comment; an acceptance carries neither.

The decision is recorded before it is reported onward, so a successful answer does not yet mean the tax authority has confirmed it — confirmedByTaxAuthority says whether it has. This is not an acknowledgement: ack says you fetched the document, this says what you decided about it.

The example applies to the demo environment only.

Request

curl -i -X POST "https://sandbox.api.earhiva.mk/api/integration/v1/inbound/<docUid>/decision" \
  -H "X-Api-Key: <YOUR KEY>" \
  -H "X-Software-Id: <NAME AND VERSION OF YOUR APPLICATION>" \
  -H "Content-Type: application/json" \
  -d '{ }'

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 being decided on.
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.

Request Body

The decision.

Type: application/json.

null

Error codes

EARH-1001 · EARH-1002 · EARH-1003 · EARH-1004 · EARH-1005 · EARH-1006 · EARH-1010 · EARH-1011 · EARH-2022 · EARH-3001 · EARH-3006 · EARH-9002

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

Responses

200

The decision is recorded.

{
  "docUid": "eah_i_01M0ZZB88FT117S27PM8ZEK9RY",
  "accepted": true,
  "confirmedByTaxAuthority": false,
  "confirmedAt": null,
  "failureCode": null
}

All fields in the body (5)

Field	Type	Presence	Description
docUid	string	always	Identifier of the document the decision was made on.
accepted	boolean	always	The decision as it was recorded: true accepted, false rejected.
confirmedByTaxAuthority	boolean	always	Whether the tax authority has already confirmed the decision. The decision is recorded before it is reported onward, so false here does not mean it was lost: it means the reporting is still under way and the answer will appear on the document itself.
confirmedAt	string · date-time	nullable	When the tax authority confirmed it, or null while confirmedByTaxAuthority is false.
failureCode	string	nullable	Present only when the tax authority refused the decision — then it is EARH-4006 and the decision can be replaced with a corrected one. null in every other case.

400

EARH-2022 — the decision cannot be read as submitted: a rejection without a reason or without a comment, an acceptance carrying either, or a reason code that is not active.

{
  "type": "https://earhiva.mk/errors/EARH-2022",
  "title": "Decision cannot be read as submitted.",
  "status": 400,
  "code": "EARH-2022"
}

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, or nothing on that document to decide on. 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.

409

EARH-3006 — the state does not allow a decision: the deadline has passed, a decision is already confirmed, or one is being reported right now.

EARH-9002 — the decision cannot be handed on because of something on our side: the document has no EUID at the tax authority, the signer is not configured, or their address is not resolved. Nothing about the request is wrong, so repeating it will not help until we fix it — that is why it is 9xxx and not 3xxx.

{
  "type": "https://earhiva.mk/errors/EARH-3006",
  "title": "Current state does not allow a decision.",
  "status": 409,
  "code": "EARH-3006"
}

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.