Step-by-Step Integration

⚠️Preview — playground only

SIGN CZ (Unified API) is currently available in the test environment only and transmits to the tax authority’s playground. All confirmations carry test="true" and have no legal standing. Production is not yet activated: real onboarding opens on 2026-11-01, the legal obligation starts on 2027-01-01. See Onboarding & Credentials.

SIGN CZ follows the standard Unified API resource flow: taxpayer → location → system → record. Steps 1–7 are identical to every other Unified API product; steps 8–11 walk through the CZ-specific parts.

1. Register on HUB

   Begin by registering on the fiskaly HUB. For more guidance on getting started, head to our HUB - First steps section.

2. Create Account & Organization GROUP

   Creating a fiskaly Account is the first step, after which you can proceed with setting up the first organizational structure for your business and generating your API Key.

   The Account represents the PoS provider or a retailer that operates its own PoS system. It is the top-level organization in the structure.

   After creating your fiskaly Account, you will be taken to the Organization Selector where you can create your Group.

   A Group is an intermediate level within an Account that helps you organize multiple Units into logical clusters.

3. Create API Key

   The next step is to generate an API Key for your organization via the HUB. This API Key and Secret pair is required to create your first Organization of type UNIT (Step 5).

   💡TEST vs. LIVE environments

   API Keys generated in the TEST environment (https://test.api.fiskaly.com) will create TEST resources, while those from the LIVE environment (https://live.api.fiskaly.com) will create LIVE resources. SIGN CZ currently accepts CZ operations in the TEST environment only.

1. Create Token

   Starting from this step, you will be using the SIGN CZ (Unified API).

   Call the createToken endpoint with the API Key and Secret from step 3 to obtain a bearer token. Include this token in the Authorization header of steps 5 and 6.

2. Create Organization UNIT

   Create an Organization of type UNIT via the createOrganization endpoint. A UNIT represents a single legal entity (merchant). You will need to create one Organization UNIT for each taxpayer representation you manage.

   Using the bearer token generated in Step 4 with the API Key and Secret created for your Group ensures the UNIT is correctly nested under that Group in the hierarchy.

3. Create Subject (API Key)

   Create a Subject of type API_KEY for the Organization UNIT via the createSubject endpoint.

   To associate the Subject (API Key) with your UNIT, include the X-Scope-Identifier header set to the id of the Organization UNIT in your request.

4. Create new Token

   Create a token using the Subject API Key and Secret you just generated. This bearer token will be used for all subsequent steps to create resources within the corresponding Organization UNIT.

1. Create Taxpayer

   Now you’re ready to create the operational parts required for sales registration in Czechia.

   Use the createTaxpayer endpoint and add a fiscalization of type CZ. The only CZ property is tax_id_number — the taxpayer’s DIČ:

   {
     "fiscalization": {
       "type": "CZ",
       "tax_id_number": "699001238"
     }
   }

   • Set the taxpayer as type Company (legal entity) or Individual (natural person); both accept the CZ fiscalization.
   • Pattern: ^[0-9]{8,10}$ (8–10 digits, no CZ prefix). The DIČ is the general Czech tax identification number, not the VAT number — a non-VAT-registered sole trader has one too. It becomes the EET eic_popl. There is no separate EET registration.
   • A record on an entity with no CZ fiscalization configured is rejected with 4xx.

   ⚠️Playground identity

   On the playground, the DIČ must be exactly 699001238 — the module signs with the shared playground certificate, and any other identity is rejected before the wire.

   Once you create a Taxpayer, its state is set to ACQUIRED by default. To make it fully functional, update the state to COMMISSIONED using the updateTaxpayer endpoint.

2. Create Location — one per business unit

   Every declared business unit (evidenční jednotka — a premises, or per § 4 of the Act a website or app) is one Location. Its label carries the EET id_jednotky:

   • The id_jednotky is allocated by the authority through DIS+ when the unit is declared. It cannot be chosen — store the number the GFŘ assigned.
   • Valid values are integers 1…999999999.
   • The LocationLabel schema requires exactly 14 digits. A CZ id_jednotky has at most 9 digits, so it must be zero-padded to 14 digits (e.g. id_jednotky 181 → label "00000000000181").
   • The label is required and validated at commissioning — a missing or malformed value is a clear 4xx on the commissioning PATCH, not a surprise at sale time.

   📘Note

   A HEAD_OFFICE location is automatically created upon Taxpayer creation and shares the same UUID as the Taxpayer. For sales registration, create a separate Location of type BRANCH per declared business unit (it may have the same address). One physical device may serve several units by switching; the unit belongs to the sale. Model the unit as the Location and the till as the System.

   For each business unit, create a Location of type BRANCH via the createLocation endpoint, then update its state to COMMISSIONED with the updateLocation endpoint — setting the label — before proceeding.

3. Create System — one per till

   Each register or till is one System of type FISCAL_DEVICE, created via the createSystem endpoint and connected to a previously created BRANCH Location. Its label carries the EET id_pokl:

   • Chosen by the integrator: 1–16 characters of [0-9a-zA-Z.,:;/#\-_ ] (e.g. "REG-1").
   • Required for CZ and validated at commissioning (4xx otherwise), re-validated at sale time.

   Once a System is created, its state is set to ACQUIRED by default. To create Records, update its state to COMMISSIONED using the updateSystem endpoint.

   📘Billing note

   For most contracts, Systems are the units used for billing with fiskaly. A System becomes relevant for billing once you change its state from ACQUIRED to COMMISSIONED in the LIVE environment. Resources in the TEST environment are not billed. For the exact billing conditions, please refer to your contract with fiskaly.

4. Create Record — report a sale

   For each sale, the createRecord endpoint is called twice in sequence: first an INTENTION, then the TRANSACTION.

   Part A) Intention

   A Record of type INTENTION (OPENING / TRANSACTION / CLOSING as usual) associates the System with the upcoming operation. For CZ these only signal the transaction lifecycle — EET 2.0 has no register-open/close message.

   Part B) Transaction

   A Record of type TRANSACTION with a RECEIPT operation carries the sale. One record = one EET message. fiskaly maps the CZ-relevant fields as follows:

   EET field	API source	Notes
   eic_popl	taxpayer tax_id_number
   id_jednotky	Location.label	zero-padded, see step 9
   id_pokl	System.label
   porad_cis	document.number	receipt sequence number
   dat_trzby	document.issued_at (else send time)	issued_at is optional in the Unified API but meaningful here — supply it
   celk_trzba	sum of the receipt’s contact-reportable payments, gross	see Payment Channels

   Rules enforced at validation:

   • Currency must be CZK. Any other currency is rejected. currency on PaymentDetails is optional and defaults to EUR — an integrator who omits it is therefore rejected. Always send "currency": "CZK" explicitly.
   • Amounts need exactly two decimal places; the module rejects rather than rounds. celk_trzba is the amount actually received — cash rounded to whole crowns is sent as whole crowns; a card payment settled to the heller is sent with both decimals. Zero and negative amounts are legitimate.
   • Payments may carry an optional channel (CONTACT / REMOTE, default CONTACT) — see Payment Channels for when to set REMOTE.

   Reading the confirmation

   On success, the authority’s confirmation code is written to the record’s compliance.data as EET,<POK>. Authority warnings, if any, are appended to the record’s content.logs as WARNING entries, one per warning code. Before the POK is returned, fiskaly verifies the authority’s WS-Security signature on the response; the full signed exchange is persisted as record transmission evidence — the proof of recording.

   If the send fails, the record lands in FAILED (resend required) or REJECTED (client defect) — see the Process Overview for the exact classification and Outages & the 48-Hour Rule for the resend obligations.

   📘Note

   All Records created in the LIVE environment represent tax-relevant documents and must always reflect actual transactions. Use the designated TEST environment for integration testing.

Playground quick check

1. Taxpayer with tax_id_number: "699001238"
2. Location with label "00000000000181", System with label "REG-1"
3. RECEIPT with a CZK cash payment, two decimals
4. Expect compliance.data = EET,<POK>

This path is suitable for exploring the resource model and the response shape. It is not a customer onboarding path — see Onboarding & Credentials.