Skip to main content

Sandbox Onboarding — Overview

Per-country prerequisites, registration steps, and credential conventions for the sandbox environments behind .github/workflows/sandbox-nightly.yml (fi-sts).

What this is​

A practical guide to getting test credentials from each tax authority so the cluster's sandbox-integration tests can run end-to-end in CI. Read the country-specific page for each authority you need to onboard.

What if you're not in the country?​

Most cluster countries assume the developer or operator holds the local taxpayer registration. We don't, in many cases. The patterns below are how to make sandbox (and eventually production) work without that.

Cheapest pathways for foreign developers (in order):

  • HU, GR, FR, PT — software-vendor track is openly accessible. NAV, AADE, LNE/AFNOR, and AT all certify or onboard non-resident software vendors directly. No local entity required for sandbox; minimal local presence for production.
  • ES — Spanish consulate FNMT issuance is the back door for AEAT (Verifactu/SII) certs. TicketBAI's three foral haciendas are stricter; Bizkaia is the most foreign-friendly.
  • PL, SI, HR, RO, IT — fiscal representative is the standard path. Budget €100-600/month per country plus one-off setup. 2-6 weeks to first credentials.

Fiscal representative as a service. Several firms specialise in this — Avalara (multi-country), Marosa (ES/PT), KEN (HR), and the local Big-Four advisory practices all offer non-resident fiscalization onboarding. The internal team should keep a vetted shortlist; per-country pages flag where this is the recommended route.

Production vs sandbox split. For HU, GR, FR, and PT software certification, you can do all sandbox testing without local presence. Production deployment introduces VAT representative or branch obligations once real money flows through the platform's books. Other countries (PL, SI, HR, RO, IT) require a local hand for sandbox already.

Platform vs direct model. Most cluster regulators expect the merchant to hold the local taxpayer registration, not the software platform. Zyntem just needs developer/software-vendor access; the residency burden lives with the customer, who has already solved it. This is the operating assumption — it shifts most of the non-resident problem off our backs. Where the platform itself needs to issue invoices on its own books (corporate billing, subscription fees), that's where local VAT representation kicks in.

For per-country detail see each page's Non-resident path section: HU, GR, PL, SI, HR, RO, ES, IT, PT, FR.

Prerequisites across the board​

  • Tax/VAT registration in each country, OR a test taxpayer issued by the authority — see per-country page.
  • Some authorities require a digital certificate; some require only credentials. Costs and timelines vary widely.
  • A secure place to store credentials. We use GitHub organization-level Encrypted Secrets (Settings → Secrets and variables → Actions → Organization).
OrderCountryCostTimePage
1Hungary NAV€01-3 dayshungary-sandbox
2Greece myDATA€01-3 daysgreece-sandbox
3Poland KSeF (token mode)€01-3 dayspoland-sandbox
4Slovenia FURS€01-2 weeks (cert delivery)slovenia-sandbox
5Croatia Fiskalizacija€0 dev / ~€60/yr prod1-2 weekscroatia-sandbox
6Romania ANAF€50-200/yr eIDAS2-4 weeksromania-sandbox
7Spain (Verifactu / TicketBAI / SII)€01-3 weeksspain-sandbox
8Italy SDI€01-2 weeksitaly-sandbox
9Portugal ATCUD/SAF-T~€300-500 software cert4-8 weeksportugal-sandbox
10France NF525~€500-1.5K cert4-12 weeksfrance-nf525-sandbox

After provisioning​

Once you have credentials, set them at the org level using the env-var names listed in each country's page. The sandbox-nightly.yml workflow picks them up automatically.

Local testing while provisioning:

export HU_NAV_TAX_NUMBER=12345678
export HU_NAV_TECH_USER_LOGIN=...
# ... etc
cargo test -p hungary-nav -- --ignored sandbox

The #[ignore] gate on sandbox tests means missing env vars cause clean skips, not failures. Once secrets are set in CI, the nightly run un-skips them automatically.

Risks during provisioning​

  • FNMT / FINA / eIDAS cert procurement typically requires a Spanish / Croatian / Romanian-resident person to do an in-person identity verification. If your team has no one local, expect 4-6 weeks instead of 1-2.
  • Sandbox availability varies wildly: HU/GR/PL are reliable; ES/IT preprod environments occasionally have multi-day outages around tax-season pushes; HR sandbox sometimes drops on weekends.
  • Test taxpayer numbers have lifecycle — some authorities (especially RO, PL) periodically purge unused test accounts. Plan for credential refresh quarterly.