ZenotiHelp

Configure Fiskaly for Spain e-invoicing

ZTZenoti Docs Team Updated October 16, 2026 11 min readHow-to

The Fiskaly integration submits Zenoti invoices to the Spanish tax authority through Fiskaly, a cloud-hosted compliance provider. Once configured, every invoice closed at an enabled Spanish center is digitally signed and submitted for compliance — no per-invoice action is required from front-desk staff.

Region served: Spain only. This article covers the Spain deployment of Fiskaly (TicketBAI / VeriFactu). Fiskaly also offers Germany and Austria deployments (based on their Technical Security System, or TSS); those are not in scope for this article and use a different configuration flow.

Deployment model: Fiskaly is a cloud service. There is no on-premise component — Zenoti calls Fiskaly's REST API over the public internet, and Fiskaly in turn communicates with the Spanish tax authority.

Availability: This integration renders only when the Spain e-invoicing feature is enabled for your organization. Contact Zenoti Support to request enablement. The Spain E - Invoicing (Fiskaly) accordion is visible only to organizations registered in Spain.


On this page


Before you begin

Permission: You need organization administrator access to configure regional compliance integrations.

  • Your Spanish centers must have accurate address, NIF/CIF, and tax region (territory) values before you enable fiscal submission. Corrections after go-live require void-and-reissue.
  • Zenoti does not obtain Fiskaly credentials on your behalf. Complete the external-system prerequisites below first.
  • Fiskaly configuration is per center. You must enable and configure each Spanish center separately.

External-system prerequisites

These prerequisites are handled outside Zenoti before you begin configuration in the Zenoti admin UI.

1. Register your business for Spanish e-invoicing

  • Your business must be registered with the Spanish tax authority (Agencia Tributaria) and have a valid NIF (Número de Identificación Fiscal) or CIF for companies.
  • Depending on your region, you must be enrolled in the applicable Spanish e-invoicing scheme (TicketBAI in the Basque Country, VeriFactu nationally, or the relevant regional variant). Confirm your scheme with your tax advisor — Zenoti cannot determine this for you. Consult the Agencia Tributaria's official documentation for the current enrolment steps.

2. Obtain a Fiskaly account and credentials

  • Sign a Fiskaly contract for Spain. Fiskaly then provisions a Fiskaly organization for your business and issues API credentials (API key and API secret).
  • Record the API endpoint (host URL) Fiskaly gives you — sandbox and production URLs differ.

3. Plan certificate / signer management

  • Fiskaly issues and rotates the digital signing certificates used to sign each invoice. You do not need to upload your own certificate. However, certificates expire: note the expiry date Fiskaly provides and plan for rotation before expiry.

If any of the above are incomplete, the first invoice submission fails. Complete enrolment and obtain credentials before continuing.


Network requirements

Fiskaly is a cloud service. Zenoti, Fiskaly, and the Spanish tax authority all communicate over the public internet.

Direction Port Protocol Endpoint to allowlist
Outbound: Zenoti → Fiskaly 443 HTTPS The host URL provided by Fiskaly (sandbox or production).

Because submission happens server-to-server between Zenoti and Fiskaly, you do not need to open firewall rules on your own network — front-desk devices do not talk to Fiskaly directly. If Zenoti cannot reach Fiskaly (for example during a Fiskaly incident), invoices queue for retry; see Failure paths.


Spain invoice classification

Zenoti classifies each invoice as Complete or Simplified based on the invoice total and buyer information captured on the invoice.

Classification Triggered when Buyer NIF required?
Simplified invoice Invoice total is 3,000 EUR or less and no buyer tax data is collected. Optional.
Complete invoice Invoice total exceeds 3,000 EUR, OR the buyer explicitly requests a complete invoice regardless of amount. Yes — the buyer's NIF is mandatory before the invoice can close.

The 3,000 EUR threshold is the Spain-wide default. If your scheme or region uses a different threshold, confirm with your tax advisor and adjust the threshold in Configure invoice settings.

Train staff to ask for the buyer's NIF on any transaction that might approach or exceed the threshold, and on any transaction where the buyer needs the invoice for business tax purposes.


Configure Fiskaly credentials

Note: For conceptual background on how the Fiskaly integration works, see How it works.

Steps

  1. Select the center in the scope selector, navigate to Configuration > Integrations > Integration Settings, and expand Spain E - Invoicing (Fiskaly).

  2. Enter the following values.

    Field Source What to enter
    Org Legal Name Your own business records — must match the name registered with the Agencia Tributaria. Legal name as it appears on your tax registration.
    Territory Your own business setup. One of: Araba/Álava (Basque Country), Bizkaia/Biscay (Basque Country), Gipuzkoa (Basque Country), Nafarroa/Navarre, Canary Islands, Ceuta, Melilla, or Other Territories of Spain. Consult your tax advisor if unsure.
    API Key Fiskaly account (provided by Fiskaly when your contract is signed). The API key issued by Fiskaly.
    API Secret Fiskaly account. The secret paired with the API key. Zenoti stores the secret encrypted at rest.
    Host URL Fiskaly account. The REST endpoint Fiskaly provided (sandbox for testing, production for live).
    Organization ID (Fiskaly) Fiskaly account. The identifier of your organization in Fiskaly.
    Signer ID Generated from this page — see note below. Select Generate beside this field after saving all credential fields above.
    Client ID Generated from this page — see note below. Select Generate beside this field after the Signer ID is generated.

    Note on generation order: Zenoti requires the credentials first. If you attempt to generate before entering API Key, API Secret, Host URL, and Organization ID (Fiskaly), Zenoti displays a prompt asking you to fill those fields first. The Signer ID must be generated before the Client ID — attempting to generate the Client ID first prompts you to generate the Signer ID first. When both are generated successfully, Zenoti confirms with a success message. If generation fails, verify your credentials and try again.

  3. Select Save. Every field is required. Zenoti saves the credentials and enables Fiskaly e-invoicing for the organization.

Worked example

A spa group called "Iberian Wellness S.L." is setting up the integration for their Bilbao center. They enter:

  • Org Legal Name: Iberian Wellness S.L.
  • Territory: Bizkaia/Biscay (Basque Country) — because the center is in Bilbao and the business is enrolled in TicketBAI
  • API Key and API Secret: provided by Fiskaly on contract signing
  • Host URL: the production endpoint Fiskaly issued
  • Organization ID (Fiskaly): the organization identifier in Fiskaly's portal

They then generate Signer ID and Client ID in order, select Save, and proceed to enable the integration at center level.


Configure invoice settings

Steps

  1. In the same Spain E - Invoicing (Fiskaly) accordion, review the invoice classification threshold.

    Setting Default Notes
    Simplified invoice threshold (EUR) 3,000 EUR Invoices at or below this amount are submitted as Simplified unless the buyer requests a Complete invoice.
    Require buyer NIF for Complete invoices On Required by Spanish law. Do not disable without guidance from your tax advisor.
  2. If your applicable scheme uses a threshold other than 3,000 EUR, enter the correct amount and select Save.


Enable per center

Fiskaly configuration is per center. Enable it only on Spanish centers.

Steps

  1. For each Spanish center, select the center in the scope selector and expand Spain E - Invoicing (Fiskaly) on Configuration > Integrations > Integration Settings.
  2. Turn on Fiskaly e-invoicing for the center.
  3. Verify the center's NIF, legal name, address, and territory match the Agencia Tributaria records. Mismatches cause rejections at submission time.
  4. Select Save.

Important: Repeat steps 1–4 for every Spanish center in your organization. Centers that are not individually enabled will not submit invoices to Fiskaly, which creates a compliance gap.


How it works

  1. A service is completed and an invoice is created in Zenoti.
  2. When staff close the invoice, Zenoti checks whether the invoice qualifies as Simplified or Complete using the configured threshold and the buyer information captured.
  3. If a Complete invoice is required and the buyer's NIF is missing, Zenoti blocks closure and prompts for the NIF.
  4. Zenoti extracts invoice data (line items, taxes, totals, buyer information) and formats it for submission to Fiskaly's API.
  5. Fiskaly signs the invoice using the digital signing certificate associated with the configured Signer ID and Client ID, then routes the signed document to the Spanish tax authority.
  6. Fiskaly returns a compliance response containing the signature, QR code, and a compliance reference. Zenoti stores these with the invoice and displays the QR code on the guest receipt.

Authentication between Zenoti and Fiskaly uses your API Key and API Secret to obtain a bearer token. Zenoti caches the token and renews it automatically before expiry — no manual token management is required.


Failure paths

When a submission fails, Zenoti keeps the invoice in a retriable state and surfaces the error to staff. Do not manually recreate the invoice — retry from the failure state.

Failure mode User-visible symptom Resolution
Fiskaly unreachable (network, incident, or host URL wrong). Submission error with a network timeout or connection failure. Confirm outbound HTTPS to the Fiskaly host URL is reachable. If Fiskaly is down, retry when their status page reports recovery. The invoice remains unsigned in the meantime.
Authentication failed (invalid or rotated API key/secret). 401 / unauthorized error. Re-enter the API Key and API Secret. If Fiskaly rotated credentials, request the new pair and update Zenoti.
Signer expired. Signing error on first invoice after expiry. Zenoti attempts to regenerate the signer automatically. If regeneration fails, open a Fiskaly support ticket — this usually indicates a contract or provisioning issue.
Buyer NIF missing (Complete invoice). Closure is blocked with a prompt for the NIF. Ask the guest for their NIF and enter it on the invoice, or confirm with the guest that a Simplified invoice is acceptable (only if under the threshold).
Invalid NIF format. Fiskaly rejects the invoice with a validation error naming the field. Verify the NIF with the guest. For non-Spanish EU buyers, Zenoti formats the tax number using the country prefix — confirm the country on the guest profile.
Duplicate submission (same invoice submitted twice). Fiskaly returns an error referencing the existing invoice. Check whether the original submission succeeded (see Reconciliation). If the first attempt succeeded, do not resubmit — the duplicate error confirms the fiscal record exists.
Schema version mismatch (Fiskaly updated its API). Validation errors on fields Zenoti has been sending successfully. Contact Zenoti Support — this typically requires a Zenoti-side update.

For operational visibility, review the regional compliance log daily.


Edit or cancel a submitted invoice

Once Fiskaly and the Spanish tax authority have accepted an invoice, the fiscal record is immutable. The Spanish e-invoicing scheme does not permit editing a signed, submitted invoice.

Invoice state What you can do
Open in Zenoti, not yet submitted Edit freely. The invoice has not been signed or reported.
Closed in Zenoti, successfully submitted to Fiskaly Cannot be edited. To correct, issue a credit note (factura rectificativa) that reverses the original, then issue a new invoice with the correct details. See Refunds and credit notes.
Closed in Zenoti, submission failed Fix the cause of the failure (missing NIF, network, credentials) and retry submission. No reversal is required because no fiscal record was created.

Refunds and credit notes

A refund in Zenoti produces a corresponding fiscal document on the Spanish side.

Zenoti action Fiskaly / Spanish tax authority side Reconciliation note
Full refund of a submitted invoice. A credit note (factura rectificativa) is submitted that references the original invoice number. Both the original invoice and the credit note appear in the fiscal record. Neither is deleted.
Partial refund. A partial credit note referencing the original invoice. The original retains its full amount; the credit note records the reversed portion.
Refund of an invoice that has NOT been successfully submitted. No credit note is generated — the original record does not exist on the authority side. If the original submission was pending, cancel that submission first, then proceed with the refund.

Manual reconciliation is recommended at month end to ensure every Zenoti credit note has a paired original invoice on the Spanish side.


Reconciliation

Reconcile Zenoti's compliance log against Fiskaly's portal to catch missed submissions.

Source What to match on Cadence
Zenoti: Collections by Invoices report, filtered to Spanish centers. Zenoti invoice number. Daily at close.
Fiskaly portal: invoices list for your Fiskaly organization. Zenoti invoice number (passed as the external reference) and amount. Daily.
Spanish tax authority submissions list (TicketBAI / VeriFactu portal). NIF + period + document number. Monthly or as required by your tax advisor.

Any Zenoti invoice that does not appear in Fiskaly within 24 hours should be investigated using the compliance log on the Zenoti side. Fiskaly support can confirm receipt on their side if the Zenoti log shows a success but the portal does not.


Tips

  • Run the full flow in the Fiskaly sandbox before pointing Zenoti at production credentials. Use non-production guest records and invoice amounts.
  • Train front-desk staff to recognise the Complete-invoice prompt and to ask for the buyer's NIF for high-value transactions or when the buyer will claim the invoice on their tax return.
  • Monitor the signer expiry date. Zenoti regenerates automatically, but scheduling a check a week before expiry avoids mid-day surprises.
  • Changes to center name, NIF, or address must be made in Zenoti AND in your Fiskaly account — mismatches cause rejections.
  • Enable the integration at center level before go-live. A center that is not enabled does not submit invoices, which creates a compliance gap that may be difficult to close retroactively.

Troubleshooting

Problem Likely cause Resolution
Spain E - Invoicing (Fiskaly) accordion does not appear in Integration Settings. The Spain e-invoicing feature is not enabled for your organization. Contact Zenoti Support to enable the feature. The accordion only renders for organizations registered in Spain with the feature flag on.
Generate button for Signer ID is unavailable or returns an error. API Key, API Secret, Host URL, or Organization ID (Fiskaly) has not been saved, or the credentials are incorrect. Save all credential fields first. If the error persists after saving, verify each credential against your Fiskaly account and try again.
Client ID cannot be generated. Signer ID has not been generated yet. Generate the Signer ID first, then generate the Client ID.
Invoice closes but does not appear in the Fiskaly portal within 24 hours. Submission failed silently, or there is a network issue between Zenoti and Fiskaly. Review the compliance log for the center. Check the failure mode table above and resolve the identified cause, then retry the submission.
Fiskaly rejects invoice with a territory mismatch. The Territory field in Zenoti does not match the scheme your business is enrolled in. Update the Territory field to match your enrolment (for example, change to Bizkaia/Biscay (Basque Country) for a TicketBAI center in Bilbao). Contact your tax advisor if unsure.
Guest receipt does not show the compliance QR code. The invoice was not successfully submitted to Fiskaly before the receipt was printed. Resolve the underlying submission failure and reprint the receipt after the submission succeeds.

Was this article helpful?
Your feedback helps us improve our documentation.