e-Faktura API

Postman collection

The collection has one request for every operation in the public API, a ready-made Merot sandbox environment, and a Get started folder that walks the Full setup guide top to bottom. It is generated from the public OpenAPI description, so it always matches the API reference: download it again after a release and re-import.

Download the collection Download the sandbox environment

Import and set up

1. In Postman, choose Import and drop in both files, or use Import from a link with the URLs below.
2. Select the Merot sandbox environment in the top-right environment picker. Postman stores the ids the collection saves for you (see below) in the selected environment, so pick it before sending anything.
3. Open the environment and paste your sandbox key into apiKey. It starts with mfk_test_; you get one when you sign up for a Developer account. The value is marked secret, so Postman keeps it out of exports and shared views by default.
4. Leave companyId empty. Create a company and List companies fill it in for you. If your key reaches several companies, set it yourself to the company you want to act on.

The file URLs:

https://developer.merot.com/postman/merot-efaktura-api.postman_collection.json
https://developer.merot.com/postman/merot-sandbox.postman_environment.json

The environment has no production variant on purpose: production keys are not available yet. baseUrl is https://api.efaktura.merot.com, the same host for sandbox and production. The key decides which environment you reach.

What is in the collection

• Get started: create a company, create a signer, link the signer to the company, find the certificate Merot Bridge bound, activate it, issue a test invoice, get its status, list the inbox. Each step stores the id it returns (companyId, signerId, certificateId, einvoiceId) so the next one needs no copy and paste. Steps 4 to 6 need Merot Bridge installed and paired, exactly as in the guide, and step 6 waits for you to accept the signing confirmation in Bridge.
• Vendors: get an OAuth access token (last request of Get started): the client-credentials grant for software vendors. Put clientId and clientSecret in the environment and send it; the token is stored as accessToken and used automatically as the bearer while apiKey is empty. Tokens last 15 minutes, so send the request again when one expires.
• One folder per resource: OAuth, Companies, Signers and certificates, E-invoices, Inbox, Webhooks and events, Archive, Sandbox, Bridge and signing, and Usage and health. Optional query parameters are listed but switched off; tick the ones you want.

Every request sends Authorization: Bearer {{apiKey}} (set once on the collection) and Merot-Version: {{merotVersion}}. Requests that act on one company also send X-Company-Id: {{companyId}}; the header is left out while companyId is empty. Money in the example bodies is a decimal string such as "10000.00", never a JSON number.

Idempotency-Key

Every write except POST /v1/oauth/token needs an Idempotency-Key. The collection does it for you: a pre-request script puts a fresh UUID v4 in the header before each write. You never type one.

Retries are handled the way the API expects. If a write ends in a network error, a timeout, 429 or a 5xx, and you send the same request with the same body again, the collection reuses the key, so the server treats it as a replay of the first attempt. If you change the body, or the previous attempt got a final answer (any status below 500 except 429), the next send gets a new key.

Regenerating

The collection and environment are generated from the public OpenAPI description by a script in this site’s repository, not written by hand. To rebuild them after the API changes:

npm run postman:sync    # copy the latest spec from merot-erp
npm run postman:build   # rewrite public/postman/*.json

A test fails the site build if the committed files drift from the OpenAPI snapshot, the folder layout no longer covers every operation, or a secret sneaks in.