efakt sandbox – dokumentácia pre vývojárov

SANDBOX – nespracúvajte skutočné údaje. Nič sa neodosiela skutočnému poštárovi ani finančnej správe.

Rýchly štart

Zaregistrujte sa na portáli sandboxu (e-mail, názov firmy, súhlas, overenie robotom). Príde potvrdzovací e-mail; po kliknutí na odkaz vznikne váš izolovaný sandbox.
Zobrazí sa jednorazovo: heslo do webu, API kľúč (X-API-Key) a ERP token (Authorization: Bearer erp_…), obidva „iba test“ (test_only).

Test odoslania faktúry (nič sa neodošle):

curl -X POST "https://<sandbox>/api/v1/invoices?test=true" -H "X-API-Key: $EFAKT_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/xml" --data-binary @invoice.xml

UBL 2.1 Peppol BIS 3.0, dátum vystavenia = dnes (Europe/Bratislava), predávajúci = DIČ vášho sandbox tenanta.

Ostré odoslanie do simulovaného poštára: vo webe vytvorte nový API kľúč bez príznaku „iba test“; stav queued → sent → delivered.
Simulácia výsledku: ?test=true&simulate=delivered|undeliverable|rejected|provider_error|timeout|late_issue, výsledok GET /api/v1/test-runs/{id} (24 h).

Magické hodnoty v dokladoch

Hodnota	Výsledok
DIČ príjemcu končí `0000`	nedoručiteľné (`RECIPIENT_NOT_REGISTERED`)
suma na úhradu `666,66`	odmietnuté poskytovateľom
suma na úhradu `777,77`	neskoré doručenie (zostane `sent`)
číslo faktúry končí `-TIMEOUT`	poštár neodpovie
číslo faktúry končí `-HTTP503` / `-HTTP429` / `-HTTP409`	prvý pokus zlyhá týmto kódom, opakovanie prejde

Limity a pravidlá

Denná kvóta odoslaní (vrátane testov), najväčší dokument, počet API kľúčov a ERP integrácií – zobrazuje GET /api/v1/sandbox/usage a stránka Môj sandbox. Pri prekročení 429 SANDBOX_QUOTA_EXCEEDED.
Sandbox bez aktivity vyprší (skryje sa a zablokuje, údaje sa nemažú); obnoví ho nová registrácia s rovnakým e-mailom.
Zákaz skutočných údajov, záťažových testov a skenovania. Bez záruky dostupnosti. Zbierame iba e-mail a názov firmy, technické logy bez obsahu faktúr a IP v logu proxy.

Na stiahnutie

efakt sandbox – dokumentace pro vývojáře

SANDBOX – nezpracovávejte skutečné údaje. Nic se neodesílá skutečnému poštáři ani finanční správě.

Rychlý start

Zaregistrujte se na portálu sandboxu (e-mail, název firmy, souhlas, ověření proti robotům). Přijde potvrzovací e-mail; po kliknutí na odkaz vznikne váš izolovaný sandbox.
Zobrazí se jednorázově: heslo do webu, API klíč (X-API-Key) a ERP token (Authorization: Bearer erp_…), oba „jen test“ (test_only).

Test odeslání faktury (nic se neodešle):

curl -X POST "https://<sandbox>/api/v1/invoices?test=true" -H "X-API-Key: $EFAKT_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/xml" --data-binary @invoice.xml

UBL 2.1 Peppol BIS 3.0, datum vystavení = dnes (Europe/Bratislava), prodávající = DIČ vašeho sandbox tenanta.

Ostré odeslání do simulovaného poštáře: ve webu vytvořte nový API klíč bez příznaku „jen test“; stav queued → sent → delivered.
Simulace výsledku: ?test=true&simulate=delivered|undeliverable|rejected|provider_error|timeout|late_issue, výsledek GET /api/v1/test-runs/{id} (24 h).

Magické hodnoty v dokladech

Hodnota	Výsledek
DIČ příjemce končí `0000`	nedoručitelné (`RECIPIENT_NOT_REGISTERED`)
částka k úhradě `666,66`	odmítnuto poskytovatelem
částka k úhradě `777,77`	pozdní doručení (zůstane `sent`)
číslo faktury končí `-TIMEOUT`	poštář neodpoví
číslo faktury končí `-HTTP503` / `-HTTP429` / `-HTTP409`	první pokus selže tímto kódem, opakování projde

Limity a pravidla

Denní kvóta odeslání (včetně testů), největší dokument, počet API klíčů a ERP integrací – ukazuje GET /api/v1/sandbox/usage a stránka Můj sandbox. Při překročení 429 SANDBOX_QUOTA_EXCEEDED.
Sandbox bez aktivity vyprší (skryje se a zablokuje, data se nemažou); obnoví ho nová registrace se stejným e-mailem.
Zákaz skutečných údajů, zátěžových testů a skenování. Bez záruky dostupnosti. Sbíráme jen e-mail a název firmy, technické logy bez obsahu faktur a IP v logu proxy.

Ke stažení

efakt sandbox – developer documentation

SANDBOX – do not process real data. Nothing is sent to a real postman or to the tax authority.

Quick start

Register on the sandbox portal (e-mail, company name, consent, anti-bot check). A confirmation e-mail arrives; clicking its link creates your isolated sandbox.
Shown once: the web password, the API key (X-API-Key) and the ERP token (Authorization: Bearer erp_…), both "test only" (test_only).

Test submission of an invoice (nothing is sent):

curl -X POST "https://<sandbox>/api/v1/invoices?test=true" -H "X-API-Key: $EFAKT_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/xml" --data-binary @invoice.xml

UBL 2.1 Peppol BIS 3.0, issue date = today (Europe/Bratislava), seller = the tax ID of your sandbox tenant.

Live send to the simulated postman: create a new API key without the "test only" flag in the web UI; status queued → sent → delivered.
Outcome simulation: ?test=true&simulate=delivered|undeliverable|rejected|provider_error|timeout|late_issue, result GET /api/v1/test-runs/{id} (24 h).

Magic values in documents

Value	Result
Recipient tax ID ends in `0000`	undeliverable (`RECIPIENT_NOT_REGISTERED`)
payable amount `666.66`	rejected by the provider
payable amount `777.77`	late delivery (stays `sent`)
invoice number ends in `-TIMEOUT`	the postman does not answer
invoice number ends in `-HTTP503` / `-HTTP429` / `-HTTP409`	the first attempt fails with that code, a retry succeeds

Limits and rules

Daily submission quota (tests included), maximum document size, number of API keys and ERP integrations – see GET /api/v1/sandbox/usage and the My sandbox page. Exceeding it returns 429 SANDBOX_QUOTA_EXCEEDED.
A sandbox without activity expires (hidden and blocked, data is never deleted); a new registration with the same e-mail restores it.
No real data, no load tests or scanning. No availability guarantee. We collect only your e-mail and company name, technical logs without invoice content and the IP in the proxy log.