openapi: 3.0.3
servers:
  - url: 'https://live.api.fiskaly.com'
    description: |
      Live Environment
      
  - url: 'https://test.api.fiskaly.com'
    description: |
      Test Environment
      
info:
  version: '2025-08-12'
  title: 'fiskaly SIGN IT'
  contact:
    email: info@fiskaly.com
    name: 'info'
    url: 'https://fiskaly.com'
  description: |
    Imprint: [fiskaly.com/impressum](https://fiskaly.com/impressum)
    <br>
    Privacy Policy: [fiskaly.com/privacy-policy](https://www.fiskaly.com/privacy-policy)
    <br>
    Service Details: [fiskaly.com/signit](https://www.fiskaly.com/signit)
    <br>
    Developer Guide: [workspace.fiskaly.com/sign-it/2025-08-12/integration-guide/](https://workspace.fiskaly.com/sign-it/2025-08-12/integration-guide/)
    
    # Introduction
    The fiskaly API is a RESTful, cross-country solution designed to support compliance with the relevant legislation. 
    
    The fiskaly API is a platform-independent and software-only solution.
    Since this is a cloud-based API, the only requirement to integrate and use this fiskaly API is a stable Internet connection. The API ...
    
    - has resource-oriented URLs,
    
    - accepts [JSON](https://wikipedia.org/wiki/JSON)-encoded request bodies,
    
    - returns [JSON](https://wikipedia.org/wiki/JSON)-encoded responses,
    
    - uses standard HTTP status codes and verbs, and
    
    - is designed to be easily integrated into any system.
    
    ## Italy specifications
    
      This API documentation specifically covers the Italian module, SIGN IT, that ensures compliance with Italian legislation for the telematic transmission of daily transactions. Compliance can be achieved through two different options: **SIGN IT** in its *lite* version or in its *full* version:
    
      - **SIGN IT** in its *lite* version connects your PoS with the Revenue Agencys web portal for the issuance of Online Commercial Documents, a [legally valid alternative](https://www.agenziaentrate.gov.it/portale/gli-strumenti-a-disposizione) to the telematic registers to issue compliant receipts.
      - **SIGN IT** in its *full* version will comply with the new generation of software fiscalization as described in article 24 of D lgs 1 - 2024.
    
      **SIGN IT** provides a test environment for integration and testing purposes as well as a dedicated live environment for performing the real-time sending of official transactions (commercial documents) to the Italian "Online commercial document" web procedure, present in the "Invoices and Fees" portal of the Revenue Agency. In order to access the live environment, please contact our [sales team](mailto:sales@fiskaly.com). 
    
    # Background
    
    **SIGN IT** implements legal requirements and technical guidelines for fiscalization compliance of PoS softwares in Italy.
    
    **SIGN IT** in its *lite* version is based on the following Italian regulation:
    - Legislative Decree no. 127/2015 for the "Telematic transmission of VAT operations and control of sales of goods carried out through automatic dispensers" for the technological tools that guarantee the inalterability and security of the data, mandatory since 2021 for all taxpayers issuing commercial documents.
    
    **SIGN IT** in its *full* version is based on the following Italian regulation:
    - [Article 24 of the Legislative Decree published on January 8, 2024](https://www.gazzettaufficiale.it/eli/id/2024/01/12/24G00007/SG). The electronic storage of the total amount and telematic transmission of daily fees may be performed by means of software solutions that guarantee the security and inalterability of the data. These solutions must be able to enable the full integration and interaction with electronic payment processes, in order to simplify and reduce the administrative operations for taxpayers.
    
    # Service
    
    Our fiskaly API service offers a compliance-as-a-service solution implementation that records business transaction, technical events, and taxpayer interactions in an inalterable and cryptographically secure way.
    
    ## Italy specifications
    
    The fiskaly SIGN IT [service](https://www.fiskaly.com/signit) provides a 100% legally compliant implementation in order to transmit the information from each transaction to the Revenue Agency in real time.
    
    ## Guides
    
    To ensure a smooth implementation of our fiskaly API, we highly recommend that you first have a look at our [integration guide](https://workspace.fiskaly.com/sign-it/2025-08-12/integration_guide) where you will find an explanation of how to create your organizational structure and API keys, as well as a first overview of our fiskaly API endpoints.
    
    ## Changes
    
    The up-to-date information below is organized in a change log format.
    
    ### <a name="2026-01-26"></a>[2026-01-26](#2026-01-26) Record transmission
    
    * More explicit error returned when submitting entries with mixed or wrong number for a `TRANSACTION::RECEIPT`
    * Improved description of `fiscalization.tax_id_number` and `fiscalization.credentials.tax_id_number`
    * Allow correction of receipt belonging to a different system
    * Record submission general latency and reliability improvements
    * Improved error message reported under the record logs property
    * Support authentication for more tax_id types ending with `-000` suffix
    * Reject receipts with negative amounts in test environment
    
    ### <a name="2025-12-30"></a>[2025-12-30](#2025-12-30) Improved Resource Checks
    
    * provided improved resource constraint checks for all update and retrieve endpoint operations
    * provided new `X-Trace-Identifier` in the OAS schema
    
    ### <a name="2025-12-23"></a>[2025-12-23](#2025-12-23) Entity, System, and Records
    
    * provided new `X-Trace-Identifier` for all HTTP service responses to support customer success communication
    * provided `entity` property to `updateSystem` to alter the entity connection of `System::FISCAL_DEVICE` resources in mode `SUSPENDED`
    * refined `ComplianceData` string length to maximum 128 characters
    * provided a new `TRANSACTION::ABORT` record schema to the `createRecord` endpoint to gracefully abort started sale (`INTENTION::TRANSACTION` records) operations
    
    ### <a name="2025-12-15"></a>[2025-12-15](#2025-12-15) File Streaming
    
    * refined `GET /files/<path>` (`streamFile`) functionality to download an arbitrary path
    * enabled downloading of signed integrity check JWS file from a dedicated automatic exported and archived ZIP file
    
    ### <a name="2025-12-12"></a>[2025-12-12](#2025-12-12) Archiving and Files
    
    * enabled automatic archiving support for French `System::FISCAL_DEVICE` resources based on `CLOSING::DAILY` computations
    * enabled `GET /files` (`listFiles`) endpoint to search for automatic exported and archived ZIP files
    * added pagination query parameters to `listFiles` endpoint
    * enabled `GET /files/<id>.zip` (`streamFile`) endpoint to download a dedicated automatic exported and archived ZIP file
    * improved `createToken` endpoint rate limit behavior
    
    ### <a name="2025-12-08"></a>[2025-12-08](#2025-12-08) Offline Record Replay
    
    * enabled `INTENTION::REPLAY` record functionality for offline-based recording support for France
    * updated `createToken` endpoint rate limit behavior
    * added support for new role selection flows in the AdE portal for Italian FISCONLINE credentials
    
    ### <a name="2025-12-01"></a>[2025-12-01](#2025-12-01) Record Export and Files
    
    * enabled `INTENTION::EXPORT` record creation support to generate dedicated system-based exports of records produced in a given time range with optional filter mechanism
    * added `INTENTION::REPLAY` record OAS schema design for offline-based recording support
    * added `streamFile` endpoint to download ZIP archive files from generated exports
    * added `listFiles` endpoint OAS design for listing and searching of file resources
    * added `data-artifact` query to fetch on demand data artifact information of a record
    * added `data-integrity` query to fetch on demand data integrity information of a record
    * provided `data` property for all `RecordResource` to provide data artifact and data integrity information of given record export ZIP archive and its current location `SERVICE` or `ARCHIVE`
    
    ### <a name="2025-11-27"></a>[2025-11-27](#2025-11-27) Record Integrity and Closing
    
    * enabled lower case characters for Italian tax identification number (codice fiscale)
    * enabled record file signed integrity check based on JSON Web Signature (JWS) information
    * enabled automatic closing functionality for French `System::FISCAL_DEVICE` resources
    * refined `RecordFileIntegrity` schema to provide dedicated `application/jose` MIME type
    * added `INTENTION::CLOSING`, `CLOSING::DAILY`, `CLOSING::MONTHLY`, and `CLOSING::YEARLY` system types
    * added `INFOCERT` as new French `fiscalization.credentials.provider`
    * added `429` error response for too many requests to all endpoints
    * added `used_in` connection on intention record to retrieve outcome records
    
    ### <a name="2025-09-29"></a>[2025-09-29](#2025-09-29) Entities and Records
    
    * added `fiscalization.fiscal_year_date` property in `POST /entities` and `PATCH /entities` for FR entities
    * provided journaling support for record creation of `INTENTION` type `EVENT` and `DUPLICATE`
    * provided journaling support for record creation of `TRANSACTION` type `DOWN_PAYMENT`, `PROOF_OF_PAYMENT`, `DRAFT_RECEIPT`, `PRO_FORMA_INVOICE`, `INVOICE`, and `ENRICHMENT`
    
    ### <a name="2025-09-08"></a>[2025-09-08](#2025-09-08) Entity Fiscalization
    
    * enabled configuration of `fiscalization.credentials.tax_id_number` in `POST /entities` and `PATCH /entities`
    
    ### <a name="2025-09-01"></a>[2025-09-01](#2025-09-01) Record Compliance Artifact
    
    * added record query `compliance-artifact` to obtain an existing compliance artifact
    * enabled production LIVE endpoint
    
    ### <a name="2025-08-12"></a>[2025-08-12](#2025-08-12) Entities & Records
    
    * enabled FR-based entity fiscalization configuration support
    * added record `TRANSACTION` type `DRAFT_RECEIPT` API schema
    * added record `TRANSACTION` type `INVOICE` API schema
    * added record `TRANSACTION` type `PRO_FORMA_INVOICE` API schema
    * added record `TRANSACTION` type `ENRICHMENT` API schema
    * added record `TRANSACTION` type `PROOF_OF_PAYMENT` API schema
    * added record `TRANSACTION` type `DOWN_PAYMENT` API schema
    * added record `INTENTION` type `EVENT` API schema
    * added record `INTENTION` type `EXPORT` API schema
    * added record `INTENTION` type `DUPLICATE` API schema
    * added record query `file-artifact` to obtain the signed record of the journal
    * added record query `operation` to obtain the raw record operation information
    
    ## Versioning
    
    Our fiskaly API follows [Calendar (Date-based) Versioning](https://calver.org/).
    The version number has a pattern of `YYYY-MM-DD` whereas the `YYYY` stands for the year, `MM` stands for the month, and `DD` stands for the day.
    
    The latest version is: `X-Api-Version: 2025-08-12`.
    
    | Version | Supported Country |
    | --- | --- |
    | `X-Api-Version: 2025-08-12` | SIGN IT 🇮🇹  SIGN FR 🇫🇷 |
    | `X-Api-Version: 2024-10-31` | SIGN IT 🇮🇹 |
    
    ## Idempotency
    
    Idempotency ensures that repeated identical requests produce the same result, even if they are retried due to network issues, timeouts, or other transient problems.
    This [idempotency](https://en.wikipedia.org/wiki/Idempotence) behavior prevents duplicate resource creation or unintended side effects in APIs that accept `POST` (creation) or `PATCH` (alteration) requests.
    
    The `X-Idempotency-Key` HTTP header in this API follows the principles of the Internet Engineering Task Force (IETF) [idempotency specification](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-05.txt) and plays a vital role in implementing idempotent requests.
    API clients use this header to uniquely identify requests, enabling the API to track and manage their outcomes across retries.
    
    The value of the HTTP header is a [Universally Unique Identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) -- version 3 or version 4 -- key provided by the client for each idempotent request.
    This key ensures that retries of the same request are recognized by the server.
    
    This key is **required for** all `POST` and `PATCH` requests.
    This key is **ignored for** all other HTTP request methods like `GET`, `PUT`, `DELETE` etc. since these are inherently idempotent by HTTP standards.
    
    Exception: The `POST /tokens` endpoint currently does not react on the provided `X-Idempotency-Key` HTTP header.
    This exception will be resolved by upcoming improvements to the API.
    
    The HTTP header format is defined as: `X-Idempotency-Key: <key>`.
    The `<key>` value shall be a valid and randomized `UUIDv4` string.
    Furthermore, this key shall be unique for each logically distinct request.
    
    The API service keeps track of the `X-Idempotency-Key` (key) and the associated request status, payload, and response (value) in a persistence cache.
    By default the stored idempotency key-value pairs expire after 24 hours (1 day) after their creation timestamp.
    If another request reaches the API service and there is already the same `X-Idempotency-Key` available, where the request method and payload are also equal to the cached value, the API service returns the cached response.
    
    If the API service returns:
    - `422 Unprocessable Entity`: Verify that the request headers and payload match exactly between retries. Ensure the idempotency key is not reused for unrelated operations.
    - `409 Conflict`: The request is already being processed. Wait before retrying and ensure there are no concurrent retries with the same idempotency key.
    
    # 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](https://www.getpostman.com/downloads/) application.<br><br>
    
    2. Create an **API Key** and **API Secret** via the [fiskaly dashboard](https://dashboard.fiskaly.com).<br><br>
    
    3. Insert your **API Key** and **API Secret** to download your personalized __fiskaly **SIGN IT** Postman Environment__ JSON based configuration file:
      <form action="/static/postman/fiskaly_sign_it_2025-08-12_postman_environment.json" method="get">
      <table>
      <tr>
      <th>API Key</th>
      <td><input type="text" name="api_key" placeholder="api_key" required=""></td>
      </tr><tr>
      <th>API Secret</th>
      <td><input type="password" name="api_secret" placeholder="api_secret" required=""></td>
      </tr>
      </table>
      <input type="submit" value="Download Postman Environment">
      </form><br>
    
    4. Download the __fiskaly **SIGN IT** Postman Collection__ JSON based configuration file:
      <form action="/static/postman/fiskaly_sign_it_2025-08-12_postman_collection.json" method="get">
      <input type="submit" value="Download Postman Collection">
      </form><br>
    
    5. Start Postman and import the downloaded Postman environment and collection files.<br><br>
    
    6. Select the fiskaly **SIGN IT** Postman environment and run the collection.<br><br>
    
    
    # FAQs
    
    We have a dedicated FAQ page for each country the fiskaly API service solution can be used and integrated: [SIGN IT 🇮🇹](https://support.fiskaly.com/hc/en-001/categories/14274771396636) and [SIGN FR 🇫🇷](https://support.fiskaly.com/hc/en-001/categories/21399793331484)
    
  x-logo:
    url: 'https://fiskaly.com/fiskaly_logo.svg'
    altText: 'fiskaly Logo'
tags:
  - name: 'Tokens'
    description: |
      In order to access the fiskaly API, a valid **JSON Web Token (JWT)** is required.
      The information carried inside the **JWT** is used for authentication and authorization of every request towards the fiskaly API.
      API requests without a **JWT** present will fail with an unauthorized access HTTP error `401`.xf
      
      A `Token` resource can be created by using the `key` and `secret` credentials information of an already existing `Subject::API_KEY`.
      The API key `secret` will be generated from the fiskaly API and provided only in the response of the `POST /tokens` request.
      
      Each `Token` resource has its own unique `id` in form of a [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122), the **JWT** `bearer` string, an `issued_at` timestamp, and an `expires_at` timestamp.
      Additionally, the `token` resource provides the information to which `Asset` and which `Subject` the token belongs to.
      
      The **JWT** `bearer` string must be sent with every following request in the HTTP `Authorization` header field using the `Bearer` [authentication scheme](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).
      
      The fiskaly API processes only `https` based requests.
      Plain `http` based requests are redirected to `https` by the fiskaly service.
      
  - name: 'Subjects'
    description: |
      A `Subject` represents an authenticated identity with defined access rights.
      
      Currently, the fiskaly API supports `Subject` resources of type `API_KEY` (`Subject::API_KEY`).
      The support for handling `Subject` resources of type `USER` (`Subject::USER`) is available soon.
      
      The `X-Scope-Identifier` HTTP header establishes the link between the `Subject` and the corresponding `Asset` resource.
      
  - name: 'Assets'
    description: |
      `Asset` resources are used to represent the management structure (organizational hierarchy):
      
      - `ACCOUNT` represents the PoS provider or a retailer that operates its own PoS system. It is the top-level asset in the structure. This type represents the first created account via the fiskaly Dashboard and cannot be created via the API.
      - `GROUP` an optional intermediate layer used to group multiple `Asset` resources of type `UNIT`.
      - `UNIT` represents a merchant.
      
  - name: 'Entities'
    description: |
      An `Entity` resource represents a particular `Asset::UNIT` with the relevant legal entity (taxpayer) data.
      A legal entity consists of two main parts: taxpayer information and country-specific fiscalization details.
      
      The lifecycle of an `Entity` resource is depicted in the following `state` and `mode` transitions:
      
      ![](https://dev.workspace.fiskaly.com/static/docs/entity_system_state_mode_en_it.png)
      
  - name: 'Systems'
    description: |
      A `System` represents an Electronic Recording System (ERS), such as a Point of Sale (PoS) or any other system capable of performing business operations.
      
      The lifecycle of a `System` resource is depicted in the following `state` and `mode` transitions:
      
      ![](https://dev.workspace.fiskaly.com/static/docs/entity_system_state_mode_en_it.png)
      
  - name: 'Records'
    description: |
      A `Record` represents a persisted and signed artifact of any kind interaction with a given `System` resource that is carried out through the fiskaly API.
      
      ![](https://workspace.fiskaly.com/static/docs/record_state_mode_en.png)
      
  - name: 'Files'
    description: |
      A `File` represents a save file resource.
      
x-tagGroups:
  - name: 'Management'
    tags:
      - 'Tokens'
      - 'Subjects'
      - 'Assets'
  - name: 'Operation'
    tags:
      - 'Entities'
      - 'Systems'
      - 'Records'
      - 'Files'
paths:
  /tokens:
    post:
      summary: 'Create a token'
      description: |
        This endpoint is used to create a `Token` resource.
        Currently, the fiskaly API supports an `Subject::API_KEY` based `Token` creation which returns the [JWT](#tag/Tokens) `bearer` HTTP authentication string that is valid until a given `expires_at` timestamp.
        
        Recreations of the new `Token` resource is required only then if the received [JWT](#tag/Tokens) `bearer` string has expired.
        
      tags:
        - 'Tokens'
      security: []
      operationId: createToken
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /subjects:
    get:
      summary: 'List subjects'
      description: |
        This endpoint is used to list `Subject` resources.
        
      tags:
        - 'Subjects'
      security:
        - JWT: []
      operationId: listSubjects
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/ScopeIdentifier'
        - $ref: '#/components/parameters/PaginationLimitQuery'
        - $ref: '#/components/parameters/PaginationTokenQuery'
      responses:
        '200':
          $ref: '#/components/responses/SubjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    post:
      summary: 'Create a subject'
      description: |
        A `Subject` represents an authenticated identity with defined access rights.
        
        Currently, the fiskaly API supports `Subject` resources of type `API_KEY` (`Subject::API_KEY`).
        The support for handling `Subject` resources of type `USER` (`Subject::USER`) is available soon.
        
        The `X-Scope-Identifier` HTTP header establishes the link between the `Subject` and the corresponding `Asset` resource.
        
      tags:
        - 'Subjects'
      security:
        - JWT: []
      operationId: createSubject
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/ScopeIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubjectCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/SubjectResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  '/subjects/{subject_id}':
    patch:
      summary: 'Update a subject
                '
      description: |
        This endpoint is used to update a `Subject` resource.
        
      tags:
        - 'Subjects'
      security:
        - JWT: []
      operationId: updateSubject
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/SubjectIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubjectUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/SubjectResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
    get:
      summary: 'Retrieve a subject
                '
      description: |
        This endpoint is used to retrieve a `Subject` resource.
        
      tags:
        - 'Subjects'
      security:
        - JWT: []
      operationId: retrieveSubject
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/SubjectIdentifier'
      responses:
        '200':
          $ref: '#/components/responses/SubjectResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  /assets:
    get:
      summary: 'List assets'
      description: |
        This endpoint is used to list `Asset` resources.
        
      tags:
        - 'Assets'
      security:
        - JWT: []
      operationId: listAssets
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/ScopeIdentifier'
        - $ref: '#/components/parameters/PaginationLimitQuery'
        - $ref: '#/components/parameters/PaginationTokenQuery'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    post:
      summary: 'Create an asset'
      description: |
        This endpoint is used to create `Asset` resources.
        
      tags:
        - 'Assets'
      security:
        - JWT: []
      operationId: createAsset
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/ScopeIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  '/assets/{asset_id}':
    patch:
      summary: 'Update an asset'
      description: |
        This endpoint is used to update an `Asset` resource.
        
      tags:
        - 'Assets'
      security:
        - JWT: []
      operationId: updateAsset
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/OrganizationIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
    get:
      summary: 'Retrieve an asset'
      description: |
        This endpoint is used to retrieve an `Asset` resource.
        
      tags:
        - 'Assets'
      security:
        - JWT: []
      operationId: retrieveAsset
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/OrganizationIdentifier'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  /entities:
    get:
      summary: 'List entities'
      description: |
        This endpoint is used to list `Entity` resources.
        
      tags:
        - 'Entities'
      security:
        - JWT: []
      operationId: listEntities
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/PaginationLimitQuery'
        - $ref: '#/components/parameters/PaginationTokenQuery'
      responses:
        '200':
          $ref: '#/components/responses/TaxpayersResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    post:
      summary: 'Create an entity'
      description: |
        This endpoint is used to create `Entity` resources. Currently the fiskaly API supports the following creation use cases:
        
        - legal entities (taxpayer) as a `COMPANY` (for business entities) or as an `INDIVIDUAL` (for self-employed) which require the details of the entity legal name, legal address, and fiscalization-related data such as the VAT number, tax identification number, and credentials for accessing the Revenue Agency portal.
        - `LOCATION` entities represent the physical address of the business premises or establishment of a given legal entity -- `COMPANY` or `INDIVIDUAL`
        
        When an `Entity` is created, its initial `state` is automatically set to `ACQUIRED`. In order to make it fully operational, the `state` must be updated to `COMMISSIONED` using the [updateEntity](#tag/Entities/operation/updateEntity) endpoint.
        
      tags:
        - 'Entities'
      security:
        - JWT: []
      operationId: createEntity
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxpayerCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/TaxpayerResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  '/entities/{entity_id}':
    patch:
      summary: 'Update an entity'
      description: |
        This endpoint is used to update an `Entity` resource.
        
        Please note that, for certain use cases, particular state and mode transitions are required. Please refer to our [Guide](https://workspace.fiskaly.com/sign-it/taxpayer_system_states_and_modes) for examples.
        
      tags:
        - 'Entities'
      security:
        - JWT: []
      operationId: updateEntity
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/TaxpayerIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxpayerUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/TaxpayerResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    get:
      summary: 'Retrieve an entity'
      description: |
        This endpoint is used to retrieve an `Entity` resource.
        
      tags:
        - 'Entities'
      security:
        - JWT: []
      operationId: retrieveEntity
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/TaxpayerIdentifier'
      responses:
        '200':
          $ref: '#/components/responses/TaxpayerResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /systems:
    get:
      summary: 'List systems'
      description: |
        This endpoint is used to list `System` resources.
        
      tags:
        - 'Systems'
      security:
        - JWT: []
      operationId: listSystems
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/PaginationLimitQuery'
        - $ref: '#/components/parameters/PaginationTokenQuery'
        - $ref: '#/components/parameters/TaxpayerIdentifierQuery'
        - $ref: '#/components/parameters/LocationIdentifierQuery'
      responses:
        '200':
          $ref: '#/components/responses/SystemsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    post:
      summary: 'Create a system'
      description: |
        This endpoint is used to create `System` resources.
        
      tags:
        - 'Systems'
      security:
        - JWT: []
      operationId: createSystem
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/SystemResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  '/systems/{system_id}':
    patch:
      summary: 'Update a system'
      description: |
        This endpoint is used to update `System` resources.
        
        Please note that, for certain use cases, particular state and mode transitions are required.
        Please refer to our [Guide](https://workspace.fiskaly.com/sign-it/taxpayer_system_states_and_modes) for examples.
        
      tags:
        - 'Systems'
      security:
        - JWT: []
      operationId: updateSystem
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/SystemIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/SystemResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
    get:
      summary: 'Retrieve a system'
      description: |
        This endpoint is used to retrieve `System` resources.
        
      tags:
        - 'Systems'
      security:
        - JWT: []
      operationId: retrieveSystem
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/SystemIdentifier'
      responses:
        '200':
          $ref: '#/components/responses/SystemResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  /records:
    get:
      summary: 'List records'
      description: |
        This endpoint is used to list `Record` resources.
        
      tags:
        - 'Records'
      security:
        - JWT: []
      operationId: listRecords
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/PaginationLimitQuery'
        - $ref: '#/components/parameters/PaginationTokenQuery'
        - $ref: '#/components/parameters/TaxpayerIdentifierQuery'
        - $ref: '#/components/parameters/LocationIdentifierQuery'
        - $ref: '#/components/parameters/SystemIdentifierQuery'
        - $ref: '#/components/parameters/RecordTypeQuery'
      responses:
        '200':
          $ref: '#/components/responses/RecordsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    post:
      summary: 'Create a record'
      description: |
        This endpoint is used to create `Record` resources.
        
        Every interaction with a `System` resource requires an initial `Record` creation of type `INTENTION` (`Record::INTENTION`).
        
        Currently the fiskaly API supports only an `INTENTION` of a `TRANSACTION` which reflects the interaction with a `System` resource right at the beginning of a purchase process.
        Directly after the payment process, the transaction can be concluded with a subsequent `Record` creation call providing the `TRANSACTION` information, containing details of a given business activity which links to the previous `Record::INTENTION::TRANSACTION`.
        
      tags:
        - 'Records'
      security:
        - JWT: []
      operationId: createRecord
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/ReplayRemaining'
        - $ref: '#/components/parameters/ReplayHash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/RecordResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
  '/records/{record_id}':
    patch:
      summary: 'Update a record'
      description: |
        This endpoint is used to update `Record` resources.
        
        Please note that currently all state and mode transitions are carried out by the fiskaly API service itself internally for `Record` resources.
        Please refer to our [Guide](https://workspace.fiskaly.com/sign-it/record_states_and_modes).
        
      tags:
        - 'Records'
      security:
        - JWT: []
      operationId: updateRecord
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RecordIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/RecordResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '409':
          $ref: '#/components/responses/ResourceConflictResponse'
        '422':
          $ref: '#/components/responses/UnprocessableContentResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '501':
          $ref: '#/components/responses/NotImplementedErrorResponse'
    get:
      summary: 'Retrieve a record'
      description: |
        This endpoint is used to retrieve `Record` resources.
        
      tags:
        - 'Records'
      security:
        - JWT: []
      operationId: retrieveRecord
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/RecordIdentifier'
        - $ref: '#/components/parameters/RecordOperationQuery'
        - $ref: '#/components/parameters/RecordFileArtifactQuery'
        - $ref: '#/components/parameters/RecordFileIntegrityQuery'
        - $ref: '#/components/parameters/RecordComplianceArtifactQuery'
        - $ref: '#/components/parameters/RecordDataArtifactQuery'
        - $ref: '#/components/parameters/RecordDataIntegrityQuery'
      responses:
        '200':
          $ref: '#/components/responses/RecordResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /files:
    get:
      summary: 'List files'
      description: |
        This endpoint is used to list `File` resources.
        
      tags:
        - 'Files'
      security:
        - JWT: []
      operationId: listFiles
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/PaginationLimitQuery'
        - $ref: '#/components/parameters/PaginationTokenQuery'
        - $ref: '#/components/parameters/SystemIdentifierQuery'
        - $ref: '#/components/parameters/FileCreatedStartQuery'
        - $ref: '#/components/parameters/FileCreatedEndQuery'
      responses:
        '200':
          $ref: '#/components/responses/FilesResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  '/files/{path}':
    get:
      summary: 'Stream a file'
      description: |
        This endpoint is used to stream a `File` content.
        
      tags:
        - 'Files'
      security:
        - JWT: []
      operationId: streamFile
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/FilePath'
      responses:
        '200':
          $ref: '#/components/responses/FileStream'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedAccessResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  parameters:
    ApiVersion:
      description: |
        The API version, see [versioning](#section/Service/Versioning).
        
      in: header
      name: X-Api-Version
      required: true
      schema:
        $ref: '#/components/schemas/ApiVersion'
    IdempotencyKey:
      description: |
        The idempotency key, see [idempotency](#section/Service/Idempotency).
        
      in: header
      name: X-Idempotency-Key
      required: true
      schema:
        $ref: '#/components/schemas/IdempotencyKey'
    ScopeIdentifier:
      description: |
        The `X-Scope-Identifier` header specifies the organization scope in which the request is executed. This ensures that the operation is linked to the correct organization within the organization hierarchy.
        
      in: header
      name: X-Scope-Identifier
      required: false
      schema:
        $ref: '#/components/schemas/ScopeIdentifier'
    ReplayRemaining:
      description: |
        Not supported in 🇮🇹 Italy - Current number of records left (only relevant for offline scenario)
        
      in: header
      name: X-Replay-Remaining
      schema:
        $ref: '#/components/schemas/ReplayRemaining'
    ReplayHash:
      description: |
        Not supported in 🇮🇹 Italy - The hash stored during offline phase in base64 format (only relevant for offline scenario)
        
      in: header
      name: X-Replay-Hash
      schema:
        $ref: '#/components/schemas/ReplayHash'
    SubjectIdentifier:
      description: |
        Subject identifier
        
      in: path
      name: subject_id
      required: true
      schema:
        $ref: '#/components/schemas/SubjectIdentifier'
    OrganizationIdentifier:
      description: |
        Organization identifier
        
      in: path
      name: asset_id
      required: true
      schema:
        $ref: '#/components/schemas/OrganizationIdentifier'
    TaxpayerIdentifier:
      description: |
        Taxpayer identifier
        
      in: path
      name: entity_id
      required: true
      schema:
        $ref: '#/components/schemas/TaxpayerIdentifier'
    LocationIdentifier:
      description: |
        oas_components_parameters_location_identifier_description
      in: path
      name: location_id
      required: true
      schema:
        $ref: '#/components/schemas/LocationIdentifier'
    SystemIdentifier:
      description: |
        System identifier
        
      in: path
      name: system_id
      required: true
      schema:
        $ref: '#/components/schemas/SystemIdentifier'
    RecordIdentifier:
      description: |
        Record identifier
        
      in: path
      name: record_id
      required: true
      schema:
        $ref: '#/components/schemas/RecordIdentifier'
    FilePath:
      description: |
        oas_components_parameters_file_path_description
      in: path
      name: path
      required: true
      schema:
        $ref: '#/components/schemas/Path'
    FileCreatedStartQuery:
      description: |
        Defines the start date and time
        
      in: query
      name: start
      required: false
      schema:
        $ref: '#/components/schemas/FileCreationTimestamp'
    FileCreatedEndQuery:
      description: |
        Defines the end date and time
        
      in: query
      name: end
      required: false
      schema:
        $ref: '#/components/schemas/FileCreationTimestamp'
    PaginationLimitQuery:
      description: |
        Represents the pagination limit of the results set of a listing endpoint.
        
      in: query
      name: limit
      required: false
      schema:
        $ref: '#/components/schemas/PaginationLimit'
    PaginationTokenQuery:
      description: |
        Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.  
        
      in: query
      name: token
      required: false
      schema:
        $ref: '#/components/schemas/PaginationToken'
    TaxpayerIdentifierQuery:
      description: |
        Taxpayer identifier
        
      in: query
      name: entity_id
      required: false
      schema:
        $ref: '#/components/schemas/TaxpayerIdentifier'
    LocationIdentifierQuery:
      description: |
        oas_components_parameters_location_identifier_query_description
      in: query
      name: location_id
      required: false
      schema:
        $ref: '#/components/schemas/LocationIdentifier'
    SystemIdentifierQuery:
      description: |
        System identifier
        
      in: query
      name: system_id
      required: false
      schema:
        $ref: '#/components/schemas/SystemIdentifier'
    RecordTypeQuery:
      description: |
        oas_components_parameters_record_type_query_description
      in: query
      name: type
      required: false
      style: form
      explode: false
      schema:
        type: array
        uniqueItems: true
        minItems: 1
        maxItems: 10
        items:
          $ref: '#/components/schemas/SystemRecordType'
    RecordOperationQuery:
      description: |
        Defines the operation.
        
      in: query
      name: operation
      required: false
      allowEmptyValue: true
      schema:
        type: string
        enum:
          - ''
    RecordFileArtifactQuery:
      description: |
        oas_components_parameters_record_file_artifact_query_description
      in: query
      name: file-artifact
      required: false
      allowEmptyValue: true
      schema:
        type: string
        enum:
          - ''
    RecordFileIntegrityQuery:
      description: |
        oas_components_parameters_record_file_integrity_query_description
      in: query
      name: file-integrity
      required: false
      allowEmptyValue: true
      schema:
        type: string
        enum:
          - ''
    RecordDataArtifactQuery:
      description: |
        oas_components_parameters_record_data_artifact_query_description
      in: query
      name: data-artifact
      required: false
      allowEmptyValue: true
      schema:
        type: string
        enum:
          - ''
    RecordDataIntegrityQuery:
      description: |
        oas_components_parameters_record_data_integrity_query_description
      in: query
      name: data-integrity
      required: false
      allowEmptyValue: true
      schema:
        type: string
        enum:
          - ''
    RecordComplianceArtifactQuery:
      description: |
        oas_components_parameters_record_compliance_artifact_query_description
      in: query
      name: compliance-artifact
      required: false
      allowEmptyValue: true
      schema:
        type: string
        enum:
          - ''
    TraceIdentifier:
      description: |
        oas_components_parameters_trace_identifier_description
      in: header
      name: X-Trace-Identifier
      required: true
      schema:
        $ref: '#/components/schemas/TraceIdentifier'
  responses:
    TokenResponse:
      description: |
        Token Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenResource'
    SubjectsResponse:
      description: |
        Subjects Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubjectResources'
    SubjectResponse:
      description: |
        Subject Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Scope-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/ScopeIdentifier'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubjectResource'
    OrganizationsResponse:
      description: |
        Organizations Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationResources'
    OrganizationResponse:
      description: |
        Organization Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Scope-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/ScopeIdentifier'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationResource'
    TaxpayersResponse:
      description: |
        Taxpayers Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TaxpayerResources'
    TaxpayerResponse:
      description: |
        Taxpayer Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TaxpayerResource'
    LocationsResponse:
      description: |
        oas_components_responses_locations_response_description
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LocationResources'
    LocationResponse:
      description: |
        oas_components_responses_location_response_description
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LocationResource'
    SystemsResponse:
      description: |
        Systems Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SystemResources'
    SystemResponse:
      description: |
        System Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SystemResource'
    RecordsResponse:
      description: |
        Records Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RecordResources'
    FilesResponse:
      description: |
        Files Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FileResources'
    FileStream:
      description: |
        Returns the attachment of the file
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
        Content-Disposition:
          schema:
            type: string
          description: |
            Returns the attachment of the file
            
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary
    RecordResponse:
      description: |
        Record Response
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RecordResource'
    BadRequestResponse:
      description: |
        Bad Request
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    UnauthorizedAccessResponse:
      description: |
        Unauthorized Access
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    ResourceNotFoundResponse:
      description: |
        Resource Not Found
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    ResourceConflictResponse:
      description: |
        Resource Conflict
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    UnprocessableContentResponse:
      description: |
        Unprocessable Content
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    MethodNotAllowedResponse:
      description: |
        Method Not Allowed
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    TooManyRequestsResponse:
      description: |
        Too Many Requests
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    InternalServerErrorResponse:
      description: |
        Internal Server Error
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
    NotImplementedErrorResponse:
      description: |
        Not Implemented
        
      headers:
        X-Api-Version:
          required: true
          schema:
            $ref: '#/components/schemas/ApiVersion'
        X-Trace-Identifier:
          required: true
          schema:
            $ref: '#/components/schemas/TraceIdentifier'
      content:
        application/json:
          schema:
            type: object
            required:
              - content
            properties:
              content:
                $ref: '#/components/schemas/ErrorResponse'
            additionalProperties: false
  schemas:
    ApiVersion:
      allOf:
        - $ref: '#/components/schemas/DateFormatISO8601'
    IdempotencyKey:
      oneOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV4'
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV3'
    ReplayRemaining:
      allOf:
        - $ref: '#/components/schemas/UnsignedInteger4'
    ReplayHash:
      allOf:
        - $ref: '#/components/schemas/PlainString64'
    ScopeIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV4'
    TokenIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV4'
    SubjectIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV4'
    OrganizationIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV4'
    TaxpayerIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV7'
    LocationIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV7'
    SystemIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV7'
    RecordIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV7'
    FileIdentifier:
      allOf:
        - $ref: '#/components/schemas/UniversallyUniqueIdentifierV7'
    Path:
      type: string
      minLength: 1
      maxLength: 44
      example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f.zip
      pattern: '^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}\.zip(\.jws)?$'
    TraceIdentifier:
      type: string
    TokenCreateRequest:
      description: |
        oas_components_schemas_token_create_request_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/TokenCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    TokenResource:
      description: |
        oas_components_schemas_token_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/TokenContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    TokenCreateContent:
      description: |
        Defines the structure required to create the token.
        
      discriminator:
        propertyName: type
        mapping:
          API_KEY: '#/components/schemas/ApiKeyToken'
      oneOf:
        - $ref: '#/components/schemas/ApiKeyToken'
    TokenContent:
      allOf:
        - $ref: '#/components/schemas/Token'
    Token:
      description: |
        Defines the structure returned in the response when creating the token.
        
      type: object
      required:
        - id
        - authentication
        - organization
        - subject
      properties:
        id:
          $ref: '#/components/schemas/TokenIdentifier'
        authentication:
          $ref: '#/components/schemas/TokenAuthentication'
        organization:
          $ref: '#/components/schemas/OrganizationConnection'
        subject:
          $ref: '#/components/schemas/SubjectConnection'
      additionalProperties: false
    TokenAuthentication:
      description: |
        Token authentication
        
      discriminator:
        propertyName: type
        mapping:
          JWT: '#/components/schemas/JsonWebTokenAuthentication'
      oneOf:
        - $ref: '#/components/schemas/JsonWebTokenAuthentication'
    JsonWebTokenAuthentication:
      description: |
        oas_components_schemas_json_web_token_authentication_description
      type: object
      required:
        - type
        - bearer
        - expires_at
        - issued_at
      properties:
        type:
          type: string
          enum:
            - JWT
        bearer:
          $ref: '#/components/schemas/TokenBearer'
        expires_at:
          $ref: '#/components/schemas/TokenExpirationTimestamp'
        issued_at:
          $ref: '#/components/schemas/TokenIssuingTimestamp'
      additionalProperties: false
    TokenBearer:
      description: |
        Token bearer
        
      allOf:
        - $ref: '#/components/schemas/Bearer'
    TokenExpirationTimestamp:
      description: |
        Token expiration timestamp
        
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    TokenIssuingTimestamp:
      description: |
        Token issuing timestamp
        
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    ApiKeyToken:
      description: |
        oas_components_schemas_api_key_token_description
      type: object
      required:
        - type
        - key
        - secret
      properties:
        type:
          type: string
          enum:
            - API_KEY
        key:
          $ref: '#/components/schemas/ApiKeyString'
        secret:
          $ref: '#/components/schemas/ApiSecretString'
      additionalProperties: false
    SubjectCreateRequest:
      description: |
        oas_components_schemas_subject_create_request_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/SubjectCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    SubjectUpdateRequest:
      description: |
        oas_components_schemas_subject_update_request_description
      type: object
      properties:
        content:
          $ref: '#/components/schemas/SubjectUpdateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    SubjectResource:
      description: |
        oas_components_schemas_subject_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/SubjectContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    SubjectResources:
      description: |
        oas_components_schemas_subject_resources_description
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubjectResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    SubjectCreateContent:
      description: |
        Defines the structure required to create the token.
        
      discriminator:
        propertyName: type
        mapping:
          API_KEY: '#/components/schemas/ApiKeySubject'
      oneOf:
        - $ref: '#/components/schemas/ApiKeySubject'
    SubjectUpdateContent:
      description: |
        Defines the structure required to update the token.
        
      type: object
      properties:
        name:
          $ref: '#/components/schemas/SubjectName'
      additionalProperties: false
    SubjectContent:
      allOf:
        - $ref: '#/components/schemas/Subjects'
        - $ref: '#/components/schemas/Subject'
    Subjects:
      oneOf:
        - $ref: '#/components/schemas/ApiKeySubject'
    Subject:
      description: |
        Defines the structure returned in the response when creating the Subject
        
      type: object
      required:
        - id
        - state
      properties:
        id:
          $ref: '#/components/schemas/SubjectIdentifier'
        state:
          $ref: '#/components/schemas/SubjectState'
        credentials:
          $ref: '#/components/schemas/SubjectCredentials'
      additionalProperties: false
    SubjectState:
      description: |
        Subject state
        
      type: string
      enum:
        - ENABLED
        - DISABLED
    SubjectConnection:
      description: |
        Connection to an already created subject
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/SubjectIdentifier'
      additionalProperties: false
    SubjectCredentials:
      description: |
        Subject credentials
        
      type: object
      required:
        - key
      properties:
        key:
          $ref: '#/components/schemas/SubjectKey'
        secret:
          $ref: '#/components/schemas/SubjectSecret'
      additionalProperties: false
    SubjectName:
      description: |
        API Key name
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    SubjectKey:
      description: |
        Subject key
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    SubjectSecret:
      description: |
        Subject secret
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    ApiKeySubject:
      description: |
        oas_components_schemas_api_key_subject_description
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - API_KEY
        name:
          $ref: '#/components/schemas/ApiKeySubjectName'
      additionalProperties: false
    ApiKeySubjectName:
      description: |
        API Key name
        
      type: string
      pattern: '^[a-z0-9\-]{3,30}$'
      minLength: 3
      maxLength: 30
      example: my-api-key-0
    OrganizationCreateRequest:
      description: |
        oas_components_schemas_organization_create_request_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/OrganizationCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    OrganizationUpdateRequest:
      description: |
        oas_components_schemas_organization_update_request_description
      type: object
      properties:
        content:
          $ref: '#/components/schemas/OrganizationUpdateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    OrganizationResource:
      description: |
        oas_components_schemas_organization_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/OrganizationContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    OrganizationResources:
      description: |
        oas_components_schemas_organization_resources_description
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    OrganizationCreateContent:
      description: |
        Defines the structure required to create an Organization.
        
      discriminator:
        propertyName: type
        mapping:
          UNIT: '#/components/schemas/UnitOrganization'
          GROUP: '#/components/schemas/GroupOrganization'
      oneOf:
        - $ref: '#/components/schemas/UnitOrganization'
        - $ref: '#/components/schemas/GroupOrganization'
    OrganizationUpdateContent:
      description: |
        Defines the structure required to update an Organization.
        
      type: object
      properties:
        name:
          $ref: '#/components/schemas/OrganizationName'
      additionalProperties: false
    OrganizationContent:
      allOf:
        - $ref: '#/components/schemas/Organizations'
        - $ref: '#/components/schemas/Organization'
    Organizations:
      oneOf:
        - $ref: '#/components/schemas/UnitOrganization'
        - $ref: '#/components/schemas/GroupOrganization'
        - $ref: '#/components/schemas/AccountOrganization'
    Organization:
      description: |
        Defines the structure of an organization returned in the response.
        
      type: object
      required:
        - id
        - state
      properties:
        id:
          $ref: '#/components/schemas/OrganizationIdentifier'
        state:
          $ref: '#/components/schemas/OrganizationState'
        organization:
          $ref: '#/components/schemas/OrganizationConnection'
      additionalProperties: false
    OrganizationName:
      description: |
        Organization name
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    OrganizationState:
      description: |
        Organization state
        
      type: string
      enum:
        - ENABLED
        - DISABLED
    OrganizationConnection:
      description: |
        Connection to an already created organization.
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/OrganizationIdentifier'
      additionalProperties: false
    AccountOrganization:
      description: |
        Organization of type ACCOUNT representing the top level organization.
        
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - ACCOUNT
        name:
          $ref: '#/components/schemas/OrganizationName'
      additionalProperties: false
    GroupOrganization:
      description: |
        Organization of type GROUP representing an optional grouping layer.
        
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - GROUP
        name:
          $ref: '#/components/schemas/OrganizationName'
      additionalProperties: false
    UnitOrganization:
      description: |
        Organization of type UNIT representing a merchant
        
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - UNIT
        name:
          $ref: '#/components/schemas/OrganizationName'
      additionalProperties: false
    TaxpayerCreateRequest:
      description: |
        Request body schema to create a Taxpayer
        
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/TaxpayerCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    TaxpayerUpdateRequest:
      description: |
        Request body schema to update a Taxpayer
        
      type: object
      properties:
        content:
          $ref: '#/components/schemas/TaxpayerUpdateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    TaxpayerResource:
      description: |
        Schema of a single Taxpayer resource.
        
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/TaxpayerContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    TaxpayerResources:
      description: |
        Collection of Taxpayer resources returned by list endpoints.
        
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/TaxpayerResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    TaxpayerCreateContent:
      description: |
        Defines the structure required to create a Taxpayer.
        
      discriminator:
        propertyName: type
        mapping:
          COMPANY: '#/components/schemas/CompanyTaxpayer'
          INDIVIDUAL: '#/components/schemas/IndividualTaxpayer'
      oneOf:
        - $ref: '#/components/schemas/CompanyTaxpayer'
        - $ref: '#/components/schemas/IndividualTaxpayer'
    TaxpayerUpdateContent:
      description: |
        Defines the structure required to update a Taxpayer.
        
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TaxpayerType'
        state:
          $ref: '#/components/schemas/TaxpayerState'
        mode:
          $ref: '#/components/schemas/TaxpayerMode'
        fiscalization:
          $ref: '#/components/schemas/TaxpayerFiscalization'
        name:
          $ref: '#/components/schemas/TaxpayerName'
        address:
          $ref: '#/components/schemas/Address'
      additionalProperties: false
    TaxpayerContent:
      allOf:
        - $ref: '#/components/schemas/Taxpayers'
        - $ref: '#/components/schemas/Taxpayer'
    Taxpayers:
      oneOf:
        - $ref: '#/components/schemas/CompanyTaxpayer'
        - $ref: '#/components/schemas/IndividualTaxpayer'
    Taxpayer:
      description: |
        Taxpayer
        
      type: object
      required:
        - id
        - state
        - mode
        - country
        - locations
      properties:
        id:
          $ref: '#/components/schemas/TaxpayerIdentifier'
        state:
          $ref: '#/components/schemas/TaxpayerState'
        mode:
          $ref: '#/components/schemas/TaxpayerMode'
        country:
          $ref: '#/components/schemas/TaxpayerCountry'
        locations:
          $ref: '#/components/schemas/TaxpayerLocations'
        vat_number:
          $ref: '#/components/schemas/TaxpayerVatNumber'
        created_at:
          $ref: '#/components/schemas/TaxpayerCreatedAt'
        updated_at:
          $ref: '#/components/schemas/TaxpayerUpdatedAt'
      additionalProperties: false
    TaxpayerState:
      description: |
        Taxpayer state
        
      type: string
      enum:
        - ACQUIRED
        - COMMISSIONED
        - DECOMMISSIONED
    TaxpayerMode:
      description: |
        Taxpayer mode
        
      type: string
      enum:
        - INACTIVE
        - OPERATIVE
        - SUSPENDED
        - DEGRADED
    TaxpayerFiscalization:
      anyOf:
        - $ref: '#/components/schemas/CompanyFiscalization'
        - $ref: '#/components/schemas/IndividualFiscalization'
    TaxpayerCountry:
      description: |
        Country where the taxpayer is registered
        
      oneOf:
        - $ref: '#/components/schemas/PlainString128'
    TaxpayerVatNumber:
      description: |
        VAT Identification Number of the taxpayer
        
      type: string
      pattern: '^([A-Za-z0-9-]{1,20})$'
      minLength: 1
      maxLength: 20
      example: FR12345678901
    TaxpayerLocations:
      description: |
        oas_components_schemas_taxpayer_locations_description
      type: array
      items:
        $ref: '#/components/schemas/TaxpayerLocation'
    TaxpayerLocation:
      description: |
        oas_components_schemas_taxpayer_location_description
      type: object
      required:
        - type
        - description
      properties:
        type:
          $ref: '#/components/schemas/TaxpayerLocationType'
        description:
          $ref: '#/components/schemas/TaxpayerLocationDescription'
      additionalProperties: false
    TaxpayerLocationType:
      description: |
        oas_components_schemas_taxpayer_location_type_description
      type: string
      enum:
        - HEAD_OFFICE
        - BRANCH
    TaxpayerLocationDescription:
      description: |
        oas_components_schemas_taxpayer_location_description_description
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    TaxpayerUpdatedAt:
      description: |
        oas_components_schemas_taxpayer_updated_at_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    TaxpayerCreatedAt:
      description: |
        oas_components_schemas_taxpayer_created_at_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    CompanyTaxpayer:
      description: |
        oas_components_schemas_company_taxpayer_description
      type: object
      required:
        - type
        - name
        - address
      properties:
        type:
          type: string
          enum:
            - COMPANY
        name:
          $ref: '#/components/schemas/CompanyName'
        address:
          $ref: '#/components/schemas/CompanyAddress'
        fiscalization:
          $ref: '#/components/schemas/CompanyFiscalization'
      additionalProperties: false
    CompanyName:
      description: |
        Company name
        
      type: object
      required:
        - legal
        - trade
      properties:
        legal:
          $ref: '#/components/schemas/LegalName'
        trade:
          $ref: '#/components/schemas/TradeName'
      additionalProperties: false
    LegalName:
      description: |
        Legal name of the company
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    TradeName:
      description: |
        Trade name of the company
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    CompanyAddress:
      description: |
        Legal address of the company
        
      allOf:
        - $ref: '#/components/schemas/LegalAddress'
    LegalAddress:
      description: |
        Recipient address data
        
      allOf:
        - $ref: '#/components/schemas/Address'
    IndividualTaxpayer:
      description: |
        oas_components_schemas_individual_taxpayer_description
      type: object
      required:
        - type
        - name
        - address
      properties:
        type:
          type: string
          enum:
            - INDIVIDUAL
        name:
          $ref: '#/components/schemas/IndividualName'
        address:
          $ref: '#/components/schemas/IndividualAddress'
        fiscalization:
          $ref: '#/components/schemas/IndividualFiscalization'
      additionalProperties: false
    IndividualName:
      description: |
        Individual taxpayer name
        
      type: object
      required:
        - legal
        - person
      properties:
        legal:
          $ref: '#/components/schemas/LegalName'
        person:
          $ref: '#/components/schemas/PersonName'
      additionalProperties: false
    IndividualAddress:
      description: |
        Legal address of an individual taxpayer
        
      allOf:
        - $ref: '#/components/schemas/Address'
    TaxpayerName:
      description: |
        Taxpayer name
        
      oneOf:
        - $ref: '#/components/schemas/CompanyName'
        - $ref: '#/components/schemas/IndividualName'
    TaxpayerType:
      description: |
        Details specific to the taxpayer type
        
      type: string
      enum:
        - COMPANY
        - INDIVIDUAL
    CompanyFiscalization:
      description: |
        Country-specific fiscalization information for a company. <br>
        🇮🇹 Use the type `IT` for Italy.
        
      discriminator:
        propertyName: type
        mapping:
          FR: '#/components/schemas/FrenchFiscalization'
          IT: '#/components/schemas/ItalianFiscalization'
          BE: '#/components/schemas/BelgianFiscalization'
      oneOf:
        - $ref: '#/components/schemas/FrenchFiscalization'
        - $ref: '#/components/schemas/ItalianFiscalization'
        - $ref: '#/components/schemas/BelgianFiscalization'
    IndividualFiscalization:
      description: |
        Country-specific fiscalization information for an individual. <br>
        🇮🇹 Use the type `IT` for Italy.
        
      discriminator:
        propertyName: type
        mapping:
          FR: '#/components/schemas/FrenchFiscalization'
          IT: '#/components/schemas/ItalianFiscalization'
          BE: '#/components/schemas/BelgianFiscalization'
      oneOf:
        - $ref: '#/components/schemas/ItalianFiscalization'
        - $ref: '#/components/schemas/FrenchFiscalization'
        - $ref: '#/components/schemas/BelgianFiscalization'
    ItalianFiscalization:
      description: |
        oas_components_schemas_italian_fiscalization_description
      type: object
      required:
        - type
        - tax_id_number
        - vat_id_number
        - credentials
      properties:
        type:
          type: string
          enum:
            - IT
        tax_id_number:
          $ref: '#/components/schemas/ItalianTaxIdentificationNumber'
        vat_id_number:
          $ref: '#/components/schemas/ItalianVatIdentificationNumber'
        credentials:
          $ref: '#/components/schemas/ItalianCredentials'
      additionalProperties: false
    ItalianTaxIdentificationNumber:
      description: |
        Italian Tax code (“Codice fiscale”) of the business registered with the Italian Revenue Agency (Agenzia delle Entrate).
        
        For COMPANY entities, it consists of 11 numeric digits. <br>
        For INDIVIDUAL entities, it consists of 16 alphanumeric characters.
        
      type: string
      pattern: '^[0-9]{11}|[0-9A-Za-z]{16}'
      minLength: 11
      maxLength: 16
      example: LLLLLL99L99L999L
    ItalianPersonalTaxIdentificationNumber:
      description: |
        Italian Tax code (“Codice fiscale”) of the natural person authorised to access the Agenzia delle Entrate (AdE) portal using Fisconline credentials and to operate on behalf of the business. It consists of 16 alphanumeric characters. 
        
        **Recommended**: Provide this field explicitly. If omitted, it will be automatically populated from `fiscalization.tax_id_number`. However, this fallback value may not always match the specific requirements of this field and can cause issues during Entity commissioning and/or Record submission. 
        
      type: string
      minLength: 16
      maxLength: 16
      example: LLLLLL99L99L999L
    ItalianVatIdentificationNumber:
      description: |
        Italian VAT identification number (VATIN). Partita IVA. 11-digit code that uniquely identifies all operators who carry out economic activities in Italy.
        
      type: string
      pattern: '^([0-9]{11})$'
      minLength: 11
      maxLength: 11
      example: '99999999999'
    ItalianCredentials:
      description: |
        Italian fiscalization credentials
        
      discriminator:
        propertyName: type
        mapping:
          FISCONLINE: '#/components/schemas/ItalianFisconlineCredentials'
      oneOf:
        - $ref: '#/components/schemas/ItalianFisconlineCredentials'
    ItalianFisconlineCredentials:
      description: |
        FISCONLINE Credential
        
      type: object
      required:
        - type
        - pin
        - password
        - tax_id_number
      properties:
        type:
          type: string
          enum:
            - FISCONLINE
        pin:
          $ref: '#/components/schemas/ItalianFisconlinePersonalIdentificationNumber'
        password:
          $ref: '#/components/schemas/ItalianFisconlinePassword'
        tax_id_number:
          $ref: '#/components/schemas/ItalianPersonalTaxIdentificationNumber'
      additionalProperties: false
    ItalianFisconlinePersonalIdentificationNumber:
      description: |
        Italian Fisconline personal identification number
        
      type: string
      minLength: 1
      maxLength: 10
    ItalianFisconlinePassword:
      description: |
        Italian Fisconline password
        
      type: string
      minLength: 1
      maxLength: 50
    FrenchFiscalization:
      description: |
        oas_components_schemas_french_fiscalization_description
      type: object
      required:
        - type
        - tax_id_number
        - credentials
      properties:
        type:
          type: string
          enum:
            - FR
        tax_id_number:
          $ref: '#/components/schemas/FrenchTaxIdentificationNumber'
        fiscal_year_date:
          $ref: '#/components/schemas/FiscalYearDate'
        credentials:
          $ref: '#/components/schemas/FrenchCredentials'
      additionalProperties: false
    FrenchTaxIdentificationNumber:
      description: |
        French company identification number (SIREN number) issued by INSEE and consisting of 9 characters
        
      type: string
      pattern: '^([0-9]{9})$'
      minLength: 9
      maxLength: 9
      example: '123456789'
    FrenchCredentials:
      description: |
        French fiscalization credentials
        
      discriminator:
        propertyName: type
        mapping:
          LNE: '#/components/schemas/FrenchLneCredentials'
          INFOCERT: '#/components/schemas/FrenchInfocertCredentials'
      oneOf:
        - $ref: '#/components/schemas/FrenchLneCredentials'
        - $ref: '#/components/schemas/FrenchInfocertCredentials'
    FrenchLneCredentials:
      description: |
        oas_components_schemas_french_lne_credentials_description
      type: object
      required:
        - type
        - properties
      properties:
        type:
          type: string
          enum:
            - LNE
        properties:
          $ref: '#/components/schemas/TaxpayerProperties'
      additionalProperties: false
    FrenchInfocertCredentials:
      description: |
        oas_components_schemas_french_infocert_credentials_description
      type: object
      required:
        - type
        - properties
      properties:
        type:
          type: string
          enum:
            - INFOCERT
        certificate_code:
          $ref: '#/components/schemas/FrenchInfocertCertificateCode'
        properties:
          $ref: '#/components/schemas/TaxpayerProperties'
      additionalProperties: false
    FrenchInfocertCertificateCode:
      description: |
        oas_components_schemas_french_infocert_certificate_code_description
      type: string
      pattern: '^[AB][0-9]{1,4}$'
      minLength: 2
      maxLength: 5
      example: B9999
    TaxpayerProperties:
      description: |
        Additional company or individual properties<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 32
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    FiscalYearDate:
      description: |
        Defines the start of the fiscal year date. By default the calender year start date `01-01` is used.
              type: string
      pattern: '^(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$'
      minLength: 5
      maxLength: 5
      example: 07-14
    BelgianFiscalization:
      description: |
        oas_components_schemas_belgian_fiscalization_description
      type: object
      required:
        - type
        - tax_id_number
        - vat_id_number
        - credentials
      properties:
        type:
          type: string
          enum:
            - BE
        tax_id_number:
          $ref: '#/components/schemas/BelgianTaxIdentificationNumber'
        vat_id_number:
          $ref: '#/components/schemas/BelgianVatIdentificationNumber'
        credentials:
          $ref: '#/components/schemas/BelgianCredentials'
      additionalProperties: false
    BelgianTaxIdentificationNumber:
      description: |
        The Belgian Enterprise Number must be the KBO/BCE identifier issued by the Crossroads Bank for Enterprises.
        
      type: string
      pattern: '^[01]?\d{9}$'
      minLength: 9
      maxLength: 10
      example: '1234567890'
    BelgianVatIdentificationNumber:
      description: |
        The Belgian VAT identification number (VATIN) is a BE-prefixed code that uniquely identifies operators conducting economic activities in Belgium.
        
      type: string
      pattern: '^([0-9]{10})$'
      minLength: 10
      maxLength: 10
      example: '1403019261'
    BelgianCredentials:
      description: |
        Belgian fiscalization credentials
        
      discriminator:
        propertyName: type
        mapping:
          MYMINFIN: '#/components/schemas/BelgianMyminifinCredentials'
      oneOf:
        - $ref: '#/components/schemas/BelgianMyminifinCredentials'
    BelgianMyminifinCredentials:
      description: |
        oas_components_schemas_belgian_myminifin_credentials_description
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - MYMINFIN
      additionalProperties: false
    LocationCreateRequest:
      description: |
        oas_components_schemas_location_create_request_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/LocationCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    LocationUpdateRequest:
      description: |
        oas_components_schemas_location_update_request_description
      type: object
      properties:
        content:
          $ref: '#/components/schemas/LocationUpdateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    LocationResource:
      description: |
        oas_components_schemas_location_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/LocationContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    LocationResources:
      description: |
        oas_components_schemas_location_resources_description
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/LocationResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    LocationCreateContent:
      description: |
        Defines the structure required to create a location.
        
      discriminator:
        propertyName: type
        mapping:
          BRANCH: '#/components/schemas/BranchLocation'
      oneOf:
        - $ref: '#/components/schemas/BranchLocation'
    LocationUpdateContent:
      description: |
        oas_components_schemas_location_update_content_description
      type: object
      properties:
        state:
          $ref: '#/components/schemas/LocationState'
        mode:
          $ref: '#/components/schemas/LocationMode'
        taxpayer:
          $ref: '#/components/schemas/LocationTaxpayer'
        name:
          $ref: '#/components/schemas/LocationName'
        address:
          $ref: '#/components/schemas/Address'
        coordinates:
          $ref: '#/components/schemas/LocationCoordinates'
        label:
          $ref: '#/components/schemas/LocationLabel'
      additionalProperties: false
    LocationContent:
      allOf:
        - $ref: '#/components/schemas/Locations'
        - $ref: '#/components/schemas/Location'
    Locations:
      oneOf:
        - $ref: '#/components/schemas/HeadOfficeLocation'
        - $ref: '#/components/schemas/BranchLocation'
    Location:
      description: |
        oas_components_schemas_location_description
      type: object
      required:
        - id
        - state
        - mode
        - systems
      properties:
        id:
          $ref: '#/components/schemas/LocationIdentifier'
        state:
          $ref: '#/components/schemas/LocationState'
        mode:
          $ref: '#/components/schemas/LocationMode'
        systems:
          $ref: '#/components/schemas/LocationSystems'
        created_at:
          $ref: '#/components/schemas/LocationCreatedAt'
        updated_at:
          $ref: '#/components/schemas/LocationUpdatedAt'
      additionalProperties: false
    LocationState:
      description: |
        oas_components_schemas_location_state_description
      type: string
      enum:
        - ACQUIRED
        - COMMISSIONED
        - DECOMMISSIONED
    LocationMode:
      description: |
        oas_components_schemas_location_mode_description
      type: string
      enum:
        - INACTIVE
        - OPERATIVE
        - SUSPENDED
        - DEGRADED
    LocationTaxpayer:
      description: |
        Connection to an already created taxpayer.
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/TaxpayerIdentifier'
      additionalProperties: false
    LocationSystems:
      description: |
        oas_components_schemas_location_systems_description
      type: array
      items:
        $ref: '#/components/schemas/LocationSystem'
    LocationSystem:
      description: |
        oas_components_schemas_location_system_description
      type: object
      required:
        - type
        - description
      properties:
        type:
          $ref: '#/components/schemas/LocationSystemType'
        description:
          $ref: '#/components/schemas/LocationSystemDescription'
      additionalProperties: false
    LocationSystemType:
      description: |
        oas_components_schemas_location_system_type_description
      type: string
      enum:
        - FISCAL_DEVICE
        - PAYMENT_DEVICE
        - E_INVOICE_SERVICE
    LocationSystemDescription:
      description: |
        oas_components_schemas_location_system_description_description
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    LocationUpdatedAt:
      description: |
        oas_components_schemas_location_updated_at_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    LocationCreatedAt:
      description: |
        oas_components_schemas_location_created_at_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    HeadOfficeLocation:
      description: |
        oas_components_schemas_head_office_location_description
      type: object
      required:
        - type
        - taxpayer
        - name
        - address
      properties:
        type:
          type: string
          enum:
            - HEAD_OFFICE
        name:
          $ref: '#/components/schemas/TaxpayerName'
        address:
          $ref: '#/components/schemas/LegalAddress'
        taxpayer:
          $ref: '#/components/schemas/LocationTaxpayer'
        coordinates:
          $ref: '#/components/schemas/LocationCoordinates'
        label:
          $ref: '#/components/schemas/LocationLabel'
      additionalProperties: false
    BranchLocation:
      description: |
        oas_components_schemas_branch_location_description
      type: object
      required:
        - type
        - taxpayer
        - name
        - address
      properties:
        type:
          type: string
          enum:
            - BRANCH
        taxpayer:
          $ref: '#/components/schemas/LocationTaxpayer'
        name:
          $ref: '#/components/schemas/LocationName'
        address:
          $ref: '#/components/schemas/LocationAddress'
        coordinates:
          $ref: '#/components/schemas/LocationCoordinates'
        label:
          $ref: '#/components/schemas/LocationLabel'
      additionalProperties: false
    SystemCreateRequest:
      description: |
        oas_components_schemas_system_create_request_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/SystemCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    SystemUpdateRequest:
      description: |
        oas_components_schemas_system_update_request_description
      type: object
      properties:
        content:
          $ref: '#/components/schemas/SystemUpdateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    SystemResource:
      description: |
        oas_components_schemas_system_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/SystemContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    SystemResources:
      description: |
        oas_components_schemas_system_resources_description
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SystemResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    SystemCreateContent:
      description: |
        Defines the structure required to create a System.
        
      discriminator:
        propertyName: type
        mapping:
          FISCAL_DEVICE: '#/components/schemas/FiscalDeviceSystem'
          PAYMENT_DEVICE: '#/components/schemas/PaymentDeviceSystem'
          E_INVOICE_SERVICE: '#/components/schemas/ElectronicInvoiceServiceSystem'
      oneOf:
        - $ref: '#/components/schemas/FiscalDeviceSystem'
        - $ref: '#/components/schemas/PaymentDeviceSystem'
        - $ref: '#/components/schemas/ElectronicInvoiceServiceSystem'
    SystemUpdateContent:
      description: |
        Defines the structure required to update a System.
        
      type: object
      properties:
        state:
          $ref: '#/components/schemas/SystemState'
        mode:
          $ref: '#/components/schemas/SystemMode'
        location:
          $ref: '#/components/schemas/SystemLocation'
        software:
          $ref: '#/components/schemas/Software'
        producer:
          $ref: '#/components/schemas/ManufacturerPartNumberProduct'
        acquirer:
          $ref: '#/components/schemas/PaymentDeviceAcquirer'
        label:
          $ref: '#/components/schemas/PaymentDeviceLabel'
        connected_to:
          $ref: '#/components/schemas/PaymentDeviceSystemConnections'
      additionalProperties: false
    SystemContent:
      allOf:
        - $ref: '#/components/schemas/Systems'
        - $ref: '#/components/schemas/System'
    Systems:
      oneOf:
        - $ref: '#/components/schemas/FiscalDeviceSystem'
        - $ref: '#/components/schemas/PaymentDeviceSystem'
        - $ref: '#/components/schemas/ElectronicInvoiceServiceSystem'
    System:
      description: |
        Defines the structure returned in the response when creating the system.
        
      type: object
      required:
        - id
        - state
        - mode
        - journal
        - compliance
        - records
        - vat_rates
        - vat_exemptions
      properties:
        id:
          $ref: '#/components/schemas/SystemIdentifier'
        state:
          $ref: '#/components/schemas/SystemState'
        mode:
          $ref: '#/components/schemas/SystemMode'
        journal:
          $ref: '#/components/schemas/SystemJournal'
        compliance:
          $ref: '#/components/schemas/SystemCompliance'
        records:
          $ref: '#/components/schemas/SystemRecords'
        vat_rates:
          $ref: '#/components/schemas/SystemVatRates'
        vat_exemptions:
          $ref: '#/components/schemas/SystemVatExemptions'
        logs:
          $ref: '#/components/schemas/SystemLogs'
        annotations:
          $ref: '#/components/schemas/SystemAnnotations'
        created_at:
          $ref: '#/components/schemas/SystemCreatedAt'
        updated_at:
          $ref: '#/components/schemas/SystemUpdatedAt'
      additionalProperties: false
    SystemState:
      description: |
        System state
        
      type: string
      enum:
        - ACQUIRED
        - COMMISSIONED
        - DECOMMISSIONED
    SystemMode:
      description: |
        System mode
        
      type: string
      enum:
        - INACTIVE
        - OPERATIVE
        - SUSPENDED
        - DEGRADED
    SystemLocation:
      description: |
        Connection to the Location that the System belongs to.
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/LocationIdentifier'
      additionalProperties: false
    SystemLogs:
      description: |
        Log entries for the System. 
        
      type: array
      items:
        $ref: '#/components/schemas/SystemLog'
      minItems: 1
      maxItems: 1000
    SystemLog:
      description: |
        oas_components_schemas_system_log_description
      type: object
      required:
        - severity
        - message
      properties:
        severity:
          $ref: '#/components/schemas/SystemLogSeverity'
        message:
          $ref: '#/components/schemas/SystemLogMessage'
      additionalProperties: false
    SystemLogSeverity:
      description: |
        Severity level of the System log entry
        
      type: string
      enum:
        - ERROR
    SystemLogMessage:
      description: |
        Log message
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    SystemJournal:
      description: |
        oas_components_schemas_system_journal_description
      type: object
      required:
        - cryptography
      properties:
        cryptography:
          $ref: '#/components/schemas/SystemCryptography'
      additionalProperties: false
    SystemCompliance:
      description: |
        oas_components_schemas_system_compliance_description
      type: object
      required:
        - software
      properties:
        cryptography:
          $ref: '#/components/schemas/SystemCryptography'
        software:
          $ref: '#/components/schemas/Software'
      additionalProperties: false
    SystemCryptography:
      description: |
        System cryptography
        
      type: object
      required:
        - certificate
        - signature
      properties:
        certificate:
          $ref: '#/components/schemas/CryptographyCertificate'
        signature:
          $ref: '#/components/schemas/CryptographySignature'
      additionalProperties: false
    SystemAnnotations:
      description: |
        Annotations
        
      type: object
      properties:
        peppol_id:
          $ref: '#/components/schemas/PeppolIdentifierAnnotation'
      additionalProperties: false
    SystemUpdatedAt:
      description: |
        oas_components_schemas_system_updated_at_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    SystemCreatedAt:
      description: |
        oas_components_schemas_system_created_at_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    PeppolIdentifierAnnotation:
      description: |
        PEPPOL Network Identifier
        
      type: string
      pattern: '^[0-9]{4}:[a-zA-Z0-9._/, -]{1,59}$'
      minLength: 6
      maxLength: 64
      example: '1234:0123456789'
    SystemRecords:
      description: |
        System records
        
      type: array
      items:
        $ref: '#/components/schemas/SystemRecord'
    SystemRecord:
      description: |
        System record
        
      type: object
      required:
        - type
        - description
      properties:
        type:
          $ref: '#/components/schemas/SystemRecordType'
        description:
          $ref: '#/components/schemas/SystemRecordDescription'
      additionalProperties: false
    SystemRecordType:
      description: |
        System record type
        
      type: string
      enum:
        - 'INTENTION::TRANSACTION'
        - 'INTENTION::EVENT'
        - 'INTENTION::EXPORT'
        - 'INTENTION::DUPLICATE'
        - 'INTENTION::CLOSING'
        - 'TRANSACTION::ABORT'
        - 'INTENTION::UPLOAD'
        - 'TRANSACTION::RECEIPT'
        - 'TRANSACTION::ABORT'
        - 'TRANSACTION::CANCELLATION'
        - 'TRANSACTION::CORRECTION'
        - 'TRANSACTION::DRAFT_RECEIPT'
        - 'TRANSACTION::ENRICHMENT'
        - 'TRANSACTION::INVOICE'
        - 'TRANSACTION::PROOF_OF_PAYMENT'
        - 'TRANSACTION::PRO_FORMA_INVOICE'
        - 'CLOSING::DAILY'
        - 'CLOSING::MONTHLY'
        - 'CLOSING::YEARLY'
        - 'EXPORT::RECORDS'
        - 'E_INVOICE::TRANSMISSION'
        - 'E_INVOICE::RECEPTION'
        - 'UPLOAD::PEPPOL_PROOF_OF_OWNERSHIP'
    SystemRecordDescription:
      description: |
        System record description
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    SystemVatRates:
      description: |
        VAT rates supported by the System
        
      type: array
      items:
        $ref: '#/components/schemas/SystemVatRate'
    SystemVatRate:
      description: |
        System VAT rate
        
      type: object
      required:
        - code
        - percentage
        - description
      properties:
        code:
          $ref: '#/components/schemas/SystemVatRateCode'
        percentage:
          $ref: '#/components/schemas/SystemVatRatePercentage'
        description:
          $ref: '#/components/schemas/SystemVatRateDescription'
        historic:
          $ref: '#/components/schemas/SystemVatRateHistoric'
      additionalProperties: false
    SystemVatRateCode:
      description: |
        Encoding for the VAT rates supported by the System
        
      type: string
      enum:
        - STANDARD
        - REDUCED_1
        - REDUCED_2
        - REDUCED_3
      example: REDUCED_1
    SystemVatRatePercentage:
      description: |
        Percentage corresponding to the VAT rate
        
      allOf:
        - $ref: '#/components/schemas/UnsignedDecimal3p2'
    SystemVatRateDescription:
      description: |
        Description of the System VAT rate
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    SystemVatRateHistoric:
      description: |
        Indication if the VAT rate corresponds to a historic value.
        
      type: boolean
    SystemVatExemptions:
      description: |
        System VAT exemptions
        
      type: array
      items:
        $ref: '#/components/schemas/SystemVatExemption'
    SystemVatExemption:
      description: |
        VAT exemptions supported by the System
        
      type: object
      required:
        - code
        - description
      properties:
        code:
          $ref: '#/components/schemas/SystemVatExemptionCode'
        description:
          $ref: '#/components/schemas/SystemVatExemptionDescription'
      additionalProperties: false
    SystemVatExemptionCode:
      description: |
        Encoding for the VAT exemptions supported by the System
        
      type: string
      enum:
        - NOT_SUBJECT
        - NOT_TAXABLE
        - CAUSE_1
        - CAUSE_2
        - CAUSE_3
        - CAUSE_4
      example: CAUSE_1
    SystemVatExemptionDescription:
      description: |
        Description of the System VAT exemptions
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    FiscalDeviceSystem:
      description: |
        Fiscal device system
        
      type: object
      required:
        - type
        - location
        - producer
        - software
      properties:
        type:
          type: string
          enum:
            - FISCAL_DEVICE
        kind:
          $ref: '#/components/schemas/FiscalDeviceSystemKind'
        location:
          $ref: '#/components/schemas/SystemLocation'
        producer:
          $ref: '#/components/schemas/ManufacturerPartNumberProduct'
        software:
          $ref: '#/components/schemas/Software'
      additionalProperties: false
    FiscalDeviceSystemKind:
      description: |
        'INTERNAL' represents an abstraction of a Registration Terminal (RT) within SIGN IT and can issue fiscal records via the API; 'EXTERNAL' represents a physical Registration Terminal (RT) and cannot issue fiscal records via the API.
      type: string
      enum:
        - INTERNAL
        - EXTERNAL
      default: INTERNAL
    PaymentDeviceAcquirer:
      description: |
        oas_components_schemas_payment_device_acquirer_description
      type: object
      required:
        - tax_id_number
        - legal_name
      properties:
        tax_id_number:
          $ref: '#/components/schemas/PaymentDeviceTaxIdNumber'
        legal_name:
          $ref: '#/components/schemas/LegalName'
      additionalProperties: false
    PaymentDeviceTaxIdNumber:
      description: |
        oas_components_schemas_payment_device_tax_id_number_description
      allOf:
        - $ref: '#/components/schemas/PlainString16'
    PaymentDeviceLabel:
      description: |
        oas_components_schemas_payment_device_label_description
      allOf:
        - $ref: '#/components/schemas/PlainString16'
    PaymentDeviceSystem:
      description: |
        oas_components_schemas_system_payment_device_description
      type: object
      required:
        - type
        - location
        - producer
        - software
      properties:
        type:
          type: string
          enum:
            - PAYMENT_DEVICE
        kind:
          $ref: '#/components/schemas/PaymentDeviceSystemKind'
        location:
          $ref: '#/components/schemas/SystemLocation'
        producer:
          $ref: '#/components/schemas/ManufacturerPartNumberProduct'
        software:
          $ref: '#/components/schemas/Software'
        acquirer:
          $ref: '#/components/schemas/PaymentDeviceAcquirer'
        label:
          $ref: '#/components/schemas/PaymentDeviceLabel'
        connected_to:
          $ref: '#/components/schemas/PaymentDeviceSystemConnections'
      additionalProperties: false
    PaymentDeviceSystemKind:
      description: |
        oas_components_schemas_system_payment_device_system_kind_description
      type: string
      enum:
        - PHYSICAL
        - VIRTUAL
      default: PHYSICAL
    PaymentDeviceSystemConnections:
      description: |
        oas_components_schemas_system_payment_device_system_connections_description
      type: array
      minItems: 0
      maxItems: 100
      uniqueItems: true
      items:
        $ref: '#/components/schemas/SystemIdentifier'
    ElectronicInvoiceServiceSystem:
      description: |
        oas_components_schemas_system_electronic_invoice_service_description
      type: object
      required:
        - type
        - location
        - software
      properties:
        type:
          type: string
          enum:
            - E_INVOICE_SERVICE
        location:
          $ref: '#/components/schemas/SystemLocation'
        software:
          $ref: '#/components/schemas/Software'
      additionalProperties: false
    RecordCreateRequest:
      description: |
        oas_components_schemas_record_create_request_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/RecordCreateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    RecordUpdateRequest:
      description: |
        oas_components_schemas_record_update_request_description
      type: object
      properties:
        content:
          $ref: '#/components/schemas/RecordUpdateContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    RecordResource:
      description: |
        oas_components_schemas_record_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/RecordContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    RecordResources:
      description: |
        oas_components_schemas_record_resources_description
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/RecordResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    RecordCreateContent:
      description: |
        Defines the structure required to create a Record.
        
      discriminator:
        propertyName: type
        mapping:
          INTENTION: '#/components/schemas/IntentionRecord'
          TRANSACTION: '#/components/schemas/TransactionRecord'
      oneOf:
        - $ref: '#/components/schemas/IntentionRecord'
        - $ref: '#/components/schemas/TransactionRecord'
    RecordUpdateContent:
      description: |
        Defines the structure required to update a Record.
        
      type: object
      additionalProperties: false
    RecordContent:
      allOf:
        - $ref: '#/components/schemas/Record'
    Record:
      description: |
        Record
        
      required:
        - id
        - type
        - state
        - mode
        - system
        - journal
        - file
      type: object
      properties:
        id:
          $ref: '#/components/schemas/RecordIdentifier'
        type:
          $ref: '#/components/schemas/SystemRecordType'
        state:
          $ref: '#/components/schemas/RecordState'
        mode:
          $ref: '#/components/schemas/RecordMode'
        system:
          $ref: '#/components/schemas/RecordSystem'
        record:
          $ref: '#/components/schemas/RecordConnection'
        used_in:
          $ref: '#/components/schemas/RecordConnection'
        replayed_by:
          $ref: '#/components/schemas/RecordConnection'
        journal:
          $ref: '#/components/schemas/Journal'
        file:
          $ref: '#/components/schemas/RecordFile'
        operation:
          $ref: '#/components/schemas/RecordOperation'
        compliance:
          $ref: '#/components/schemas/Compliance'
        transmission:
          $ref: '#/components/schemas/RecordTransmission'
        data:
          $ref: '#/components/schemas/RecordData'
        logs:
          $ref: '#/components/schemas/RecordLogs'
      additionalProperties: false
    RecordFile:
      description: |
        oas_components_schemas_record_file_description
      type: object
      required:
        - location
      properties:
        location:
          $ref: '#/components/schemas/FileLocation'
        artifact:
          $ref: '#/components/schemas/RecordFileArtifact'
        integrity:
          $ref: '#/components/schemas/RecordFileIntegrity'
      additionalProperties: false
    RecordFileArtifact:
      description: |
        oas_components_schemas_record_file_artifact_description
      allOf:
        - $ref: '#/components/schemas/Content'
    RecordFileIntegrity:
      description: |
        oas_components_schemas_record_file_integrity_description
      allOf:
        - $ref: '#/components/schemas/IntegrityContent'
    RecordOperation:
      description: |
        Record
        
      allOf:
        - $ref: '#/components/schemas/JsonData'
    RecordTransmission:
      description: |
        Contains information regarding the transmission of the record to the tax authorities.
        
      type: object
      required:
        - request
      properties:
        request:
          $ref: '#/components/schemas/RecordTransmissionRequest'
        response:
          $ref: '#/components/schemas/RecordTransmissionResponse'
      additionalProperties: false
    RecordTransmissionRequest:
      description: |
        Base64-encoded raw payload that was submitted to the tax authorities.
        
      allOf:
        - $ref: '#/components/schemas/Content'
    RecordTransmissionResponse:
      description: |
        Base64-encoded raw response from the tax authorities after the record was transmitted.
        Note: If this field is not populated, an error occurred during the transmission process. The error can be retrieved inside `content.logs`.
        
      allOf:
        - $ref: '#/components/schemas/Content'
    RecordLogs:
      description: |
        Collection of log entries for the Record. Includes timestamp, severity, and message details. Used for diagnostics and error analysis.
        
      type: array
      items:
        $ref: '#/components/schemas/RecordLog'
      minItems: 1
      maxItems: 1000
    RecordLog:
      description: |
        oas_components_schemas_record_log_description
      type: object
      required:
        - severity
        - message
      properties:
        severity:
          $ref: '#/components/schemas/RecordLogSeverity'
        message:
          $ref: '#/components/schemas/RecordLogMessage'
      additionalProperties: false
    RecordLogSeverity:
      description: |
        Severity level of a log entry
        
      type: string
      enum:
        - ERROR
    RecordLogMessage:
      description: |
        Log message
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    RecordState:
      description: |
        Enum: "ACCEPTED" "REJECTED" "COMPLETED" "FAILED"
        The state property reflects the current status of the Record resource.
        ACCEPTED: The Record request has been received, the Record resource has been created, and processing has started.
        REJECTED: The Record request has been received, the Record resource has been created, but validation errors during creation caused the request to be rejected. Details are available in the logs of the Record response.
        COMPLETED: The Record request has been successfully processed.
        FAILED: The Record request failed and one or more errors occurred during processing. Details are available in the logs of the Record response.
        
      type: string
      enum:
        - ACCEPTED
        - REJECTED
        - COMPLETED
        - FAILED
    RecordMode:
      description: |
        Enum: "PROCESSING" "FINISHED"
        The mode property reflects the current activity of the Record resource.
        PROCESSING: The Record resource still has ongoing processing activity.
        FINISHED: The Record resource finished all processing activity. The state determines the resulting outcome of the requested operation.
        
      type: string
      enum:
        - PROCESSING
        - FINISHED
    RecordSystem:
      description: |
        Connection to an already created System
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/SystemIdentifier'
      additionalProperties: false
    RecordConnection:
      description: |
        Connection to an already created record
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/RecordIdentifier'
      additionalProperties: false
    RecordReference:
      description: |
        Connection to an already created record
        
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/RecordIdentifier'
        offset:
          $ref: '#/components/schemas/RecordOffset'
      additionalProperties: false
    RecordOffset:
      description: |
        oas_components_schemas_record_offset_description
      allOf:
        - $ref: '#/components/schemas/UnsignedInteger4'
    RecordCreators:
      description: |
        Record creators
        
      type: array
      items:
        $ref: '#/components/schemas/RecordCreator'
      minItems: 1
      maxItems: 1
    RecordCreator:
      description: |
        oas_components_schemas_record_creator_description
      discriminator:
        propertyName: type
        mapping:
          PERSON: '#/components/schemas/PersonRecordCreator'
      oneOf:
        - $ref: '#/components/schemas/PersonRecordCreator'
    PersonRecordCreator:
      description: |
        oas_components_schemas_person_record_creator_description
      type: object
      required:
        - type
        - label
      properties:
        type:
          type: string
          enum:
            - PERSON
        label:
          $ref: '#/components/schemas/PersonLabel'
        name:
          $ref: '#/components/schemas/PersonName'
      additionalProperties: false
    RecordTrainingOption:
      description: |
        Indicates whether a record is being issued for training purposes.
        
      type: boolean
    IntentionRecord:
      description: |
        oas_components_schemas_intention_record_description
      type: object
      required:
        - type
        - system
        - operation
      properties:
        type:
          type: string
          enum:
            - INTENTION
        system:
          $ref: '#/components/schemas/RecordSystem'
        operation:
          $ref: '#/components/schemas/IntentionOperation'
      additionalProperties: false
    IntentionOperation:
      description: |
        Every interaction with a `System` starts with an `IntentionRecord`.<br>
        🇮🇹 In Italy, the supported intention operation is:
        `TRANSACTION`
        
      discriminator:
        propertyName: type
        mapping:
          TRANSACTION: '#/components/schemas/TransactionIntention'
          EVENT: '#/components/schemas/EventIntention'
          EXPORT: '#/components/schemas/ExportIntention'
          DUPLICATE: '#/components/schemas/DuplicateIntention'
          REPLAY: '#/components/schemas/ReplayIntention'
          UPLOAD: '#/components/schemas/UploadIntention'
      oneOf:
        - $ref: '#/components/schemas/TransactionIntention'
        - $ref: '#/components/schemas/EventIntention'
        - $ref: '#/components/schemas/ExportIntention'
        - $ref: '#/components/schemas/DuplicateIntention'
        - $ref: '#/components/schemas/ReplayIntention'
        - $ref: '#/components/schemas/UploadIntention'
    TransactionIntention:
      description: |
        oas_components_schemas_transaction_intention_description
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - TRANSACTION
        details:
          $ref: '#/components/schemas/TransactionDetails'
      additionalProperties: false
    TransactionDetails:
      description: |
        Record details of intended `TRANSACTION`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/TransactionProperties'
      additionalProperties: false
    TransactionProperties:
      description: |
        Record properties of intended `TRANSACTION`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    EventIntention:
      description: |
        oas_components_schemas_event_intention_description
      type: object
      required:
        - type
        - code
        - description
      properties:
        type:
          type: string
          enum:
            - EVENT
        code:
          $ref: '#/components/schemas/EventCode'
        description:
          $ref: '#/components/schemas/EventDescription'
        occurred_at:
          $ref: '#/components/schemas/EventTimestamp'
        details:
          $ref: '#/components/schemas/EventDetails'
      additionalProperties: false
    EventCode:
      description: |
        Code identifying the Event
        
      allOf:
        - $ref: '#/components/schemas/PlainString32'
    EventDescription:
      description: |
        Additional Event description
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    EventTimestamp:
      description: |
        Timestamp of Event
        
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    EventDetails:
      description: |
        Record details of intended `EVENT`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/EventProperties'
      additionalProperties: false
    EventProperties:
      description: |
        Record properties of intended `EVENT`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    ExportIntention:
      description: |
        oas_components_schemas_export_intention_description
      type: object
      required:
        - type
        - range
      properties:
        type:
          type: string
          enum:
            - EXPORT
        range:
          $ref: '#/components/schemas/ExportRange'
        filters:
          $ref: '#/components/schemas/ExportFilters'
        details:
          $ref: '#/components/schemas/ExportDetails'
      additionalProperties: false
    ExportRange:
      description: |
        Defines start and end timestamp.
        
      type: object
      required:
        - start
        - end
      properties:
        start:
          $ref: '#/components/schemas/JournalSigningTimestamp'
        end:
          $ref: '#/components/schemas/JournalSigningTimestamp'
      additionalProperties: false
    ExportFilters:
      description: |
        Defines export filtering options.
        
      type: array
      items:
        $ref: '#/components/schemas/ExportFilter'
      minItems: 1
      maxItems: 1
      uniqueItems: true
      additionalProperties: false
    ExportFilter:
      description: |
        oas_components_schemas_export_filter_description
      discriminator:
        propertyName: type
        mapping:
          SYSTEM_RECORD: '#/components/schemas/ExportSystemRecordFilter'
      oneOf:
        - $ref: '#/components/schemas/ExportSystemRecordFilter'
    ExportSystemRecordFilter:
      description: |
        Defines export filtering options.
        
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - SYSTEM_RECORD
        value:
          $ref: '#/components/schemas/SystemRecordType'
      additionalProperties: false
    ExportDetails:
      description: |
        Record details of intended `EXPORT`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/ExportProperties'
      additionalProperties: false
    ExportProperties:
      description: |
        Record properties of intended `EXPORT`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    DuplicateIntention:
      description: |
        oas_components_schemas_duplicate_intention_description
      type: object
      required:
        - type
        - record
        - number
        - reason
      properties:
        type:
          type: string
          enum:
            - DUPLICATE
        record:
          $ref: '#/components/schemas/RecordReference'
        number:
          $ref: '#/components/schemas/DuplicateNumber'
        reason:
          $ref: '#/components/schemas/DuplicateReason'
        details:
          $ref: '#/components/schemas/DuplicateDetails'
      additionalProperties: false
    DuplicateNumber:
      description: |
        Reprint number
        
      allOf:
        - $ref: '#/components/schemas/UnsignedInteger4'
    DuplicateReason:
      description: |
        Reason for issuing the duplicate
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    DuplicateDetails:
      description: |
        Record details of intended `DUPLICATE`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/DuplicateProperties'
      additionalProperties: false
    DuplicateProperties:
      description: |
        Record properties of intended `DUPLICATE`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    UploadIntention:
      description: |
        oas_components_schemas_upload_intention_description
      type: object
      required:
        - type
        - content
        - purpose
      properties:
        type:
          type: string
          enum:
            - UPLOAD
        content:
          $ref: '#/components/schemas/UploadContent'
        purpose:
          $ref: '#/components/schemas/UploadPurpose'
        details:
          $ref: '#/components/schemas/UploadDetails'
      additionalProperties: false
    UploadContent:
      description: |
        Defines the structure required to upload content.
        
      allOf:
        - $ref: '#/components/schemas/Content'
    UploadPurpose:
      description: |
        Specifies the purpose of the file upload.
        
      type: string
      enum:
        - PEPPOL_PROOF_OF_OWNERSHIP
    UploadDetails:
      description: |
        oas_components_schemas_upload_details_description
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
      additionalProperties: false
    ReplayIntention:
      description: |
        oas_components_schemas_replay_intention_description
      type: object
      required:
        - type
        - recorded_at
        - seed
        - record
        - content
      properties:
        type:
          type: string
          enum:
            - REPLAY
        recorded_at:
          $ref: '#/components/schemas/ReplayRecordedTimestamp'
        seed:
          $ref: '#/components/schemas/ReplaySeed'
        record:
          $ref: '#/components/schemas/ReplayRecord'
        content:
          $ref: '#/components/schemas/ReplayContent'
      additionalProperties: false
    ReplayRecordedTimestamp:
      description: |
        oas_components_schemas_replay_recorded_timestamp_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    ReplaySeed:
      description: |
        oas_components_schemas_replay_seed_description
      allOf:
        - $ref: '#/components/schemas/PlainString64'
    ReplayRecord:
      description: |
        oas_components_schemas_replay_record_description
      allOf:
        - $ref: '#/components/schemas/RecordConnection'
    ReplayContent:
      description: |
        oas_components_schemas_intention_replay_content_description
      discriminator:
        propertyName: type
        mapping:
          INTENTION: '#/components/schemas/ReplayIntentionContent'
          TRANSACTION: '#/components/schemas/ReplayTransactionContent'
      oneOf:
        - $ref: '#/components/schemas/ReplayIntentionContent'
        - $ref: '#/components/schemas/ReplayTransactionContent'
    ReplayIntentionContent:
      description: |
        oas_components_schemas_replay_intention_content_description
      type: object
      required:
        - type
        - system
        - operation
      properties:
        type:
          type: string
          enum:
            - INTENTION
        system:
          $ref: '#/components/schemas/RecordSystem'
        operation:
          $ref: '#/components/schemas/ReplayIntentionOperation'
      additionalProperties: false
    ReplayIntentionOperation:
      description: |
        oas_components_schemas_replay_intention_operation_description
      discriminator:
        propertyName: type
        mapping:
          TRANSACTION: '#/components/schemas/TransactionIntention'
          EVENT: '#/components/schemas/EventIntention'
          EXPORT: '#/components/schemas/ExportIntention'
          DUPLICATE: '#/components/schemas/DuplicateIntention'
      oneOf:
        - $ref: '#/components/schemas/TransactionIntention'
        - $ref: '#/components/schemas/EventIntention'
        - $ref: '#/components/schemas/ExportIntention'
        - $ref: '#/components/schemas/DuplicateIntention'
    ReplayTransactionContent:
      description: |
        oas_components_schemas_replay_transaction_content_description
      type: object
      required:
        - type
        - record
        - operation
      properties:
        type:
          type: string
          enum:
            - TRANSACTION
        record:
          $ref: '#/components/schemas/RecordReference'
        operation:
          $ref: '#/components/schemas/TransactionOperation'
      additionalProperties: false
    TransactionRecord:
      description: |
        oas_components_schemas_transaction_record_description
      type: object
      required:
        - type
        - record
        - operation
      properties:
        type:
          type: string
          enum:
            - TRANSACTION
        record:
          $ref: '#/components/schemas/RecordReference'
        operation:
          $ref: '#/components/schemas/TransactionOperation'
      additionalProperties: false
    TransactionOperation:
      description: |
        An initial `IntentionRecord` of type `TRANSACTION` is required to proceed a given transaction operations. <br>
        🇮🇹 In Italy, the supported transaction operations are:
        `RECEIPT` used to certify the sale of goods or services,
        `CORRECTION` used to represent a return process. Establish a reference to the receipt being corrected via the `record` field in the `CorrectionRecord` API schema.
        `CANCELLATION`, used to void an existing receipt. Establish a reference to the receipt being cancelled via the `record` field in the `CancellationRecord` API schema. 
        
      discriminator:
        propertyName: type
        mapping:
          RECEIPT: '#/components/schemas/ReceiptTransaction'
          ABORT: '#/components/schemas/AbortTransaction'
          CANCELLATION: '#/components/schemas/CancellationTransaction'
          CORRECTION: '#/components/schemas/CorrectionTransaction'
          DRAFT_RECEIPT: '#/components/schemas/DraftReceiptTransaction'
          ENRICHMENT: '#/components/schemas/EnrichmentTransaction'
          INVOICE: '#/components/schemas/InvoiceTransaction'
          PROOF_OF_PAYMENT: '#/components/schemas/ProofOfPaymentTransaction'
          PRO_FORMA_INVOICE: '#/components/schemas/ProFormaInvoiceTransaction'
      oneOf:
        - $ref: '#/components/schemas/AbortTransaction'
        - $ref: '#/components/schemas/ReceiptTransaction'
        - $ref: '#/components/schemas/DraftReceiptTransaction'
        - $ref: '#/components/schemas/InvoiceTransaction'
        - $ref: '#/components/schemas/ProFormaInvoiceTransaction'
        - $ref: '#/components/schemas/EnrichmentTransaction'
        - $ref: '#/components/schemas/CorrectionTransaction'
        - $ref: '#/components/schemas/CancellationTransaction'
        - $ref: '#/components/schemas/ProofOfPaymentTransaction'
    AbortTransaction:
      description: |
        oas_components_schemas_abort_transaction_description
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - ABORT
        details:
          $ref: '#/components/schemas/AbortDetails'
      additionalProperties: false
    AbortDetails:
      description: |
        oas_components_schemas_abort_details_description
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/AbortProperties'
      additionalProperties: false
    AbortProperties:
      description: |
        oas_components_schemas_abort_properties_description
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    ReceiptTransaction:
      description: |
        oas_components_schemas_receipt_transaction_description
      type: object
      required:
        - type
        - document
        - entries
        - payments
      properties:
        type:
          type: string
          enum:
            - RECEIPT
        document:
          $ref: '#/components/schemas/Document'
        entries:
          $ref: '#/components/schemas/Entries'
        customer:
          $ref: '#/components/schemas/Customer'
        payments:
          $ref: '#/components/schemas/Payments'
        details:
          $ref: '#/components/schemas/ReceiptDetails'
      additionalProperties: false
    ReceiptDetails:
      description: |
        Record details of transaction `RECEIPT`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/ReceiptProperties'
      additionalProperties: false
    ReceiptProperties:
      description: |
        Record properties of transaction `RECEIPT`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    DraftReceiptTransaction:
      description: |
        oas_components_schemas_draft_receipt_transaction_description
      type: object
      required:
        - type
        - document
        - entries
      properties:
        type:
          type: string
          enum:
            - DRAFT_RECEIPT
        document:
          $ref: '#/components/schemas/Document'
        entries:
          $ref: '#/components/schemas/Entries'
        customer:
          $ref: '#/components/schemas/Customer'
        details:
          $ref: '#/components/schemas/DraftReceiptDetails'
      additionalProperties: false
    DraftReceiptDetails:
      description: |
        Record details of transaction `DRAFT_RECEIPT`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/DraftReceiptProperties'
      additionalProperties: false
    DraftReceiptProperties:
      description: |
        Record properties of transaction `DRAFT_RECEIPT`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    EnrichmentTransaction:
      description: |
        oas_components_schemas_enrichment_transaction_description
      type: object
      required:
        - type
        - record
        - recipients
        - breakdown
      properties:
        type:
          type: string
          enum:
            - ENRICHMENT
        record:
          $ref: '#/components/schemas/EnrichmentRecord'
        recipients:
          $ref: '#/components/schemas/Recipients'
        breakdown:
          $ref: '#/components/schemas/VatBreakdown'
        details:
          $ref: '#/components/schemas/EnrichmentDetails'
      additionalProperties: false
    EnrichmentRecord:
      description: |
        oas_components_schemas_enrichment_record_description
      allOf:
        - $ref: '#/components/schemas/RecordReference'
    EnrichmentDetails:
      description: |
        Record details of transaction `ENRICHMENT`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/EnrichmentProperties'
      additionalProperties: false
    EnrichmentProperties:
      description: |
        Record properties of transaction `ENRICHMENT`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    InvoiceTransaction:
      description: |
        oas_components_schemas_invoice_transaction_description
      type: object
      required:
        - type
        - document
        - entries
        - recipients
        - payments
        - breakdown
      properties:
        type:
          type: string
          enum:
            - INVOICE
        document:
          $ref: '#/components/schemas/Document'
        entries:
          $ref: '#/components/schemas/Entries'
        recipients:
          $ref: '#/components/schemas/Recipients'
        payments:
          $ref: '#/components/schemas/Payments'
        breakdown:
          $ref: '#/components/schemas/VatBreakdown'
        details:
          $ref: '#/components/schemas/InvoiceDetails'
      additionalProperties: false
    InvoiceDetails:
      description: |
        Record details of transaction `INVOICE`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/InvoiceProperties'
      additionalProperties: false
    InvoiceProperties:
      description: |
        Record properties of transaction `INVOICE`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    ProFormaInvoiceTransaction:
      description: |
        oas_components_schemas_pro_forma_invoice_transaction_description
      type: object
      required:
        - type
        - document
        - entries
        - recipients
      properties:
        type:
          type: string
          enum:
            - PRO_FORMA_INVOICE
        document:
          $ref: '#/components/schemas/Document'
        entries:
          $ref: '#/components/schemas/Entries'
        recipients:
          $ref: '#/components/schemas/Recipients'
        breakdown:
          $ref: '#/components/schemas/VatBreakdown'
        details:
          $ref: '#/components/schemas/ProFormaInvoiceDetails'
      additionalProperties: false
    ProFormaInvoiceDetails:
      description: |
        Record details of transaction `PRO_FORMA_INVOICE`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/ProFormaInvoiceProperties'
      additionalProperties: false
    ProFormaInvoiceProperties:
      description: |
        Record properties of transaction `PRO_FORMA_INVOICE`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    CorrectionTransaction:
      description: |
        oas_components_schemas_correction_transaction_description
      type: object
      required:
        - type
        - record
        - data
      properties:
        type:
          type: string
          enum:
            - CORRECTION
        record:
          $ref: '#/components/schemas/CorrectionRecord'
        data:
          $ref: '#/components/schemas/CorrectionData'
        details:
          $ref: '#/components/schemas/CorrectionDetails'
      additionalProperties: false
    CorrectionRecord:
      description: |
        Used to represent any return process carried out for an existing receipt. Establish a reference to the transaction being corrected via the `record` field.
        
      allOf:
        - $ref: '#/components/schemas/RecordReference'
    CorrectionData:
      description: |
        Correction transaction data
        
      discriminator:
        propertyName: type
        mapping:
          RECEIPT: '#/components/schemas/ReceiptTransaction'
      oneOf:
        - $ref: '#/components/schemas/ReceiptTransaction'
    CorrectionDetails:
      description: |
        Record details of transaction `CORRECTION`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/CorrectionProperties'
      additionalProperties: false
    CorrectionProperties:
      description: |
        Record properties of transaction `CORRECTION`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    CancellationTransaction:
      description: |
        oas_components_schemas_cancellation_transaction_description
      type: object
      required:
        - type
        - record
      properties:
        type:
          type: string
          enum:
            - CANCELLATION
        record:
          $ref: '#/components/schemas/CancellationRecord'
        details:
          $ref: '#/components/schemas/CancellationDetails'
      additionalProperties: false
    CancellationRecord:
      description: |
        Used to invalidate an existing transaction. Establish a reference to the transaction to be cancelled via the `record` field.
        
      allOf:
        - $ref: '#/components/schemas/RecordReference'
    CancellationDetails:
      description: |
        Record details of transaction `CANCELLATION`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/CancellationProperties'
      additionalProperties: false
    CancellationProperties:
      description: |
        Record properties of transaction `CANCELLATION`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    ProofOfPaymentTransaction:
      description: |
        oas_components_schemas_proof_of_payment_transaction_description
      type: object
      required:
        - type
        - record
        - payments
      properties:
        type:
          type: string
          enum:
            - PROOF_OF_PAYMENT
        record:
          $ref: '#/components/schemas/ProofOfPaymentRecord'
        payments:
          $ref: '#/components/schemas/Payments'
        details:
          $ref: '#/components/schemas/ProofOfPaymentDetails'
      additionalProperties: false
    ProofOfPaymentRecord:
      description: |
        oas_components_schemas_proof_of_payment_record_description
      allOf:
        - $ref: '#/components/schemas/RecordReference'
    ProofOfPaymentDetails:
      description: |
        Record details of transaction `PROOF_OF_PAYMENT`.
        
      type: object
      required:
        - creators
      properties:
        creators:
          $ref: '#/components/schemas/RecordCreators'
        training:
          $ref: '#/components/schemas/RecordTrainingOption'
        properties:
          $ref: '#/components/schemas/ProofOfPaymentProperties'
      additionalProperties: false
    ProofOfPaymentProperties:
      description: |
        Record properties of transaction `PROOF_OF_PAYMENT`.<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    FileResource:
      description: |
        oas_components_schemas_file_resource_description
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/FileContent'
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: false
    FileResources:
      description: |
        oas_components_schemas_file_resources_description
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/FileResource'
          minItems: 1
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    FileContent:
      allOf:
        - $ref: '#/components/schemas/File'
    File:
      description: |
        oas_components_schemas_file_description
      required:
        - id
        - created_at
        - system
        - location
        - artifact
      type: object
      properties:
        id:
          $ref: '#/components/schemas/FileIdentifier'
        created_at:
          $ref: '#/components/schemas/FileCreationTimestamp'
        system:
          $ref: '#/components/schemas/RecordSystem'
        location:
          $ref: '#/components/schemas/FileLocation'
        artifact:
          $ref: '#/components/schemas/FileArtifact'
        integrity:
          $ref: '#/components/schemas/FileIntegrity'
      additionalProperties: false
    FileLocation:
      description: |
        Defines where file is derived from - `SERVICE`: retrieved from UAPI storage.
        `ARCHIVE`: retrieved from archive.
        
      type: string
      enum:
        - SERVICE
        - ARCHIVE
    FileArtifact:
      description: |
        Information about the downloadable file
        
      required:
        - type
        - path
      properties:
        type:
          $ref: '#/components/schemas/FileType'
        path:
          $ref: '#/components/schemas/FilePath'
      additionalProperties: false
    FileType:
      description: |
        Defines the file content type
        
      type: string
      enum:
        - application/zip
    FilePath:
      description: |
        Returns the path where to download the file<br>
        e.g. /files/0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f.zip
        
      allOf:
        - $ref: '#/components/schemas/UniformResourceIdentifier'
    FileIntegrity:
      description: |
        Includes the integrity information of the file
        
      required:
        - type
        - path
      properties:
        type:
          $ref: '#/components/schemas/IntegrityContentType'
        path:
          $ref: '#/components/schemas/FilePath'
      additionalProperties: false
    FileCreationTimestamp:
      description: |
        File creation time (format RFC3339)
        
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    Document:
      description: |
        General information of the document being issued
        
      type: object
      required:
        - number
        - total_vat
      properties:
        number:
          $ref: '#/components/schemas/DocumentNumber'
        series:
          $ref: '#/components/schemas/DocumentSeries'
        text:
          $ref: '#/components/schemas/DocumentText'
        activity_code:
          $ref: '#/components/schemas/DocumentActivityCode'
        issued_at:
          $ref: '#/components/schemas/DocumentIssuingTimestamp'
        operation_date:
          $ref: '#/components/schemas/DocumentOperationDate'
        total_vat:
          $ref: '#/components/schemas/DocumentTotalVat'
      additionalProperties: false
    DocumentNumber:
      description: |
        Unique and correlative document number. This number refers to the taxpayer’s own internal document numbering system. This value must be generated by the taxpayer.
        
      allOf:
        - $ref: '#/components/schemas/DocumentIdentifier'
    DocumentSeries:
      description: |
        Document series number
        
      allOf:
        - $ref: '#/components/schemas/DocumentIdentifier'
    DocumentIdentifier:
      description: |
        oas_components_schemas_document_identifier_description
      type: string
      pattern: '^[0-9A-Z_/\-\.]{1,20}$'
      minLength: 1
      maxLength: 20
      example: '2022'
    DocumentText:
      description: |
        oas_components_schemas_document_text_description
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    DocumentActivityCode:
      description: |
        Business activity code to which the document belongs, if applicable. Activity codes are predefined.
        
      allOf:
        - $ref: '#/components/schemas/PlainString32'
    DocumentIssuingTimestamp:
      description: |
        Timestamp of document issuance
        
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    DocumentOperationDate:
      description: |
        Operation date of the business activity, if different from the document issuing date.
        
      allOf:
        - $ref: '#/components/schemas/DateFormatISO8601'
    DocumentTotalVat:
      description: |
        Total VAT amounts for the transaction
        
      type: object
      required:
        - amount
        - exclusive
        - inclusive
      properties:
        amount:
          $ref: '#/components/schemas/VatAmount'
        exclusive:
          $ref: '#/components/schemas/VatExclusive'
        inclusive:
          $ref: '#/components/schemas/VatInclusive'
      additionalProperties: false
    Entries:
      description: |
        Array of entries describing items sold or services provided in the business transaction.
        
      type: array
      items:
        $ref: '#/components/schemas/Entry'
      minItems: 1
      maxItems: 1000
    Entry:
      discriminator:
        propertyName: type
        mapping:
          SALE: '#/components/schemas/SaleEntry'
          RETURN: '#/components/schemas/ReturnEntry'
          VOUCHER: '#/components/schemas/VoucherEntry'
      oneOf:
        - $ref: '#/components/schemas/SaleEntry'
        - $ref: '#/components/schemas/ReturnEntry'
        - $ref: '#/components/schemas/VoucherEntry'
    SaleEntry:
      description: |
        Entry of type SALE for the sale of goods or services
        
      type: object
      required:
        - type
        - data
        - details
      properties:
        type:
          type: string
          enum:
            - SALE
        data:
          $ref: '#/components/schemas/EntryData'
        details:
          $ref: '#/components/schemas/EntryDetails'
      additionalProperties: false
    ReturnEntry:
      description: |
        Entry of type RETURN for returned goods or refunds
        
      type: object
      required:
        - type
        - data
        - details
      properties:
        type:
          type: string
          enum:
            - RETURN
        data:
          $ref: '#/components/schemas/EntryData'
        details:
          $ref: '#/components/schemas/EntryDetails'
      additionalProperties: false
    VoucherEntry:
      description: |
        Entry of type VOUCHER for vouchers
        
      type: object
      required:
        - type
        - data
        - details
      properties:
        type:
          type: string
          enum:
            - VOUCHER
        data:
          $ref: '#/components/schemas/EntryData'
        details:
          $ref: '#/components/schemas/EntryDetails'
      additionalProperties: false
    EntryProperties:
      description: |
        Additional entry properties<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 32
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    EntryDetails:
      description: |
        Details specific to the entry type
        
      type: object
      required:
        - concept
      properties:
        concept:
          $ref: '#/components/schemas/EntryConcept'
        purpose:
          $ref: '#/components/schemas/EntryPurpose'
        description:
          $ref: '#/components/schemas/EntryDescription'
        regulatory:
          $ref: '#/components/schemas/EntryRegulatory'
        label:
          $ref: '#/components/schemas/EntryLabel'
        number:
          $ref: '#/components/schemas/EntryNumber'
        properties:
          $ref: '#/components/schemas/EntryProperties'
      additionalProperties: false
    EntryConcept:
      description: |
        Indicates the economic concept of the entry: `GOOD` or `SERVICE`.
        
      type: string
      enum:
        - GOOD
        - SERVICE
    EntryPurpose:
      description: |
        Reflects the intention of the entry.
        
      type: string
      enum:
        - STANDARD
        - GIFT
      default: STANDARD
    EntryDescription:
      description: |
        Additional entry description
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    EntryRegulatory:
      description: |
        Additional regulatory text applicable to the entry
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    EntryLabel:
      description: |
        Human-readable entry label or description
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    EntryNumber:
      description: |
        This optional field specifies the print order of entries[] on a document. Each entry using this field must have a unique number to establish print order. If this field is not used, the print order defaults to the sequence of the array index, starting at one (1). 
        **Note**: In case of a correction record, this number is required as it indicates the original entry number being corrected.
        
      allOf:
        - $ref: '#/components/schemas/UnsignedInteger4'
    EntryText:
      description: |
        Text describing the entry item e.g. text to be printed on the document of that entry.
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    EntryData:
      description: |
        Contains the data of the entry which can be either a singular `ITEM`
        or a `GROUP` of one or multiple items.
        
      discriminator:
        propertyName: type
        mapping:
          ITEM: '#/components/schemas/ItemEntry'
          GROUP: '#/components/schemas/GroupEntry'
      oneOf:
        - $ref: '#/components/schemas/ItemEntry'
        - $ref: '#/components/schemas/GroupEntry'
    ItemEntry:
      description: |
        oas_components_schemas_item_entry_description
      type: object
      required:
        - type
        - text
        - unit
        - value
        - vat
      properties:
        type:
          type: string
          enum:
            - ITEM
        text:
          $ref: '#/components/schemas/EntryText'
        unit:
          $ref: '#/components/schemas/Unit'
        value:
          $ref: '#/components/schemas/EntryValue'
        vat:
          $ref: '#/components/schemas/EntryVat'
        product:
          $ref: '#/components/schemas/Product'
      additionalProperties: false
    GroupEntry:
      description: |
        oas_components_schemas_group_entry_description
      type: object
      required:
        - type
        - text
        - unit
        - value
        - vat
        - items
      properties:
        type:
          type: string
          enum:
            - GROUP
        text:
          $ref: '#/components/schemas/EntryText'
        unit:
          $ref: '#/components/schemas/Unit'
        value:
          $ref: '#/components/schemas/GroupEntryValue'
        vat:
          $ref: '#/components/schemas/GroupEntryVat'
        items:
          $ref: '#/components/schemas/GroupEntryItems'
      additionalProperties: false
    GroupEntryValue:
      description: |
        Total amounts for the group of items in the entry
        
      allOf:
        - $ref: '#/components/schemas/EntryValue'
    GroupEntryVat:
      description: |
        Defines the VAT information of the particular group of items
        
      oneOf:
        - $ref: '#/components/schemas/EntryVat'
    GroupEntryItems:
      description: |
        Items included in the group entry
        
      type: array
      items:
        $ref: '#/components/schemas/GroupEntryItem'
      minItems: 1
      maxItems: 10
    GroupEntryItem:
      description: |
        oas_components_schemas_group_entry_item_description
      allOf:
        - $ref: '#/components/schemas/ItemEntry'
    RecordData:
      description: |
        oas_components_schemas_record_data_description
      type: object
      required:
        - location
      properties:
        location:
          $ref: '#/components/schemas/FileLocation'
        artifact:
          $ref: '#/components/schemas/FileArtifact'
        integrity:
          $ref: '#/components/schemas/RecordDataIntegrity'
      additionalProperties: false
    RecordDataIntegrity:
      description: |
        oas_components_schemas_record_data_integrity_description
      allOf:
        - $ref: '#/components/schemas/IntegrityContent'
    Compliance:
      description: |
        oas_components_schemas_compliance_description
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/ComplianceData'
        url:
          $ref: '#/components/schemas/ComplianceUrl'
        artifact:
          $ref: '#/components/schemas/ComplianceArtifact'
      additionalProperties: false
    ComplianceData:
      description: |
        oas_components_schemas_compliance_data_description
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    ComplianceUrl:
      description: |
        oas_components_schemas_compliance_url_description
      allOf:
        - $ref: '#/components/schemas/UniformResourceIdentifier'
    ComplianceArtifact:
      description: |
        oas_components_schemas_compliance_artifact_description
      allOf:
        - $ref: '#/components/schemas/Content'
    Journal:
      description: |
        oas_components_schemas_journal_description
      type: object
      required:
        - signature
        - signed_at
      properties:
        signature:
          $ref: '#/components/schemas/JournalSignature'
        signed_at:
          $ref: '#/components/schemas/JournalSigningTimestamp'
        record:
          $ref: '#/components/schemas/JournalPreviousRecord'
      additionalProperties: false
    JournalSignature:
      description: |
        oas_components_schemas_journal_signature_description
      allOf:
        - $ref: '#/components/schemas/PlainString64'
    JournalSigningTimestamp:
      description: |
        Defines the start/end date and time
        
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    JournalPreviousRecord:
      description: |
        oas_components_schemas_journal_previous_record_description
      allOf:
        - $ref: '#/components/schemas/RecordConnection'
    EntryValue:
      description: |
        Value amounts of the entry
        
      type: object
      required:
        - base
      properties:
        base:
          $ref: '#/components/schemas/BaseValue'
        discount:
          $ref: '#/components/schemas/DiscountValue'
        surcharge:
          $ref: '#/components/schemas/SurchargeValue'
      additionalProperties: false
    BaseValue:
      description: |
        Base amount of the entry in EUR (€) excluding VAT
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    DiscountValue:
      description: |
        Discount amount of the entry in EUR (€) including VAT
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    SurchargeValue:
      description: |
        Surcharge amount of the entry in EUR (€) including VAT
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    Unit:
      description: |
        Unit details
        
      type: object
      required:
        - quantity
        - price
      properties:
        quantity:
          $ref: '#/components/schemas/UnitQuantity'
        measure:
          $ref: '#/components/schemas/UnitMeasure'
        factor:
          $ref: '#/components/schemas/UnitFactor'
        price:
          $ref: '#/components/schemas/UnitPrice'
      additionalProperties: false
    UnitQuantity:
      description: |
        Quantity or amount
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    UnitMeasure:
      description: |
        Unit of measurement of the quantity
        
      allOf:
        - $ref: '#/components/schemas/PlainString32'
    UnitFactor:
      description: |
        Reference amount of the price of the unit
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    UnitPrice:
      description: |
        Price per unit in EUR (€) including VAT, if applicable
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    EntryVat:
      description: |
        Defines the VAT information of the particular item
        
      discriminator:
        propertyName: type
        mapping:
          VAT_RATE: '#/components/schemas/VatRateCategory'
          VAT_EXEMPTION: '#/components/schemas/VatExemptionCategory'
      oneOf:
        - $ref: '#/components/schemas/VatRateCategory'
        - $ref: '#/components/schemas/VatExemptionCategory'
    VatRateCategory:
      description: |
        oas_components_schemas_vat_rate_category_description
      type: object
      required:
        - type
        - code
        - percentage
        - amount
        - exclusive
        - inclusive
      properties:
        type:
          type: string
          enum:
            - VAT_RATE
        code:
          $ref: '#/components/schemas/SystemVatRateCode'
        percentage:
          $ref: '#/components/schemas/SystemVatRatePercentage'
        amount:
          $ref: '#/components/schemas/VatAmount'
        exclusive:
          $ref: '#/components/schemas/VatExclusive'
        inclusive:
          $ref: '#/components/schemas/VatInclusive'
      additionalProperties: false
    VatExemptionCategory:
      description: |
        oas_components_schemas_vat_exemption_category_description
      type: object
      required:
        - type
        - code
      properties:
        type:
          type: string
          enum:
            - VAT_EXEMPTION
        code:
          $ref: '#/components/schemas/SystemVatExemptionCode'
      additionalProperties: false
    VatAmount:
      description: |
        Total VAT amount in EUR (€)
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    VatExclusive:
      description: |
        Total amount excluding VAT in EUR (€)
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    VatInclusive:
      description: |
        Total amount including VAT in EUR (€)
        
      allOf:
        - $ref: '#/components/schemas/Decimal12p8'
    VatBreakdown:
      description: |
        Provides the breakdown of the VAT into VAT rate and amounts per VAT rate.
        
      type: array
      items:
        $ref: '#/components/schemas/VatCategory'
      minItems: 1
      maxItems: 100
    VatCategory:
      description: |
        oas_components_schemas_vat_category_description
      type: object
      required:
        - percentage
        - amount
      properties:
        percentage:
          $ref: '#/components/schemas/SystemVatRatePercentage'
        amount:
          $ref: '#/components/schemas/VatAmount'
      additionalProperties: false
    Customer:
      description: |
        Information about the consumer of the business transaction
        
      discriminator:
        propertyName: type
        mapping:
          EXTERNAL: '#/components/schemas/ExternalCustomer'
          INTERNAL: '#/components/schemas/InternalCustomer'
      oneOf:
        - $ref: '#/components/schemas/ExternalCustomer'
        - $ref: '#/components/schemas/InternalCustomer'
    ExternalCustomer:
      description: |
        oas_components_schemas_external_customer_description
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - EXTERNAL
        code:
          $ref: '#/components/schemas/CustomerCode'
      additionalProperties: false
    InternalCustomer:
      description: |
        oas_components_schemas_internal_customer_description
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - INTERNAL
        code:
          $ref: '#/components/schemas/CustomerCode'
      additionalProperties: false
    CustomerCode:
      description: |
        Identifier provided by the consumer (e.g. lottery code in Italy 🇮🇹)
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    Recipients:
      description: |
        Recipient data
        
      type: array
      items:
        $ref: '#/components/schemas/Recipient'
      minItems: 1
      maxItems: 100
    Recipient:
      description: |
        oas_components_schemas_recipient_description
      discriminator:
        propertyName: type
        mapping:
          CONSUMER: '#/components/schemas/ConsumerRecipient'
          BUSINESS: '#/components/schemas/BusinessRecipient'
      oneOf:
        - $ref: '#/components/schemas/ConsumerRecipient'
        - $ref: '#/components/schemas/BusinessRecipient'
    ConsumerRecipient:
      description: |
        oas_components_schemas_customer_recipient_description
      type: object
      required:
        - type
        - name
        - address
      properties:
        type:
          type: string
          enum:
            - CONSUMER
        name:
          $ref: '#/components/schemas/NaturalName'
        address:
          $ref: '#/components/schemas/NaturalAddress'
        shipping:
          $ref: '#/components/schemas/Shipping'
        identification:
          $ref: '#/components/schemas/Identification'
        origin:
          $ref: '#/components/schemas/RecipientOrigin'
      additionalProperties: false
    BusinessRecipient:
      description: |
        oas_components_schemas_business_recipient_description
      type: object
      required:
        - type
        - name
        - address
        - identification
      properties:
        type:
          type: string
          enum:
            - BUSINESS
        name:
          $ref: '#/components/schemas/LegalName'
        address:
          $ref: '#/components/schemas/LegalAddress'
        shipping:
          $ref: '#/components/schemas/Shipping'
        identification:
          $ref: '#/components/schemas/Identification'
        origin:
          $ref: '#/components/schemas/RecipientOrigin'
        invoicing:
          $ref: '#/components/schemas/RecipientInvoicing'
      additionalProperties: false
    RecipientInvoicing:
      description: |
        Recipient details
        
      discriminator:
        propertyName: type
        mapping:
          PEPPOL: '#/components/schemas/RecipientInvoicingPeppol'
      oneOf:
        - $ref: '#/components/schemas/RecipientInvoicingPeppol'
    RecipientInvoicingPeppol:
      description: |
        oas_components_schemas_recipient_invoicing_peppol_description
      type: object
      required:
        - type
        - identifier
      properties:
        type:
          type: string
          enum:
            - PEPPOL
        identifier:
          $ref: '#/components/schemas/PeppolIdentifierAnnotation'
      additionalProperties: false
    RecipientOrigin:
      description: |
        Indicates whether the recipient is national or international
        
      type: string
      enum:
        - NATIONAL
        - INTERNATIONAL
      default: NATIONAL
    NaturalName:
      description: |
        Natural name or legal name
        
      allOf:
        - $ref: '#/components/schemas/PersonName'
    NaturalAddress:
      description: |
        Recipient address data
        
      allOf:
        - $ref: '#/components/schemas/Address'
    Identification:
      description: |
        VAT number of the recipient
        
      discriminator:
        propertyName: type
        mapping:
          VAT: '#/components/schemas/VatIdentification'
      oneOf:
        - $ref: '#/components/schemas/VatIdentification'
    VatIdentification:
      description: |
        oas_components_schemas_vat_identification_description
      type: object
      required:
        - type
        - number
      properties:
        type:
          type: string
          enum:
            - VAT
        number:
          $ref: '#/components/schemas/TaxpayerVatNumber'
      additionalProperties: false
    Shipping:
      description: |
        Shipping details
        
      type: object
      required:
        - address
      properties:
        address:
          $ref: '#/components/schemas/ShippingAddress'
        date:
          $ref: '#/components/schemas/ShippingDate'
      additionalProperties: false
    ShippingAddress:
      description: |
        Shipping address data
        
      allOf:
        - $ref: '#/components/schemas/Address'
    ShippingDate:
      description: |
        Shipping date
        
      allOf:
        - $ref: '#/components/schemas/DateFormatISO8601'
    Payments:
      description: |
        Collection of payment entries for the transaction<br>
        🇮🇹 In Italy, the supported payment types are:
        `CASH`, `CARD`, `ONLINE`, `OUTSTANDING`
        
      type: array
      items:
        $ref: '#/components/schemas/Payment'
      minItems: 1
      maxItems: 10
    Payment:
      discriminator:
        propertyName: type
        mapping:
          CASH: '#/components/schemas/CashPayment'
          CARD: '#/components/schemas/CardPayment'
          ONLINE: '#/components/schemas/OnlinePayment'
          OTHER: '#/components/schemas/OtherPayment'
          OUTSTANDING: '#/components/schemas/OutstandingPayment'
          VOUCHER: '#/components/schemas/VoucherPayment'
      oneOf:
        - $ref: '#/components/schemas/CashPayment'
        - $ref: '#/components/schemas/CardPayment'
        - $ref: '#/components/schemas/OnlinePayment'
        - $ref: '#/components/schemas/OtherPayment'
        - $ref: '#/components/schemas/OutstandingPayment'
        - $ref: '#/components/schemas/VoucherPayment'
    CashPayment:
      description: |
        Cash payment
        
      type: object
      required:
        - type
        - details
      properties:
        type:
          type: string
          enum:
            - CASH
        details:
          $ref: '#/components/schemas/PaymentDetails'
      additionalProperties: false
    CardPayment:
      description: |
        Card payment
        
      type: object
      required:
        - type
        - details
        - number
        - kind
      properties:
        type:
          type: string
          enum:
            - CARD
        details:
          $ref: '#/components/schemas/PaymentDetails'
        number:
          $ref: '#/components/schemas/PaymentCardNumber'
        kind:
          $ref: '#/components/schemas/PaymentCardKind'
      additionalProperties: false
    OnlinePayment:
      description: |
        Online or electronic payment
        
      type: object
      required:
        - type
        - details
        - name
      properties:
        type:
          type: string
          enum:
            - ONLINE
        details:
          $ref: '#/components/schemas/PaymentDetails'
        name:
          $ref: '#/components/schemas/PaymentName'
      additionalProperties: false
    OtherPayment:
      description: |
        Payment by a method not covered by other types
        
      type: object
      required:
        - type
        - details
      properties:
        type:
          type: string
          enum:
            - OTHER
        details:
          $ref: '#/components/schemas/PaymentDetails'
        name:
          $ref: '#/components/schemas/PaymentName'
      additionalProperties: false
    OutstandingPayment:
      description: |
        Amount that remains unpaid
        
      type: object
      required:
        - type
        - details
        - concept
      properties:
        type:
          type: string
          enum:
            - OUTSTANDING
        details:
          $ref: '#/components/schemas/PaymentDetails'
        concept:
          $ref: '#/components/schemas/EntryConcept'
      additionalProperties: false
    VoucherPayment:
      description: |
        Voucher issuance or redemption as a payment
        
      type: object
      required:
        - type
        - details
        - number
        - kind
      properties:
        type:
          type: string
          enum:
            - VOUCHER
        details:
          $ref: '#/components/schemas/PaymentDetails'
        number:
          $ref: '#/components/schemas/PaymentCardNumber'
        kind:
          $ref: '#/components/schemas/VoucherPaymentKind'
      additionalProperties: false
    VoucherPaymentKind:
      description: |
        Represents the voucher type.
        
      type: string
      enum:
        - SINGLE
        - MULTIPLE
    PaymentProperties:
      description: |
        Additional payment properties<br>
        Not applicable in 🇮🇹 Italy
        
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 64
      example:
        FAC-DUP-RES: 1A2B3C
        my_tag_123: '20250811'
    PaymentDetails:
      description: |
        Payment details
        
      type: object
      required:
        - amount
      properties:
        amount:
          $ref: '#/components/schemas/PaymentAmount'
        currency:
          $ref: '#/components/schemas/PaymentCurrency'
        date:
          $ref: '#/components/schemas/PaymentDate'
        discount:
          $ref: '#/components/schemas/PaymentDiscount'
        properties:
          $ref: '#/components/schemas/PaymentProperties'
      additionalProperties: false
    PaymentAmount:
      description: |
        Payment amount
        
      oneOf:
        - $ref: '#/components/schemas/Decimal12p8'
    PaymentDiscount:
      description: |
        Discount amount applied to this payment, if any
        
      oneOf:
        - $ref: '#/components/schemas/Decimal12p8'
    PaymentCurrency:
      description: |
        Currency of the payment in ISO 4217 format
        
      oneOf:
        - $ref: '#/components/schemas/CurrencyFormatISO4217'
    PaymentDate:
      description: |
        Payment date
        
      oneOf:
        - $ref: '#/components/schemas/DateFormatISO8601'
    PaymentCardKind:
      description: |
        Represents the card type
        
      type: string
      enum:
        - CREDIT
        - DEBIT
        - PREPAID
        - GIFT
        - TICKET
    PaymentCardNumber:
      description: |
        Card number
        
      allOf:
        - $ref: '#/components/schemas/MaskedCardNumberFormatISO7812'
    PaymentName:
      description: |
        Payment name
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    CryptographyCertificatePEM:
      description: |
        oas_components_schemas_cryptography_certificate_pem_description
      allOf:
        - $ref: '#/components/schemas/PrivacyEnhancedMailFormat'
    PrivacyEnhancedMailFormat:
      description: |
        oas_components_schemas_privacy_enhanced_main_format_description
      type: string
      maxLength: 16384
    Content:
      description: |
        oas_components_schemas_content_description
      required:
        - type
        - data
      properties:
        type:
          $ref: '#/components/schemas/ContentType'
        data:
          $ref: '#/components/schemas/ContentData'
      additionalProperties: false
    ContentType:
      description: |
        oas_components_schemas_content_type_description
      type: string
      enum:
        - application/json
        - application/xml
        - application/pdf
        - application/zip
    ContentData:
      description: |
        oas_components_schemas_content_data_description
      type: string
      format: byte
      maxLength: 65536
    IntegrityContent:
      description: |
        oas_components_schemas_integrity_content_description
      required:
        - type
        - data
      properties:
        type:
          $ref: '#/components/schemas/IntegrityContentType'
        data:
          $ref: '#/components/schemas/IntegrityContentData'
      additionalProperties: false
    IntegrityContentType:
      description: |
        Defines the integrity file content type
        
      type: string
      enum:
        - application/jose
    IntegrityContentData:
      description: |
        oas_components_schemas_integrity_content_data_description
      type: string
      format: byte
      maxLength: 16384
    CryptographySignature:
      description: |
        oas_components_schemas_cryptography_signature_description
      discriminator:
        propertyName: type
        mapping:
          ECDSA: '#/components/schemas/CryptographySignatureECDSA'
          RSA: '#/components/schemas/CryptographySignatureRSA'
      oneOf:
        - $ref: '#/components/schemas/CryptographySignatureECDSA'
        - $ref: '#/components/schemas/CryptographySignatureRSA'
    CryptographySignatureECDSA:
      description: |
        oas_components_schemas_cryptography_signature_ecdsa_description
      type: object
      required:
        - type
        - hash
      properties:
        type:
          type: string
          enum:
            - ECDSA
        hash:
          $ref: '#/components/schemas/CryptographyHashECDSA'
      additionalProperties: false
    CryptographyHashECDSA:
      description: |
        oas_components_schemas_cryptography_hash_ecdsa_description
      type: string
      enum:
        - SHA-256
        - SHA-384
    CryptographySignatureRSA:
      description: |
        oas_components_schemas_cryptography_signature_rsa_description
      type: object
      required:
        - type
        - hash
      properties:
        type:
          type: string
          enum:
            - RSA
        hash:
          $ref: '#/components/schemas/CryptographyHashRSA'
      additionalProperties: false
    CryptographyHashRSA:
      description: |
        oas_components_schemas_cryptography_hash_rsa_description
      type: string
      enum:
        - SHA-256
    CryptographyCertificate:
      description: |
        oas_components_schemas_cryptography_certificate_description
      type: object
      required:
        - serial_number
        - expires_at
        - x509_pem
      properties:
        serial_number:
          $ref: '#/components/schemas/CertificateSerialNumber'
        expires_at:
          $ref: '#/components/schemas/CertificateExpirationTimestamp'
        x509_pem:
          $ref: '#/components/schemas/CryptographyCertificatePEM'
      additionalProperties: false
    CertificateSerialNumber:
      description: |
        oas_components_schemas_cryptography_serial_number_description
      allOf:
        - $ref: '#/components/schemas/AlphaNumerical32'
    CertificateExpirationTimestamp:
      description: |
        oas_components_schemas_cryptography_expiration_timestamp_description
      allOf:
        - $ref: '#/components/schemas/DatetimeFormatRFC3339'
    Software:
      description: |
        Software information of the system
        
      type: object
      required:
        - name
        - version
      properties:
        name:
          $ref: '#/components/schemas/SoftwareName'
        version:
          $ref: '#/components/schemas/SoftwareVersion'
      additionalProperties: false
    SoftwareName:
      description: |
        Software name
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    SoftwareVersion:
      description: |
        Software version
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    Product:
      description: |
        Product details
        
      discriminator:
        propertyName: type
        mapping:
          GTIN-8: '#/components/schemas/GlobalTradeItemNumber8Product'
          GTIN-12: '#/components/schemas/GlobalTradeItemNumber12Product'
          GTIN-13: '#/components/schemas/GlobalTradeItemNumber13Product'
          GTIN-14: '#/components/schemas/GlobalTradeItemNumber14Product'
          MPN: '#/components/schemas/ManufacturerPartNumberProduct'
          SKU: '#/components/schemas/StockKeepingUnitProduct'
          OTHER: '#/components/schemas/OtherProduct'
      oneOf:
        - $ref: '#/components/schemas/GlobalTradeItemNumber8Product'
        - $ref: '#/components/schemas/GlobalTradeItemNumber12Product'
        - $ref: '#/components/schemas/GlobalTradeItemNumber13Product'
        - $ref: '#/components/schemas/GlobalTradeItemNumber14Product'
        - $ref: '#/components/schemas/ManufacturerPartNumberProduct'
        - $ref: '#/components/schemas/StockKeepingUnitProduct'
        - $ref: '#/components/schemas/OtherProduct'
    GlobalTradeItemNumber8Product:
      description: |
        Global Trade Item Number 8
        
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - GTIN-8
        number:
          $ref: '#/components/schemas/ProductGlobalTradeItemNumber8'
        details:
          $ref: '#/components/schemas/ProductDetails'
      additionalProperties: false
    GlobalTradeItemNumber12Product:
      description: |
        Global Trade Item Number 12
        
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - GTIN-12
        number:
          $ref: '#/components/schemas/ProductGlobalTradeItemNumber12'
        details:
          $ref: '#/components/schemas/ProductDetails'
      additionalProperties: false
    GlobalTradeItemNumber13Product:
      description: |
        Global Trade Item Number 13
        
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - GTIN-13
        number:
          $ref: '#/components/schemas/ProductGlobalTradeItemNumber13'
        details:
          $ref: '#/components/schemas/ProductDetails'
      additionalProperties: false
    GlobalTradeItemNumber14Product:
      description: |
        Global Trade Item Number 14
        
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - GTIN-14
        number:
          $ref: '#/components/schemas/ProductGlobalTradeItemNumber14'
        details:
          $ref: '#/components/schemas/ProductDetails'
      additionalProperties: false
    ManufacturerPartNumberProduct:
      description: |
        Manufacturer Part Number
        
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - MPN
        number:
          $ref: '#/components/schemas/ProductManufacturerPartNumber'
        details:
          $ref: '#/components/schemas/ProductDetails'
      additionalProperties: false
    StockKeepingUnitProduct:
      description: |
        Stock Keeping Unit
        
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - SKU
        number:
          $ref: '#/components/schemas/ProductStockKeepingUnitNumber'
        details:
          $ref: '#/components/schemas/ProductDetails'
      additionalProperties: false
    OtherProduct:
      description: |
        oas_components_schemas_other_product_description
      type: object
      required:
        - type
        - number
        - details
      properties:
        type:
          type: string
          enum:
            - OTHER
        number:
          $ref: '#/components/schemas/ProductNumber'
        details:
          $ref: '#/components/schemas/ProductDetails'
        code:
          $ref: '#/components/schemas/ProductCode'
      additionalProperties: false
    ProductDetails:
      description: |
        Additional product information such as production and entry dates.
        
      type: object
      required:
        - name
      properties:
        name:
          $ref: '#/components/schemas/ProductName'
        brand:
          $ref: '#/components/schemas/ProductBrand'
        model:
          $ref: '#/components/schemas/ProductModel'
        serial:
          $ref: '#/components/schemas/ProductSerial'
        label:
          $ref: '#/components/schemas/ProductLabel'
        batch:
          $ref: '#/components/schemas/ProductBatch'
        date_of_entry:
          $ref: '#/components/schemas/ProductDateOfEntry'
        date_of_production:
          $ref: '#/components/schemas/ProductDateOfProduction'
      additionalProperties: false
    ProductManufacturerPartNumber:
      description: |
        Manufacturer Part Number assigned by the producer
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
      example: PSP20U-99P98R
    ProductName:
      description: |
        Product name
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    ProductModel:
      description: |
        Product model
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    ProductBrand:
      description: |
        Product brand
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    ProductSerial:
      description: |
        Unique serial number of the individual unit
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    ProductLabel:
      description: |
        Human-readable product label or description
        
      allOf:
        - $ref: '#/components/schemas/PlainString256'
    ProductNumber:
      description: |
        Product identifier matching the selected code type (e.g., SKU, MPN, GTIN)
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
      example: '10000'
    ProductBatch:
      description: |
        Batch or lot identifier
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
      example: AGT-M10000
    ProductDateOfEntry:
      description: |
        Date the product was first put into operation
        
      allOf:
        - $ref: '#/components/schemas/DateFormatISO8601'
    ProductDateOfProduction:
      description: |
        Date the product was produced
        
      allOf:
        - $ref: '#/components/schemas/DateFormatISO8601'
    ProductCode:
      description: |
        General product code used when the identifier is not a SKU, MPN, or GTIN
        
      allOf:
        - $ref: '#/components/schemas/AlphaNumerical20'
    ProductGlobalTradeItemNumber8:
      description: |
        8-digit Global Trade Item Number (GTIN-8)
        
      allOf:
        - $ref: '#/components/schemas/Numerical8'
    ProductGlobalTradeItemNumber12:
      description: |
        12-digit Global Trade Item Number (GTIN-12)
        
      allOf:
        - $ref: '#/components/schemas/Numerical12'
    ProductGlobalTradeItemNumber13:
      description: |
        13-digit Global Trade Item Number (GTIN-13)
        
      allOf:
        - $ref: '#/components/schemas/Numerical13'
    ProductGlobalTradeItemNumber14:
      description: |
        14-digit Global Trade Item Number (GTIN-14)
        
      allOf:
        - $ref: '#/components/schemas/Numerical14'
    ProductStockKeepingUnitNumber:
      description: |
        Stock Keeping Unit number used by the seller
        
      type: string
      pattern: '^[A-Za-z0-9]+([A-Za-z0-9-_/.+:;]+)*$'
      minLength: 8
      maxLength: 12
      example: G1-T-F-XL-R4
    LocationName:
      description: |
        Location name
        
      allOf:
        - $ref: '#/components/schemas/PlainString32'
    LocationAddress:
      description: |
        Address of the business location or establishment; may differ from the legal address
        
      allOf:
        - $ref: '#/components/schemas/Address'
    LocationCoordinates:
      description: |
        Location coordinates
        
      type: object
      required:
        - latitude
        - longitude
      properties:
        latitude:
          $ref: '#/components/schemas/Latitude'
        longitude:
          $ref: '#/components/schemas/Longitude'
      additionalProperties: false
    Latitude:
      description: |
        Latitude (ranges from -90 to +90 degrees)
        
      type: string
      pattern: '^(-)?\d{1,2}(\.\d{1,6})?$'
      example: '48.199916'
    Longitude:
      description: |
        Longitude (ranges from -180 to +180 degrees)
        
      type: string
      pattern: '^(-)?\d{1,3}(\.\d{1,6})?$'
      example: '48.199916'
    LocationLabel:
      description: |
        Location label
        
      type: string
      pattern: '^([0-9]{14})$'
      minLength: 14
      maxLength: 14
      example: '73282932000074'
    Address:
      description: |
        Address
        
      type: object
      required:
        - line
        - code
        - city
        - country
      properties:
        line:
          $ref: '#/components/schemas/AddressLine'
        code:
          $ref: '#/components/schemas/AddressCode'
        city:
          $ref: '#/components/schemas/AddressCity'
        country:
          $ref: '#/components/schemas/AddressCountry'
      additionalProperties: false
    AddressLine:
      description: |
        Address line
        
      discriminator:
        propertyName: type
        mapping:
          STREET_NUMBER: '#/components/schemas/StreetNumberAddressLine'
      oneOf:
        - $ref: '#/components/schemas/StreetNumberAddressLine'
    StreetNumberAddressLine:
      description: |
        Street number
        
      type: object
      required:
        - type
        - street
        - number
      properties:
        type:
          type: string
          enum:
            - STREET_NUMBER
        prefix:
          $ref: '#/components/schemas/AddressPrefix'
        street:
          $ref: '#/components/schemas/AddressStreet'
        infix:
          $ref: '#/components/schemas/AddressInfix'
        number:
          $ref: '#/components/schemas/AddressNumber'
        suffix:
          $ref: '#/components/schemas/AddressSuffix'
      additionalProperties: false
    AddressPrefix:
      description: |
        Address prefix
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressStreet:
      description: |
        Street name
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressInfix:
      description: |
        Address infix
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressNumber:
      description: |
        Street number
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressSuffix:
      description: |
        Address suffix
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressCode:
      description: |
        Postal code
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressCity:
      description: |
        City
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    AddressCountry:
      description: |
        Country
        
      oneOf:
        - $ref: '#/components/schemas/CountryCode2'
    PersonName:
      description: |
        Name of a natural person
        
      type: object
      required:
        - gender
        - forename
        - surname
      properties:
        gender:
          $ref: '#/components/schemas/PersonGender'
        prefix:
          $ref: '#/components/schemas/PersonNamePrefix'
        forename:
          $ref: '#/components/schemas/PersonForename'
        infix:
          $ref: '#/components/schemas/PersonNameInfix'
        surname:
          $ref: '#/components/schemas/PersonSurname'
        suffix:
          $ref: '#/components/schemas/PersonNameSuffix'
      additionalProperties: false
    PersonGender:
      description: |
        Gender
        
      type: string
      enum:
        - DIVERSE
        - FEMALE
        - MALE
    PersonNamePrefix:
      description: |
        Name prefix
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    PersonForename:
      description: |
        Forename
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    PersonNameInfix:
      description: |
        Name infix
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    PersonSurname:
      description: |
        Surname
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    PersonNameSuffix:
      description: |
        Name suffix
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    PersonLabel:
      description: |
        Additional information about the person, e.g. an internal company identifier
        
      allOf:
        - $ref: '#/components/schemas/PlainString128'
    Numerical8:
      description: |
        oas_components_schemas_numerical_8_description
      type: string
      pattern: '^\d{8}$'
      example: '01234567'
    Numerical12:
      description: |
        oas_components_schemas_numerical_12_description
      type: string
      pattern: '^\d{12}$'
      example: '012345677012'
    Numerical13:
      description: |
        oas_components_schemas_numerical_13_description
      type: string
      pattern: '^\d{13}$'
      example: '0143456701110'
    Numerical14:
      description: |
        oas_components_schemas_numerical_14_description
      type: string
      pattern: '^\d{14}$'
      example: '00012345600012'
    UnsignedInteger4:
      description: |
        oas_components_schemas_unsigned_integer_4_description
      type: string
      pattern: '^(\d{1,4})$'
      example: '1234'
    Decimal12p8:
      description: |
        Decimal number as string, up to 12 digits before 
        and 8 digits after the decimal point.
        
      type: string
      pattern: '^(-)?\d{1,12}(\.\d{1,8})?$'
      example: '123456789012.34567890'
    AlphaNumerical20:
      description: |
        oas_components_schemas_alpha_numerical_20_description
      type: string
      pattern: '^( *[0-9A-Za-z.\-_/] *)*$'
      minLength: 1
      maxLength: 20
      example: 0a1B2cD ...
    AlphaNumerical32:
      description: |
        oas_components_schemas_alpha_numerical_32_description
      type: string
      pattern: '^( *[0-9A-Za-z.\-_/] *)*$'
      minLength: 1
      maxLength: 32
      example: 0a1B2cD ...
    UnsignedDecimal3p2:
      description: |
        oas_components_schemas_unsigned_decimal_3p2_description
      type: string
      pattern: '^\d{1,3}(\.\d{1,2})?$'
      example: '123.45'
    UniversallyUniqueIdentifierV3:
      description: |
        A Universally Unique Identifier Version 3 (UUIDv3) is a string-based label used to uniquely identify objects in a computer system based on MD5 hashed textual information of a namespace and name.
        The representation of UUIDs is defined in the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122).
        
      type: string
      format: uuid
      pattern: '^[0-9a-f]{8}-?[0-9a-f]{4}-?3[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$'
      example: c6437ef1-5b86-3a4e-a071-c2d4ad414e65
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
    UniversallyUniqueIdentifierV4:
      description: |
        A Universally Unique Identifier Version 4 (UUIDv4) is a string-based label used to uniquely identify objects in a computer system.
        The representation of UUIDs is defined in the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122).
        
      type: string
      format: uuid
      pattern: '^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$'
      example: 1c81cb86-c2e8-4074-afc3-a0601b2bf063
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
    UniversallyUniqueIdentifierV7:
      description: |
        A Universally Unique Identifier Version 7 (UUIDv7) is a string-based label used to uniquely identify objects in a computer system based on a millisecond Unix timestamp and a (pseudo) randomized number to avoid collisions. 
        The representation of UUIDs is defined in the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122).
        
      type: string
      format: uuid
      pattern: '^[0-9a-f]{8}-?[0-9a-f]{4}-?7[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}$'
      example: 0189f7ea-ae2c-7809-8aeb-b819cf5e9e7f
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
    PlainString16:
      description: |
        oas_components_schemas_plain_string_16_description
      type: string
      minLength: 1
      maxLength: 16
      example: text example...
    PlainString32:
      description: |
        A plain string with a maximum length of 32 characters
        
      type: string
      minLength: 1
      maxLength: 32
      example: text example...
    PlainString64:
      description: |
        A plain string with a maximum length of 64 characters
        
      type: string
      minLength: 1
      maxLength: 64
      example: text example...
    PlainString128:
      description: |
        A plain string with a maximum length of 128 characters
        
      type: string
      minLength: 1
      maxLength: 128
      example: text example...
    PlainString256:
      description: |
        A plain string with a maximum length of 256 characters
        
      type: string
      minLength: 1
      maxLength: 256
      example: text example...
    ErrorResponse:
      description: |
        Representation of error responses
        
      type: object
      required:
        - code
        - message
        - status
        - error
      properties:
        status:
          $ref: '#/components/schemas/ErrorStatus'
        code:
          $ref: '#/components/schemas/ErrorCode'
        error:
          $ref: '#/components/schemas/ErrorText'
        message:
          $ref: '#/components/schemas/ErrorMessage'
      additionalProperties: false
    ErrorStatus:
      description: |
        Integer-based HTTP error status code
        
      type: integer
      format: int32
      example: 401
    ErrorCode:
      description: |
        Representation of a unique error name of the HTTP error status code
        
      type: string
      example: E_UNAUTHORIZED_ACCESS
    ErrorText:
      description: |
        Representation of short description of the HTTP error status code
        
      type: string
      example: Unauthorized Access
    ErrorMessage:
      description: |
        Representation of long description of the HTTP error status code
        
      type: string
      example: Not authorized to perform this operation.
    Metadata:
      description: |
        Attach custom key value data to a resource. Useful for storing additional, structured information.
        If `metadata` appears in a response, it reflects the current metadata of the object.
        You can update metadata via the resource’s update endpoint. If a key is sent with an empty string value in an update, that key–value pair is removed.
        
        **Note**: Up to 20 keys. Key names up to 40 characters. Values up to 500 characters.
        
      allOf:
        - type: object
          maxProperties: 20
          additionalProperties:
            type: string
            maxLength: 500
          example:
            my_property_1: '1234'
            my_property_2: 'https://my-internal-system/path/to/resource/1234'
    ApiKeyString:
      description: |
        Key string of the API key pair
        
      type: string
    ApiSecretString:
      description: |
        Secret string of the API key pair. Keep this value confidential.
        
      type: string
    Bearer:
      description: |
        oas_components_schemas_bearer_description
      type: string
    Pagination:
      description: |
        Represents the pagination information of a list endpoint `results` set. If not provided, the current elements in the `results` set are the last elements.
        
      type: object
      required:
        - next
        - token
        - limit
      properties:
        next:
          $ref: '#/components/schemas/PaginationNext'
        token:
          $ref: '#/components/schemas/PaginationToken'
        limit:
          $ref: '#/components/schemas/PaginationLimit'
    PaginationNext:
      description: |
        Represents the pagination request to the next results set, which is composed of the requested resources, pagination token, and the pagination limit.
        
      allOf:
        - $ref: '#/components/schemas/UniformResourceIdentifier'
    PaginationToken:
      description: |
        Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.
        
      type: string
      pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$'
      maxLength: 1024
    PaginationLimit:
      description: |
        Represents the pagination limit of the results set of a listing endpoint.
        
      type: integer
      minimum: 1
      maximum: 100
      default: 10
    UniformResourceIdentifier:
      description: |
        oas_components_schemas_uniform_resource_identifier_description
      allOf:
        - format: '(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?'
          type: string
    JsonData:
      description: |
        oas_components_schemas_json_data_description
      type: string
      maxLength: 65536
    CountryCode2:
      description: |
        [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes
        
      allOf:
        - type: string
          enum:
            - AD
            - AE
            - AF
            - AG
            - AI
            - AL
            - AM
            - AO
            - AQ
            - AR
            - AS
            - AT
            - AU
            - AW
            - AX
            - AZ
            - BA
            - BB
            - BD
            - BE
            - BF
            - BG
            - BH
            - BQ
            - BI
            - BJ
            - BL
            - BM
            - BN
            - BO
            - BR
            - BS
            - BT
            - BV
            - BW
            - BY
            - BZ
            - CA
            - CC
            - CD
            - CF
            - CG
            - CH
            - CI
            - CK
            - CL
            - CM
            - CN
            - CO
            - CR
            - CU
            - CV
            - CW
            - CX
            - CY
            - CZ
            - DE
            - DJ
            - DK
            - DM
            - DO
            - DZ
            - EC
            - EE
            - EG
            - EH
            - ER
            - ES
            - ET
            - FI
            - FJ
            - FK
            - FM
            - FO
            - FR
            - GA
            - GB
            - GD
            - GE
            - GF
            - GG
            - GH
            - GI
            - GL
            - GM
            - GN
            - GP
            - GQ
            - GR
            - GS
            - GT
            - GU
            - GW
            - GY
            - HK
            - HM
            - HN
            - HR
            - HT
            - HU
            - ID
            - IE
            - IL
            - IM
            - IN
            - IO
            - IQ
            - IR
            - IS
            - IT
            - JE
            - JM
            - JO
            - JP
            - KE
            - KG
            - KH
            - KI
            - KM
            - KN
            - KP
            - KR
            - KW
            - KY
            - KZ
            - LA
            - LB
            - LC
            - LI
            - LK
            - LR
            - LS
            - LT
            - LU
            - LV
            - LY
            - MA
            - MC
            - MD
            - ME
            - MF
            - MG
            - MH
            - MK
            - ML
            - MM
            - MN
            - MO
            - MP
            - MQ
            - MR
            - MS
            - MT
            - MU
            - MV
            - MW
            - MX
            - MY
            - MZ
            - NA
            - NC
            - NE
            - NF
            - NG
            - NI
            - NL
            - 'NO'
            - NP
            - NR
            - NU
            - NZ
            - OM
            - PA
            - PE
            - PF
            - PG
            - PH
            - PK
            - PL
            - PM
            - PN
            - PR
            - PS
            - PT
            - PW
            - PY
            - QA
            - RE
            - RO
            - RS
            - RU
            - RW
            - SA
            - SB
            - SC
            - SD
            - SE
            - SG
            - SH
            - SI
            - SJ
            - SK
            - SL
            - SM
            - SN
            - SO
            - SR
            - SS
            - ST
            - SV
            - SX
            - SY
            - SZ
            - TC
            - TD
            - TF
            - TG
            - TH
            - TJ
            - TK
            - TL
            - TM
            - TN
            - TO
            - TR
            - TT
            - TV
            - TW
            - TZ
            - UA
            - UG
            - UM
            - US
            - UY
            - UZ
            - VA
            - VC
            - VE
            - VG
            - VI
            - VN
            - VU
            - WF
            - WS
            - YE
            - YT
            - ZA
            - ZM
            - ZW
    DateFormatISO8601:
      description: |
        API version used in your implementation
        
      type: string
      pattern: '^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$'
      minLength: 10
      maxLength: 10
      example: '2006-01-02'
    DatetimeFormatRFC3339:
      description: |
        oas_components_schemas_date_format_rfc3339_description
      type: string
      format: date-time
      minLength: 25
      maxLength: 25
      example: '2006-01-02T15:04:05+00:00'
    MaskedCardNumberFormatISO7812:
      description: |
        oas_components_schemas_masked_card_number_format_iso7812_description
      type: string
      pattern: '^([*0-9]{4,19})$'
      minLength: 4
      maxLength: 19
      example: '***************1234'
    CurrencyFormatISO4217:
      description: |
        ISO 4217 currency format
        
      type: string
      enum:
        - EUR
  securitySchemes:
    JWT:
      $ref: '#/components/securitySchemes/JsonWebToken'
    JsonWebToken:
      description: |
        A JSON Web Token (JWT) used for access control and authorization. Provided as a Bearer token in the HTTP `Authorization` header.
        
      type: http
      scheme: bearer
      bearerFormat: JWT
