One invoice with your own content

When you need this endpoint

POST sandbox/inbound places one inbound document into your organisation, with content you supply.

The typical case: a customer reports that an invoice from one particular supplier breaks the parsing in your software. You take that file, send it here, and work against the real content — not against something we invented.

The document is registered down the same path a real one from the tax authority takes: same registration, same numbering, same identifiers. That is why everything you read afterwards behaves as it will in production.

This endpoint or the series by scenario

The two sandbox endpoints answer different questions. Neither replaces the other.

	This page `POST sandbox/inbound`	A series by scenario `POST sandbox/seed`
The question	“here is this document, put it in”	“give me every state”
Content is supplied by	you, field by field	us, from a catalogue
How many documents it creates	one	a whole series
States such as an expired deadline or a decision already made	⛔ cannot create them	✅ ready-made

⛔ The document this endpoint creates is always in its INITIAL state. The decision deadline is in the future and no decision has been made on it — because those states come about through the passage of time or through an action that has already happened, not through a field in the request.

If you need a document in one of them, that is the series by scenario.

The shortest request

Only documentNumber is required. Everything else has a sensible default.

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

{
  "docUid": "eah_i_01M1BVN00S4GDT718V8SA9A7QR",  // the identifier on our side
  "euid": "SBX-7F3A4B2C9D1E5A8B0C3D",            // generated, because we sent none
  "alreadyExisted": false
}

That document exists and appears in the list, but has no content: GET inbound/{docUid}/file returns 404 with EARH-3002.

⚠️ That is not an unfinished entry. It is how a document looks when the privilege to fetch its content is missing at the tax authority — a real state, worth trying.

With your own content

payload and pdfBase64 are independent of each other. You may send one, both, or neither.

curl -X POST https://sandbox.api.earhiva.mk/api/integration/v1/sandbox/inbound \
  -H "X-Api-Key: <YOUR KEY>" \
  -H "X-Software-Id: <NAME AND VERSION OF YOUR APPLICATION>" \
  -H "Content-Type: application/json" \
  -d '{
        "euid": "MY-TEST-001",
        "documentNumber": "2026-000412",
        "docDate": "2026-09-01",
        "sellerName": "Supplier Ltd",
        "sellerTin": "MK4030995155258",
        "docNetAmount": 10000.00,
        "docVatAmount": 1800.00,
        "docGrossAmount": 11800.00,
        "payload": "{ …UJP JSON… }",
        "pdfBase64": "JVBERi0xLjQK…"
      }'

📌 Which part of the content is then downloaded with which format is described under Inbound documents → Downloading the content.

The fields of the request

Field	Required	What it means	If you omit it
`documentNumber`	✅ yes	the invoice number, as the issuer issued it	the request is refused
`euid`	no	the identifier the tax authority gives the document	one is generated, prefixed `SBX-`
`docDate`	no	date of issue	today’s date
`docDeliveryDate`	no	date of supply	the same as `docDate`
`sellerName`	no	name of the company that issued the invoice	left empty
`sellerTin`	no	tax number of that company	left empty
`docNetAmount`	no	amount excluding VAT	`0`
`docVatAmount`	no	VAT amount	`0`
`docGrossAmount`	no	total amount	`0`
`payload`	no	the machine-readable content, as UJP JSON	the document has no such content
`pdfBase64`	no	the PDF, encoded as base64	the document has no PDF

How to make the call repeatable

If you send your own euid, the same value twice does not create a second document. The second call returns the existing one:

{ "docUid": "eah_i_…", "euid": "MY-TEST-001", "alreadyExisted": true }

The response is still 201, not 409 — the alreadyExisted field carries the difference, so you do not have to branch on the HTTP status. It is the same choice as a repeated idempotency key when submitting a document.

Errors this endpoint returns

Code	When it appears
`EARH-2030` · `400`	`documentNumber` is missing, or `pdfBase64` is not valid base64
`EARH-1008` · `400`	the `X-Software-Id` header is missing
`EARH-1009` · `404`	the endpoint was called on a server that is not the sandbox

What this endpoint does NOT do


It creates inbound invoices only	the outbound direction is tried with a real `POST outbound`
It works only in your organisation	no call sees into or changes anyone else’s
Nothing leaves for the tax authority	neither on creation nor when you send a decision
The document is in its initial state	an expired deadline or a decision already made cannot be set — the series by scenario is for those
It has no clearing	documents are deleted only through `reset` on the series, and that one leaves yours alone

A series by scenario — a catalogue of states, instead of one document
Inbound documents — the statuses, the deadlines and downloading content
Error catalogue — every code the API can return