Внесување примен документ за проба

POST

/api/integration/v1/sandbox/inbound

Places an inbound invoice into your organisation, as if it had arrived from the tax authority.

documentNumber is the only field you must supply; everything else has a sensible default.

Supply euid to make the call repeatable: sending the same one again returns the existing document with alreadyExisted: true instead of creating a second one. Omit it and a new document is created each time.

payload and pdfBase64 are independent. With neither, the document exists and is listed but carries no content — a real state worth testing, and the one you get from the tax authority when a privilege is missing.

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

Request

curl -i -X POST "https://sandbox.api.earhiva.mk/api/integration/v1/sandbox/inbound" \
  -H "X-Api-Key: <ВАШИОТ КЛУЧ>" \
  -H "X-Software-Id: <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА>" \
  -H "Content-Type: application/json" \
  -d '{ }'

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

Parameters

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

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.

Request Body

The invoice to place.

Тип: application/json.

null

Error codes

EARH-1001 · EARH-1002 · EARH-1003 · EARH-1004 · EARH-1005 · EARH-1006 · EARH-1009 · EARH-1010 · EARH-1011 · EARH-2030

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

Responses

201

The document was created; the body carries its docUid.

{
  "docUid": "",
  "euid": "",
  "alreadyExisted": false
}

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

Field	Type	Presence	Description
docUid	string	always	Identifier of the inbound document. Use it with GET inbound/{docUid}, GET inbound/{docUid}/file and POST inbound/{docUid}/decision.
euid	string	always	The tax authority identifier the document carries — the one you supplied, or the one generated for you.
alreadyExisted	boolean	always	true when a document with that euid was already there and nothing new was created. Not an error — it is what lets you re-run the same script.

400

EARH-2030 — the body is missing a required field, or pdfBase64 is not valid base64.

{
  "type": "https://earhiva.mk/errors/EARH-2030",
  "title": "The request body is not usable.",
  "status": 400,
  "code": "EARH-2030"
}

Сите полиња во телото (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. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.

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. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.

404

EARH-1009 — this endpoint does not exist outside the sandbox server.

{
  "type": "https://earhiva.mk/errors/EARH-1009",
  "title": "This endpoint does not exist in this version.",
  "status": 404,
  "code": "EARH-1009"
}

Сите полиња во телото (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. Телото е стандардното тело на грешка — исто кај сите повици. Што да се направи со секоја шифра стои во Каталог на грешки.

500

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