Skip to content

Create an export

fiskaly Logo
API docs by Redocly

fiskaly SIGN ES (1.23.0)

Download OpenAPI specification:

Contact: info@fiskaly.com URL: https://fiskaly.com

Imprint: fiskaly.com/impressum
Privacy Policy: fiskaly.com/datenschutz
Solution Details: fiskaly.com/signes
Developer Guide: workspace.fiskaly.com/sign-es

Introduction

The fiskaly SIGN ES solution provides a RESTful API and ensures compliance with the Spanish TicketBAI legislation and Verifactu legislation.

SIGN ES provides a test environment for integration and testing purposes as well as a dedicated live environment for performing the sending of official transactions (invoices). In order to access the live environment, please contact our sales team.

The fiskaly SIGN ES is a platform-independent and software-only solution. Since this is a cloud-based API, the only requirement to integrate the fiskaly SIGN ES is a stable Internet connection. The API ...

  • has resource-oriented URLs,

  • accepts JSON-encoded request bodies,

  • returns JSON-encoded responses,

  • uses standard HTTP status codes and verbs, and

  • is design to be easily integrated in any system.

With the provided compliance information from the SIGN ES Invoices API response data, the process of issuing a fiscalized invoice can be completed through our environment-friendly and award-winning Digital Receipt.

The Digital Receipt API allows the creation of the receipt in an electonic form, which the customer can easily obtain by scanning a QR code.

fiskaly's Digital Receipt supports the receipt creation for all of fiskaly's SIGN solutions. For more information, reach out to our sales team. An example of the digital receipt for SIGN ES is shown in the following figure:

Background

SIGN ES implements legal requirements and technical guidelines for fiscalization compliance of POS softwares in Spain.

The fiskaly SIGN ES API is based on the following Spanish regulations for TicketBAI in the Basque Region and the Anti-Fraud Law & Verifactu regulation for the rest of Spain.

  • Verifactu in Spain:

    Royal Decree 1007/2023, of December 5th, approving the regulation that establishes the requirements to be adopted by the computerized or electronic systems and programs that support the invoicing processes of businessmen and professionals, and the standardization of invoicing record formats.

    Ministerial Order HAC/1177/2024 of October 17th, published on October 28th, establishing the technical, functional and content specifications for Invoicing Systems.


  • TicketBAI in Araba:

    Foral Decree 48/2021, of October 5th. Approval of the regulations implementing the TicketBAI obligation.

    Foral Decree 802/2021, of December 27th. Technical and Functional requirements of TicketBAI Softwares and registration declaration for the TicketBAI Software Registry.


  • TicketBAI in Bizkaia:

    Foral Decree 5/2020, of July 15th. Establishment of a comprehensive system for the control of income from economic activities.

    Foral Decree 1482/2020, of September 9th. Technical and Legal requirements of the guarantor software and registration declaration for the Guarantor Software Registry.


  • TicketBAI in Gipuzkoa:

    Foral Decree 32/2020, of December 22nd. Approval of the regulations implementing the TicketBAI obligation.

    Foral Decree 521/2020, of December 23th. Technical and Functional requirements of TicketBAI Softwares and registration declaration for the TicketBAI Software Registry.


Territories

Spain has a complex tax system consisting of two different tax regimes: the ordinary and the foral. The regions belonging to the foral regime (Basque Country and Navarre) are entitled to develop and implement their own fiscal legislation. Some territories such as the Canary Islands, Ceuta and Melilla, due to their condition, follow a special fiscal regime, different from the rest of the peninsula.

The fiskaly SIGN ES takes into consideration the particular requirements of the different Spanish territories, anticipating possible changes between the different provinces in Spain, such as sending invoicing registries to different tax authorities or sending specific information in each province. This is why the SIGN ES API includes the following territorial regions:

  • Araba: indicates that the taxpayer has a fiscal address in Araba in the Basque Country, and has to comply with the specific TicketBAI requirements for this province.

  • Bizkaia: indicates that the taxpayer has a fiscal address in Bizkaia in the Basque Country, and has to comply with the specific TicketBAI and BATUZ requirements for this province.

  • Gipuzkoa: indicates that the taxpayer has a fiscal address in Gipuzkoa in the Basque Country, and has to comply with the specific TicketBAI requirements for this province.

  • Navarre: indicates that the taxpayer has a fiscal address in the autonomous community of Navarre and has to comply with the specific requirements of this province.

  • Other Territories of Spain: indicates that the taxpayer has a fiscal address in any other autonomous community of Spain and has to comply with the specific requirements of the Verifactu legislation. The following provinces are considered: Andalusia, Aragon, Principality of Asturias, Cantabria, Castilla-La Mancha, Castile and Leon, Catalonia, Extremadura, Galicia, Balearic Islands, La Rioja, Madrid Region, Murcia Region, and Valencian Community.

  • Canary Islands: indicates that the taxpayer has a fiscal address in the Canary Islands and has to comply with the specific requirements of this province.

  • Ceuta: indicates that the taxpayer has a fiscal address in the autonomous city of Ceuta and has to comply with the specific legal requirements.

  • Melilla: indicates that the taxpayer has a fiscal address in the autonomous city of Melilla and has to comply with the specific legal requirements.

Solution

The fiskaly SIGN ES solution provides a 100% legally compliant TicketBAI and Verifactu implementation in order to generate digital signatures for invoicing transactions. SIGN ES is already a registered guarantor software for TicketBAI in the Basque provinces.

All SIGN ES related services are operated by fiskaly within the Google Cloud Platform at the geographical data center region Madrid (europe-southwest1).

Guides

If it's the first time you are implementing one of fiskaly's SIGN solutions, we recommend that you first have a look at our guide for new customers where you will find an explanation of how to create organizations and API keys, as well as a first overview of our SIGN ES API endpoints.

If you have already implemented our SIGN DE API, we have prepared an integration guide for existing customers where you will find similarities and differences between the different endpoints compared to SIGN ES.

Changes

The up-to-date information below is organized in a change log format which is available in the following subscribable feed formats as well: RSS, Atom, and JSON.


1.23.0 [2026-02-02] Corrections Original Reference Support

  • added the field reference_original_id, it's now possible to issue corrections or enrichments by referencing the original invoice or any previous modification
  • internal improvements

1.22.2 [2026-01-26] Internal Improvements

  • fixed the response compliance field for EXTERNAL invoices in Verifactu
  • internal improvements

1.22.1 [2026-01-16] New Agreement Types

  • added support for other agreement formats via the new types: UNVERIFIED, OTHER_DOCUMENT and PROVIDED_EXTERNALLY
  • deprecated the registered field in the taxpayer and software endpoints
  • added new VAT regime ENTITY_GROUP
  • added support for all UTF-8 characters for address_line and postal_code in recipient identification
  • internal improvements

1.22.0 [2025-12-19] Extended Bizkaia Offline Functionality

  • added offline corrections, enrichments and summaries in Bizkaia with the OFFLINE annotation
  • added option to switch to non Veri*factu via the end_of_verifactu_date field
  • added new VAT regime PENDING_ACCRUAL
  • added support for character & for international recipient identification
  • internal improvements

1.21.2 [2025-12-05] Internal Improvements

  • added support for character ; in legal names and addresses
  • added new IPSI exclusive VAT regimes: INTERNAL_IPSI_EXEMPT, OBJECTIVE_ESTIMATION and CEUTA_SPECIFIC
  • updated mapping of existing VAT regimes for IPSI system in accordance with Verifactu's changes
  • added new VAT regime PROFESSIONAL_FEES
  • added support for registration_csv and cancellation_csv for invoices issued in Bizkaia
  • internal improvements

1.21.1 [2025-11-18] Internal Improvements

  • added support for characters äÄ, ëË and öÖ in legal names and addresses
  • changed invoice and item description to support the entire UTF-8 character set
  • extended invoice and item description length to allow 500 characters for Verifactu invoices
  • added new optional registration_csv and cancellation_csv fields to the invoice response, which will be populated on new invoices after successful transmissions in Verifactu territories as well as Gipuzkoa
  • internal improvements

1.21.0 [2025-11-06] Third Party Invoicing

  • added possibility to issue invoices through third parties via the optional third_party taxpayer configuration in verifactu territories
  • added support for characters Ãã, Õõ and Øø in legal names, addresses and invoice text
  • internal improvements

1.20.2 [2025-10-28] Internal Improvements

  • added OSS_IOSS vat regime
  • improved API documentation and field descriptions
  • internal improvements

1.20.1 [2025-10-17] Internal Improvements

  • corrected the internal behavior when issued_at is not provided in simplified enrichments: the default now uses Europe/Madrid local time instead of UTC
  • added new IGIC exlusive exemption causes TAXABLE_EXEMPT_7 and TAXABLE_EXEMPT_8
  • added new IGIC exlcusive VAT regimes RETAIL_TRADERS, SMALL_PROFESSIONALS and INTERNAL_IGIC_EXCEMPT

1.20.0 [2025-10-14] Draft Invoices

  • added new invoice type DRAFT to create simplified and complete draft invoices
  • added new field exception_unidentified to support complete invoices without a recipient (verifactu only)
  • added new VAT regime 04 Investment Gold
  • added new VAT regime 15 Successive Transactions Pending
  • improved taxpayer agreement validation

1.19.0 [2025-10-03] Issue Date Behavior

  • corrected the internal behavior when issued_at is not provided: the default now uses Europe/Madrid local time instead of UTC
  • clarified documentation for field issued_at
  • fixed the mapping of the INCIDENT annotation to the Verifactu XML file

1.18.1 [2025-09-16] Internal Improvements

  • added CASH_CRITERIA vat regime
  • added alternative issued_at timestamp format with timezone information
  • internal improvements

1.18.0 [2025-09-10] Summary Invoices

  • added possibility to issue summary (recapitulative) invoices
  • added possibility to issue summary correction (rappel) invoices
  • fixed an issue where the transaction date was not correctly mapped for verifactu invoices
  • internal improvements

1.17.3 [2025-09-02] Internal Improvements

  • added RENT_PREMISES vat regime
  • added additional characters + and € for InvoiceText
  • added special characters to the address number field
  • internal improvements

1.17.2 [2025-08-25] Internal Improvements

  • fixed rare rounding issues in verifactu invoices
  • internal improvements

1.17.1 [2025-08-08] Internal Improvements

  • added registered flag for NationalIdentification to indicate if a recipient is not yet registered with AEAT in verifactu
  • added additional character ' for LegalName, AddressLine and InvoiceText
  • updated postman collection with examples for AEAT and VIES validation services
  • internal improvements

1.17.0 [2025-07-29] Tax Number Validation

  • added tax number validation endpoint, supporting AEAT and VIES services
  • added new invoice system types OTHER_TAX_IVA, OTHER_TAX_IGIC, and OTHER_TAX_IPSI for transactions subject to other territories
  • added additional characters & ß for LegalName
  • added additional characters \ & @ \r ß # for InvoiceText
  • updated postman collection for taxpayer social collaboration agreement workflow
  • internal improvements

1.16.1 [2025-07-14] Travel Agencies Regimes

  • added TRAVEL_AGENCIES vat regime
  • added TRAVEL_AGENCY_MEDIATORS vat regime
  • implemented taxpayer social collaboration agreement workflow
  • updated postman collection
  • internal storage and transmission improvements

1.16.0 [2025-06-25] Invoicing by Recipient

  • added possibility to issue invoices by recipient for verifactu taxpayers
  • added ANTIQUES vat regime
  • added AGRICULTURE vat regime
  • internal storage and transmission improvements

1.15.1 [2025-06-13] Internal Improvements

  • changed the item limit to 10000 for verifactu invoices
  • internal improvements of the verifactu transmission

1.15.0 [2025-05-27] Verifactu Enablement

  • enabled creation of taxpayers for the following territories in LIVE environment: Spain_Other, Ceuta, Melilla and Canary Islands
  • enabled transmission of Verifactu invoices in LIVE environment
  • added batch sending capabilities for Verifactu transmission
  • added endpoints for social collaboration workflow
  • added possibility to add address and email information to taxpayers
  • increased the maximum signer limit for Verifactu taxpayers to 10
  • fixed mapping of EQUIVALANCE_SURCHARGE in Verifactu

1.14.0 [2025-04-23] API Improvements

  • clarified issued_at and transaction_date description
  • clarified tax_number description if used as international recipient
  • added additional characters for invoice text, legal name and address
  • fixed endpoint mapping of Ceuta, Melilla and Canary Islands taxpayer territories
  • fix issuing of invoices with the same number and series but different years
  • for verifactu signers a VerifactuCertificate is returned instead of a TicketbaiDeviceCertificate
  • internal improvements

1.13.0 [2025-02-20] Verifactu Transmission

  • enabled transmission of invoices to tax authorities test endpoints for Verifactu territories
  • enabled Ceuta, Melilla and Canary Islands taxpayer territories
  • added remedy functionality for Verifactu
  • added endpoint to allow permanently disabling a taxpayer
  • improved internal xml mapping

1.12.1 [2025-02-03] Remedies with International Recipients

  • fixed mapping of international recipients ID Type for remedy invoices

1.12.0 [2025-01-20] Remedy Improvements

  • improved remedy functionality in Bizkaia:
    • allowing cancellation of remedies
    • remedy offline invoices through the use of EXTERNAL invoices
    • remedy failed remedies in state REQUIRES_INSPECTION
  • fixed mapping of TicketBAI NON_TAXABLE types
  • fixed mapping of issue dates for ENRICHMENT invoices
  • improved internal certificate handling

1.11.1 [2024-12-11] Internal Improvements

  • improvements to transmission of cancellation XML records

1.11.0 [2024-12-04] Tax Types and Verifactu API Preparation

  • added the optional vat_type field, which is available in the API schema InvoiceItem
  • added the optional responsibility_declaration field, which is available in the API schema Software
  • improved internal mapping of Verifactu invoices
  • improved API documentation in advance of Verifactu

1.10.0 [2024-11-18] Remedy invoices for Bizkaia

  • enabled remedy functionality for Bizkaia
  • improved internal validations for creation of XML records

1.9.0 [2024-10-25] Remedy invoices

  • enabled remedy functionality for Araba and Gipuzkoa regions
  • improvements to creation of and transmission of XML records

1.8.2 [2024-09-19] Invoice Line Discount Amount

  • improved TicketBAI XML creation related to item discount amounts

1.8.1 [2024-09-12] Internal Improvements

  • improved internal creation of Validation URLs
  • improved handling of enrichment invoices
  • improved internal creation of clients

1.8.0 [2024-08-13] Resending of Invoices

  • enabled resending of invoices through the REMEDY functionality in Bizkaia, which can be used in case of transmission errors due to a not registered certificate or to update a wrongfully set IndividualAnnotation, e.g. a wrong activity code
  • fixed encoding of Validation URLs which could lead to invalid URLs in certain cases
  • improved TicketBAI XML creation and transmission during high load scenarios

1.7.2 [2024-07-18] Internal Improvements

  • improved internal transmission handling
  • improved software endpoint response

1.7.1 [2024-06-25] API and Transmission

  • improved TicketBAI XML creation and transmission towards Bizkaia

1.7.0 [2024-06-04] Verifactu API

  • added Coupon to the API schema of Correcting invoices, which can be set for corrections of simplified invoices or complete invoices with type CORRECTION_1, in Bizkaia and all Verifactu territories
  • added Incident annotation, which allows for providing information about technical incidents during the creation of invoices
  • enabled the creation of taxpayers in the SPAIN_OTHER territory to allow creation of taxpayers that fall under the Verifactu legislation in TEST environments
  • enabled the creation of invoices for taxpayers that fall under the Verifactu legislation in TEST environments
  • improved TicketBAI XML creation and transmission towards territorial tax authority servers

1.6.0 [2024-04-11] Batuz Sending for Individuals

  • added Annotations to the API schema, which allows for adding territory or legislation specific information to an invoice
  • provided functionality for transmission of invoices for individuals through the IndividualAnnotation, which can be added either while first issuing the invoice or later through PATCH
  • added the vat_withholding field, which is available in the API schema CompleteInvoice
  • improved TicketBAI XML transmission towards territorial tax authority servers

1.5.6 [2024-03-21] Invoice Text

  • added colon character (:) support for API schema InvoiceText and ExtendedSpecialAlphaNumerical250 which is used in the API schema SimplifiedInvoice as well as in InvoiceItem and allows to express colon-based description texts
  • improved TicketBAI XML transmission towards territorial tax authority servers

1.5.5 [2024-02-29] Invoicing

  • added NON_TAXABLE_4 for NotTaxableCause API schema to create invoices for sales carried out on behalf of third parties

1.5.4 [2024-02-14] External Invoice Referencing

  • added EXTERNAL invoice type for createInvoice API operation to represent and reference invoices in SIGN ES that where issued outside of the SIGN ES system boundary
  • updated CONCEPT description in the API documentation

1.5.3 [2024-01-30] LROE Transmission

  • provided the integration of TicketBAI XML files into BATUZ/LROE chapter 1.1 XML records for the BIZKAIA taxpayer territory
  • creation and sending of LROE records is already enabled in the production TEST environment
  • creation and sending of LROE records will be automatically activated for the production LIVE environment on 2024-02-01 00:00:00 UTC+1
  • renamed API schema TicketbaiCommunication to InvoiceExportCommunication
  • renamed API schema TicketbaiXML to TransmissionFile
  • updated Spanish API documentation

1.5.2 [2024-01-10] TicketBAI and Taxpayer

  • enabled TicketBAI invoice registration and cancellation XML file creation and sending in version v1.2.2 in the production LIVE system
  • improved Taxpayer API response to provide the taxpayer type information which is either a COMPANY or an INDIVIDUAL based on a tax number distinction
  • provided typed API schema for TaxpayerCreateRequest
  • refined the TaxNumber regex string pattern

1.5.1 [2023-12-30] TicketBAI Signature

  • updated BIZKAIA signature policy to v1.1
  • improved XAdES-EPES signing process and signature creation
  • provided masculine ordinal character support in API schema ExtendedAlphaNumerical120, ExtendedAlphaNumerical250, and ExtendedSpecialAlphaNumerical250
  • increased decimal place precision up to 8 digits in API schema InvoiceItemUnitAmount, InvoiceItemFullAmount, InvoiceItemDiscount, and InvoiceQuantity

1.5.0 [2023-12-22] TicketBAI v1.2.2

  • provided TicketBAI invoice registration and cancellation XML file creation and sending for version v1.2.2
  • enabled in the production TEST system for now
  • introduced new NON_TAXABLE_3 code

1.4.4 [2023-11-30] Export in Dashboard

  • provided Export UI integration in the fiskaly dashboard
  • improved TicketBAI XML transmission towards territorial tax authority servers

1.4.3 [2023-11-24] Product Localization

  • provided Spanish translation of the OpenAPI specification
  • added localization integration in the developer guide
  • improved TicketBAI XML transmission towards territorial tax authority servers

1.4.2 [2023-11-17] Invoicing and Transmission

  • updated createInvoice breakdown computation for international recipients regarding the invoice item declaration of services and goods
  • improved TicketBAI XML transmission towards territorial tax authority servers

1.4.1 [2023-11-10] Verifactu Ready

  • provided Territory enumerator values for Verifactu-based regions
  • provided VerifactuInvoiceCompliance schema for Invoice API response schema SignedInvoice for Verifactu-based regions

1.4.0 [2023-10-30] Export Functionality

  • provided Exports resource functionality to create asynchronous exports of multiple invoices in form of downloadable ZIP archives
  • enabled createExport, updateExport, retrieveExport, listExport, and downloadExport API operation
  • updated Invoice API documentation of invoice types
  • added InvoiceAdditionalVat API schema and invoice functionality to apply additional VAT amount and rates to invoice items

1.3.2 [2023-10-11] Invoice Enrichment

  • enabled ENRICHMENT functionality in order to enrich simplified invoices with recipient information
  • provided EnrichmentInvoice API request schema for the createInvoice API operation
  • updated VAT rate API field description for the usage of the InvoicePercentage type in the InvoiceWithVatCategory schema
  • provided 400 API error response code description to TaxpayerResponse, SingerResponse, SignersResponse, ClientResponse, ClientsResponse, InvoiceResponse, InvoicesResponse, ExportResponse, and SoftwareResponse.

1.3.1 [2023-09-29] Invoice Transmission

  • improved Invoices sending transmission behavior to corresponding tax authority services
  • improved exportInvoice API operation performance providing the registration request XML data

1.3.0 [2023-09-22] External Certificates

  • enabled updateSigner external device certificate support
  • updated Certificate API request schema of updateSigner API operation
  • improved SignedInvoice API response schema of Invoices API operations by adding InvoiceSigner and InvoiceClient information
  • provided new sections in the developer guide for external device certificate creation

1.2.1 [2023-09-01] Invoicing and Pagination

  • modified createInvoice validation behavior and direct validation feedback in the SignedInvoice API response validations field
  • improved createInvoice signing request performance
  • improved TicketbaiInvoiceIdentifier string regex pattern to allow more alpha-numerical and special characters
  • provided Pagination support for all listing endpoints to page through large results sets with a pagination limit and a token-based approach

1.2.0 [2023-08-23] Invoice Search and Listing

  • enabled createInvoice functionality for creating correction invoices by differences
  • updated ValidationError enumeration API documentation with detailed enumerator code description
  • provided searchInvoices API endpoint to filter and search for taxpayers' invoices by using optional query parameters for invoice number, invoice series, and invoice issuing time range
  • improved Invoices request handling and concurrent processing
  • changed listSigners, listClients, and listInvoices API response schema layout and content to return a results array of resource schema elements consisting of the actual content and metadata

1.1.1 [2023-08-04] Invoice Validation & Metadata

  • provided Invoices validation with dedicated request HTTP error 422 for invalid invoice requests with dedicated ValidationError code and description in the validations schema field
  • provided Invoices transmission validation error propagation in the API for the SignedInvoice response validations schema field
  • updated createInvoice API request to allow optional issued_at field to specify the invoice issue timestamp
  • updated createInvoice API request to allow optional transaction_date field to specify the invoice transaction date
  • provided Invoices export system with taxable exempt causes
  • improved Invoices endpoint functionality and enabled the corresponding Metadata functionality
  • improved Clients endpoint functionality and enabled the corresponding Metadata functionality
  • improved Signers endpoint functionality and enabled the corresponding Metadata functionality
  • improved Taxpayer endpoint functionality and enabled the corresponding Metadata functionality

1.1.0 [2023-06-23] Complete Invoice Functionality

  • enabled Invoices endpoint functionality to handle CompleteInvoice API request schema to issue COMPLETE invoices which contains recipient information and provides additional VAT systems, VAT categories, and the new economic concept for national and international invoicing transactions
  • updated Invoices endpoint functionality to handle CorrectionInvoice API request schema to perform CORRECTION of COMPLETE to COMPLETE invoices as well as the "upgrading" of SIMPLIFIED invoices to COMPLETE invoices
  • improved Signers endpoint functionality

1.0.1 [2023-06-16] Complete Invoice Schema

  • refined CompleteInvoice API request schema of Recipients structure for national and international invoice recipient information
  • extended InvoiceItem API schema with new optional economic Concept abstraction
  • improved Authentication endpoint functionality for LIVE environment tokens
  • updated Taxpayer endpoint functionality that all information changes are only allowed without any ENABLED resources

1.0.0 [2023-06-14] Production Live Environment

  • Enabled live.es.sign.fiskaly.com production live environment
  • Enabled Software endpoint functionality for in-person verification
  • Improved API documentation and field descriptions

0.15.0 [2023-06-11] Invoice Correction Functionality

  • Enabled createInvoice API CORRECTION schema and functionality
  • Updated Invoices API response schema
  • Improved Invoices endpoint functionality

0.14.0 [2023-06-02] Cancel Invoice Functionality

  • Enabled updateInvoice API functionality
  • Updated updateInvoice API request schema
  • Updated Invoice response schema
  • Improved Invoices endpoint functionality

0.13.0 [2023-05-29] Production Test Environment

  • Enabled test.es.sign.fiskaly.com production test environment
  • Improved Data Exports endpoint export functionality
  • Improved Invoices endpoint invoicing functionality

0.12.0 [2023-05-26] Export Invoice Functionality

  • Enabled Data Exports endpoint export functionality
  • Improved Invoices endpoint invoicing functionality
  • Improved Signers endpoint maintenance functionality

0.11.2 [2023-05-16] Invoicing Functionality

  • Updated SimplifiedInvoice request schema documentation
  • Improved Invoices endpoint invoicing functionality
  • Improved Clients endpoint maintenance functionality
  • Improved Signers endpoint maintenance functionality

0.11.1 [2023-04-28] Postman Collection

  • Enabled Postman integration for retrieval of Postman collection and environment configurations
  • Updated Invoice endpoint functionality
  • Added Quick Start API documentation section
  • Added FAQs API documentation section

0.11.0 [2023-04-23] Simplified Invoicing

  • Enabled createInvoice API functionality
  • Enabled retrieveInvoice API functionality
  • Enabled listInvoices API functionality
  • Updated SimplifiedInvoice request schema
  • Updated Invoice response schema
  • Improved Signers endpoint maintenance functionality
  • Improved Clients endpoint maintenance functionality

0.10.0 [2023-04-17] Invoice API

  • Updated SimplifiedInvoice request schema
  • Updated Invoice response schema
  • Improved Taxpayer endpoint maintenance functionality
  • Improved Signers endpoint maintenance functionality
  • Improved Clients endpoint maintenance functionality

0.9.0 [2023-04-02] Client Functionality

  • Enabled Clients endpoint maintenance functionality with default signer allocation
  • Updated Signers endpoint maintenance functionality
  • Updated Taxpayer endpoint maintenance functionality
  • Updated Authentication endpoint functionality
  • Updated Authentication endpoint API response schema
  • Refined Invoices endpoint API response schema

0.8.0 [2023-03-29] Signer Functionality

  • Refined createSigner endpoint API error responses
  • Refined updateSigner endpoint API error responses
  • Refined retrieveSigner endpoint API error responses
  • Refined listSigner endpoint API error responses
  • Refined createClient endpoint API error responses
  • Refined updateClient endpoint API error responses
  • Refined retrieveClient endpoint API error responses
  • Refined listClient endpoint API error responses
  • Updated SigningDevice API schema with explicit certificate field
  • Updated maintenance functionality for Taxpayer information
  • Enabled maintenance functionality for Signer with managed certificates

0.7.0 [2023-03-22] Update of API

  • Changes affect the API Taxpayer endpoints
  • Renamed TicketbaiIssuer schema field tax_id to tax_number
  • Renamed TicketbaiIssuer schema field name to legal_name
  • Renamed TicketbaiVatRegistrationNumber schema to TicketbaiTaxNumber

0.6.0 [2023-03-20] Update of API

  • Updated Authentication, Taxpayer, and Signer endpoint request/response schema
  • Updated ErrorResponse schema
  • Introduced generic BadRequestResponse, UnauthorizedAccessResponse, ResourceNotFoundResponse, and InternalServerErrorResponse schema
  • Service Authentication functionality enabled
  • Service Taxpayer functionality enabled
  • Product changes are integrated in OpenAPI specification and available through RSS, Atom, and a generic JSON-based feeds

0.5.0 [2023-02-23] Update of API

  • Introduced ErrorResponse endpoint response schema type
  • Updated Client response schema
  • Introduced SignerState schema
  • Provided deployment cycle of service

0.4.0 [2023-02-07] Rework of API

  • Updated endpoint response schema types
  • Updated SigningDevice schema
  • Introduced SignerState schema

0.3.0 [2023-01-30] Update of API

  • Updated TicketBaiInvoiceState schema
  • Changed TicketBaiInvoiceTransmission to TicketBaiInvoiceCancellationState
  • Updated TicketBaiIssuer documentation
  • Updated TicketBaiVatRegistrationNumber documentation
  • Changed Decimal3p2 regex patterns

0.2.0 [2023-01-20] Rework of API

  • Updated UniversallyUniqueIdentifierV4 schema description
  • Changed AccessToken refresh key from token to refresh_token
  • Provided basic test server functionality

0.1.1 [2023-01-13] Rework of API

  • Updated AccessToken schema
  • Changed ApiKeyString and ApiSecretString representation
  • Provided PKCS and PEM formats
  • Updates TicketBAI regime and taxable codes

0.1.0 [2023-01-05] Initial Release

  • Provides draft of OpenAPI specification of SIGN ES
  • Defines TicketBAI schemas
  • Defines SIGN ES endpoints

Versioning

The fiskaly SIGN ES follows Semantic Versioning. The version number has a pattern of MAJOR.MINOR.PATCH. We increment the

  • MAJOR version when we make incompatible API changes,

  • MINOR version when we add functionality in a backwards-compatible manner, and

  • PATCH version when we make backwards-compatible bug fixes.

Resources

This API uses Universally Unique IDentifiers (UUID) to address the resources created in the SIGN ES solution.

In order to provide truly (pseudo-)randomized identifiers for SIGN ES resources, the API only allows UUIDs in version 4 (UUIDv4).

The used UUIDv4-based identifiers for all SIGN ES resources like Signer, Client, Invoice, and Export should always be automatically generated by using a (standard) library functionality provided by your programming language choice e.g. JavaScript or Golang.

Quick Start

For a quick first demo, you may use Postman. We prepared a Postman collection that allows you to step through the most important functions of this API.

  1. Download the Postman application.

  2. Create an API Key and API Secret via the fiskaly dashboard:

  3. Insert your API Key and API Secret to download your personalized fiskaly SIGN ES Postman Environment JSON based configuration file:

    API Key
    API Secret

  4. Download the fiskaly SIGN ES Postman Collection JSON based configuration file:


  5. Start Postman and import the downloaded Postman environment and collection files:

  6. Select the fiskaly SIGN ES Postman environment and run the collection:

FAQs

The FAQs of SIGN ES are provided at the fiskaly support page.

Authentication

The fiskaly APIs use a JWT based security mechanism to authenticate API requests. API requests without authentication will fail with an unauthorized access HTTP error. The fiskaly APIs process only https based request. Plain http based requests are redirected to https.

JWT

A JSON Web Token (JWT) used for access control and authorization. The JWT can be obtained through a retrieve authentication token API request.

Retrieve access token

To access a fiskaly API, you need to have a valid JWT access_token. This endpoint creates the access token with your api_key and api_secret.

If you do not have an api_key, you can create one via Management API endpoint createApiKey or the fiskaly dashboard.

The api_secret will be generated for you after you create the api_key.

The access_token token must be sent with every following request in the Authorization header field using the Bearer authentication scheme.

See details here.

Request Body schema: application/json
required
required
ApiKeySecretAuthentication (object) or RefreshTokenAuthentication (object)

Responses

Request samples

Content type
application/json
{
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "content": {
    }
}

Taxpayer

Create taxpayer

This endpoint is used to create the taxpayer (invoice issuer) information.

Authorizations:
JWT
Request Body schema: application/json
required
required
object (TaxpayerCreateContent)

Represents the taxpayer information which is used for issuing invoices for all signing devices within the context of the managed organization which is associated in the JWT. It consists of the invoice issuer (taxpayer) information and the territory representing the legal address of the taxpayer.

object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a taxpayer

In order to update a specific taxpayer state, this endpoint allows to disable (deactivate) a taxpayer permanently and/or update the taxpayer metadata.

Authorizations:
JWT
Request Body schema: application/json
required
object (TaxpayerUpdateContent)
object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve taxpayer

This endpoint is used to retrieve the taxpayer (invoice issuer) information.

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Generate agreement

Generates a draft for a social collaborator agreement document. This document is required for taxpayers under Verifactu legislation to authorize fiskaly to transmit invoices on their behalf. Taxpayers must add their address using the update endpoint.

The generated document must be digitally signed by the taxpayer's legal representative and uploaded through this API. For an individual taxpayer, the legal representative is the taxpayer itself, while for companies personal information of a representative must be provided.

Multiple agreement drafts can be generated without invalidating existing valid ones.

Authorizations:
JWT
Request Body schema: application/json
required
required
object (GenerateAgreementContent)

Responses

Request samples

Content type
application/json
{
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "content": {
    }
}

Upload signed agreement

This endpoint enables the upload of a digitally signed agreement previously generated through this API. It accepts a digitally signed agreement in PAdES format. The signature must be valid and applied by the taxpayer's representative.

Successful uploads will replace any existing agreement associated with the resource.

By signing and submitting this AUTHORIZATION, the TAXPAYER expressly acknowledges and assumes responsibility for the truthfulness and accuracy of the information contained therein, declaring that such information is complete, true, and accurate as of the date of signature. Furthermore, the TAXPAYER expressly and unequivocally grants Fiskaly Iberia the authority to act as their representative for the purpose of submitting the invoice files generated through the Invoicing Information System (SIF) to the Spanish Tax Agency.

Authorizations:
JWT
Request Body schema: application/json
required
required
object (TaxpayerAgreementDocument)

Responses

Request samples

Content type
application/json
{
  • "content": {
    }
}

Response samples

Content type
application/json
{}

Retrieve agreement

This endpoint allows to retrieve the taxpayer's the latest uploaded social collaborator agreement.

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{}

Download agreement

This endpoint allows to download the taxpayer's latest uploaded social collaborator agreement as PDF.

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "content": {
    }
}

Signers

Create a signer

This endpoint is used to create a signing device (signer). SIGN ES manages certificates for Verifactu and TicketBAI.

There needs to be at least one signing device present per managed organization in order to issue invoices.
A signing device allows to use a dedicated certificate and keeps track of the invoicing chain.

For TicketBAI, a signing device allows to use a dedicated device certificate of type 'Invoicing Point' and generate a signature chain for one or multiple client devices. Each signing device needs a device certificate. If no external device certificate is provided during the signing device creation, by default SIGN ES uses a fiskaly GmbH managed device certificate.

For Verifactu, SIGN ES will use by default an electronic certificate managed by fiskaly GmbH for the signature of files, chaining per taxpayer and transmission to the tax authorities.

This call is idempotent.

Authorizations:
JWT
path Parameters
signer_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a signer (signing device) resource by using a randomized UUIDv4 format.

Request Body schema: application/json
required
object (Signer)

Represents the signing device which performs the invoice chaining and signing operations.

object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update a signer

In order to update a specific signing device state, this endpoint allows to disable (deactivate) a signing device permanently and/or update the signing device metadata.

Authorizations:
JWT
path Parameters
signer_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a signer (signing device) resource by using a randomized UUIDv4 format.

Request Body schema: application/json
required
object
object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve a signer

Retrieve a specific signing device (signer) of an organization.

Authorizations:
JWT
path Parameters
signer_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a signer (signing device) resource by using a randomized UUIDv4 format.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

List signers

Retrieve a list of signing devices (signers) of an organization.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Clients

Create a client

This endpoint is used to create a client device.
A client device allows to uniquely identify (through the provided device_id path parameter) a terminal, POS system, application, or any other client that wants to issue invoices.

In order to issue invoices you need one client per POS system and at least one signing device.

This call is idempotent.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

Request Body schema: application/json
required
object (Client)

Represents an invoicing device which is accessed by an invoicing application, whether or not it accesses a remote server for this purpose. For example in the case of a web-based application, the serial number of the invoicing device will be that of the device on which the browser is installed, and not the remote server which it accesses to operate the application.

object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Update a client

In order to update a specific client device state, this endpoint allows to disable (deactivate) a client device permanently and/or update the client device metadata.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

Request Body schema: application/json
required
object
object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve a client

Retrieve a specific client device of an organization.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

Responses

Response samples

Content type
application/json
{}

List clients

List of client devices of an organization.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Software

Retrieve software

This endpoint is used to retrieve the SIGN ES software information according to the software registration for a configured taxpayer, which is needed in case of an in-person verification (audit use case).

For more details, please refer to the software registration section of the SIGN ES the developer guide.

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{}

Invoices

The fiskaly SIGN ES API provides TicketBAI and Verifactu compliant invoice information in the response data of the createInvoice, updateInvoice, and retrieveInvoice endpoints below. This invoice information is required to be printed on an actual invoice, but we recommend to implement our Digital Receipt API to represent invoices in an electronic form.

Create an invoice

This endpoint is used to issue an invoice through a client device.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

invoice_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an invoice resource by using a randomized UUIDv4 format.

query Parameters
code
string (InvoiceRepresentationCode)
Enum: "QR_CODE" "CENTERED_CODE" "PORTRAIT_CODE" "LANDSCAPE_CODE"

Allows optionally to query the invoice compliance code in a specific representation (see TicketbaiRepresentationCode). By default the QR_CODE representation is used in the response, if the query parameter is omitted.

Request Body schema: application/json
required
required
any (Invoice)

An invoice can be either of type SIMPLIFIED, COMPLETE, CORRECTING, ENRICHMENT, REMEDY or EXTERNAL.

  • SIMPLIFIED: Issued up to 400 EUR (including VAT) or up to 3.000 EUR (including VAT) in many cases (retail sales, ambulances services, services to the customers home, transport of people and their luggage, hospitality and catering services, dance halls, and night clubs, among others. For more information, visit the tax authority information page. Simplified invoices can also be issued for correcting invoices and invoices authorized by the department of tax management.

  • COMPLETE: Must be issued in the cases where a simplified invoice is not allowed to be issued. Includes information of the recipient of the invoice: Tax number identification (NIF) of recipient from other countries, full name or company name, and address with postal code (not mandatory in Bizkaia). And indicates itemization on invoice level for national recipients or on transaction level for provision of services or delivery of goods when the recipient is non-national. A complete invoice can be a summary that replaces multiple simplified invoices, according to Art. 13 of the Spanish Invoicing regulations.

  • CORRECTING: Has to be issued in cases that one or more requirements of articles 6 (invoice content) and 7 (simplified invoice content) of the invoicing regulation are not met, or when the modification of the taxable base according to article 80 of law 37/1992 has occurred. For more details, please refer to the tax authority information page. A summary correction can also be issued.

  • ENRICHMENT: Can be issued if the original invoice does not have recipients and the only change is to add one or more recipients.

  • REMEDY: Can be issued to remedy incorrect invoice information which would not necessitate a correction by law.

  • EXTERNAL: Can be used to create invoices that were already issued, but were not issued through SIGN ES. External invoices are never signed or registered to the tax authorities and cannot be cancelled. External invoices may be corrected or enriched through the CORRECTING and ENRICHMENT invoices.

Array of objects (Annotations) = 1 items unique

A list of unique annotations.

object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "annotations": [
    ],
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "annotations": [
    ],
  • "metadata": {}
}

Update an invoice

This endpoint is used to cancel an already registered (created) invoice in the SIGN ES system, or to modify the metadata of an already created invoice.
By performing a cancellation, the state of an invoice changes and initiates another synchronization to the tax authority to invalidate (cancel) the already registered invoice.

When to cancel? In cases when it is not required to provide a correction. For example, when the operation was not carried out (DGT V0611/ 11-3-2011) and the invoice was not given to the customer.

Once an invoice is cancelled, the same number and series number can’t be used again.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

invoice_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an invoice resource by using a randomized UUIDv4 format.

query Parameters
code
string (InvoiceRepresentationCode)
Enum: "QR_CODE" "CENTERED_CODE" "PORTRAIT_CODE" "LANDSCAPE_CODE"

Allows optionally to query the invoice compliance code in a specific representation (see TicketbaiRepresentationCode). By default the QR_CODE representation is used in the response, if the query parameter is omitted.

Request Body schema: application/json
required
object
Array of objects (Annotations) = 1 items unique

A list of unique annotations.

object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "annotations": [
    ],
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "annotations": [
    ],
  • "metadata": {}
}

Retrieve an invoice

This endpoint returns an issued invoice from a client device.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

invoice_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an invoice resource by using a randomized UUIDv4 format.

query Parameters
code
string (InvoiceRepresentationCode)
Enum: "QR_CODE" "CENTERED_CODE" "PORTRAIT_CODE" "LANDSCAPE_CODE"

Allows optionally to query the invoice compliance code in a specific representation (see TicketbaiRepresentationCode). By default the QR_CODE representation is used in the response, if the query parameter is omitted.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "annotations": [
    ],
  • "metadata": {}
}

List invoices

This endpoint retrieves a list of issued invoices from a client device.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

query Parameters
code
string (InvoiceRepresentationCode)
Enum: "QR_CODE" "CENTERED_CODE" "PORTRAIT_CODE" "LANDSCAPE_CODE"

Allows optionally to query the invoice compliance code in a specific representation (see TicketbaiRepresentationCode). By default the QR_CODE representation is used in the response, if the query parameter is omitted.

limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Search invoices

This endpoint retrieves a list of issued invoices for the taxpayer, optionally filtered by any combination of number, series, or issue date.
Invoices are uniquely identified by their number, series and the year they are issued.

The issue_date_from and issue_date_to parameters let you specify a time range in which the invoices were issued, where issued_at_from is inclusive and issue_at_to is exclusive.
This means, if there was an invoice issued at 10-08-2023 15:04:03 and you specify a issued_at_from as 10-08-2023 15:04:03, the invoice will get included in the response, if you specifiy issued_at_to as 10-08-2023 15:04:03, it will not get included.

Authorizations:
JWT
query Parameters
number
string (TicketbaiInvoiceIdentifier) [ 1 .. 20 ] characters ^[0-9A-Z_/\-\.]{1,20}$
Example: number=2022

Uniquely identifies an invoice number in a given year.

series
string (TicketbaiInvoiceIdentifier) [ 1 .. 20 ] characters ^[0-9A-Z_/\-\.]{1,20}$
Example: series=2022

Uniquely identifies an invoice series in a given year.

issued_at_from
string (TimestampFormat19) = 19 characters ^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}$
Example: issued_at_from=24-12-1992 15:35:01

Defines the earliest possible date of the invoice (inclusive).

issued_at_to
string (TimestampFormat19) = 19 characters ^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}$
Example: issued_at_to=24-12-1992 15:35:01

Defines the last possible date of the invoice (exclusive).

client_id
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: client_id=1c81cb86-c2e8-4074-afc3-a0601b2bf063

Defines the identifier of the client that issued the invoice.

limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Export an invoice

This endpoint provides a synchronous export functionality of a single invoice transmission state in form of TicketBAI registration/cancellation request/response XML files.

It is recommended to use this endpoint only to inspect a single invoice.
For exporting and inspecting multiple invoices, use the export functionality.

Authorizations:
JWT
path Parameters
client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies a client device resource by using a randomized UUIDv4 format.

invoice_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an invoice resource by using a randomized UUIDv4 format.

Responses

Response samples

Content type
application/json
{
  • "content": {
    }
}

Validation

Validate Tax Number

Validates one or more tax numbers against the list of registered taxpayers. The AEAT registry supports the validation of multiple spanish tax numbers, while the VIES system for non-Spanish EU taxpayers supports only the validation of one tax number at a time. Since multiple systems allow validation of different tax number types, for example VAT or NIF, these types are summarized as TIN (Tax Identification Number).

Authorizations:
JWT
Request Body schema: application/json
required
required
any (TinValidationContent)

Depending on the validation service used, this endpoint requires different parameters:

  • AEAT: List of entries, consisting of tax number and legal name, where the legal name is optional for companies.
  • VIES: Single entry, consisting of tax number and country code.

Since the AEAT validation service does not have a test endpoint, this call returns INVALID for all tax numbers in TEST. To allow for integration tests, the AEAT validation type returns the following values if called with specific tax numbers in TEST environments:

  • T00000001: INVALID_SIMILAR
  • T00000002: VALID
  • T00000003: VALID_REMOVED
  • T00000004: VALID_REVOKED

Responses

Request samples

Content type
application/json
{
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Exports

Create an export

This endpoint creates an asynchronous export of invoices that match a given criteria.

Authorizations:
JWT
path Parameters
export_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an export resource by using a randomized UUIDv4 format.

query Parameters
series
string (TicketbaiInvoiceIdentifier) [ 1 .. 20 ] characters ^[0-9A-Z_/\-\.]{1,20}$
Example: series=2022

Uniquely identifies an invoice series in a given year.

issued_at_from
string (TimestampFormat19) = 19 characters ^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}$
Example: issued_at_from=24-12-1992 15:35:01

Defines the earliest possible date of the invoice (inclusive).

issued_at_to
string (TimestampFormat19) = 19 characters ^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}$
Example: issued_at_to=24-12-1992 15:35:01

Defines the last possible date of the invoice (exclusive).

client_id
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: client_id=1c81cb86-c2e8-4074-afc3-a0601b2bf063

Defines the identifier of the client that issued the invoice.

Request Body schema: application/json
required
object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Update an export

This endpoint allows to update the metadata of an export.

Authorizations:
JWT
path Parameters
export_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an export resource by using a randomized UUIDv4 format.

Request Body schema: application/json
required
object (Metadata) <= 20 properties

You can use this parameter to attach custom key-value data to an object.
Metadata is useful for storing additional, structured information on an object.
If MetaData is used in responses it returns the existing (request) metadata of the object. You can update metadata using the update endpoint of each resource. If a key is provided with an empty value string in an update request, that key-value pair is removed from the metadata.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

Retrieve an export

This endpoint retrieves an export resource which provides the status of the export request.

Authorizations:
JWT
path Parameters
export_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an export resource by using a randomized UUIDv4 format.

Responses

Response samples

Content type
application/json
{
  • "content": {
    },
  • "metadata": {}
}

List exports

This endpoint retrieves a list of requested exports of the taxpayer.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Download an export

This endpoint retrieves the zip archive of an export.

Authorizations:
JWT
path Parameters
export_id
required
string <uuid> (UniversallyUniqueIdentifierV4) [a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab...
Example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063

Uniquely identifies an export resource by using a randomized UUIDv4 format.

Responses

Response samples

Content type
application/json
{
  • "content": {
    }
}

Was this page helpful?