Fill a series of received documents for a trial run

POST

/api/integration/v1/sandbox/seed

Fills your organisation with a series of inbound invoices, one per scenario.

The same seed always produces the same series — same amounts, same dates, same senders, same deadlines. That is the whole reason the number exists: without it a test that failed yesterday would pass today, because the data is different rather than because anything was fixed. Omit it and 1 is used, not a random one.

reset deletes what this endpoint created earlier and nothing else, so an automated run can start from the same state every time. A document placed through sandbox/inbound is left alone.

scenarios narrows the series; omit it for all of them. The response names the scenario of every document — read the list from there rather than hard-coding it, and your test stays correct when a scenario is added.

Some of these states cannot be created any other way: an expired deadline and a decision already confirmed come about with the passage of time or through an action that has already happened. They are the ones a caller usually meets first in production.

The example applies to the demo environment only.

Request

curl -i -X POST "https://sandbox.api.earhiva.mk/api/integration/v1/sandbox/seed" \
  -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 (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

Which series to create.

Type: 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

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

Responses

201

The series was created; the body lists every document with its scenario.

{
  "seed": 0,
  "created": 0,
  "deleted": 0,
  "documents": [
    {
      "scenario": "",
      "docUid": "",
      "euid": "",
      "expect": ""
    }
  ]
}

All fields in the body (4)

Field	Type	Presence	Description
seed	integer · int32	always	The series number that was used — the one you sent, or 1.
created	integer · int32	always	How many documents the call created.
deleted	integer · int32	always	How many previously seeded documents reset removed; 0 without it.
documents	array of object	always	One entry per scenario, in the order they were created.

400

EARH-2030 — a scenario name is not one of the allowed values; the response lists them.

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

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-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"
}

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.