Skip to main content

Portugal — ATCUD / SAF-T PT Sandbox Onboarding

Operational guide for getting test credentials at the Portuguese Autoridade Tributária e Aduaneira (AT) test environment.

PropertyValue
AuthorityAT (Autoridade Tributária e Aduaneira)
Sandbox basePortal das Finanças test environment (portaldasfinancas.gov.pt — test mode)
CostSoftware certification one-time ~€300-500; per-merchant taxpayer registration is free
Time to provision4-8 weeks for software certification (one-time per major version)
Identity requiredPortuguese NIF + AT-certified billing software

Steps​

  1. Submit your software for AT certification via the portal.
  2. AT issues a software certification number — this is tied to your codebase, not per-merchant. One number covers all your test taxpayers.
  3. For each test merchant, register their NIF and document series with AT to receive ATCUD validation codes (one per series).
  4. Validate with a small SAF-T PT batch upload.

GitHub secrets to set​

PT_AT_NIF
PT_AT_SOFTWARE_CERT_NUMBER
PT_AT_TEST_SERIES_VALIDATION_CODE

Gotchas​

  • ATCUD is local-computed — no per-receipt round-trip with AT. The sandbox-nightly job for PT mostly tests SAF-T monthly batch upload, not per-receipt submission.
  • Software certification is the long pole. Has to be re-done when major version of the codebase changes (cryptographic-relevant code in particular).
  • "Sandbox" for AT is more about test-NIF accounts than a separate URL. Same Portal das Finanças, with --ambiente=teste flag or test-specific endpoint paths.
  • ATCUD format is <validation-code>-<sequence> — validation code from AT, sequence is local. Both must be on every receipt.
  • Position rules for ATCUD print are specific in the regulation — must be in a "visible" area, font size minimums apply.

Non-resident path​

Software certification by AT does not require Portuguese residency — AT certifies international software vendors directly. This is one of the friendliest regimes in the cluster for foreign platforms.

  • Per-platform: software certification. Apply for AT software certification as a foreign vendor. ~€300-500 + 4-8 weeks audit. No NIF required for the certification step itself.
  • Per-merchant: each merchant uses their own Portuguese NIF plus their AT-issued ATCUD validation codes. The platform doesn't need a NIF on the certification side; it just integrates against each merchant's own AT profile.
  • Cheapest dev path: apply directly for AT software certification. For per-merchant test NIF, a Portuguese accountant can provide one; merchants in production register their own.
  • Production. No platform-side residency requirement. Merchants register themselves; the certified software identifier is what AT cares about for the platform.
  • Adapter crate: rust/adapters/portugal/
  • Sandbox tests: rust/adapters/portugal/tests/sandbox.rs