openapi: 3.0.1
info:
  title: B2Brouter API
  description: The B2Brouter API allows you to send and receive electronic documents.
  version: '2026-04-20'
  contact:
    name: Service Delivery Team
    email: servicedelivery@b2brouter.net
servers:
  - url: https://api-staging.b2brouter.net
    description: Test server
  - url: https://api.b2brouter.net
    description: Production server
tags:
  - name: Accounts
    description: Related to accounts
  - name: Bank Accounts
    description: Related to bank accounts
  - name: Code lists
    description: Related our defined code lists
  - name: Contacts
    description: Related to contacts (clients and providers)
  - name: eAccounting
    description: Related to eAccounting
  - name: Events
    description: Related to events
  - name: Invoices
    description: Related to invoices
  - name: Ledgers
    description: Related to ledgers (sets of tax reports)
  - name: Lookup
    description: Related to lookup capacities of recipients
  - name: Orders
    description: Related to orders
  - name: Tax Reports
    description: Related tax reports
  - name: Tax Report Settings
    description: Related to tax report settings
  - name: Transports
    description: Related to transport configurations
  - name: TIN Verifications
    description: Batch TIN verification against tax authority census
  - name: Validation
    description: Related to validations
paths:
  /accounts:
    get:
      operationId: get-accounts
      tags:
        - Accounts
      summary: List accounts
      description: This endpoint lists all accounts associated with the group. Supports optional query language filtering.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - name: query
          in: query
          description: |
            Query language filter expression for flexible account filtering.

            **Operators:**
            - `=` Exact match
            - `~` Substring match (case-insensitive)  
            - `>` Greater than
            - `<` Less than
            - `>=` Greater than or equal
            - `<=` Less than or equal
            - `-` Negation
            - `AND` Logical AND
            - `OR` Logical OR

            **Searchable Fields:**
            - `tin_value`, `tin_scheme`, `cin_value`, `cin_scheme`, `country`, `name` (from Company)
            - `name`, `identifier`, `created_at`, `status` (from Project/Account)

            **Examples:**
            - `tin_value=ES92915236C` - Find account with specific TIN
            - `name~"Acme Corp"` - Find accounts containing "Acme Corp" in name  
            - `country=es AND tin_scheme=9920` - Spanish accounts with specific TIN scheme
            - `-status=9` - Exclude archived accounts (status 9)

            Returns 400 Bad Request with error code `invalid_query` if field is not recognized or syntax is invalid.
          required: false
          schema:
            type: string
            example: country=es AND tin_scheme=9920
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Account'
                        - $ref: '#/components/schemas/TransactionsEdocsync'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    post:
      operationId: create-account
      tags:
        - Accounts
      summary: Create an account
      description: This endpoint creates a new account associated with the group. Only available for eDocSync subscriptions.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      requestBody:
        description: The account object in format JSON to create
        content:
          application/json:
            schema:
              type: object
              required:
                - account
              properties:
                account:
                  $ref: '#/components/schemas/AccountCreate'
            examples:
              basic:
                summary: Create an account
                value:
                  account:
                    name: Example Company S.L.
                    tin_value: 13262627E
                    tin_scheme: 9920
                    address: Gran Via de les Corts Catalanes, 1
                    postalcode: '08001'
                    city: Barcelona
                    province: Barcelona
                    country: es
                    phone: '+34931234567'
                    email: billing@example-company.com
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}:
    get:
      operationId: get-account
      tags:
        - Accounts
      summary: Retrieve an account
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    put:
      operationId: put-account
      tags:
        - Accounts
      summary: Update an account
      description: |
        This endpoint updates an account associated with a group.
        Returns the full account representation after successful update.
        Note*: The TIN can not be updated.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The account object in format JSON to update
        content:
          application/json:
            schema:
              type: object
              required:
                - account
              properties:
                account:
                  $ref: '#/components/schemas/AccountUpdate'
      responses:
        '200':
          description: Successful operation - returns full account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-account
      tags:
        - Accounts
      summary: Delete or archive an account
      description: |
        Deletes or archives an account depending on its activity. By default, the account is permanently deleted.
        However, if the account has any associated transactions, it will be archived instead to ensure data recoverability.
        If the account has both `tin` and `cin` identifiers, archiving the account will cause the `cin` identifier to be lost.
        Returns the updated account object.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      responses:
        '200':
          description: Account archived/deleted successfully - returns full account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/AccountDeleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - account cannot be deleted (archived or main account)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/unarchive:
    post:
      operationId: unarchive-account
      tags:
        - Accounts
      summary: Unarchive an account
      description: |
        This endpoint unarchives an account associated with a group.
        Returns the full account representation after successful unarchive.
        Only available for eDocSync subscriptions.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      responses:
        '200':
          description: Account unarchived successfully - returns full account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - account cannot be unarchived because it's already unarchived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/logo:
    post:
      operationId: upload-account-logo
      tags:
        - Accounts
      summary: Upload an account logo
      description: |
        Uploads a logo file for the specified account. If a logo already exists, it will be replaced.
        The logo will be displayed automatically in all generated PDF invoices for this account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The logo attachment to add to the account
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Successful operation - returns full account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-account-logo
      tags:
        - Accounts
      summary: Deletes account logo
      description: Deletes the uploaded logo for the specified account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      responses:
        '200':
          description: Successful operation - returns full account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/bank_accounts:
    get:
      operationId: get-bank-accounts
      tags:
        - Bank Accounts
      summary: List bank accounts
      description: Returns an array of the bank accounts of the account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/BankAccount'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    post:
      operationId: create-bank-account
      tags:
        - Bank Accounts
      summary: Create a bank account
      description: Creates a new bank account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: Bank account object in format JSON to create
        content:
          application/json:
            schema:
              type: object
              required:
                - bank_account
              properties:
                bank_account:
                  $ref: '#/components/schemas/BankAccount'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_account:
                    $ref: '#/components/schemas/BankAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /attachments/{id}:
    delete:
      operationId: destroy-attachment
      tags:
        - Attachments
      summary: Delete an attachment
      description: Deletes an attachment. Returns the deleted attachment's details.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/attachment_id'
      responses:
        '200':
          description: Attachment successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  attachment:
                    $ref: '#/components/schemas/Attachment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not authorized to delete this attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      security:
        - api_key: []
  /bank_accounts/{id}:
    get:
      operationId: get-bank-account
      tags:
        - Bank Accounts
      summary: Get a bank account
      description: Returns a bank account entity
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: Bank account identifier
          schema:
            type: integer
      responses:
        '200':
          description: Returns a bank account
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_account:
                    $ref: '#/components/schemas/BankAccount'
        '404':
          description: Bank account not found
      security:
        - api_key: []
    put:
      operationId: put-bank-account
      tags:
        - Bank Accounts
      summary: Update a bank account
      description: Updates a bank account and returns the full bank account representation
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: Bank account identifier
          schema:
            type: integer
      requestBody:
        description: The Bank Account object in format JSON to update
        content:
          application/json:
            schema:
              type: object
              properties:
                bank_account:
                  $ref: '#/components/schemas/BankAccount'
      responses:
        '200':
          description: Bank account updated successfully - returns full bank account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_account:
                    $ref: '#/components/schemas/BankAccount'
        '422':
          description: The bank account has not been updated due to validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - api_key: []
    delete:
      operationId: delete-bank-account
      tags:
        - Bank Accounts
      summary: Delete a bank account
      description: Deletes a bank account and returns the full bank account representation
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: Bank account identifier
          schema:
            type: integer
      responses:
        '200':
          description: Bank account deleted successfully - returns full bank account representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_account:
                    $ref: '#/components/schemas/BankAccount'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Bank account not found
        '422':
          description: Unable to delete bank account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - api_key: []
  /accounts/{account}/eaccounting/connected_accounts:
    get:
      operationId: get-connected-accounts
      tags:
        - eAccounting
      summary: List connected accounts
      description: This endpoint list all connected client accounts associated through eAccounting connection with your account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/tax_report_settings:
    get:
      operationId: get-tax-report-settings
      tags:
        - Tax Report Settings
      summary: List tax report settings
      description: This endpoint list all tax report settings this account has configured.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report_settings:
                    type: array
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/TbaiTaxReportSetting'
                        - $ref: '#/components/schemas/SdiTaxReportSetting'
                        - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                        - $ref: '#/components/schemas/KsefTaxReportSetting'
                        - $ref: '#/components/schemas/DgfipTaxReportSetting'
                        - $ref: '#/components/schemas/SiiTaxReportSetting'
                  total_count:
                    type: integer
                    example: 1
                  offset:
                    type: integer
                    example: 0
                  limit:
                    type: integer
                    example: 25
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    post:
      operationId: create-tax-report-setting
      tags:
        - Tax Report Settings
      summary: Create a tax report setting
      description: This endpoint creates a new tax report setting associated with the group.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The tax report setting object in format JSON to create
        content:
          application/json:
            schema:
              type: object
              required:
                - tax_report_setting
              properties:
                tax_report_setting:
                  oneOf:
                    - allOf:
                        - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                        - required:
                            - code
                            - reason_vat_exempt
                            - special_regime_key
                            - special_regime_key_igic
                            - reason_no_subject
                            - credit_note_code
                    - allOf:
                        - $ref: '#/components/schemas/TbaiTaxReportSetting'
                        - required:
                            - code
                            - delegation
                            - reason_vat_exempt
                            - special_regime_key
                            - reason_no_subject
                            - credit_note_code
                            - type_operation
                    - allOf:
                        - $ref: '#/components/schemas/SdiTaxReportSetting'
                        - required:
                            - code
                    - allOf:
                        - $ref: '#/components/schemas/LhdnTaxReportSetting'
                        - required:
                            - code
                    - allOf:
                        - $ref: '#/components/schemas/KsefTaxReportSetting'
                        - required:
                            - code
                            - type_operation
                            - credit_note_code
                            - certificate
                            - certificate_pin
                    - allOf:
                        - $ref: '#/components/schemas/DgfipTaxReportSetting'
                        - required:
                            - code
                            - start_date
                            - type_operation
                    - allOf:
                        - $ref: '#/components/schemas/SiiTaxReportSetting'
                        - required:
                            - code
            examples:
              ksef_example:
                summary: Create KSeF Tax Report Setting
                value:
                  tax_report_setting:
                    code: ksef
                    type_operation: services
                    credit_note_code: '1'
                    certificate: MIIKZAIBAzCCCh4GCSqGSIb3DQEHAaCCCg8EggoLMIIKBzCCBXcGCSqGSIb3DQEHBqCCBWgwggVkAgEAMIIFXQYJKoZIhvcNAQcBMBwGCiqGSIb3DQEMAQYwDgQIvFzJKLMtK4YCAggAgIIFMGxampleBase64EncodedCertificateDataHere...
                    certificate_pin: MySecurePassword123
                    auto_generate: true
                    auto_send: true
                    enabled: true
              dgfip_example:
                summary: Create DGFiP Tax Report Setting
                value:
                  tax_report_setting:
                    code: dgfip
                    start_date: '2025-04-29T00:00:00.000Z'
                    type_operation: services
                    email: contact@company.fr
                    enterprise_size: pme
                    naf_code: '62'
                    auto_generate: true
                    auto_send: true
                    enabled: true
              dgfip_annuaire_only_example:
                summary: Create DGFiP Tax Report Setting (annuaire only)
                value:
                  tax_report_setting:
                    code: dgfip
                    start_date: '2025-04-29T00:00:00.000Z'
                    type_operation: services
                    email: contact@company.fr
                    annuaire_only: true
                    enabled: true
              verifactu_example:
                summary: Create Verifactu (Spain, AEAT) Tax Report Setting
                description: |
                  Enables Verifactu reporting for a Spanish account. `auto_generate` is always forced to `true` for Verifactu (legal requirement), so the report is generated before the invoice is issued. The `reason_*`/`special_regime_key*`/`credit_note_code` fields set the account-level defaults applied when an invoice doesn't specify them.
                value:
                  tax_report_setting:
                    code: verifactu
                    start_date: '2025-06-06'
                    auto_generate: true
                    auto_send: true
                    reason_vat_exempt: E1
                    special_regime_key: '01'
                    special_regime_key_igic: '01'
                    reason_no_subject: N1
                    credit_note_code: R1
                    type_operation: services
              ticketbai_example:
                summary: Create TicketBAI (Basque Country) Tax Report Setting
                description: |
                  Enables TicketBAI reporting. `delegation` is mandatory and selects the Basque provincial tax authority (`araba`, `gipuzkoa` or `bizkaia`); for `bizkaia` the company `epigraph` is also required. `auto_generate` is forced to `true` (legal requirement) and fires once the invoice reaches the `sent` state.
                value:
                  tax_report_setting:
                    code: tbai
                    start_date: '2024-06-06'
                    auto_generate: true
                    auto_send: true
                    delegation: gipuzkoa
                    reason_vat_exempt: E1
                    special_regime_key: '01'
                    reason_no_subject: OT
                    credit_note_code: R1
                    type_operation: services
                    epigraph: '147410'
              sdi_example:
                summary: Create SDI (Italy) Tax Report Setting
                description: |
                  SDI has no special configuration requirements — creating the setting is enough to start reporting.
                value:
                  tax_report_setting:
                    code: sdi
                    start_date: '2024-06-06'
                    auto_generate: true
                    auto_send: true
              lhdn_example:
                summary: Create LHDN / MyInvois (Malaysia) Tax Report Setting
                description: |
                  Enables MyInvois reporting for a Malaysian account. Requires B2Brouter to be registered as your intermediary ERP on the MyInvois portal first. `msic` and `classification_code` must be official LHDN codes (https://sdk.myinvois.hasil.gov.my/codes/).
                value:
                  tax_report_setting:
                    code: lhdn
                    msic: '01111'
                    type_operation: services
                    classification_code: '001'
              sii_example:
                summary: Create SII (Spain, AEAT) Tax Report Setting
                description: |
                  Enables SII reporting through the JSON Tax Report API for a Spanish account. Available from API version 2026-04-20. Creating the setting is enough to start reporting; `auto_send` controls whether generated SII tax reports are submitted to AEAT automatically.
                value:
                  tax_report_setting:
                    code: sii
                    start_date: '2026-04-29T00:00:00.000Z'
                    auto_send: true
                    enabled: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report_setting:
                    anyOf:
                      - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                      - $ref: '#/components/schemas/TbaiTaxReportSetting'
                      - $ref: '#/components/schemas/SdiTaxReportSetting'
                      - $ref: '#/components/schemas/LhdnTaxReportSetting'
                      - $ref: '#/components/schemas/KsefTaxReportSetting'
                      - $ref: '#/components/schemas/DgfipTaxReportSetting'
                      - $ref: '#/components/schemas/SiiTaxReportSetting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/tax_report_settings/{code}:
    get:
      operationId: get-tax-report-setting
      tags:
        - Tax Report Settings
      summary: Retrieve a tax report setting
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/tax_authority_code'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report_setting:
                    anyOf:
                      - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                      - $ref: '#/components/schemas/TbaiTaxReportSetting'
                      - $ref: '#/components/schemas/SdiTaxReportSetting'
                      - $ref: '#/components/schemas/LhdnTaxReportSetting'
                      - $ref: '#/components/schemas/KsefTaxReportSetting'
                      - $ref: '#/components/schemas/DgfipTaxReportSetting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    put:
      operationId: put-tax-report-setting
      tags:
        - Tax Report Settings
      summary: Update a tax report setting
      description: |
        This endpoint updates a tax report setting associated with an account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/tax_authority_code'
      requestBody:
        description: The tax report setting object in format JSON to update
        content:
          application/json:
            schema:
              type: object
              required:
                - tax_report_setting
              properties:
                tax_report_setting:
                  anyOf:
                    - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                    - $ref: '#/components/schemas/TbaiTaxReportSetting'
                    - $ref: '#/components/schemas/SdiTaxReportSetting'
                    - $ref: '#/components/schemas/LhdnTaxReportSetting'
                    - $ref: '#/components/schemas/KsefTaxReportSetting'
                    - $ref: '#/components/schemas/DgfipTaxReportSetting'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report_setting:
                    oneOf:
                      - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                      - $ref: '#/components/schemas/TbaiTaxReportSetting'
                      - $ref: '#/components/schemas/SdiTaxReportSetting'
                      - $ref: '#/components/schemas/LhdnTaxReportSetting'
                      - $ref: '#/components/schemas/KsefTaxReportSetting'
                      - $ref: '#/components/schemas/DgfipTaxReportSetting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-tax-report-setting
      tags:
        - Tax Report Settings
      summary: Delete a tax report setting
      description: This endpoint deletes a tax report setting associated with an account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/tax_authority_code'
      responses:
        '200':
          description: Successful operation - returns full tax report setting representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report_setting:
                    oneOf:
                      - $ref: '#/components/schemas/VerifactuTaxReportSetting'
                      - $ref: '#/components/schemas/TbaiTaxReportSetting'
                      - $ref: '#/components/schemas/SdiTaxReportSetting'
                      - $ref: '#/components/schemas/LhdnTaxReportSetting'
                      - $ref: '#/components/schemas/KsefTaxReportSetting'
                      - $ref: '#/components/schemas/DgfipTaxReportSetting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /invoices/{id}:
    get:
      operationId: get-invoice
      tags:
        - Invoices
      summary: Get an invoice
      description: Returns information about a specific invoice, it can be an **issued invoice** or a **received invoice**.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
        - $ref: '#/components/parameters/include'
        - $ref: '#/components/parameters/disposition'
        - $ref: '#/components/parameters/ack'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/InvoiceResponse'
        '302':
          description: |-
            Found. This response indicates that the requested invoice is a **received invoice**.  
               The response includes a `Location` header with the URL where the full invoice details can be obtained.
          headers:
            Location:
              description: URL of the resource to which the request is redirected
              schema:
                type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Invoice not found
      security:
        - api_key: []
    put:
      operationId: put-invoice
      tags:
        - Invoices
      summary: Update an invoice
      description: Update a specific invoice.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      requestBody:
        description: The Invoice object in format JSON to update
        content:
          application/json:
            schema:
              type: object
              properties:
                invoice:
                  $ref: '#/components/schemas/InvoiceUpdate'
      responses:
        '200':
          description: Successful update - returns full invoice representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/InvoiceResponse'
        '400':
          description: Invalid status value
        '422':
          description: Unprocessable Entity
      security:
        - api_key: []
    delete:
      operationId: delete-invoice
      tags:
        - Invoices
      summary: Delete an invoice
      description: Delete a specific invoice.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      responses:
        '200':
          description: Invoice deleted successfully - returns full invoice representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/InvoiceResponse'
        '404':
          description: Invoice not found
        '422':
          description: Unprocessable Entity
      security:
        - api_key: []
  /invoices/{id}/as/{document_type_code}:
    get:
      operationId: get-invoice-with-document-type
      tags:
        - Invoices
      summary: Get an invoice with a specific document type
      description: |
        Returns the specified invoice with the indicated document type.<br> It can be an **issued invoice** or a **received invoice**.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
        - $ref: '#/components/parameters/document_type_code'
      responses:
        '200':
          description: Successful operation
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Invoice not found
        '422':
          description: The document type is not supported for invoices
      security:
        - api_key: []
  /accounts/{account}/invoices:
    get:
      operationId: get-invoices
      tags:
        - Invoices
      summary: List of invoices
      description: Returns a paginated list of the invoices of the account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/ack_filter'
        - $ref: '#/components/parameters/date_from'
        - $ref: '#/components/parameters/date_to'
        - $ref: '#/components/parameters/due_date_from'
        - $ref: '#/components/parameters/due_date_to'
        - $ref: '#/components/parameters/number'
        - $ref: '#/components/parameters/state_updated_at_from'
        - $ref: '#/components/parameters/updated_at_from'
        - $ref: '#/components/parameters/tin_value'
        - $ref: '#/components/parameters/cin_value'
        - $ref: '#/components/parameters/new'
        - $ref: '#/components/parameters/sending'
        - $ref: '#/components/parameters/error'
        - $ref: '#/components/parameters/sent'
        - $ref: '#/components/parameters/refused'
        - $ref: '#/components/parameters/closed'
        - $ref: '#/components/parameters/registered'
        - $ref: '#/components/parameters/accepted'
        - $ref: '#/components/parameters/downloaded'
        - $ref: '#/components/parameters/annotated'
        - $ref: '#/components/parameters/allegedly_paid'
        - $ref: '#/components/parameters/paid'
        - $ref: '#/components/parameters/received_invoice_received'
        - $ref: '#/components/parameters/received_invoice_ocr_failed'
        - $ref: '#/components/parameters/received_invoice_exclude_offices'
        - $ref: '#/components/parameters/from_net'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoiceReduced'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
      security:
        - api_key: []
    post:
      operationId: create-invoice
      tags:
        - Invoices
      summary: Create an invoice
      description: Create an invoice
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The Invoice object in format JSON to create
        content:
          application/json:
            schema:
              type: object
              required:
                - invoice
              properties:
                send_after_import:
                  $ref: '#/components/schemas/SendAfterImport'
                ack:
                  $ref: '#/components/schemas/Ack'
                invoice:
                  $ref: '#/components/schemas/Invoice'
            examples:
              minimal:
                summary: Minimal issued invoice (one line, 21% VAT)
                value:
                  invoice:
                    type: IssuedInvoice
                    number: '001'
                    date: '2026-06-19'
                    due_date: '2026-07-19'
                    contact:
                      name: Example Customer S.L.
                      tin_value: ESA13585625
                      tin_scheme: '9920'
                      address: Gran Via de les Corts Catalanes, 1
                      postalcode: '08001'
                      city: Barcelona
                      province: Barcelona
                      country: es
                      email: billing@example.com
                    invoice_lines_attributes:
                      - description: Consulting services
                        quantity: 1
                        price: 100
                        taxes_attributes:
                          - name: IVA
                            category: S
                            percent: 21
              with_discount:
                summary: Invoice with a 10% line discount
                value:
                  invoice:
                    type: IssuedInvoice
                    number: '002'
                    date: '2026-06-19'
                    due_date: '2026-07-19'
                    contact:
                      name: Example Customer S.L.
                      tin_value: ESA13585625
                      tin_scheme: '9920'
                      address: Gran Via de les Corts Catalanes, 1
                      postalcode: '08001'
                      city: Barcelona
                      province: Barcelona
                      country: es
                      email: billing@example.com
                    invoice_lines_attributes:
                      - description: Consulting services
                        quantity: 1
                        price: 100
                        taxes_attributes:
                          - name: IVA
                            category: S
                            percent: 21
                        allowance_charges_attributes:
                          - allowance_charge_indicator: allowance
                            percentage: 10
                            description: Early-payment discount
                            apply_taxes: true
              multiple_vat:
                summary: Invoice with two VAT rates (21% and 10%)
                value:
                  invoice:
                    type: IssuedInvoice
                    number: '003'
                    date: '2026-06-19'
                    due_date: '2026-07-19'
                    contact:
                      name: Example Customer S.L.
                      tin_value: ESA13585625
                      tin_scheme: '9920'
                      address: Gran Via de les Corts Catalanes, 1
                      postalcode: '08001'
                      city: Barcelona
                      province: Barcelona
                      country: es
                      email: billing@example.com
                    invoice_lines_attributes:
                      - description: Standard-rate item
                        quantity: 1
                        price: 100
                        taxes_attributes:
                          - name: IVA
                            category: S
                            percent: 21
                      - description: Reduced-rate item
                        quantity: 1
                        price: 50
                        taxes_attributes:
                          - name: IVA
                            category: S
                            percent: 10
              with_withholding:
                summary: Invoice with IRPF withholding (retención, -15% on the base)
                value:
                  invoice:
                    type: IssuedInvoice
                    number: '004'
                    date: '2026-06-19'
                    due_date: '2026-07-19'
                    contact:
                      name: Example Customer S.L.
                      tin_value: ESA13585625
                      tin_scheme: '9920'
                      address: Gran Via de les Corts Catalanes, 1
                      postalcode: '08001'
                      city: Barcelona
                      province: Barcelona
                      country: es
                      email: billing@example.com
                    invoice_lines_attributes:
                      - description: Professional services
                        quantity: 1
                        price: 100
                        taxes_attributes:
                          - name: IVA
                            category: S
                            percent: 21
                          - name: IRPF
                            category: S
                            percent: -15
      responses:
        '201':
          description: Invoice created successfully - returns full invoice representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    allOf:
                      - $ref: '#/components/schemas/InvoiceResponse'
                      - type: object
                        properties:
                          lines:
                            type: array
                            readOnly: false
                            writeOnly: true
        '400':
          description: Invalid status value
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Entity
      security:
        - api_key: []
  /accounts/{account}/payments:
    get:
      operationId: get-account-payments
      tags:
        - Payments
      summary: List of payments
      description: Returns a paginated list of the payments recorded on the account's invoices, newest first, across all its invoices. Use the `invoice_id` parameter to list the payments of a single invoice.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - name: invoice_id
          in: query
          required: false
          description: Only return the payments of this invoice. An invoice that does not belong to the account yields an empty list.
          schema:
            type: integer
          example: 12345
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
    post:
      operationId: create-payment
      tags:
        - Payments
      summary: Record a payment on an invoice
      description: |-
        Records a payment — total or partial — on one of the account's invoices, identified by the `invoice_id` field of the body. An invoice that does not belong to the account is a `404`.

        The invoice may be in any state — drafts included. When the accumulated payments cover the invoice total, the invoice automatically transitions to `paid`, whatever its current state.

        Send either `amount` or `full: true`. With `full`, the payment settles exactly the outstanding amount, computed when the request executes — use it to settle an invoice without racing other payments recorded between reading the outstanding amount and posting it.

        On accounts with an active payment-reporting tax authority the corresponding fiscal report fires automatically. For DGFiP: a domestic French payment emits a CDV 212 lifecycle declaration; a cross-border or B2C payment creates an F10 payment tax report.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The payment to record.
        content:
          application/json:
            schema:
              type: object
              required:
                - payment
              properties:
                payment:
                  allOf:
                    - $ref: '#/components/schemas/Payment'
                    - required:
                        - invoice_id
                      properties:
                        full:
                          type: boolean
                          description: Settle exactly the outstanding amount, computed at execution time. Mutually exclusive with `amount` — sending both answers `422` with code `parameter_conflict`; one of the two is required. The response carries the computed `amount`.
            example:
              payment:
                invoice_id: 12345
                amount: 150.5
                date: '2026-07-01'
                payment_method: 4
                reference: REF-2026-001
      responses:
        '201':
          description: Payment recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment:
                    $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /payments/{id}:
    get:
      operationId: get-payment
      tags:
        - Payments
      summary: Get a payment
      description: Retrieves a single payment by its ID.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: ID of the payment.
          schema:
            type: integer
          example: 981
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment:
                    $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
    put:
      operationId: update-payment
      tags:
        - Payments
      summary: Update a payment
      description: |-
        Updates the payment's own fields (amount, date, payment method, reference).

        The invoice link is immutable — `invoice_id` in the body is ignored. `full` is only accepted when creating a payment — sending it here answers `422` with code `parameter_not_allowed`. A payment already declared to a tax authority cannot be updated — the request answers `422` with the lock reason.

        An amount change re-evaluates the invoice: when the accumulated payments now cover its total, the invoice automatically transitions to `paid`, whatever its current state. Lowering an amount never reverts a `paid` invoice.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: ID of the payment to update.
          schema:
            type: integer
          example: 981
      requestBody:
        description: The payment fields to update.
        content:
          application/json:
            schema:
              type: object
              required:
                - payment
              properties:
                payment:
                  $ref: '#/components/schemas/Payment'
            example:
              payment:
                amount: 150.5
                date: '2026-07-01'
                payment_method: 4
                reference: REF-2026-001
      responses:
        '200':
          description: Payment updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment:
                    $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-payment
      tags:
        - Payments
      summary: Delete a payment
      description: |-
        Deletes a payment and returns it.

        Deleting a payment does **not** revert the invoice state: an invoice already marked `paid` stays `paid`. A payment already declared to a tax authority cannot be deleted — the request answers `422` with the lock reason.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: ID of the payment to delete.
          schema:
            type: integer
          example: 981
      responses:
        '200':
          description: Payment deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment:
                    $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/invoices/import:
    post:
      operationId: import-invoice
      tags:
        - Invoices
      summary: Import an invoice from a file
      description: Import an invoice from a supported file.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/send_after_import'
        - $ref: '#/components/parameters/transport_type_code_for_contact'
        - $ref: '#/components/parameters/document_type_code_for_contact'
        - $ref: '#/components/parameters/issued'
        - $ref: '#/components/parameters/ack'
      requestBody:
        description: The invoice file to import
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Invoice imported successfully - returns full invoice representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/InvoiceResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '406':
          description: Not Acceptable
      security:
        - api_key: []
  /accounts/{account}/invoices/imports:
    post:
      operationId: create-invoice-import-batch
      tags:
        - Invoices
      summary: Create a bulk invoice import batch
      description: |-
        Submits up to 100 invoice XML files in a single multipart request and imports them asynchronously, using the same per-file pipeline as the web-UI bulk upload.

        Processing is always asynchronous. This endpoint returns `202 Accepted` immediately with the batch ID and `processing` status. Use the `GET /accounts/{account}/invoices/imports/{id}` endpoint to poll for per-file outcomes, or subscribe to the `invoice_import.finished` webhook event to be notified when the whole batch finishes.

        **Per-file deduplication:** files whose SHA-256 digest is already present in the project are recorded with `error_message: duplicated_document` instead of being re-imported. Two files in the same batch with the same digest also collide — the second receives the same dedup marker.

        **Filename correlation:** the `results[].filename` field echoes the multipart filename for items that have not yet been imported. Once an item is imported, the polymorphic association on the wrapper row swaps from the original `Attachment` to the resulting `Invoice` and the filename is no longer accessible. Clients correlate imported items by the explicit `results[].index` (zero-based position in the original upload, always present) or by `invoice_id`.

        **Webhook payload note:** the `invoice_import.finished` webhook carries only the batch summary (batch_id, status, summary, status_url). Per-file results are not included to keep the payload under the `web_hook_calls.data` 65535-byte cap — fetch them via the `status_url` GET endpoint.

        **Limits:** Maximum 100 files per batch.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  minItems: 1
                  maxItems: 100
                  description: Invoice XML files to import.
                  items:
                    type: string
                    format: binary
                from_net:
                  type: string
                  description: Origin tag stored on the resulting Invoice (e.g. `uploaded`, `sftp`, `peppol`). Defaults to `uploaded`.
                  example: uploaded
                issued:
                  type: boolean
                  description: Whether the files should be imported as issued (sent by the account) or received. Defaults to the receiver behaviour for most networks.
                validate:
                  type: boolean
                  description: Run import-time validations (default true).
                keep_original:
                  type: boolean
                  description: Keep the original XML attached to the Invoice (default true).
                send_after_import:
                  type: boolean
                  description: After importing, attempt to send the resulting invoice. Same semantics as the single-file `POST .../invoices/import` endpoint.
              required:
                - files
      responses:
        '202':
          description: Batch accepted. Poll `GET /accounts/{account}/invoices/imports/{id}` for per-file outcomes or subscribe to the `invoice_import.finished` webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceImportBatch'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
  /accounts/{account}/invoices/imports/{id}:
    get:
      operationId: get-invoice-import-batch
      tags:
        - Invoices
      summary: Get a bulk invoice import batch
      description: |-
        Returns the current state of a batch import and the per-file outcomes.

        The response includes one `results[]` entry per uploaded file, in the original upload order. Each result carries an explicit `index` (its zero-based position in the upload, the reliable correlation key), its `status` (`unfinished`, `done`, `error`, `done_with_error`, etc.), the resulting `invoice_id` when applicable, and the importer error message when the import failed.

        While the batch is still `processing`, items not yet picked up by the job report `status: unfinished`. Once the batch reaches `done`, all items have a terminal status.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - name: id
          in: path
          required: true
          description: ID of the batch (`BulkAction`).
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceImportBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
  /invoices/{id}/mark_as:
    post:
      operationId: mark-as-invoice
      tags:
        - Invoices
      summary: Switch invoice state
      description: Switch the state of an existing invoice.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      requestBody:
        description: Attributes to update the state of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - state
              properties:
                state:
                  $ref: '#/components/schemas/StateInput'
                commit:
                  $ref: '#/components/schemas/InvoiceMarkAsCommit'
                reason:
                  $ref: '#/components/schemas/InvoiceMarkAsReason'
      responses:
        '200':
          description: State successfully switched - returns full invoice representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/InvoiceResponse'
        '401':
          description: ' Unauthorized'
        '403':
          description: Forbidden
        '404':
          description: ' Invoice not found'
        '422':
          description: ' Unprocessable Entity'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorItem'
      security:
        - api_key: []
  /invoices/{id}/add_attachment:
    post:
      operationId: add-attachment-invoice
      tags:
        - Invoices
      summary: Add attachment
      description: Adds an attachment to an existing invoice. Do not confuse with add_attachments method (note plural)
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
        - $ref: '#/components/parameters/filename'
        - $ref: '#/components/parameters/use_as_pdf_view'
      requestBody:
        description: The attachment to add to the invoice
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Attachment successfully added
        '403':
          description: Forbidden
      security:
        - api_key: []
  /invoices/{id}/add_attachments:
    post:
      operationId: add-attachments-invoice
      tags:
        - Invoices
      summary: Add attachments
      description: Adds attachments to an existing invoice. Expects a multipart POST request, attachments must be compressed in a zip file.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                attachments:
                  description: A zip file containing the attachments to add to the invoice.
                  type: string
                  format: binary
      responses:
        '201':
          description: Attachments successfully added
          content:
            application/json:
              schema:
                type: object
                properties:
                  saved_attachments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attachment'
                  errors:
                    type: array
                    items: {}
        '403':
          description: Forbidden
        '422':
          description: Errors adding attachments
          content:
            application/json:
              schema:
                type: object
                properties:
                  saved_attachments:
                    type: array
                    items: {}
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorMessage'
      security:
        - api_key: []
  /invoices/{id}/generate_tax_report:
    post:
      operationId: generate-tax-report-from-invoice
      tags:
        - Invoices
      summary: Generate a tax report from an Invoice
      description: |-
        Generates the tax report for an existing invoice. Depending on the Tax Authority and the settings of your account, the tax report might be automatically send after issuing an invoice. Thus, it might not be necessary to explicitly call this method if you issue your invoices via B2Brouter.
        Note that you will have to check the status of the tax report we send in your behalf in order to be able to take the necessary actions in case any error or warning is issued by the Tax Authority. Because of the asynchronous nature of the tax report sending process, there is no guarantee that when you check the status of the tax reports it will already have the response of the Tax Authority. It usually takes a few seconds to complete the transaction. You will know that the transaction is complete if the response of the check of the status of the tax report has an status **registered** or **error**. We recommend you retry the status check until you get a final state on your tax report.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      responses:
        '200':
          description: Tax report successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReportGenerated'
        '403':
          description: Forbidden
      security:
        - api_key: []
  /invoices/send_invoice/{id}:
    post:
      operationId: send-invoice
      tags:
        - Invoices
      summary: Send invoice
      description: Send the invoice
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      responses:
        '204':
          description: Invoice successfully sent
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Entity
      security:
        - api_key: []
  /invoices/{id}/validate:
    get:
      operationId: validate
      tags:
        - Invoices
      summary: Validates an invoice
      description: |
        This endpoint validates the electronic invoice identified by the ID specified in the request parameters.

        The validation of the e-document is performed through:

          - Checking the use of a correct syntax schema (XSD).
          - Checking the business rules depending on the document type (Schematron).
          - Checking the B2Brouter rules.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      responses:
        '200':
          description: Validation returned correctly
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/DocumentValidation'
                  - type: object
                    properties:
                      validation_result:
                        type: object
                        properties:
                          status:
                            description: |
                              Status validation of the validated document.
                              - If xsd or sch or model are ´invalid,´ the global status will be ´invalid´.
                              - If sch is ´valid_with_warnings´, the global status will be ´valid_with_warnings´.
                              - If xsd and sch and model are ´valid´, the global status will be ´valid´.
                              - If xsd and sch are ´not_applicable´ and model is ´valid´ the global status will be ´valid´.
                              - If xsd and sch are ´not_applicable´ and model is ´invalid´ the global status will be ´invalid´.
                          xsd:
                            properties:
                              status:
                                enum:
                                  - not_applicable
                          sch:
                            properties:
                              status:
                                enum:
                                  - not_applicable
                          model:
                            type: object
                            description: Representation of the B2Brouter model validation.
                            properties:
                              status:
                                type: string
                                example: valid
                                enum:
                                  - valid
                                  - invalid
                                description: Validity status of document validation against the B2Brouter invoice model rules.
                              errors:
                                type: array
                                items:
                                  type: object
                                  description: Representation of a invoice model error
                                  properties:
                                    attribute:
                                      type: string
                                      example: contact
                                      description: Invoice field that has the error
                                    message:
                                      type: string
                                      example: Does not belong to the same project
                                      description: Description of the error encountered
                                    type:
                                      type: string
                                      example: not_same_project
                                      description: Error code associated
        '403':
          description: Forbidden
        '404':
          description: Invoice not found
      security:
        - api_key: []
  /invoices/{id}/ack:
    post:
      operationId: ack-invoice
      tags:
        - Invoices
      summary: Mark an invoice as acknowledged
      description: Mark an invoice as acknowledged. This will prevent the invoice from being listed when  getting the list of issued or received invoices, unless when param ack=true is given.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/invoice_id'
      responses:
        '200':
          description: Invoice acknowledged successfully - returns full invoice representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/InvoiceResponse'
        '403':
          description: Forbidden
      security:
        - api_key: []
  /orders/{id}.{format}:
    get:
      operationId: get-order
      tags:
        - Orders
      summary: Get an order
      description: Returns information about a specific order.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/order_id'
        - $ref: '#/components/parameters/order_format'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Order not found
      security:
        - api_key: []
  /accounts/{account}/orders:
    get:
      operationId: get-orders
      tags:
        - Orders
      summary: List of orders
      description: Returns a paginated list of the submitted orders of the company
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order_number'
        - $ref: '#/components/parameters/order_filename'
        - $ref: '#/components/parameters/order_delivery_location_id'
        - $ref: '#/components/parameters/order_contact'
        - $ref: '#/components/parameters/order_sel_data'
        - $ref: '#/components/parameters/order_date_from'
        - $ref: '#/components/parameters/order_date_to'
        - $ref: '#/components/parameters/order_country'
        - $ref: '#/components/parameters/order_delivery_confirmed'
        - $ref: '#/components/parameters/order_closed'
        - $ref: '#/components/parameters/order_accepted'
        - $ref: '#/components/parameters/order_refused'
        - $ref: '#/components/parameters/order_received'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '403':
          description: Forbidden
      security:
        - api_key: []
  /orders/{id}/mark_as:
    post:
      operationId: mark-as-order
      tags:
        - Orders
      summary: Switch order state
      description: Switch the state of an existing order.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/order_id'
      requestBody:
        description: Attributes to update the state of the order
        content:
          application/json:
            schema:
              type: object
              required:
                - state
              properties:
                state:
                  $ref: '#/components/schemas/OrderState'
      responses:
        '200':
          description: State successfully switched - returns full order representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
        '401':
          description: ' Unauthorized'
        '403':
          description: Forbidden
        '404':
          description: ' Order not found'
        '422':
          description: ' Unprocessable Entity'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorItem'
      security:
        - api_key: []
  /contacts/{id}:
    get:
      operationId: get-contact
      tags:
        - Contacts
      summary: Get a contact (client/provider)
      description: Returns a contact entity
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: Contact identifier
          schema:
            type: integer
      responses:
        '200':
          description: Returns a contact
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
        '404':
          description: Contact not found
      security:
        - api_key: []
    put:
      operationId: put-contact
      tags:
        - Contacts
      summary: Update a contact
      description: Updates a contact and returns the full contact representation
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: Contact identifier
          schema:
            type: integer
      requestBody:
        description: The Contact object in format JSON to update
        content:
          application/json:
            schema:
              type: object
              properties:
                contact:
                  $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Contact updated successfully - returns full contact representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
        '404':
          description: |
            Not found. Returned when contact was not found or `parent_id` is provided but no contact with that ID exists in the account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: resource_missing
                      message:
                        type: string
                        example: 'No such contact: ''999'''
                      type:
                        type: string
                        example: invalid_request_error
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-contact
      tags:
        - Contacts
      summary: Delete a contact
      description: Deletes a contact and returns the full contact representation
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: Contact identifier
          schema:
            type: integer
      responses:
        '200':
          description: Contact deleted successfully - returns full contact representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Contact not found
        '422':
          description: Unable to delete contact
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorItem'
      security:
        - api_key: []
  /accounts/{account}/contacts:
    get:
      operationId: get-contacts
      tags:
        - Contacts
      summary: List contacts
      description: Returns an array of the contacts for the specified account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/client_name'
        - $ref: '#/components/parameters/client_is_client'
        - $ref: '#/components/parameters/client_is_provider'
        - $ref: '#/components/parameters/integration_code'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactReduced'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
      security:
        - api_key: []
    post:
      operationId: create-contact
      tags:
        - Contacts
      summary: Create a contact
      description: |
        Creates a new contact and returns the full contact representation.
        **Creating an office (organisational unit):** To create an office, set the `parent_id` field to the ID of the parent contact. Offices inherit `tin_value` and `tin_scheme` from the parent contact; if provided, these must match the parent's values exactly, otherwise the request is rejected with `422 Unprocessable Entity`. `cin_value` and `cin_scheme` are not validated against the parent.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The Contact object in format JSON to create
        content:
          application/json:
            schema:
              type: object
              properties:
                contact:
                  $ref: '#/components/schemas/Contact'
            examples:
              simple:
                summary: Spanish contact identified by TIN only
                description: |
                  Minimal self-contained contact: a Spanish company identified by its TIN (`tin_value` + `tin_scheme` `9920` = ES:VAT). The TIN must be unique within the account — re-sending this example after the first success returns `422 parameter_taken` ("Tax Identifier Number Duplicated").
                value:
                  contact:
                    name: Example Supplier S.L.
                    tin_value: ESD29766391
                    tin_scheme: '9920'
                    address: Gran Via de les Corts Catalanes, 1
                    postalcode: '08001'
                    city: Barcelona
                    province: Barcelona
                    country: es
                    email: contact@example.com
              peppol:
                summary: Peppol-ready contact (TIN + CIN + Peppol endpoint)
                description: |
                  A contact addressable over the Peppol network. Carries three identifiers, each validated against its scheme:
                  - `tin_value`/`tin_scheme` — VAT identifier (`9930` = DE:VAT).
                  - `cin_value`/`cin_scheme` — Company Identifier Number; here a
                    GLN (`88` = GLN, a checksum-validated global location number).

                  - `pin_value`/`pin_scheme` — Peppol electronic address (the
                    endpoint the invoice is routed to); `pin_scheme` must be an EAS
                    code (https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/).

                  As with `simple`, `tin_value` must be unique within the account.
                value:
                  contact:
                    name: Peppol Customer GmbH
                    tin_value: DE811907980
                    tin_scheme: '9930'
                    cin_value: '4035600210708'
                    cin_scheme: '88'
                    pin_value: DE811907980
                    pin_scheme: '9930'
                    address: Unter den Linden 1
                    postalcode: '10117'
                    city: Berlin
                    country: de
                    email: ap@example-gmbh.de
                    is_client: true
                    is_provider: false
      responses:
        '201':
          description: Contact created successfully - returns full contact representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
        '404':
          description: |
            Not found. Returned when `parent_id` is provided but no contact with that ID exists in the account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: resource_missing
                      message:
                        type: string
                        example: 'No such contact: ''999'''
                      type:
                        type: string
                        example: invalid_request_error
        '422':
          description: |
            Unprocessable entity. Returned for validation errors, including when `tin_value` or `tin_scheme` do not match the parent contact's values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: parameter_invalid
                      message:
                        type: string
                        example: tin_value does not match parent contact's tin_value. Offices inherit tin from their parent.
                      param:
                        type: string
                        example: tin_value
                      type:
                        type: string
                        example: invalid_request_error
      security:
        - api_key: []
  /countries:
    get:
      operationId: get-countries
      tags:
        - Code lists
      summary: List countries
      description: Returns an array of countries where is available to use B2BRouter.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'
      security:
        - api_key: []
  /schemes:
    get:
      operationId: get-schemes
      tags:
        - Code lists
      summary: List schemes
      description: Returns an array of available schemes to use.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Scheme'
      security:
        - api_key: []
  /currencies:
    get:
      operationId: get-currencies
      tags:
        - Code lists
      summary: List of currencies
      description: Returns an array of available currencies
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  currencies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Currency'
      security:
        - api_key: []
  /languages:
    get:
      operationId: get-languages
      tags:
        - Code lists
      summary: List of available languages
      description: Returns a list of all available languages in b2brouter.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  languages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Language'
      security:
        - api_key: []
  /document_types:
    get:
      operationId: get-document-types
      tags:
        - Code lists
      summary: List of available document types
      description: Returns a list of all available document types in b2brouter.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  document_types:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentType'
      security:
        - api_key: []
  /transport_types:
    get:
      operationId: get-transport-types
      tags:
        - Code lists
      summary: List of available transport types
      description: Returns a list of all available transport types in b2brouter.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  transport_types:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransportType'
      security:
        - api_key: []
  /invoice_states:
    get:
      operationId: get-invoice-states
      tags:
        - Code lists
      summary: List of available invoice status
      description: Return an array of all available states of invoice.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice_states:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoiceState'
      security:
        - api_key: []
  /accounts/{account}/events:
    get:
      operationId: get-events
      tags:
        - Events
      summary: List of events
      description: Returns a paginated list of the events of an account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/invoice_id_query'
        - $ref: '#/components/parameters/tax_report_id_query'
        - $ref: '#/components/parameters/date_from'
        - $ref: '#/components/parameters/date_to'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/InvoiceEvent'
                        - $ref: '#/components/schemas/ContactEvent'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '403':
          description: Forbidden
      security:
        - api_key: []
  /accounts/{account}/transports:
    get:
      operationId: get-transports
      tags:
        - Transports
      summary: List configured transports
      description: This endpoint list all transports this account has configured.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  transports:
                    type: array
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/TransportB2brouter'
                        - $ref: '#/components/schemas/TransportEmail'
                        - $ref: '#/components/schemas/TransportPeppol'
                        - $ref: '#/components/schemas/TransportUserPassword'
                        - $ref: '#/components/schemas/TransportEdi'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
    post:
      operationId: create-transport
      tags:
        - Transports
      summary: Create a transport configuration
      description: 'Some transport types needs configuration. Configurable transport types are: b2brouter, email, peppol, es.pecam, es.eusko_jaurlaritza, edicom, ediversa.'
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The transport configuration to create
        content:
          application/json:
            schema:
              type: object
              required:
                - transport
              properties:
                transport:
                  oneOf:
                    - allOf:
                        - $ref: '#/components/schemas/TransportB2brouter'
                        - required:
                            - code
                    - allOf:
                        - $ref: '#/components/schemas/TransportEmail'
                        - required:
                            - code
                    - allOf:
                        - $ref: '#/components/schemas/TransportPeppol'
                        - required:
                            - code
                            - pin_scheme
                            - pin_value
                    - allOf:
                        - $ref: '#/components/schemas/TransportUserPassword'
                        - required:
                            - code
                            - username
                            - password
                    - allOf:
                        - $ref: '#/components/schemas/TransportEdi'
                        - required:
                            - code
                            - username
                            - password
                            - edi_identifier
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  transport:
                    oneOf:
                      - $ref: '#/components/schemas/TransportB2brouter'
                      - $ref: '#/components/schemas/TransportEmail'
                      - $ref: '#/components/schemas/TransportPeppol'
                      - $ref: '#/components/schemas/TransportUserPassword'
                      - $ref: '#/components/schemas/TransportEdi'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/transports/{code}:
    get:
      operationId: get-transport
      tags:
        - Transports
      summary: Retrieve a transport configuration
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/transport_type_code'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - transport
                properties:
                  transport:
                    anyOf:
                      - $ref: '#/components/schemas/TransportB2brouter'
                      - $ref: '#/components/schemas/TransportEmail'
                      - $ref: '#/components/schemas/TransportPeppol'
                      - $ref: '#/components/schemas/TransportUserPassword'
                      - $ref: '#/components/schemas/TransportEdi'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    put:
      operationId: put-transport
      tags:
        - Transports
      summary: Update a transport configuration
      description: |
        This endpoint updates a transport configuration associated with an account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/transport_type_code'
      requestBody:
        description: The transport configuration to update
        content:
          application/json:
            schema:
              type: object
              required:
                - transport
              properties:
                transport:
                  anyOf:
                    - $ref: '#/components/schemas/TransportB2brouter'
                    - $ref: '#/components/schemas/TransportEmail'
                    - $ref: '#/components/schemas/TransportPeppol'
                    - $ref: '#/components/schemas/TransportUserPassword'
                    - $ref: '#/components/schemas/TransportEdi'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  transport:
                    oneOf:
                      - $ref: '#/components/schemas/TransportB2brouter'
                      - $ref: '#/components/schemas/TransportEmail'
                      - $ref: '#/components/schemas/TransportPeppol'
                      - $ref: '#/components/schemas/TransportUserPassword'
                      - $ref: '#/components/schemas/TransportEdi'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-transport
      tags:
        - Transports
      summary: Delete a transport configuration
      description: This endpoint deletes a transport configuration associated with an account.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/transport_type_code'
      responses:
        '200':
          description: Successful operation - returns full transport representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  transport:
                    oneOf:
                      - $ref: '#/components/schemas/TransportB2brouter'
                      - $ref: '#/components/schemas/TransportEmail'
                      - $ref: '#/components/schemas/TransportPeppol'
                      - $ref: '#/components/schemas/TransportUserPassword'
                      - $ref: '#/components/schemas/TransportEdi'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/tax_reports:
    get:
      operationId: get-tax-reports
      tags:
        - Tax Reports
      summary: List tax reports
      description: Returns a paginated list of tax reports.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/invoice_id_query'
        - $ref: '#/components/parameters/sent_at_from'
        - $ref: '#/components/parameters/updated_at_from'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_reports:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxReport'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
    post:
      operationId: create-tax-report
      tags:
        - Tax Reports
      summary: Create a Tax Report
      description: |-
        Creates a Tax Report.
        If the creation of the Tax Report is successful, the response of this action will already contain the QR code and the identifier for the Tax Report.
        However, you have to check the status of the tax report that we send in your behalf in order to be able to take the necessary actions in case any error or warning is issued by the Tax Authority. Because of the asynchronous nature of the tax report sending process, there is no guarantee that when you check the status of the tax reports it will already have the response of the Tax Authority. It usually takes a few seconds to complete the transaction. You will know that the transaction is complete if the response of the check of the status of the tax report has an status **registered**, **registered_with_errors***, or **error**. We recommend you retry the status check until you get a final state on your tax report, or that you configure [WebHooks](https://developer.b2brouter.net/reference/getnewtaxreportstatechange) for tax report state changes.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The Tax Report object in JSON format
        content:
          application/json:
            schema:
              type: object
              required:
                - tax_report
              properties:
                tax_report:
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/TaxReport'
                    - type: object
            examples:
              ticketbai:
                summary: TicketBai (Basque Country) — issued invoice, 21% VAT
                value:
                  tax_report:
                    type: TicketBai
                    invoice_date: '2026-06-19'
                    invoice_number: '001'
                    invoice_series_code: FA
                    description: Issued invoice reported via TicketBai
                    customer_party_tax_id: 38424088N
                    customer_party_country: es
                    customer_party_name: Joan Ferrer
                    customer_party_postalcode: '08080'
                    customer_party_address: Carrer Example, 9
                    tax_inclusive_amount: 121
                    tax_amount: 21
                    invoice_type_code: F1
                    currency: EUR
                    special_regime_key: '01'
                    type_operation: services
                    tax_breakdowns:
                      - name: IVA
                        category: S
                        percent: 21
                        taxable_base: 100
                        tax_amount: 21
                        non_exempt: true
                        special_regime_key: '01'
                        non_exemption_code: S1
                    tax_report_lines:
                      - description: Consulting services
                        quantity: 1
                        price: 100
                        tax_inclusive_amount: 121
                        tax_amount: 21
              verifactu_basic:
                summary: Verifactu (AEAT) — issued invoice, 21% VAT
                value:
                  tax_report:
                    type: Verifactu
                    invoice_date: '2026-06-19'
                    invoice_number: '001'
                    invoice_series_code: FA
                    description: Issued invoice reported via Verifactu
                    customer_party_tax_id: 38424088N
                    customer_party_country: es
                    customer_party_name: Joan Ferrer
                    tax_inclusive_amount: 121
                    tax_amount: 21
                    invoice_type_code: F1
                    currency: EUR
                    coupon: false
                    tax_breakdowns:
                      - name: IVA
                        category: S
                        percent: 21
                        taxable_base: 100
                        tax_amount: 21
                        special_regime_key: '02'
                        non_exemption_code: S1
              verifactu_multiple_vat:
                summary: Verifactu with two VAT rates (21% and 10%)
                value:
                  tax_report:
                    type: Verifactu
                    invoice_date: '2026-06-19'
                    invoice_number: '002'
                    invoice_series_code: FA
                    description: Verifactu record with two VAT rates
                    customer_party_tax_id: 38424088N
                    customer_party_country: es
                    customer_party_name: Joan Ferrer
                    tax_inclusive_amount: 176
                    tax_amount: 26
                    invoice_type_code: F1
                    currency: EUR
                    coupon: false
                    tax_breakdowns:
                      - name: IVA
                        category: S
                        percent: 21
                        taxable_base: 100
                        tax_amount: 21
                        special_regime_key: '02'
                        non_exemption_code: S1
                      - name: IVA
                        category: S
                        percent: 10
                        taxable_base: 50
                        tax_amount: 5
                        special_regime_key: '02'
                        non_exemption_code: S1
              verifactu_with_discount:
                summary: Verifactu for an invoice with a 10% discount (net base 90)
                value:
                  tax_report:
                    type: Verifactu
                    invoice_date: '2026-06-19'
                    invoice_number: '003'
                    invoice_series_code: FA
                    description: Verifactu record for an invoice with a 10% discount
                    customer_party_tax_id: 38424088N
                    customer_party_country: es
                    customer_party_name: Joan Ferrer
                    tax_inclusive_amount: 108.9
                    tax_amount: 18.9
                    invoice_type_code: F1
                    currency: EUR
                    coupon: false
                    tax_breakdowns:
                      - name: IVA
                        category: S
                        percent: 21
                        taxable_base: 90
                        tax_amount: 18.9
                        special_regime_key: '02'
                        non_exemption_code: S1
              verifactu_with_withholding:
                summary: Verifactu with IRPF withholding (retención in tax_amount_withheld)
                value:
                  tax_report:
                    type: Verifactu
                    invoice_date: '2026-06-19'
                    invoice_number: '004'
                    invoice_series_code: FA
                    description: Verifactu record with IRPF withholding
                    customer_party_tax_id: 38424088N
                    customer_party_country: es
                    customer_party_name: Joan Ferrer
                    tax_inclusive_amount: 121
                    tax_amount: 21
                    tax_amount_withheld: 15
                    invoice_type_code: F1
                    currency: EUR
                    coupon: false
                    tax_breakdowns:
                      - name: IVA
                        category: S
                        percent: 21
                        taxable_base: 100
                        tax_amount: 21
                        special_regime_key: '02'
                        non_exemption_code: S1
      responses:
        '201':
          description: Tax Report created successfully - returns full tax report representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /accounts/{account}/tax_reports/import:
    post:
      operationId: import-tax-report
      tags:
        - Tax Reports
      summary: Import a Tax Report from an XML file
      description: |-
        Import a Tax Report from an XML file
        If the creation of the Tax Report is successful, the response of this action will already contain the QR code and the identifier for the Tax Report. Note that if the XML file has chaining information (eg Huella for Verifactu), this information will be ignored and our system will perform the chaining process regardless. This is the only way to ensure the integrity of the data sent to the Tax Authority.
        Remember that you have to check the status of the tax report that we send in your behalf in order to be able to take the necessary actions in case any error or warning is issued by the Tax Authority. Because of the asynchronous nature of the tax report sending process, there is no guarantee that when you check the status of the tax reports it will already have the response of the Tax Authority. It usually takes a few seconds to complete the transaction. You will know that the transaction is complete if the response of the check of the status of the tax report has an status **registered**, **registered_with_errors***, or **error**. We recommend you retry the status check until you get a final state on your tax report, or that you configure [WebHooks](https://developer.b2brouter.net/reference/getnewtaxreportstatechange) for tax report state changes.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: The Tax Report XML file to import
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Tax Report created successfully - returns full tax report representation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '406':
          description: Not Acceptable
      security:
        - api_key: []
  /accounts/{account}/tax_report_batches:
    post:
      operationId: create-tax-report-batch
      tags:
        - Tax Reports
      summary: Bulk-create SII tax reports (async batch)
      description: |-
        Submits up to 5000 SII tax reports in one request as a batch.

        Processing is always asynchronous. This endpoint validates only the envelope (a `tax_reports` array within the size limit) and returns `202 Accepted` immediately with a `batch_id` and a `status_url`; the per-record build, validation and ledger attach run in a background job. Use `GET /accounts/{account}/tax_report_batches/{id}` (the returned `status_url`) to poll for results, or subscribe to the `sii_batch.finished` webhook event to be notified when the batch finishes.

        Each record is validated independently in the job — a failure on one record (bad `book_type`, XSD-invalid XML, unsupported `type`) does not abort the batch; it appears as a per-record `error` in the batch status. Non-SII `type` values are rejected per-record with the `unsupported_type` code.

        For the same request shape on a single record, use [POST /tax_reports](https://developer.b2brouter.net/reference/new-create-tax-report) instead.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
      requestBody:
        description: An array of SII tax report objects.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tax_reports
              properties:
                tax_reports:
                  type: array
                  minItems: 0
                  maxItems: 5000
                  description: 'Up to 5000 tax_report payloads. Each must carry `type: ''SiiDocument''` and a valid `book_type`. Other fields follow the same shape as the per-record `POST /tax_reports`.'
                  items:
                    $ref: '#/components/schemas/TaxReport'
            examples:
              two_expedidas:
                summary: Two Expedida records
                value:
                  tax_reports:
                    - type: SiiDocument
                      book_type: Expedida
                      invoice_number: PB-2026-001
                      invoice_date: '2026-04-15'
                      fiscal_year: 2026
                      fiscal_period: 4
                      invoice_type_code: F1
                      special_regime_key: '01'
                      description: Servicio de prueba
                      customer_party_name: Cliente Bulk S.L.
                      customer_party_tax_id: B87654321
                      customer_party_country: es
                      tax_inclusive_amount: 121
                      tax_amount: 21
                      currency: EUR
                      tax_breakdowns:
                        - name: IVA
                          category: S
                          percent: 21
                          taxable_base: 100
                          tax_amount: 21
                    - type: SiiDocument
                      book_type: Expedida
                      invoice_number: PB-2026-002
                      invoice_date: '2026-04-15'
                      fiscal_year: 2026
                      fiscal_period: 4
                      invoice_type_code: F1
                      special_regime_key: '01'
                      description: Otro servicio
                      customer_party_name: Cliente Bulk S.L.
                      customer_party_tax_id: B87654321
                      customer_party_country: es
                      tax_inclusive_amount: 242
                      tax_amount: 42
                      currency: EUR
                      tax_breakdowns:
                        - name: IVA
                          category: S
                          percent: 21
                          taxable_base: 200
                          tax_amount: 42
      responses:
        '202':
          description: Batch accepted for asynchronous processing. The body carries the batch id and a `status_url` to poll; no record is created yet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: integer
                    description: Identifier of the batch; use it to poll the status endpoint.
                  status:
                    type: string
                    enum:
                      - processing
                    description: Always `processing` on this synchronous 202 — the ingest job has not run yet. Poll `status_url` (`GET /tax_report_batches/{id}`) for the terminal `done` state.
                  total:
                    type: integer
                    description: Number of records submitted.
                  status_url:
                    type: string
                    format: uri
                    description: Absolute URL of the batch-status endpoint.
              example:
                batch_id: 4567
                status: processing
                total: 2
                status_url: https://api-staging.b2brouter.net/accounts/12/tax_report_batches/4567
        '400':
          description: Top-level envelope error (missing `tax_reports` array, not an array, or record count exceeds 5000). Returned before anything is enqueued.
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: The endpoint is SII-only; one or more records have an unsupported or missing `type` (only `SiiDocument` is accepted). Rejected synchronously with the `unsupported_type` code, before anything is enqueued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: unsupported_type
                      message:
                        type: string
      security:
        - api_key: []
  /accounts/{account}/tax_report_batches/{id}:
    get:
      operationId: get-tax-report-batch
      tags:
        - Tax Reports
      summary: Get the status of a bulk SII tax report batch
      description: Returns the outcome of a batch submitted to `POST /accounts/{account}/tax_report_batches`. While the background job runs `status` is `processing`; once it finishes `status` is `done` and `results` is populated, in submission order — a created `tax_report` on success, or the rejection `errors` on failure.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/account'
        - name: id
          in: path
          required: true
          description: The `batch_id` returned by the bulk-create endpoint.
          schema:
            type: integer
      responses:
        '200':
          description: The batch status and per-record results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: integer
                  status:
                    type: string
                    enum:
                      - processing
                      - done
                      - failed
                    description: '`processing` while the ingest job runs; `done` when it finished (per-record rejections included); `failed` when the job itself crashed — `results` shows what was processed before the crash, and records listed as `created` may not yet be attached for sending. Contact support referencing the `batch_id` instead of resubmitting, to avoid duplicates.'
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      accepted:
                        type: integer
                      rejected:
                        type: integer
                  results:
                    type: array
                    description: Per-record outcomes in submission order.
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Zero-based index of the record in the original request array.
                        status:
                          type: string
                          enum:
                            - created
                            - error
                        tax_report:
                          description: Present when `status` is `created`. Deliberately slim — correlation plus outcome; fetch the full record at `GET /tax_reports/{id}`.
                          type: object
                          properties:
                            id:
                              type: integer
                            state:
                              type: string
                              example: new
                            invoice_number:
                              type: string
                            book_type:
                              type: string
                              example: Expedida
                        errors:
                          type: array
                          description: Present when `status` is `error`.
                          items:
                            type: object
                            properties:
                              code:
                                type: string
                                example: invalid_book_type
                              message:
                                type: string
                              param:
                                type: string
                                example: book_type
              examples:
                done_mixed:
                  summary: Finished — 2 created, 1 rejected
                  value:
                    batch_id: 4567
                    status: done
                    summary:
                      total: 3
                      accepted: 2
                      rejected: 1
                    results:
                      - index: 0
                        status: created
                        tax_report:
                          id: 12345
                          state: new
                          invoice_number: PB-2026-001
                          book_type: Expedida
                      - index: 1
                        status: error
                        errors:
                          - code: invalid_book_type
                            message: 'Invalid or missing book_type ''NotAType''. Expected one of: Expedida, Recibida, Inversion, Intracomunitaria, Metalico, Seguro, Viajesagencia, Cobro, Pago'
                            param: book_type
                      - index: 2
                        status: created
                        tax_report:
                          id: 12346
                          state: new
                          invoice_number: PB-2026-003
                          book_type: Expedida
                still_processing:
                  summary: Job not finished yet
                  value:
                    batch_id: 4567
                    status: processing
                    summary:
                      total: 3
                      accepted: 0
                      rejected: 0
                    results: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
  /tax_reports/{id}:
    get:
      operationId: get-tax-report
      tags:
        - Tax Reports
      summary: Get a tax report
      description: |-
        Returns a tax report
        You have to check the status of the tax report that we send in your behalf in order to be able to take the necessary actions in case any error or warning is issued by the Tax Authority. Because of the asynchronous nature of the tax report sending process, there is no guarantee that when you check the status of the tax reports it will already have the response of the Tax Authority. It usually takes a few seconds to complete the transaction. You will know that the transaction is complete if the response of the check of the status of the tax report has an status **registered** or **error**. We recommend you retry the status check until you get a final state on your tax report or you configure [WebHooks](https://developer.b2brouter.net/reference/getnewTaxReportstatechange) for tax report state changes.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/tax_report_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
    patch:
      operationId: modify-tax-report
      tags:
        - Tax Reports
      summary: Correct or Modify a Tax Report
      description: |-
        Correct or Modify a Tax Report
        If the tax report has already been registered by the Tax Authority, issue a correction ("subsanación" as it's call in Verifactu) of the tax report with the data provided in body.
        If the report has not been sent to the Tax Authority, change the fields indicated in the payload.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/tax_report_id'
      requestBody:
        required: true
        description: The Tax Report object in JSON format.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifactuTaxReportPatch'
            example:
              tax_report:
                type: Verifactu
                description: Correcció interna per sincronització cens AEAT
                customer_party_tax_id: B12345678
                customer_party_tax_scheme: VAT
                customer_party_country: ES
                customer_party_name: ACME SL
                previously_refused: S
                tax_breakdowns_attributes:
                  - id: 98765
                    special_regime_key: '01'
                    category: S
      responses:
        '200':
          description: Tax report modified
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '201':
          description: Correction report created
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: annulate-tax-report
      tags:
        - Tax Reports
      summary: Annulates a tax report
      description: Annulates a TaxReport
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/tax_report_id'
      responses:
        '200':
          description: Tax report annulled (no separate annulment report returned)
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '201':
          description: Annulment report created
          content:
            application/json:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '204':
          description: Tax report destroyed (it had not been emitted)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /tax_reports/{id}/download:
    get:
      operationId: new-download-tax-report
      tags:
        - Tax Reports
      summary: Download a tax report
      description: |-
        Download a tax report in the format that is sent to the Tax Authority.
        Note that if the Tax Authority requires the tax report to be cleared (such as in Zatca) or chained (such as in Verifactu and TicketBAI) the XML will only contain all the information after the tax report is chained or cleared. Given the the asynchronous nature of this process, there is no guarantee  that when you download the tax reports will be prepared. This process usually only takes a few seconds.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/tax_report_id'
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: object
                properties:
                  tax_report:
                    $ref: '#/components/schemas/TaxReport'
        '403':
          description: Unauthorized
        '404':
          description: Tax Report not found
      security:
        - api_key: []
  /tax_reports/{id}/download_response:
    get:
      operationId: download-tax-report-response
      tags:
        - Tax Reports
      summary: Download the official receipt for a tax report
      description: |-
        Download the Official Receipt of Acknowledgement received from the Tax Authority after successfully submitting a tax report.

        This endpoint is primarily used for KSeF (Polish tax reporting system) to retrieve the official acknowledgement (UPO) from the tax authority. The UPO serves as proof that the invoice was successfully received and registered by the Polish Ministry of Finance.

        **Note:** The UPO is only generated when the invoice is successfully accepted by KSeF. If the tax report is in error state, this endpoint will return the error reason from the tax authority.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/tax_report_id'
      responses:
        '200':
          description: UPO (Official Receipt) from KSeF tax authority
          content:
            application/xml:
              schema:
                type: string
                format: binary
                description: XML UPO (Urzędowe Poświadczenie Odbioru) from KSeF
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <ns3:UPO xmlns:ns3="http://ksef.mf.gov.pl/schema/gtw/svc/online/types/2021/10/01/0001">
                  <ns3:KsefReferenceNumber>20251107-SE-1234567890-ABCD</ns3:KsefReferenceNumber>
                  <ns3:NrFaktury>F/2025/11/001</ns3:NrFaktury>
                  <ns3:DataWplywu>2025-11-07T10:30:45Z</ns3:DataWplywu>
                  <ns3:PodpisUPO>ABC123XYZ...</ns3:PodpisUPO>
                </ns3:UPO>
        '204':
          description: No Content - The tax report has no UPO available yet (still processing or not sent)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Unprocessable Entity - Tax report submission error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                        description: Error message from the tax authority explaining why the submission failed or was rejected
                        example: 'KSeF authentication failed: Invalid certificate'
      security:
        - api_key: []
  /ledgers/{id}/download:
    get:
      operationId: download-ledger
      tags:
        - Ledgers
      summary: Download a Ledger
      description: |-
        Download a Ledger, the XML document sent to the Tax Authority.
        Note that sending the ledger to the Tax Authority is an asynchronous  process. No ledger can be downloaded until all tax reports in the ledger have been chained,
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/ledger_id'
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: object
        '403':
          description: Unauthorized
        '404':
          description: Tax Report not found
      security:
        - api_key: []
  /ledgers/{id}/download_response:
    get:
      operationId: download-response-ledger
      tags:
        - Ledgers
      summary: Download the response for a Ledger
      description: |-
        Download the response from the Tax Authority for a Ledger.
        Note that sending the ledger to the Tax Authority is an asynchronous process. No response can be downloaded until B2Brouter receives it from the Tax Authority.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/ledger_id'
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: object
        '403':
          description: Unauthorized
        '404':
          description: Tax Report not found
      security:
        - api_key: []
  /accounts/{account}/ledgers/import:
    post:
      tags:
        - Ledgers
      summary: ' Import a ledger'
      description: ' Import a ledger by providing a raw XML payload.'
      operationId: importLedger
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: account
          in: path
          description: The ID of the account.
          required: true
          schema:
            type: integer
      requestBody:
        description: The raw XML payload of the ledger.
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: The ledger was successfully imported.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ledger:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: The ID of the ledger.
                      type:
                        type: string
                        description: The type of the ledger.
                      state:
                        type: string
                        description: The state of the ledger.
        '403':
          description: Forbidden
        '406':
          description: The request's "Content-Type" header is not "application/octet-stream".
        '422':
          description: The provided XML is invalid.
      security:
        - api_key: []
  /directory/{country}/{scheme}/{id}:
    get:
      operationId: lookup-directory-by-country-and-scheme
      tags:
        - Lookup
      summary: Show company from Directory (by country and scheme codes)
      description: |
        Return the information about specified company that lists in our Directory.

        If the participant is found in the Peppol SML but not yet in the local directory, returns `202 Accepted` with a polling URL. The client should retry the same request until it resolves to `200` (found), `404` (not registered in the Peppol network), or `424` (registered, but its SMP did not provide the data we depend on to register it).
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/directory_country'
        - $ref: '#/components/parameters/directory_scheme'
        - $ref: '#/components/parameters/directory_id'
      responses:
        '200':
          description: Returns specified company from directory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCompany'
        '202':
          description: Participant found in Peppol network but not yet in local directory. Retry the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: processing
                  message:
                    type: string
                    example: Participant found in Peppol network. Syncing directory data. Please retry this request.
                  polling_url:
                    type: string
                    example: https://api.b2brouter.net/directory/es/9920/ES12345678
        '401':
          description: Unauthorized
        '404':
          description: Company not found — the participant is not registered in the Peppol network
        '424':
          description: |
            The participant is registered in the Peppol network, but its SMP did not provide the data we depend on to register it as an exchange partner (incomplete business card, no exportable invoice document types, or an unsupported or undeterminable country). The `error.code` field carries the machine-readable reason: `incomplete_businesscard`, `no_exportable_doctypes`, `no_country`, or `unsupported_country`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: no_exportable_doctypes
                      message:
                        type: string
                        example: The SMP for participant 0208:0454483701 does not publish any exportable invoice document types. Please contact the participant's Peppol Access Point.
                      type:
                        type: string
                        example: invalid_request_error
      security:
        - api_key: []
  /directory/{scheme}/{id}:
    get:
      operationId: lookup-directory-by-scheme
      tags:
        - Lookup
      summary: Show company from Directory (by scheme code)
      description: |
        Return the information about specified company that lists in our Directory.

        If the participant is found in the Peppol SML but not yet in the local directory, returns `202 Accepted` with a polling URL. The client should retry the same request until it resolves to `200` (found), `404` (not registered in the Peppol network), or `424` (registered, but its SMP did not provide the data we depend on to register it).
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/directory_scheme'
        - $ref: '#/components/parameters/directory_id'
      responses:
        '200':
          description: Returns specified company from directory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCompany'
        '202':
          description: Participant found in Peppol network but not yet in local directory. Retry the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: processing
                  message:
                    type: string
                    example: Participant found in Peppol network. Syncing directory data. Please retry this request.
                  polling_url:
                    type: string
                    example: https://api.b2brouter.net/directory/9920/ES12345678
        '401':
          description: Unauthorized
        '404':
          description: Company not found — the participant is not registered in the Peppol network
        '424':
          description: |
            The participant is registered in the Peppol network, but its SMP did not provide the data we depend on to register it as an exchange partner (incomplete business card, no exportable invoice document types, or an unsupported or undeterminable country). The `error.code` field carries the machine-readable reason: `incomplete_businesscard`, `no_exportable_doctypes`, `no_country`, or `unsupported_country`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: no_exportable_doctypes
                      message:
                        type: string
                        example: The SMP for participant 0208:0454483701 does not publish any exportable invoice document types. Please contact the participant's Peppol Access Point.
                      type:
                        type: string
                        example: invalid_request_error
      security:
        - api_key: []
  /directory/{country}/{id}:
    get:
      operationId: lookup-directory-by-country
      tags:
        - Lookup
      summary: Show company from Directory (by country code)
      description: |
        Return the information about specified company that lists in our Directory.

        If the participant is found in the Peppol SML but not yet in the local directory, returns `202 Accepted` with a polling URL. The client should retry the same request until it resolves to `200` (found), `404` (not registered in the Peppol network), or `424` (registered, but its SMP did not provide the data we depend on to register it).
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/directory_country'
        - $ref: '#/components/parameters/directory_id'
      responses:
        '200':
          description: Returns specified company from directory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCompany'
        '202':
          description: Participant found in Peppol network but not yet in local directory. Retry the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: processing
                  message:
                    type: string
                    example: Participant found in Peppol network. Syncing directory data. Please retry this request.
                  polling_url:
                    type: string
                    example: https://api.b2brouter.net/directory/es/ES12345678
        '401':
          description: Unauthorized
        '404':
          description: Company not found — the participant is not registered in the Peppol network
        '424':
          description: |
            The participant is registered in the Peppol network, but its SMP did not provide the data we depend on to register it as an exchange partner (incomplete business card, no exportable invoice document types, or an unsupported or undeterminable country). The `error.code` field carries the machine-readable reason: `incomplete_businesscard`, `no_exportable_doctypes`, `no_country`, or `unsupported_country`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: no_exportable_doctypes
                      message:
                        type: string
                        example: The SMP for participant 0208:0454483701 does not publish any exportable invoice document types. Please contact the participant's Peppol Access Point.
                      type:
                        type: string
                        example: invalid_request_error
      security:
        - api_key: []
  /tin_verifications:
    post:
      operationId: create-tin-verification
      tags:
        - TIN Verifications
      summary: Create a TIN verification request
      description: |-
        Submits a batch of TIN (Tax Identification Number) + name pairs for verification against a tax authority census.

        Processing is always asynchronous. This endpoint returns `202 Accepted` immediately with the request ID and `pending` status. Use the `GET /tin_verifications/{id}` endpoint to poll for results, or subscribe to the `tin_verification.finished` webhook event to be notified when processing completes.

        **Supported countries:** Currently only Spain (`es`) is supported. The TIN+name pair is validated against the AEAT (Agencia Estatal de Administraci\u00F3n Tributaria) census.

        **Caching:** Results from the last 24 hours are cached. If a TIN was recently verified, the cached result is reused without making a new call to the tax authority.

        **Billing:** Each request counts as one billable transaction (only on success).

        **Limits:** Maximum 20,000 entities per request.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: country
          in: query
          required: true
          description: ISO 3166-1 alpha-2 country code. Determines which tax authority census to verify against. Currently only `es` (Spain) is supported.
          schema:
            type: string
            enum:
              - es
          example: es
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: Array of TIN+name pairs to verify. Each item must contain a `tin` and a `name` field.
              minItems: 1
              maxItems: 20000
              items:
                type: object
                required:
                  - tin
                  - name
                properties:
                  tin:
                    type: string
                    description: The Tax Identification Number to verify. May include the country prefix (e.g. `ESB86561412`) — it will be stripped during normalization.
                    example: B86561412
                  name:
                    type: string
                    description: The entity name to verify against the census.
                    example: EMPRESA EXEMPLE SA
            example:
              - tin: B86561412
                name: EMPRESA EXEMPLE SA
              - tin: 12345678Z
                name: GARCIA LOPEZ MARIA
      responses:
        '202':
          description: Request accepted for async processing. Poll `GET /tin_verifications/{id}` for results or subscribe to the `tin_verification.finished` webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TinVerificationRequest'
              example:
                id: 42
                status: pending
                results: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - api_key: []
  /tin_verifications/{id}:
    get:
      operationId: get-tin-verification
      tags:
        - TIN Verifications
      summary: Get a TIN verification request
      description: |-
        Retrieves the current status and results of a TIN verification request.

        While the request is `pending` or `processing`, the `results` array will be empty. Once the status transitions to `success` or `failed`, the array is populated with one result per submitted TIN+name pair.

        If the request `failed`, an `error_message` field describes what went wrong.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - name: id
          in: path
          required: true
          description: ID of the TIN verification request.
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TinVerificationRequest'
              example:
                id: 42
                status: success
                results:
                  - tin: B86561412
                    normalized_tin: B86561412
                    name: EMPRESA EXEMPLE SA
                    tin_format_valid: true
                    census_match: true
                  - tin: 12345678Z
                    normalized_tin: 12345678Z
                    name: GARCIA LOPEZ MARIA
                    tin_format_valid: true
                    census_match: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
  /documents/validate:
    post:
      operationId: validate-document
      tags:
        - Validation
      summary: Validates an electronic document
      description: |
        This endpoint validates a single electronic document provided in the request body. 

        The validation of the e-document is performed through:

        - Checking the use of a correct syntax schema (XSD).
        - Checking the business rules depending on the document type (Schematron).

        The following formats can be validated:
        - UBL (Universal Business Language)
        - CII (Cross Industry Invoice)
        - Peppol BIS
        - PINT (JP, SG, MY, AUNZ)
        - ZUGFeRD
        - XRechnung
        - Factur-X
        - FacturaE
        - Svefaktura
        - Fattura PA
        - eSPap
        - Any EN16931 CIUS-compliant format
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      requestBody:
        description: The document file to validate.
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentValidation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - api_key: []
  /web_hooks:
    get:
      operationId: get-web-hooks
      tags:
        - Web Hooks
      summary: List web hooks
      description: |-
        Retrieves a list of Web Hooks.
        This endpoint returns all Web Hooks associated with the authenticated integration group, including their configuration details such as destination URL, enabled status, subscribed events, and description.
        Use this operation to audit existing Web Hooks, verify active event subscriptions, or manage multiple Web Hook configurations from a single place.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  web_hooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebHook'
                  meta:
                    $ref: '#/components/schemas/IndexMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - api_key: []
    post:
      operationId: create-web-hook
      tags:
        - Web Hooks
      summary: Create a new web hook
      description: |-
        Creates a new Web Hook configuration.
        A Web Hook allows you to register an HTTP endpoint that will receive real-time notifications when specific events occur in the platform, such as tax report, issued invoice, or ledger state changes.
        When creating a Web Hook, you must specify the destination URL and the events you want to subscribe to. The Web Hook will be created under the integration group associated with the API key.
        By default, newly created Web Hooks are enabled. When enabled, the platform will send HTTP POST requests to the configured URL whenever one of the subscribed events is triggered.
        Note: If you create the Web Hook with enabled=false, events may be omitted, but they will be required again when enabling the Web Hook.
        Use this endpoint to start receiving asynchronous notifications instead of continuously polling the API for status changes.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - web_hook
              properties:
                web_hook:
                  allOf:
                    - $ref: '#/components/schemas/WebHook'
                    - required:
                        - url
                        - events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  web_hook:
                    $ref: '#/components/schemas/WebHook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
  /web_hooks/{id}:
    get:
      operationId: get-web-hook
      tags:
        - Web Hooks
      summary: Get a web hook
      description: |-
        Retrieves the configuration of a specific Web Hook.
        A Web Hook defines an HTTP endpoint that will receive event notifications from the platform (such as tax report, issued invoice, or ledger state changes). This endpoint allows you to fetch the current settings of an existing Web Hook, including its target URL, enabled status, subscribed events, description, and integration group association.
        Use this operation to inspect or verify the configuration of a Web Hook before updating it, troubleshooting delivery issues, or auditing event subscriptions.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/web_hook_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  web_hook:
                    $ref: '#/components/schemas/WebHook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
    patch:
      operationId: update-web-hook
      tags:
        - Web Hooks
      summary: Modify a web hook
      description: |-
        Updates the configuration of an existing Web Hook.
        This endpoint allows you to modify one or more properties of a Web Hook, such as the destination URL, enabled status, subscribed events or the description.
        Changes are applied immediately. Once updated and enabled, the Web Hook will continue delivering HTTP POST notifications according to the new configuration.
        Use this operation to temporarily disable a Web Hook, adjust event subscriptions, rotate the target URL, or update the description without creating a new Web Hook.
        Note: The request must include the web_hook root object. Also, when enabled=true, events must be present and non-empty (validation rule).
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/web_hook_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - web_hook
              properties:
                web_hook:
                  $ref: '#/components/schemas/WebHook'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  web_hook:
                    $ref: '#/components/schemas/WebHook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
        - api_key: []
    delete:
      operationId: delete-web-hook
      tags:
        - Web Hooks
      summary: Deletes a web hook
      description: |-
        Deletes an existing Web Hook.
        Once a Web Hook is deleted, its configuration is permanently removed and the platform will immediately stop sending event notifications to its associated endpoint.
        This operation cannot be undone. Use this endpoint when a Web Hook is no longer needed or when you want to permanently stop receiving notifications for its subscribed events.
      parameters:
        - $ref: '#/components/parameters/api_version_header'
        - $ref: '#/components/parameters/web_hook_id'
      responses:
        '200':
          description: Successful deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  web_hook:
                    $ref: '#/components/schemas/WebHook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      description: API Key of your account
      name: X-B2B-API-Key
      in: header
  parameters:
    api_version_header:
      name: X-B2B-API-Version
      in: header
      description: |
        Specifies the version of the API to use in this request. If not specified uses the API-Version set in the group conifguration
        B2Brouter UI Application -> Developers -> API Keys -> API Version
      required: false
      schema:
        type: string
        example: '2026-04-20'
        default: '2026-04-20'
    offset:
      name: offset
      description: Jump to the first object.
      in: query
      required: false
      schema:
        type: integer
        default: 0
        example: 0
    limit:
      name: limit
      description: Number of items in the response (500 maximum)
      in: query
      required: false
      schema:
        type: integer
        default: 25
        example: 25
    account:
      name: account
      in: path
      description: Account identifier (ID)
      required: true
      schema:
        type: string
      example: my-account
    attachment_id:
      name: id
      in: path
      description: |
        An internal identifier that is unique to each **Attachment** within B2Brouter.
      required: true
      example: 4053100
      schema:
        type: integer
    tax_authority_code:
      name: code
      description: Code of tax report setting
      in: path
      required: true
      schema:
        type: string
        example: verifactu
        enum:
          - tbai
          - sdi
          - lhdn
          - verifactu
          - ksef
          - dgfip
    invoice_id:
      name: id
      in: path
      description: |
        An internal identifier that is unique to each **Invoice** within B2Brouter.
      required: true
      example: 4053100
      schema:
        type: integer
    include:
      name: include
      in: query
      description: 'Comma-separated list of additional fields to include in the response. Available fields: `lines`, `detailed_lines`, `apply_to_local_government_unit`, `apply_to_vat_group_member`, `third_party`.'
      schema:
        type: string
      example: detailed_lines
    disposition:
      name: disposition
      in: query
      description: In PDF, view the PDF file instead of downloading
      schema:
        type: string
        enum:
          - inline
        example: inline
    ack:
      name: ack
      in: query
      description: Mark the invoice as acknowledged.
      required: false
      schema:
        type: boolean
      example: true
    document_type_code:
      name: document_type_code
      in: path
      description: |
        An internal identifier that is unique to each **Document Type** within
        B2Brouter.<br> You can get all valid document type codes using the **Document
        Types** endpoint in Code lists section (`/document_types`).

        Additional values:
        - `original` — returns the imported/received document as-is.
        - `legal` — returns the stored legal document: for issued invoices, the
          document as delivered; for received invoices, the original as received.
      required: true
      example: xml.facturae.3.2
      schema:
        $ref: '#/components/schemas/DocumentTypeCode'
    type:
      name: type
      description: Filter on invoice type.
      in: query
      schema:
        type: string
        enum:
          - IssuedInvoice
          - ReceivedInvoice
          - IssuedSelfInvoice
          - IssuedSimplifiedInvoice
          - ReceivedSelfInvoice
        default: IssuedInvoice
    ack_filter:
      name: ack
      in: query
      description: Filter documents with ACK.
      required: false
      schema:
        type: boolean
      example: true
    date_from:
      name: date_from
      in: query
      description: Filter from submission date.
      required: false
      schema:
        type: string
        format: date
      example: '2024-09-12'
    date_to:
      name: date_to
      in: query
      description: Filter to submission date
      required: false
      schema:
        type: string
        format: date
      example: '2024-09-12'
    due_date_from:
      name: due_date_from
      in: query
      description: Filter from due date
      required: false
      schema:
        type: string
        format: date
      example: '2024-09-12'
    due_date_to:
      name: due_date_to
      in: query
      description: Filter to due date
      required: false
      schema:
        type: string
        format: date
      example: '2024-09-12'
    number:
      name: number
      in: query
      description: Filter on invoice number. Performs an exact match search; only invoices with an invoice number exactly equal to the specified value will be returned
      required: false
      schema:
        type: string
      example: '10'
    state_updated_at_from:
      name: state_updated_at_from
      in: query
      description: Filter on change status date. Invoices with change status date later than the specified date are returned
      required: false
      schema:
        type: string
        format: date
      example: '2024-09-12'
    updated_at_from:
      name: updated_at_from
      in: query
      description: Filter on updated_at date. Entities with updated_at date later than the specified date are returned.
      required: false
      schema:
        type: string
        format: date
      example: '2024-10-11'
    tin_value:
      name: tin_value
      in: query
      description: Filter on customer VAT code
      required: false
      schema:
        type: string
      example: ESP2807900B
    cin_value:
      name: cin_value
      in: query
      description: Filter on customer Company Identification Number
      required: false
      schema:
        type: string
      example: 7080000950171
    new:
      name: new
      description: Filter on invoice status "new". Created and ready to be sent
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    sending:
      name: sending
      description: Filter on invoice status "sending". Invoice is being sent
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    error:
      name: error
      description: Filter on invoice status "error". An error has been raised when sending the invoice to its recipient
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    sent:
      name: sent
      description: Filter on invoice status "sent". Successfully sent to its recipient
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    refused:
      name: refused
      description: Filter on invoice status "refused". The recipient has refused the invoice. Usually, the reason for the rejection is provided
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    closed:
      name: closed
      description: Filter on invoice status "closed". The sender considers that the invoice is closed and does not want to perform further operations
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    registered:
      name: registered
      description: Filter on invoice status "registered". The receiver has registered the invoice. Some receivers may indicate a registration number
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    accepted:
      name: accepted
      description: Filter on invoice status "accepted". The receiver has accepted the invoice
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    downloaded:
      name: downloaded
      description: Filter on invoice status "downloaded".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    annotated:
      name: annotated
      description: Filter on invoice status "annotated".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    allegedly_paid:
      name: allegedly_paid
      description: Filter on invoice status "allegedly_paid". The receiver has indicated that he has ordered the payment of the invoice
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    paid:
      name: paid
      description: Filter on invoice status "paid".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    received_invoice_received:
      name: received
      description: Filter on received invoices with status "received".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    received_invoice_ocr_failed:
      name: ocr_failed
      description: Filter on received invoices with status "ocr_failed".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    received_invoice_exclude_offices:
      name: exclude_offices
      description: Do not show the invoices of the Organizational Units.
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    from_net:
      name: from_net
      in: query
      description: Filter on received invoice from net value. Use as a string search, for example, searching "api" lists all the received invoices that are received via API.
      required: false
      schema:
        type: string
      example: api
    send_after_import:
      name: send_after_import
      in: query
      description: |
        Indicates whether the invoice should be automatically processed after import.

        When set to `true` and the invoice passes validations:
          * For sending transports (non-`download`), the invoice is queued to be sent asynchronously.
          * For `download` transport, the invoice is not sent. Instead, if tax report generation is enabled and required for this invoice, the invoice will be issued and the tax report generated 
            (invoice ends in `state=issued` and exposes `tax_report_ids`). Otherwise, the invoice may end in `state=error`.

        **Note:** This option is incompatible with the custom signature configuration.
      required: false
      schema:
        $ref: '#/components/schemas/SendAfterImport'
    transport_type_code_for_contact:
      name: transport_type_code_for_contact
      description: |
        Internal identifier that specifies the **Transport type** used for the **contact party** of the invoice within B2Brouter. This code determines the transport in which the document is exchanged with the contact entity.

        - If the contact already exists, this value will **overwrite** the existing `transport_type_code`.
        - If the parameter is **not provided**, the system assigns the `transport_type_code` based on the following priority:

          1. If the contact already exists, its current `transport_type_code` is used.
          2. If the contact does not exist:
             - If the contact is found in the **B2Brouter directory**, the code defined there is used.
             - Otherwise, the **default transport type** defined in the account settings is applied.

        Valid transport type codes can be retrieved from the **Transport Types** endpoint in the **Code Lists** section:  
        `/transport_types`

        If the specified `transport_type_code` is **invalid** or **incompatible**, the system will apply the **default** `transport_type_code` and `document_type_code`.
      in: query
      schema:
        $ref: '#/components/schemas/TransportTypeCode'
    document_type_code_for_contact:
      name: document_type_code_for_contact
      in: query
      description: |
        Internal identifier that specifies the **Document Type** used for the **contact party** of the invoice within B2Brouter. This code determines the format in which the document is exchanged with the contact entity.

        - If the contact already exists, this value will **overwrite** the existing `document_type_code`.
        - If the parameter is **not provided**, the system assigns the `document_type_code` based on the following priority:

          1. If the contact already exists, its current `document_type_code` is used.
          2. If the contact does not exist:
             - If the contact is found in the **B2Brouter directory**, the code defined there is used.
             - Otherwise, the **default document type** defined in the account settings is applied.

        Valid document type codes can be retrieved from the **Document Types** endpoint in the **Code Lists** section:  
        `/document_types`

        If the specified `document_type_code` is **invalid** or **incompatible** with the selected `transport_type_code`, the system will apply the **default** `transport_type_code` and `document_type_code`.
      example: xml.ubl.invoice.bis3
      schema:
        $ref: '#/components/schemas/DocumentTypeCode'
    issued:
      name: issued
      in: query
      description: |
        A flag that specifies whether the invoice to be imported is issued or received.
      required: false
      schema:
        type: boolean
        default: null
    filename:
      name: filename
      in: query
      description: |
        Name of the attachment.
      required: true
      example: test.pdf
      schema:
        type: string
    use_as_pdf_view:
      name: use_as_pdf_view
      in: query
      description: |
        Boolean to indicate that the uploaded PDF attachment should be used as the visual component 
        when generating a hybrid PDF (such as a ZUGFeRD document) or any legal PDF representation.
        When set to true, this attachment will be considered the legal PDF to display or embed, 
        instead of regenerating one from the invoice data. It can be used both for PDF deliveries 
        and for embedding XML (e.g., ZUGFeRD) into the provided PDF.

        NOTICE: If the invoice is modified after this PDF has been uploaded, the attachment will still be used as-is, unless explicitly replaced. 
        B2Brouter treats it as the legal representation provided by the account.
      required: false
      example: true
      schema:
        type: boolean
    order_id:
      name: id
      in: path
      description: A unique internal identifier of the **Order** in B2Brouter.
      required: true
      example: 4053100
      schema:
        $ref: '#/components/schemas/OrderId'
    order_format:
      name: format
      description: Format of the order
      in: path
      required: true
      schema:
        type: string
        enum:
          - json
          - original
        description: |
          In addition to the standard json format, there are some extra visualization formats for an order:
           * `json` - JSON format
           * `original` - Original format
        example: json
    order_number:
      name: number
      in: query
      description: Filter on order number.
      required: false
      schema:
        type: string
      example: '01'
    order_filename:
      name: filename
      in: query
      description: |
        Name of the attachment.
      required: false
      schema:
        type: string
        example: test.pdf
    order_delivery_location_id:
      name: delivery_location_id
      description: Filtered by delivery_location_id.
      in: query
      required: false
      schema:
        type: integer
        example: 123
    order_contact:
      name: contact
      description: Search field. Searches on the customer name and VAT code.
      in: query
      required: false
      schema:
        type: string
      example: John Doe
    order_sel_data:
      name: sel_data
      in: query
      description: Filter on submission date options.
      required: false
      schema:
        type: string
        enum:
          - issue_datetime
          - validity_end
          - delivery_date_start
          - order_confirmation.created_at
        description: |
          There are this options for an order:
           * `issue_datetime` - Filter on submission issue dates.
           * `validity_end` - Filter on submission validity end dates.
           * `delivery_date_start` - Filter on submission validity start dates.
           * `order_confirmation.created_at` - Filter on submission order confirmation dates.
        example: issue_datetime
    order_date_from:
      name: date_from
      in: query
      description: Filter from submission order date.
      required: false
      schema:
        type: string
        format: date
        example: '2022-01-01'
    order_date_to:
      name: date_to
      in: query
      description: Filter to submission order date.
      required: false
      schema:
        type: string
        format: date
        example: '2022-01-01'
    order_country:
      name: country
      description: Search field. Searches on the country code.
      in: query
      required: false
      schema:
        type: string
        example: es
    order_delivery_confirmed:
      name: delivery_confirmed
      description: Filter on order status "delivery confirmed".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    order_closed:
      name: closed
      description: Filter on order status "closed".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    order_accepted:
      name: accepted
      description: Filter on order status "accepted".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    order_refused:
      name: refused
      description: Filter on order status "refused".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    order_received:
      name: received
      description: Filter on order status "received".
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1
        enum:
          - 0
          - 1
        example: 1
    client_name:
      name: name
      description: Search field. Searches on the customer name, address and VAT code.
      in: query
      required: false
      schema:
        type: string
      example: John Doe
    client_is_client:
      name: is_client
      description: Filter on contact type, if it is client.
      in: query
      required: false
      schema:
        type: boolean
        example: true
    client_is_provider:
      name: is_provider
      description: Filter on contact type, if it is provider.
      in: query
      required: false
      schema:
        type: boolean
        example: true
    integration_code:
      name: integration_code
      description: Filter on integration_code. Performs an exact match search.
      in: query
      required: false
      schema:
        type: string
        example: 123
    invoice_id_query:
      name: invoice_id
      description: Filtered per invoice.
      in: query
      required: false
      schema:
        type: integer
        example: 123
    tax_report_id_query:
      name: tax_report_id
      description: Filtered per tax_report.
      in: query
      required: false
      schema:
        type: integer
        example: 123
    transport_type_code:
      name: code
      description: Code of the transport
      in: path
      required: true
      schema:
        type: string
        enum:
          - b2brouter
          - peppol
          - email
          - es.eusko_jaurlaritza
          - es.pecam
          - edicom
          - ediversa
        example: peppol
    sent_at_from:
      name: sent_at_from
      in: query
      description: Filter on sent date. Tax reports with sent date later than the specified date are returned.
      required: false
      schema:
        type: string
        format: date
      example: '2024-10-11'
    tax_report_id:
      name: id
      in: path
      description: |
        A unique internal identifier of the Tax Report in B2Brouter.
      required: true
      example: 4053100
      schema:
        type: integer
    ledger_id:
      name: id
      in: path
      description: |
        A unique internal identifier of the Ledger in B2Brouter.
      required: true
      example: 405
      schema:
        type: integer
    directory_country:
      name: country
      description: Country identifier of the company.
      in: path
      required: true
      schema:
        type: string
        example: es
    directory_scheme:
      name: scheme
      description: Scheme number of the company identifier
      in: path
      required: true
      schema:
        type: integer
        example: 9920
    directory_id:
      name: id
      description: Value of the company identifier. You can introduce id without the prefix
      in: path
      required: true
      schema:
        type: string
        example: ES123456789, 123456789
    web_hook_id:
      name: id
      in: path
      description: |
        A unique internal identifier of the WebHook in B2Brouter.
      required: true
      example: 4053101
      schema:
        type: integer
  schemas:
    SchemeCode:
      type: string
      nullable: true
      description: |
        Identifier scheme code (e.g. for TIN, CIN or PIN). Returned as a zero-padded string in this API version. Use the **Schemes** endpoint in Code lists section (`/schemes`) to get all valid scheme codes.
      example: '9920'
    Account:
      type: object
      description: Represents an account as an object
      properties:
        id:
          type: integer
          example: 12345
          readOnly: true
          description: Internal account ID
        tin_value:
          type: string
          description: Tax identification number value
          maxLength: 255
          example: A13585625
          nullable: true
        tin_scheme:
          allOf:
            - $ref: '#/components/schemas/SchemeCode'
          description: Tax identification number scheme
          maxLength: 255
          example: 9920
        cin_value:
          type: string
          description: Company identifier number value
          maxLength: 255
          nullable: true
          example: '1234567890123'
        cin_scheme:
          allOf:
            - $ref: '#/components/schemas/SchemeCode'
          description: Company identifier number scheme
          maxLength: 255
          nullable: true
          example: '0088'
        routing_codes:
          type: object
          description: Additional company identifier numbers (CIN 1–5) used for routing purposes.
          properties:
            cin1_value:
              type: string
              description: First additional company identifier number value
              maxLength: 255
              nullable: true
              example: '7080000950171'
            cin1_scheme:
              type: string
              description: Scheme of the first additional company identifier number. Returned as a zero-padded 4-character string (e.g. "0088"), or null when unknown.
              maxLength: 255
              nullable: true
              example: '0088'
            cin2_value:
              type: string
              description: Second additional company identifier number value
              maxLength: 255
              nullable: true
              example: null
            cin2_scheme:
              type: string
              description: Scheme of the second additional company identifier number. Returned as a zero-padded 4-character string (e.g. "0088"), or null when unknown.
              maxLength: 255
              nullable: true
              example: null
            cin3_value:
              type: string
              description: Third additional company identifier number value
              maxLength: 255
              nullable: true
              example: null
            cin3_scheme:
              type: string
              description: Scheme of the third additional company identifier number. Returned as a zero-padded 4-character string (e.g. "0088"), or null when unknown.
              maxLength: 255
              nullable: true
              example: null
            cin4_value:
              type: string
              description: Fourth additional company identifier number value
              maxLength: 255
              nullable: true
              example: null
            cin4_scheme:
              type: string
              description: Scheme of the fourth additional company identifier number. Returned as a zero-padded 4-character string (e.g. "0088"), or null when unknown.
              maxLength: 255
              nullable: true
              example: null
            cin5_value:
              type: string
              description: Fifth additional company identifier number value
              maxLength: 255
              nullable: true
              example: null
            cin5_scheme:
              type: string
              description: Scheme of the fifth additional company identifier number. Returned as a zero-padded 4-character string (e.g. "0088"), or null when unknown.
              maxLength: 255
              nullable: true
              example: null
        name:
          type: string
          description: Account name
          maxLength: 255
          example: My Company S.L.
        address:
          type: string
          description: Primary address
          maxLength: 255
          example: Carrer Example 123
        address2:
          type: string
          description: Secondary address
          maxLength: 255
          nullable: true
          example: Floor 2, Office 3
        city:
          type: string
          description: City
          maxLength: 255
          example: Barcelona
          nullable: true
        postalcode:
          type: string
          description: Postal code
          maxLength: 255
          example: '08001'
        province:
          type: string
          description: Province or state
          maxLength: 255
          nullable: true
          example: Barcelona
        country:
          type: string
          description: Country code
          maxLength: 2
          example: es
          default: es
        currency:
          type: string
          description: Default currency
          maxLength: 3
          example: EUR
          default: EUR
        contact_person:
          type: string
          description: Main contact person
          maxLength: 255
          nullable: true
          example: John Doe
        phone:
          type: string
          description: Phone number
          maxLength: 255
          nullable: true
          example: 34666777888
        email:
          type: string
          description: Email address
          maxLength: 255
          format: email
          example: contact@company.com
          nullable: true
        rounding_method:
          type: string
          enum:
            - half_up
            - bankers
            - truncate
          description: |
            Roundings (only for imported invoices)
             * `half_up` - Round half up
             * `bankers` - Bank rounding
             * `truncate` - Truncate decimals
          default: half_up
          example: half_up
        round_before_sum:
          type: boolean
          description: Whether to round before summing
          default: false
        apply_taxes_per_line:
          type: boolean
          description: Whether to apply taxes per line
          default: false
        skip_line_taxable_base_rounding:
          type: boolean
          description: 'When enabled, per-line taxable bases and tax amounts are not individually rounded — only the final accumulated tax total is rounded. Intended exclusively for accounts whose ERP uses VAT-inclusive totals, as it deviates from the standard tax calculation. Requires `apply_taxes_per_line: true` to have any effect.'
          default: false
          example: false
        registered_for_empl_tax:
          type: boolean
          description: Whether registered for employment tax
          default: false
        transport_type_code:
          type: string
          description: Default transport type code
          maxLength: 255
          nullable: true
          example: peppol
        document_type_code:
          type: string
          description: Default document type code
          maxLength: 255
          nullable: true
          example: xml.ubl.2.1
        has_logo:
          type: boolean
          description: Whether the account has an uploaded logo
          readOnly: true
          example: true
        archived:
          type: boolean
          description: Whether the account is archived
          readOnly: true
          example: false
        transactions_count:
          type: integer
          description: Number of transactions in current period
          readOnly: true
          example: 150
        transactions_count_previous_period:
          type: integer
          description: Number of transactions in previous period
          readOnly: true
          example: 120
        transactions_limit:
          type: integer
          description: Transaction limit for the subscription
          readOnly: true
          example: 1000
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Account creation timestamp
          example: '2024-07-07T11:51:57Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Account last update timestamp
          example: '2024-07-07T11:51:57Z'
        parent_id:
          type: integer
          example: 12345
          readOnly: true
          description: Parent account ID
        auto_remittance:
          type: boolean
          description: When enabled, automatically generates a structured remittance information (OGM/VCS code) for invoices sent between two Belgian parties.
          default: false
          example: false
    TransactionsEdocsync:
      properties:
        transactions_count:
          type: integer
          example: 16
          description: The transactions the account has made during the current period
          nullable: true
          readOnly: true
        transactions_count_previous_period:
          type: integer
          example: 28
          description: The transactions the account has made in the past period
          nullable: true
          readOnly: true
        transactions_limit:
          type: integer
          example: 25
          description: The number of transactions available for the current product
          nullable: true
          readOnly: true
    IndexMeta:
      type: object
      description: Represents meta data for listing endpoints
      properties:
        total_count:
          type: integer
          description: Total count of returned objects
          example: 1
        offset:
          type: integer
          description: Offset set by the params
          example: 0
        limit:
          type: integer
          description: Limit of the returned list set by the params
          example: 25
    Error:
      type: object
      description: Represents an error object returned in a failed request
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A unique error code identifying the type of error. See https://developer.b2brouter.net/docs/error_codes for the full code list.
              example: parameter_empty
            message:
              type: string
              description: A human-readable error message providing more context about the error.
              example: The parameter 'param' is missing or the value is empty
            param:
              type: string
              description: The parameter in the request that caused the error (if applicable).
              example: param
            type:
              type: string
              description: The type of error. Currently the only possible value is "invalid_request_error".
              example: invalid_request
    UnauthorizedError:
      type: object
      description: Represents an error object returned in a failed request
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A unique error code identifying the type of error.
              example: unauthorized
              default: unauthorized
            message:
              type: string
              description: A human-readable error message providing more context about the error.
              example: Invalid API Key provided, or the API key might not have the necessary permissions for this action.
            type:
              type: string
              description: The type of error, often mirrors the error code for clarity.
              example: invalid_request_error
              default: invalid_request_error
    AccountCreate:
      type: object
      description: |-
        Request body schema for creating an account (POST /accounts).
        Extends the shared `Account` schema with the create-time contract: the fields the API requires on creation are listed in `required`, and each of those that is `nullable` in the response schema is re-declared here as non-nullable, since a required field cannot be sent as `null`. The response representation keeps `Account` (where these fields may legitimately be `null` for legacy/partial accounts).
      allOf:
        - $ref: '#/components/schemas/Account'
        - $ref: '#/components/schemas/TransactionsEdocsync'
        - type: object
          required:
            - name
            - postalcode
            - email
            - address
            - city
            - province
            - phone
            - tin_value
          properties:
            email:
              type: string
            address:
              type: string
            city:
              type: string
            province:
              type: string
            postalcode:
              type: string
            phone:
              type: string
            tin_value:
              type: string
    AccountUpdate:
      type: object
      description: |-
        Request body schema for updating an account (PUT /accounts/{account}).
        Extends the shared `Account` schema. Updates are partial, so no field is `required` here, but `email`, `address` and `city` are re-declared as non-nullable: the model validates their presence on update (email unconditionally; address/city via `require_address` for accounts created on or after 2020-09-28), so sending them as `null` would be rejected. `province` is left nullable because its requirement is country-dependent. The response representation keeps `Account` (where these fields may be `null`).
      allOf:
        - $ref: '#/components/schemas/Account'
        - type: object
          properties:
            email:
              type: string
            address:
              type: string
            city:
              type: string
    ForbiddenError:
      type: object
      description: Represents an error object returned when the target project is archived
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A unique error code identifying the type of error.
              example: '403'
              default: '403'
            message:
              type: string
              description: A human-readable error message providing more context about the error.
              example: The project you are trying to access has been archived.
            type:
              type: string
              description: The type of error, often mirrors the error code for clarity.
              example: invalid_request_error
              default: invalid_request_error
    AccountDeleted:
      allOf:
        - $ref: '#/components/schemas/Account'
        - type: object
          description: Account with deleted status (used in destroy responses)
          properties:
            deleted:
              type: boolean
              description: Whether the account was deleted (true) or archived (false)
              readOnly: true
              example: true
    BankAccount:
      type: object
      description: Represents a bank account as an object
      required:
        - type
      properties:
        id:
          type: integer
          description: Internal ID
          readOnly: true
          example: 402
        type:
          type: string
          description: |
            Bank account type:
             * `number` - Account number
             * `iban` - IBAN
          enum:
            - iban
            - number
          default: iban
          example: iban
        name:
          type: string
          description: Name
          example: My Bank Account
          maxLength: 255
          nullable: true
        number:
          type: string
          description: Bank account number. Required when `type` is `number`. A standard account must provide either `number` or `iban`; third-party accounts may omit both.
          example: 10000000000000000000
          maxLength: 24
          nullable: true
        iban:
          type: string
          description: International Bank Account Number (IBAN). Required when `type` is `iban`. A standard account must provide either `number` or `iban`; third-party accounts may omit both.
          example: ES6000000000000000000000
          nullable: true
        bic:
          type: string
          description: Bank Identifier Code (BIC). This field is optional, and used only when `type` is set to `iban`.
          example: 0
          maxLength: 11
          nullable: true
        sufix:
          type: integer
          description: Sufix for the bank account
          example: 1
          nullable: true
        address:
          type: string
          description: Address
          example: 1234 Main Street
          maxLength: 255
          nullable: true
        city:
          type: string
          description: City
          example: Barcelona
          maxLength: 255
          nullable: true
        province:
          type: string
          description: Province
          example: Barcelona
          nullable: true
        postalcode:
          type: string
          description: Postal Code
          example: 12345
          nullable: true
        country:
          type: string
          description: Country. Use ISO 3166-1 alpha-2 country codes.
          example: es
          maxLength: 2
          nullable: true
        is_default:
          type: boolean
          description: Whether this bank account is the default for the company. Only one bank account per company can be the default. This default applies to the company itself; it is not automatically assigned to contacts.
          example: false
        created_at:
          type: string
          format: date-time
          example: '2021-02-20T19:12:44Z'
          readOnly: true
          description: Date and time when the bank account record was created
        updated_at:
          type: string
          format: date-time
          example: '2021-02-30T15:12:44Z'
          readOnly: true
          description: Date and time when the bank account record was last updated
    Attachment:
      type: object
      description: Represents an attachment file
      properties:
        id:
          type: integer
          example: 12345
        filename:
          type: string
          example: invoice.pdf
        content_type:
          type: string
          example: application/pdf
        filesize:
          type: integer
          example: 12345
        category:
          type: string
          nullable: true
          example: original
          description: |
            Attachment category. Notable values:
            - `original`: The legal/original invoice document
            - `pdf_view`: A PDF preview of the invoice
            - `null`: A regular supplementary attachment
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00.000Z'
    TbaiTaxReportSetting:
      type: object
      description: Represents a tax report settings for 'tbai' as an object
      properties:
        code:
          type: string
          example: tbai
          description: The Tax Report Authority code.
          enum:
            - tbai
        start_date:
          type: string
          format: date-time
          example: '2024-07-09T00:00:00.000Z'
          description: Date when the Tax Report Setting was enabled. If not provided, the current date and time will be used..
          nullable: true
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        delegation:
          type: string
          example: gipuzkoa
          description: Tax Authority Delegation.
          enum:
            - gipuzkoa
            - bizkaia
            - araba
        reason_vat_exempt:
          type: string
          example: E1
          description: TicketBAI Reason for VAT Exempt.
          enum:
            - E1
            - E2
            - E3
            - E4
            - E5
            - E6
          nullable: true
        special_regime_key:
          type: string
          example: '01'
          description: TicketBAI Special Regime Key.
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - '09'
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
            - '51'
            - '52'
            - '53'
          nullable: true
        reason_no_subject:
          type: string
          example: OT
          description: Default TicketBAI Reason for No Subject.
          enum:
            - OT
            - RL
          nullable: true
        credit_note_code:
          type: string
          example: R1
          description: Default TicketBAI Credit Note Code.
          enum:
            - R1
            - R2
            - R3
            - R4
            - R5
          nullable: true
        type_operation:
          type: string
          example: services
          description: Default TicketBAI Type of Operation.
          enum:
            - services
            - goods
          nullable: true
        epigraph:
          type: string
          example: '147410'
          description: TicketBAI Epigraph needed for bizkaia delegation.
          nullable: true
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was updated
          readOnly: true
    SdiTaxReportSetting:
      type: object
      description: Represents a tax report settings for 'sdi' as an object
      properties:
        code:
          type: string
          example: sdi
          description: The Tax Report Authority code.
          enum:
            - sdi
        start_date:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was enabled
          nullable: true
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was last updated
          readOnly: true
    VerifactuTaxReportSetting:
      type: object
      description: Represents a tax report settings for Verifactu as an object
      properties:
        code:
          type: string
          example: verifactu
          description: The Tax Report Authority code.
          enum:
            - verifactu
        start_date:
          type: string
          format: date-time
          example: '2025-04-29T00:00:00.000Z'
          description: Date when the Tax Report Setting was enabled. If not provided, the current date and time will be used.
          nullable: true
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        reason_vat_exempt:
          type: string
          example: E1
          description: |
            Verifactu reason code for VAT Exemption. 
            [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#exemption-codes).
          enum:
            - E1
            - E2
            - E3
            - E4
            - E5
            - E6
          nullable: true
        special_regime_key:
          type: string
          example: '01'
          description: |
            Verifactu Special Regime Key.
            [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#special-regime-key-codes).
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - '09'
            - '10'
            - '11'
            - '14'
            - '15'
            - '17'
            - '18'
            - '19'
          nullable: true
        special_regime_key_igic:
          type: string
          example: '01'
          description: Verifactu Special Regime Key for IGIC tax.
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - '09'
            - '10'
            - '11'
            - '14'
            - '15'
            - '17'
            - '18'
            - '19'
            - '20'
          nullable: true
        reason_no_subject:
          type: string
          example: N1
          description: |
            Verifactu Reason for No Subject.
            [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#non-subject-codes)
          enum:
            - N1
            - N2
          nullable: true
        credit_note_code:
          type: string
          example: R1
          description: |
            Verifactu Credit Note Code.
            [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#invoice-type-codes)
          enum:
            - R1
            - R2
            - R3
            - R4
            - R5
          nullable: true
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was updated
          readOnly: true
    KsefTaxReportSetting:
      type: object
      description: Represents a tax report settings for 'KSeF (Krajowy System e-Faktur)' as an object
      properties:
        code:
          type: string
          example: ksef
          description: The Tax Report Authority code.
          enum:
            - ksef
        start_date:
          type: string
          format: date-time
          example: '2024-07-09T00:00:00.000Z'
          description: Date when the Tax Report Setting was enabled. If not provided, the current date and time will be used..
          nullable: true
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        credit_note_code:
          type: string
          example: '1'
          enum:
            - '1'
            - '2'
            - '3'
          nullable: false
          description: |
            Default type of effect of correction in the records for VAT:
            * `1` - Correction with effect on the date of recognition of the original invoice.
            * `2` - Correction with effect on the date of issue of the corrective invoice.
            * `3` - Correction with effect on a different date, including when the dates are different for different items of the corrective invoice.

            This setting applies to invoices with type codes KOR, KOR_ZAL, or KOR_ROZ. When creating a corrective invoice,
            you must also specify the `amended_ksef_number` field in the TaxReport with the KSeF reference number of the original invoice.
        type_operation:
          type: string
          example: services
          description: Default type of Operation.
          enum:
            - services
            - goods
            - null
          nullable: true
        certificate:
          type: string
          format: byte
          description: |
            KSeF certificate in PKCS#12 (.p12 or .pfx) format encoded in base64 (without padding or line breaks).

            **Requirements:**
            - Must contain both the certificate and private key

            **How to encode your certificate:**
            ```bash
            base64 -w 0 your-certificate.p12
            ```
          example: MIIKZAIBAzCCCh4GCSqGSIb3DQEHAaCCCg8EggoLMIIKBzCCBXcGCSqGSIb3...
          nullable: false
          writeOnly: true
        certificate_pin:
          type: string
          description: |
            Password/PIN for the PKCS#12 certificate. Required when creating a KSeF tax report setting.
          example: MySecurePassword123
          nullable: false
          writeOnly: true
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was updated
          readOnly: true
    DgfipTaxReportSetting:
      type: object
      description: '[BETA] Represents a tax report settings for DGFiP (France) as an object'
      required:
        - start_date
        - type_operation
      properties:
        code:
          type: string
          example: dgfip
          description: The Tax Report Authority code.
          enum:
            - dgfip
        start_date:
          type: string
          format: date-time
          example: '2025-04-29T00:00:00.000Z'
          description: Date when the Tax Report Setting was enabled. If not provided, the current date and time will be used.
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        type_operation:
          type: string
          example: services
          description: Default DGFiP Type of Operation.
          enum:
            - services
            - goods
            - mixed
        reason_vat_exempt:
          type: string
          example: VATEX-FR-FRANCHISE
          description: |
            DGFiP reason code for VAT Exemption (BT-121).
            Required when invoice contains exempt tax lines (category E).
            Defaults to VATEX-FR-FRANCHISE if not specified.
          enum:
            - VATEX-FR-FRANCHISE
            - VATEX-FR-CNWVAT
            - VATEX-FR-CGI261-1
            - VATEX-FR-CGI261-2
            - VATEX-FR-CGI261-3
            - VATEX-FR-CGI261-4
            - VATEX-FR-CGI261-5
            - VATEX-FR-CGI261-7
            - VATEX-FR-CGI261-8
            - VATEX-FR-CGI261A
            - VATEX-FR-CGI261B
            - VATEX-FR-CGI261C-1
            - VATEX-FR-CGI261C-2
            - VATEX-FR-CGI261C-3
            - VATEX-FR-CGI261D-1
            - VATEX-FR-CGI261D-1BIS
            - VATEX-FR-CGI261D-2
            - VATEX-FR-CGI261D-3
            - VATEX-FR-CGI261D-4
            - VATEX-FR-CGI261E-1
            - VATEX-FR-CGI261E-2
            - VATEX-FR-CGI277A
            - VATEX-FR-CGI275
            - VATEX-FR-298SEXDECIESA
            - VATEX-FR-CGI295
            - VATEX-FR-AE
            - null
          nullable: true
        enterprise_size:
          type: string
          example: pme
          description: |
            Enterprise size category as defined by French LME 2008 law (Décret 2008-1354).
            Determines the e-invoicing obligation timeline.
            - `ge` — Grande entreprise (≥ 5000 employees or revenue > €1.5B)
            - `eti` — Entreprise de taille intermédiaire (250–4999 employees, revenue ≤ €1.5B)
            - `pme` — Petite et moyenne entreprise (10–249 employees, revenue ≤ €50M)
            - `micro` — Micro-entreprise (< 10 employees, revenue ≤ €2M)
          enum:
            - ge
            - eti
            - pme
            - micro
            - null
          nullable: true
        naf_code:
          type: string
          example: '62'
          description: |
            First two digits of the company's NAF/APE code (INSEE activity classification).
            Must be exactly 2 digits. For example, `62` corresponds to "Programmation, conseil
            et autres activités informatiques".
          pattern: ^\d{2}$
          nullable: true
        email:
          type: string
          example: contact@company.fr
          description: Contact email address for DGFiP notifications.
          nullable: true
        annuaire_only:
          type: boolean
          example: false
          default: false
          description: |
            When `true`, B2Brouter only registers the company in the PPF Annuaire
            (directory) and enables Peppol reception, without generating tax reports.
            Fields `enterprise_size`, `naf_code` and `vat_regime` are not required in
            this mode. When `false` (default), full e-Reporting is enabled and
            `enterprise_size`, `naf_code` and `vat_regime` become required.
        vat_regime:
          type: string
          example: reel_normal_mensuel
          description: |
            French VAT declaration regime. Determines the frequency with which
            e-Reporting (flux 10) tax reports are transmitted to the DGFiP:
            - `reel_normal_mensuel` — transaction reports per décade (1–10, 11–20, 21–end of month)
            - `reel_normal_trimestriel` — monthly reports
            - `simplifie` — monthly reports. The regime is abolished on 2027-01-01;
              from that date stored values are treated as `reel_normal_trimestriel`
              and the value is no longer selectable.
            - `franchise_en_base` — bimonthly reports (Jan–Feb, Mar–Apr, …)

            Required when activating full e-Reporting (`enabled: true` with
            `annuaire_only: false`); not required in annuaire-only mode.
          enum:
            - reel_normal_mensuel
            - reel_normal_trimestriel
            - simplifie
            - franchise_en_base
            - null
          nullable: true
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was updated
          readOnly: true
    SiiTaxReportSetting:
      type: object
      description: Represents a tax report setting for SII (Spain, AEAT immediate supply of VAT ledgers) as an object
      properties:
        code:
          type: string
          example: sii
          description: The Tax Report Authority code.
          enum:
            - sii
        start_date:
          type: string
          format: date-time
          example: '2026-04-29T00:00:00.000Z'
          description: Date when the Tax Report Setting was enabled. If not provided, the current date and time will be used.
          nullable: true
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2026-04-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2026-04-06T11:51:57Z'
          description: Date when the Tax Report Setting was updated
          readOnly: true
    LhdnTaxReportSetting:
      type: object
      description: Represents a tax report settings for 'lhdn' as an object
      properties:
        code:
          type: string
          example: lhdn
          description: The Tax Report Authority code.
          enum:
            - lhdn
        start_date:
          type: string
          format: date-time
          example: '2024-07-09T00:00:00.000Z'
          description: Date when the Tax Report Setting was enabled. If not provided, the current date and time will be used..
          nullable: true
        auto_generate:
          type: boolean
          example: true
          default: true
          description: Generate the Tax Report automatically
        auto_send:
          type: boolean
          example: true
          default: true
          description: Send the Tax Report automatically
        enabled:
          type: boolean
          example: true
          default: true
          description: Represents if the tax report setting is enabled
        msic:
          type: string
          example: '01111'
          description: Malaysia Standard Industrial Classification (MSIC) Code
          enum:
            - '00000'
            - A
            - '01111'
            - '01112'
            - '01113'
            - '01119'
            - '01120'
            - '01131'
            - '01132'
            - '01133'
            - '01134'
            - '01135'
            - '01136'
            - '01137'
            - '01138'
            - '01140'
            - '01150'
            - '01160'
            - '01191'
            - '01192'
            - '01193'
            - '01199'
            - '01210'
            - '01221'
            - '01222'
            - '01223'
            - '01224'
            - '01225'
            - '01226'
            - '01227'
            - '01228'
            - '01229'
            - '01231'
            - '01232'
            - '01233'
            - '01239'
            - '01241'
            - '01249'
            - '01251'
            - '01252'
            - '01253'
            - '01259'
            - '01261'
            - '01262'
            - '01263'
            - '01269'
            - '01271'
            - '01272'
            - '01273'
            - '01279'
            - '01281'
            - '01282'
            - '01283'
            - '01284'
            - '01285'
            - '01289'
            - '01291'
            - '01292'
            - '01293'
            - '01294'
            - '01295'
            - '01296'
            - '01299'
            - '01301'
            - '01302'
            - '01303'
            - '01304'
            - '01411'
            - '01412'
        type_operation:
          type: string
          example: services
          description: Default Type of Operation.
          enum:
            - services
            - goods
        classification_code:
          type: string
          description: |
            Default classification code, that defines the category of products or services being billed as a result of a commercial transaction.
          enum:
            - '001'
            - '002'
            - '003'
            - '004'
            - '005'
            - '006'
            - '007'
            - '008'
            - '009'
            - '010'
            - '011'
            - '012'
            - '013'
            - '014'
            - '015'
            - '016'
            - '017'
            - '018'
            - '019'
            - '020'
            - '021'
            - '022'
            - '023'
            - '024'
            - '025'
            - '026'
            - '027'
            - '028'
            - '029'
            - '030'
            - '031'
            - '032'
            - '033'
            - '034'
            - '035'
            - '036'
            - '037'
            - '038'
            - '039'
            - '040'
            - '041'
            - '042'
            - '043'
            - '044'
            - '045'
        locked:
          type: boolean
          example: true
          description: Cannot be completely modified or deleted
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was created
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-06-06T11:51:57Z'
          description: Date when the Tax Report Setting was updated
          readOnly: true
    TransportTypeCode:
      type: string
      maxLength: 100
      title: Transport Type Code
      description: |
        An internal identifier that is unique to each **Transport Type** within B2Brouter.<br> You can get all valid transport type codes using the **Transport Types** endpoint in Code lists section (`/transport_types`).
      example: peppol
      nullable: true
    DocumentTypeCode:
      type: string
      maxLength: 100
      title: Document Type Code
      description: |
        An internal identifier that is unique to each **Document Type** within B2Brouter.<br> You can get all valid document type codes using the **Document Types** endpoint in Code lists section (`/document_types`).
      example: xml.ubl.invoice.bis3
      nullable: true
    InvoiceContactHash:
      type: object
      description: Represents a contact as an object
      properties:
        id:
          type: integer
          nullable: true
          example: 123
          readOnly: true
          description: Contact ID
        name:
          type: string
          description: |
            The full name of the Buyer.

            ID: `BT-44`
          example: Buyer Full Name AS
        tin_value:
          type: string
          nullable: true
          description: |
            VAT identifier
            ID: `BT-48`
          maxLength: 255
          example: ESA13585625
        tin_scheme:
          type: string
          nullable: true
          description: |
            The scheme identifier of VAT Number
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          example: '9920'
        cin_scheme:
          type: string
          description: |
            The scheme identifier of Company Identifier Number (not a tax identifier number).
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          nullable: true
          example: '0088'
        cin_value:
          type: string
          description: Company Identifier Number
          nullable: true
          example: '7080000950171'
        address:
          type: string
          description: |
            The main address line in an address.

            ID: `BT-50`
          example: Lausitzer Str. 65
          nullable: true
        address2:
          type: string
          description: |
            An additional address line in an address that can be used to give further details supplementing the main line.

            ID: `BT-51`
          nullable: true
          example: Lausitzer Str. 66
        postalcode:
          type: string
          description: |
            The identifier for an addressable group of properties according to the relevant postal service.

            ID: `BT-53`
          example: '80535'
          nullable: true
        city:
          type: string
          description: |
            The common name of the city, town or village,where the Buyer's address is located.

            ID: `BT-52`
          example: Berlin
          nullable: true
        province:
          type: string
          description: |
            The  subdivision  of  a  country.

            ID: `BT-54`
          example: Berlin
          nullable: true
        country:
          type: string
          description: Country
          example: de
        email:
          type: string
          description: |
            An e-mail address for the contact point.

            ID: `BT-58`
          example: example@email.com
          nullable: true
        pin_value:
          type: string
          description: |
            Peppol Identifier Number, identifies the Buyer's electronic address to which the invoice is delivered.

            ID: `BT-49`
          example: '987654321'
          nullable: true
        pin_scheme:
          type: string
          description: |
            The identification scheme identifier of the Buyer electronic address.

            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`). The value has to be in EAS code list
            https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/
          example: '0192'
          nullable: true
        party_identification:
          type: string
          description: |
            Seller/Buyer identifier

            ID: `BT-29` if Contact is a Seller (Invoice is a Received Invoice)
            ID: `BT-46` if Contact is a Buyer (Invoice is an Issued Invoice)
          example: '506001234999'
          nullable: true
        transport_type_code:
          allOf:
            - $ref: '#/components/schemas/TransportTypeCode'
            - description: |
                An internal identifier that is unique to each **Transport Type** within B2Brouter.<br> You can get all valid transport type codes using the **Transport Types** endpoint in Code lists section (`/transport_types`).<br> Ignored for `IssuedSimplifiedInvoice`
          writeOnly: true
        document_type_code:
          allOf:
            - $ref: '#/components/schemas/DocumentTypeCode'
            - description: |
                An internal identifier that is unique to each **Document Type** within B2Brouter.<br> You can get all valid document type codes using the **Document Types** endpoint in Code lists section (`/document_types`).<br> Ignored for `IssuedSimplifiedInvoice`
          writeOnly: true
    StateOutput:
      type: string
      example: refused
      enum:
        - new
        - sending
        - sent
        - read
        - downloaded
        - annulled
        - billed
        - expired
        - issued
        - accepted
        - registered
        - refused
        - received
        - closed
        - paid
        - allegedly_paid
        - performing_ocr
        - ocr_failed
        - annotated
        - payment_processed
        - error
        - invalid
      description: |
        States for an issued invoice:
         * `new` - The initial status of an invoice.
         * `sending` - The invoice is currently being transmitted (queued for delivery).
         * `sent` - The invoice has been sent successfully.
         * `read` - A read notification has been received from the recipient (e.g. via PEPPOL network).
         * `accepted` - The invoice has been accepted by the recipient or manually marked as accepted.
         * `registered` - A registered notification has been received from a tax authority or manually marked as registered.
         * `refused` - A refused notification has been received or the invoice was manually marked as refused.
         * `received` - Used in integration context to indicate the document was received by the recipient system.
         * `allegedly_paid` - The receiver has indicated that payment of the invoice has been ordered, but payment is not yet confirmed.
         * `paid` - The invoice has been fully paid.
         * `annulled` - The invoice has been voided or cancelled (e.g. via a C4 annulment notification).
         * `expired` - The invoice has passed its due date or validity period without being acted upon.
         * `issued` - The invoice has been formally issued in the tax system (C1 corner state tracking).
         * `error` - An error occurred while sending or processing the invoice.
         * `closed` - Final state indicating the invoice lifecycle is complete.

        States for a received invoice:
         * `performing_ocr` - The system is extracting text from the received invoice file using OCR.
         * `ocr_failed` - OCR processing failed and the file could not be read or processed.
         * `new` - The initial status of a received invoice (or after successful OCR processing).
         * `accepted` - The invoice has been marked as accepted.
         * `refused` - The invoice has been marked as refused.
         * `annotated` - The invoice has been marked with an accounting annotation.
         * `billed` - The invoice has been recorded as billed for accounting purposes.
         * `payment_processed` - Payment processing for the invoice has been completed.
         * `paid` - The invoice has been fully paid.
         * `invalid` - The invoice failed validation during import or reception.
         * `error` - An error occurred while processing the invoice.

        States for an issued simplified invoice:
         * `new` - The initial status of an invoice.
         * `sending` - The invoice is currently being transmitted (queued for delivery).
         * `sent` - The invoice has been sent successfully.
         * `paid` - The invoice has been paid or manually marked as paid.
         * `downloaded` - The invoice has been downloaded by the recipient or manually marked as downloaded.
         * `accepted` - The invoice has been marked as accepted.
         * `refused` - When the invoice is marked as refused.
         * `registered` - When a registered notification has been received or manually marked as registered.
         * `closed` - Final state indicating the invoice lifecycle is complete.

        States for an issued self-invoice:
         * `new` - The initial status of an invoice.
         * `sending` - The invoice is currently being transmitted (queued for delivery).
         * `sent` - The invoice has been sent successfully.
         * `accepted` - The invoice has been marked as accepted.
         * `registered` - A registered notification has been received or manually marked as registered.
         * `allegedly_paid` - The receiver has indicated that payment has been ordered, but payment is not yet confirmed.
         * `payment_processed` - Payment processing for the invoice has been completed.
         * `paid` - The invoice has been fully paid.
         * `closed` - Final state indicating the invoice lifecycle is complete.
    Tax:
      type: object
      nullable: true
      description: Represents a tax as an object
      properties:
        name:
          type: string
          description: Tax Name
          example: IVA
        base:
          type: number
          format: decimal
          description: The base amount that may be used to calculate the Tax Amount
          example: 100
          readOnly: true
        amount:
          type: number
          format: decimal
          description: The amount of the tax.
          readOnly: true
          example: 21
        category:
          type: string
          enum:
            - E
            - NS
            - Z
            - S
            - H
            - AA
            - AAA
            - AE
            - G
            - O
            - K
          example: S
          description: |
            Taxes categories
             * `E` - Exempt
             * `NS` - NotSubject
             * `Z` - ZeroRated
             * `S` - Standard
             * `H` - High Rate
             * `AA` - Low Rate
             * `AAA` - Super Low Rate
             * `AE` - Reverse
             * `G` - Free export item, VAT not charged
             * `O` - Services outside scope of tax
             * `K` - VAT exempt for EEA intra-community supply of goods and services
          writeOnly: true
        percent:
          type: number
          format: float
          description: Tax %
          example: 21
        comment:
          type: string
          description: Tax comment
          nullable: true
          example: IVA 21%
    PaymentMethodCode:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 7
        - 10
        - 11
        - 12
        - 13
        - 14
        - 15
        - 17
        - 19
        - 31
        - 54
        - 56
        - 58
        - 59
        - 101
        - 102
        - null
      nullable: true
      description: |
        The means, expressed as code, for how a payment is expected to be or has been settled.
        ID: `BT-81`
        This is B2Brouter’s internal code list for payment means. Each internal code maps to a UBL code following the EN 16931 semantic model.
        Payment method
         * `1` - Cash (UBL: 10)
         * `2` - Direct debit (UBL: 49)
         * `3` - Hold (UBL: 8)
         * `4` - Bank transfer (UBL: 30)
         * `7` - Awarded contract (UBL: ZZZ)
         * `10` - Promissory note (UBL: 60)
         * `11` - Cheque (UBL: 20)
         * `12` - Reposition (UBL: ZZZ)
         * `13` - Other (UBL: ZZZ)
         * `14` - Compensation (UBL: 97)
         * `15` - Payment by postgiro (UBL: 50)
         * `17` - Bank cheque (UBL: 23)
         * `19` - Bank card (UBL: 48)
         * `31` - Debit transfer (UBL: 31)
         * `54` - Credit card (UBL: 54)
         * `56` - Bank giro (UBL: 56)
         * `58` - SEPA bank transfer (SCT) (UBL: 58)
         * `59` - SEPA Direct Debit (SDD) (UBL: 59)
         * `101` - GIRO (UBL: ZZZ)
         * `102` - PayNow Corporate (UBL: ZZZ)
      example: 4
    BankAccountCommon:
      type: object
      description: Represents common fields of a bank account as an object
      properties:
        name:
          type: string
          description: Name
          example: My Bank Account
          maxLength: 255
          nullable: true
        type:
          type: string
          description: |
            Bank account type:
             * `number` - Account number
             * `iban` - IBAN
          enum:
            - iban
            - number
          default: iban
          example: iban
        number:
          type: string
          description: Bank account number. Required when `type` is `number`. A standard account must provide either `number` or `iban`; third-party accounts may omit both.
          example: 10000000000000000000
          maxLength: 24
          nullable: true
        iban:
          type: string
          description: International Bank Account Number (IBAN). Required when `type` is `iban`. A standard account must provide either `number` or `iban`; third-party accounts may omit both.
          example: ES6000000000000000000000
          nullable: true
        bic:
          type: string
          description: Bank Identifier Code (BIC). This field is optional, and used only when `type` is set to `iban`.
          example: 0
          maxLength: 11
          nullable: true
    CardAccountCommon:
      type: object
      nullable: true
      description: |
        Represents common fields of a card account as an object.
        A group of business terms providing information about card used for payment contemporaneous with invoice issuance.
      properties:
        id:
          type: integer
          description: A unique identifier for this CardAccount across all the system.
          readOnly: true
        account_number:
          type: string
          description: |
            The Primary Account Number (PAN) of the card used for payment. In accordance with card payments security standards, 
            an invoice should never include a full card primary account number. 
            At the moment PCI Security Standards Council has defined that the first 6 digits and last 4 digits 
            are the maximum number of digits to be shown.
            ID: `BT-87`
          example: 1234567890
          minLength: 10
          maxLength: 10
        holder_name:
          type: string
          description: |
            The name of the payment card holder.
            ID: `BT-88`
          example: John Doe
        network:
          type: string
          description: Card Network identifier, such as VISA, American Express, Master Card.
          example: VISA
          maxLength: 50
          nullable: true
    AllowanceChargeBase:
      type: object
      description: Base schema for allowance charges containing common fields
      properties:
        id:
          type: integer
          example: 12345
          description: |
            A unique internal identifier of the AllowanceCharge in B2Brouter. It can be used to update or destroy an existing AllowanceCharge.
        allowance_charge_indicator:
          type: string
          description: |
            Indicates whether this is an allowance (discount) or charge.

            ID: `BT-20`, `BT-21` for document level or `BT-140`, `BT-141` for line level
          enum:
            - allowance
            - charge
          example: allowance
        amount:
          type: number
          format: decimal
          description: |
            The amount of the allowance or charge, without VAT.
            Either amount or percentage must be provided, but not both.

            ID: `BT-92`, `BT-99` for document level or `BT-136`, `BT-141` for line level
          example: 50
          nullable: true
        percentage:
          type: number
          format: decimal
          description: |
            The percentage that may be used to calculate the allowance or charge amount.
            Either amount or percentage must be provided, but not both.

            ID: `BT-94`, `BT-101` for document level or `BT-138`, `BT-144` for line level
          example: 10.5
          nullable: true
        description:
          type: string
          maxLength: 255
          description: |
            The reason for the allowance or charge, expressed as text.

            ID: `BT-97`, `BT-104` for document level or `BT-139`, `BT-145` for line level
          example: Volume discount
          nullable: true
        is_reimbursable_expense:
          type: boolean
          description: |
            [FacturaE Only]

            Indicates whether the charge is a reimbursable expense (Spanish "suplidos").
            Only applicable to charges, not allowances.
          default: false
        base_amount:
          type: number
          format: decimal
          description: |
            The base amount used to calculate percentage-based allowances or charges.
            This is calculated automatically from the adjustable record.
          example: 1000
          readOnly: true
        calculated_amount:
          type: number
          format: decimal
          description: |
            The final calculated amount of the allowance or charge.
            For fixed amounts, this equals the amount field.
            For percentages, this is calculated from percentage and base_amount.
          example: 105
          readOnly: true
        currency:
          type: string
          description: |
            The currency of the allowance or charge amounts.
            Inherited from the associated invoice.
          example: EUR
          readOnly: true
        _destroy:
          type: boolean
          description: |
            Set to true to delete this allowance or charge when updating.
            Used in nested attribute updates.
          writeOnly: true
      required:
        - allowance_charge_indicator
    AdditionalItemProperty:
      type: object
      description: A group of business terms providing information about properties of the goods and services invoiced.
      properties:
        name:
          type: string
          description: |
            Additional Item Property (Name) 

            ID: `BT-160`
        value:
          type: string
          description: |
            Additional Item Property (Value)

            ID: `BT-161`
    InvoiceLine:
      type: object
      required:
        - quantity
      description: |
        A group of business terms providing information on individual Invoice lines.

        ID: `BG-25`
      properties:
        id:
          type: integer
          example: 435453
          description: A unique identifier for this InvoiceLine across all the system. Only shown if the query parameter "include" is "detailed_lines".
          readOnly: true
        position:
          type: integer
          example: 1
          description: position
        quantity:
          type: number
          format: decimal
          description: |
            Invoiced quantity. The quantity of items (goods or services) that is charged in the Invoice line.

            ID: `BT-129`
          maxLength: 255
          example: 1
        price:
          type: number
          format: decimal
          description: |
            Item net price. The price of an item, exclusive of VAT, after subtracting item price discount.

            This is the price for `base_quantity` units. When `base_quantity` is 1 (the default), this is the price per single unit. When `base_quantity` is greater than 1, this represents the price for that many units (e.g., 12.50 per 100 pieces).

            ID: `BT-146`
          maxLength: 255
          example: 10
        base_quantity:
          type: number
          format: decimal
          description: |
            Item price base quantity. The number of item units to which the price applies.

            Used when the price is quoted per multiple units rather than per single unit (e.g., price per 100 pieces, per 1000 sheets). The line amount is calculated as:

            `total_cost = quantity * price / base_quantity`

            For example, 500 screws at 12.50 per 100: `500 * 12.50 / 100 = 62.50`

            ID: `BT-149`
          minimum: 0
          exclusiveMinimum: true
          default: 1
          example: 1
        description:
          type: string
          description: |
            Item Name.

            ID: `BT-153`
          maxLength: 65535
          nullable: true
          example: Item 1
        total_cost:
          type: number
          format: float
          description: |
            Line base amount: `quantity * price / base_quantity`
          maxLength: 255
          readOnly: true
          example: 10
        extension_amount:
          type: number
          format: float
          description: |
            Line net total amount (total_cost + charges - discounts)

            ID: `BT-131`
          maxLength: 255
          example: 10
        unit:
          type: number
          maxLength: 255
          default: 1
          description: |
            * `1` - units
            * `2` - hours
            * `3` - kilograms
            * `4` - liters
            * `5`  - other
            * `6`  - days
            * `7`  - boxes
            * `8`  - trays
            * `9`  - barrels
            * `10` - bags
            * `11` - carboys
            * `12` - bottles
            * `15` - centiliters
            * `16` - centimeters
            * `17` - bins
            * `18` - dozens
            * `19` - cases
            * `21` - grams
            * `22` - kilometers
            * `23` - cans
            * `24` - bunches
            * `25` - meters
            * `26` - milimeters
            * `28` - packages
            * `30` - rolls
            * `31` - envelopes
            * `32` - tubs
            * `33` - cubicmeter
            * `34` - second
            * `35` - watt
            * `36` - squaremetre
            * `37` - tonnes
            * `38` - megawatt-hours
            * `39` - months
            * `40` - years
            * `41` - one (synonym of "units")
          example: 1
        allowance_charges_attributes:
          type: array
          description: |
            Line-level allowances (discounts) and charges.

            Supports multiple allowances and charges for this invoice line.

            Line-level allowances cannot have their own tax configuration.

            ID: `BG-27`, `BG-28`
          items:
            $ref: '#/components/schemas/AllowanceChargeBase'
          writeOnly: true
        allowance_charges:
          type: array
          description: |
            Line-level allowances (discounts) and charges.
            Only shown if the query parameter "include" contains "allowance_charges".

            Line-level allowances cannot have their own tax configuration.

            ID: `BG-27`, `BG-28`
          items:
            $ref: '#/components/schemas/AllowanceChargeBase'
          readOnly: true
          nullable: true
        gross_amount:
          type: number
          format: decimal
          description: total_cost + charges - discounts
          readOnly: true
          example: 100
        taxes:
          type: array
          description: Taxes
          items:
            $ref: '#/components/schemas/Tax'
          readOnly: true
        taxes_attributes:
          type: array
          description: Taxes
          items:
            $ref: '#/components/schemas/Tax'
          writeOnly: true
        article_code:
          type: string
          description: |
            Seller product ID. An identifier, assigned by the Seller, for the item.

            ID: `BT-155`
          maxLength: 255
          example: '9873242'
          nullable: true
        article_code2:
          type: string
          description: |
            Product ID. An item identifier based on a registered scheme.

            ID: `BT-157`
          maxLength: 255
          example: '10986700'
          nullable: true
        article_code2_scheme:
          type: string
          description: |
            Product ID Scheme.Item standard identifier identification scheme identifier. The identification scheme identifier of the Item standard identifier.

            ID: `BT-157-1`
          maxLength: 255
          writeOnly: true
          example: '0160'
          nullable: true
        article_code_buyer:
          type: string
          description: |
            Buyer product ID. An identifier, assigned by the Buyer, for the item.

            ID: `BT-156`
          maxLength: 255
          nullable: true
          example: '9873242'
        classification_code:
          type: string
          description: |
            Item Classification Code

            ID: `BT-158`
          maxLength: 255
          nullable: true
          example: '9873242'
        classification_code_scheme:
          type: string
          description: |
            Item Classification Code Scheme

            ID: `BT-158-1`
          maxLength: 255
          nullable: true
          example: '0160'
        item_origin_country:
          type: string
          description: |
            Item Origin Country

            ID: `BT-159`
          maxLength: 2
          nullable: true
          example: es
        buyer_accounting_reference:
          type: string
          description: |
            A textual value that specifies where to book the relevant data into the Buyer's financial accounts.

            ID: `BT-133`
          maxLength: 255
          example: '1287:65464'
          nullable: true
        delivery_note_date:
          type: string
          format: date
          description: Dispatch advice date
          nullable: true
          example: '2024-09-12'
        delivery_note_number:
          type: string
          description: Dispatch advice no
          maxLength: 255
          nullable: true
          example: '123'
        file_reference:
          type: string
          description: |
            Project Reference
            [FacturaE Only]
          maxLength: 255
          nullable: true
          example: BE-123
        file_date:
          type: string
          format: date
          description: |
            Date of file
            [Facturae Only] Tag: FileDATE
          nullable: true
          example: '2024-09-12'
        invoicing_period_start:
          type: string
          format: date
          description: |
            Invoice line period start date. The date when the Invoice period for this Invoice line starts.

            ID: `BT-134`
          maxLength: 255
          example: '2017-10-10'
          nullable: true
        invoicing_period_end:
          type: string
          format: date
          description: |
            Invoice line period end date. The date when the Invoice period for this Invoice line ends.

            ID: `BT-135`
          maxLength: 255
          example: '2017-10-15'
          nullable: true
        issuer_transaction_reference:
          type: string
          description: Receiving advice
          maxLength: 255
          nullable: true
          example: '123'
        issuer_transaction_date:
          type: string
          format: date
          description: |
            Date of issuer's operation
            [Facturae Only] Tag: IssuerTransactionDate
          nullable: true
          example: '2024-09-12'
        notes:
          type: string
          description: |
            A description for an item.

            ID: `BT-154`
          maxLength: 65535
          example: Long description of the item on the invoice line
          nullable: true
        ponumber:
          type: string
          description: |
            Purchase Order Number. An identifier for an object on which the invoice line is based, given by the Seller.


            ID: `BT-128`
          maxLength: 255
          example: PO123
          nullable: true
        receiver_transaction_date:
          type: string
          format: date
          description: |
            Date of recipient's operation
            [FacturaE Only]
          nullable: true
          example: '2024-09-12'
        receiver_contract_reference:
          type: string
          description: Assignment code
          maxLength: 255
          example: reference_123
          nullable: true
        receiver_contract_date:
          type: string
          format: date
          description: |
            Date of the recipient's contract
            [FacturaE Only]
          nullable: true
          example: '2024-09-12'
        sequence_number:
          type: string
          description: |
            Sequence number. An identifier for a referenced line within a purchase order, issued by the Buyer.

            ID: `BT-132`
          example: '3'
          nullable: true
        contact_reference:
          type: string
          description: |
            Accounting Cost

            ID: `BT-133`
          example: '3'
          nullable: true
          writeOnly: true
        receipt_reference:
          type: object
          description: The information about the referenced Receipt. Used only in FatturaPA exportation.
          properties:
            identifier:
              type: string
              description: The alphanumeric identifier of the receipt (or of the RT/server RT).
              nullable: true
              example: '123456'
            number:
              type: integer
              description: The progressive number of the receipt (or of the receipt or of the commercial commercial document).
              nullable: true
              example: 123
            date:
              type: string
              format: date
              description: The date of the receipt.
              nullable: true
              example: '2024-09-12'
        additional_item_properties_attributes:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalItemProperty'
          writeOnly: true
        additional_item_properties:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalItemProperty'
          readOnly: true
    PaymentDues:
      type: object
      description: Represents a payment due as an object
      properties:
        due_date:
          type: string
          format: date
          example: '2024-09-12'
        amount:
          type: number
          example: 10
    InvoiceReference:
      type: object
      description: |
        A reference to another invoice. Used for:
        - **amend**: corrective invoices referencing the original invoice (max 1 per invoice)
        - **prepayment**: settlement invoices (ROZ) referencing advance payment invoices (ZAL)
      required:
        - reference_type
      properties:
        id:
          type: integer
          description: Unique identifier of the invoice reference.
          readOnly: true
        reference_type:
          type: string
          enum:
            - amend
            - prepayment
          description: |
            Type of reference:
            - `amend` — this invoice corrects the referenced invoice. Only one amend reference per invoice.
            - `prepayment` — this invoice settles a prior advance payment invoice. Multiple allowed.
        referenced_invoice_id:
          type: integer
          description: |
            Identifier of the referenced invoice within B2BRouter.
            `null` when the reference points to an invoice not held in B2BRouter
            (e.g. an amend identified only by external number/series/date).
          readOnly: true
          nullable: true
        number:
          type: string
          description: |
            Invoice number of the referenced invoice.
            Auto-populated from referenced_invoice_id if provided.
          maxLength: 60
          nullable: true
          example: FZ2026/02/150
        series_code:
          type: string
          description: Series code of the referenced invoice.
          maxLength: 150
          nullable: true
        date:
          type: string
          format: date
          description: Issue date of the referenced invoice.
          nullable: true
          example: '2026-02-15'
        reason:
          type: string
          description: |
            Reason for the correction (amend references only).
            For Facturae: amend reason code (01-85).
          maxLength: 130
          nullable: true
        tax_correction_code:
          type: string
          description: |
            Tax correction type code (amend references only).
            For KSeF: TypKorekty (1=effect on original date, 2=effect on corrective date, 3=different date).
          maxLength: 10
          nullable: true
          example: '1'
        tax_registration_code:
          type: string
          description: |
            Tax authority registration code of the referenced invoice.
            For KSeF: the NrKSeF number (e.g. `9999999999-20260215-8BEF280C8D35-4D`).
          maxLength: 100
          nullable: true
          example: 9999999999-20260215-8BEF280C8D35-4D
        correction_method:
          type: string
          description: |
            Correction method (amend references only).
            For Facturae: 01=full replacement, 02=differences, 03=bulk deal, 04=authorized by tax agency.
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
          nullable: true
        total_amount:
          type: number
          format: float
          description: |
            Total amount of the referenced invoice.
            For KOR_ZAL: this is P_15ZK (the P_15 value of the corrected ZAL invoice).
            Auto-populated from the referenced invoice total when referenced_invoice_id is provided.
          nullable: true
          example: 20000
        currency:
          type: string
          description: Currency of the total_amount (ISO 4217).
          maxLength: 3
          nullable: true
          example: PLN
        _destroy:
          type: boolean
          description: Set to true to delete this reference on update.
          writeOnly: true
    AllowanceCharge:
      allOf:
        - $ref: '#/components/schemas/AllowanceChargeBase'
        - type: object
          description: Represents an allowance (discount) or charge on an invoice or invoice line
          properties:
            apply_taxes:
              type: boolean
              description: |
                Indicates whether taxes should be applied to this allowance or charge.
                Defaults to `true` for allowances. For charges, defaults to `true` if the company has the "apply taxes to charge" setting enabled, `false` otherwise.
            tax_attributes:
              allOf:
                - $ref: '#/components/schemas/Tax'
              description: |
                Tax to be applied to this allowance or charge.
                Only applicable when apply_taxes is true.
                If not specified and apply_taxes is true, will inherit from invoice taxes.
              writeOnly: true
            tax:
              allOf:
                - $ref: '#/components/schemas/Tax'
              description: |
                The tax applied to this allowance or charge.
                Only present when apply_taxes is true.
              readOnly: true
    InvoiceAllowanceCharge:
      allOf:
        - $ref: '#/components/schemas/AllowanceCharge'
        - type: object
          description: Invoice-level allowance charge that supports tax configuration
    Invoice:
      type: object
      description: Represents an invoice as an object
      properties:
        id:
          type: integer
          example: 4053100
          description: |
            A unique internal identifier of the Invoice in B2Brouter.
          readOnly: true
        type:
          type: string
          description: Invoice type
          example: IssuedInvoice
          enum:
            - IssuedInvoice
            - ReceivedInvoice
            - IssuedSelfInvoice
            - IssuedSimplifiedInvoice
          default: IssuedInvoice
        number:
          type: string
          example: '3'
          description: |
            A unique identification of the Invoice.

            ID: `BT-1`
          maxLength: 100
        series_code:
          type: string
          example: S01
          nullable: true
          description: |
            The series code of the Invoice.
        to_net:
          type: string
          readOnly: true
          nullable: true
          example: '123'
        to_net_id:
          type: string
          readOnly: true
          nullable: true
          example: '123'
        from_net:
          type: string
          readOnly: true
          nullable: true
          example: '123'
        from_net_id:
          type: string
          readOnly: true
          nullable: true
          example: '123'
        account:
          type: object
          properties:
            id:
              type: integer
              example: 742
              description: Account ID
            name:
              type: string
              example: Project Trading Name
              description: Account Name
          readOnly: true
        company:
          type: object
          properties:
            id:
              type: integer
              example: 742
              description: Unique identifier for the company.
            name:
              type: string
              example: Company Trading Name
              description: |
                A name by which the Seller/Buyer is known, other than Seller/Buyer name (also known as Business name).

                ID: `BT-27` and `BT-28` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-44` and `BT-45` if the company is the Buyer Party (in case to be a ReceivedInvoice).
            tin_value:
              type: string
              description: |
                VAT identifier
                ID: `BT-31` if the company is the Seller Party (in case to be a IssuedInvoice). ID: `BT-48` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              maxLength: 255
              example: ESA13585625
            tin_scheme:
              type: string
              description: |
                The scheme identifier of VAT Number
                You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
              example: '9920'
              nullable: true
            address:
              type: string
              description: |
                The main address line in an address.

                ID: `BT-35` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-50` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              example: Main Street 1
              nullable: true
            address2:
              type: string
              description: |
                An additional address line in an address that can be used to give further details supplementing the main line.

                ID: `BT-36` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-51` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              example: Po Box 351
              nullable: true
            postalcode:
              type: string
              description: |
                The identifier for an addressable group of properties according to the relevant postal service.

                ID: `BT-38` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-53` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              example: 34567
              nullable: true
            city:
              type: string
              description: |
                The common name of the city, town or village,where the Seller/Buyer address is located.

                ID: `BT-37` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-52` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              example: Stockholm
              nullable: true
            province:
              type: string
              description: |
                The  subdivision  of  a  country. Such as a region, a county, a state, a province, etc.

                ID: `BT-39` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-54` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              example: Region A
              nullable: true
            country:
              type: string
              description: |
                A code that identifies the country.

                ID: `BT-40` if the company is the Seller Party (in case to be a IssuedInvoice).
                ID: `BT-55` if the company is the Buyer Party (in case to be a ReceivedInvoice).
              example: se
              nullable: true
          readOnly: true
        contact_id:
          type: integer
          description: |
            If the customer exists on B2Brouter and you know its ID, you can
            pass it, inside invoice hash, with contact_id. If it does not exist
            or you don’t know its ID, you can pass a hash with contact
            attributes, inside the invoice hash.

            Ignored for `IssuedSimplifiedInvoice`. Use the contact hash to set buyer data
          writeOnly: true
          example: 123
        contact:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/InvoiceContactHash'
        state:
          allOf:
            - $ref: '#/components/schemas/StateOutput'
          readOnly: true
        refuse_reason:
          type: string
          example: Incorrect invoice amount
          description: The reason provided for refusing the invoice.
          readOnly: true
          nullable: true
        date:
          type: string
          format: date
          description: |
            The date when the Invoice was issued.

            ID: `BT-2`
          example: '2020-11-12'
        due_date:
          type: string
          format: date
          description: |
            The date when the payment is due.

            ID: `BT-9`
          example: '2021-01-04'
          nullable: true
        tax_point_date:
          type: string
          format: date
          description: |
            The date when the VAT becomes accountable for the Seller and for the Buyer in so far as that date can be
            determined and differs from the date of issue of the invoice, according to the VAT directive.
            This element is required if the Value added tax point date is different from the Invoice issue date.

            ID: `BT-7`
          example: '2022-02-01'
          nullable: true
        invoicing_period_start:
          type: string
          format: date
          description: |
            The date when the invoice period starts.

            ID: `BT-73`
          example: '2024-07-07'
          nullable: true
        invoicing_period_end:
          type: string
          format: date
          description: |
            The date when the invoice period ends.

            ID: `BT-74`
          example: '2024-07-07'
          nullable: true
        buyer_reference:
          type: string
          maxLength: 255
          description: |
            An identifier assigned by the Buyer used for internal routing purposes.

            ID: `BT-10`
          example: '321654'
          nullable: true
        file_reference:
          type: string
          description: |
            The identification of the project the invoice refers to.

            ID: `BT-11`
          maxLength: 255
          example: PID33
          nullable: true
        ponumber:
          type: string
          maxLength: 255
          description: |
            Purchase order reference. An identifier of a referenced purchase order, issued by the Buyer.

            ID: `BT-13`
          nullable: true
          example: '123'
        order_date:
          type: string
          format: date
          description: |
            Purchase order date.
          nullable: true
          example: '2026-01-15'
        sales_order_reference:
          type: string
          maxLength: 255
          description: |
            An identifier of a referenced sales order, issued by the Seller.

            ID: `BT-14`
          example: '123'
          nullable: true
        receiving_advice_reference:
          type: string
          maxLength: 255
          description: |
            An identifier of a referenced receiving advice.

            ID: `BT-15`
          example: '123'
          nullable: true
        lot_reference:
          type: string
          maxLength: 255
          description: |
            Tender or Lot number. The identification of the call for tender or lot
            the invoice relates to.


            ID: `BT-17`
          example: '321654'
          nullable: true
        contract_number:
          type: string
          maxLength: 255
          description: |
            Contract reference. The identification of a contract.

            ID: `BT-12`
          example: 123Contractref
          nullable: true
        party_identification:
          type: string
          maxLength: 60
          description: |
            Seller identifier or bank assigned creditor identifier

            *This element is used for both the identification of the Seller, or the unique banking reference identifier of Seller (assigned by the Seller bank.). For seller identification use ICD code list, for SEPA bank assigned creditor reference, use SEPA. In order for the buyer to automatically identify a supplier, the Seller identifier (`BT-29`), the Seller legal registration identifier (`BT-30`) and/or the Seller VAT identifier (`BT-31`) shall be present*
          example: '506001234999'
          nullable: true
        delivery_note_number:
          type: string
          maxLength: 220
          description: |
            An identifier of a referenced despatch advice

            ID: `BT-16`
          example: '321654'
          nullable: true
        delivery_note_date:
          type: string
          format: date
          description: |
            Dispatch advice date
            [FacturaE and FatturaPA only]
          example: '2024-07-07'
          nullable: true
        buyer_accounting_reference:
          type: string
          description: |
            A textual value that specifies where to book the relevant data into the Buyer's financial accounts.

            ID: `BT-19`
          maxLength: 255
          nullable: true
        customer_contact_person:
          type: string
          maxLength: 170
          description: Overwrites the existing contact of the client
          example: John Doe
          nullable: true
        language:
          type: string
          maxLength: 2
          description: |
            Contact language. It should be a language available inside B2Brouter.
            You can check all available languages using the **Languages** endpoint in Code lists section (`/languages`)
          enum:
            - en
            - es
            - ca
            - fr
            - it
            - de
            - pt
            - nl
            - pl
            - da
            - sv
            - ar
            - null
          example: en
          nullable: true
        is_credit_note:
          type: boolean
          description: |
            Marks this invoice as a credit note.  

            - Set to `true` if the invoice is meant to **refund** or **correct** a previously issued invoice in general cases.
            - **Do NOT use this field for Spanish "Factura Rectificativa"**. In Spain, credit adjustments must be created following local rules, using a standard invoice format with negative amounts if needed.
            - Set to `false` (or omit) for a standard invoice.

            **Amounts behavior:**
            - **Provide positive values** for line amounts, taxes, and totals.
            - The system will automatically treat these amounts as reducing the original invoice balance when `is_credit_note` is `true`.
            - Reference the original invoice being corrected using `invoice_references` with `reference_type: "amend"`.
          example: false
          default: false
        total_amount_due:
          type: number
          format: float
          writeOnly: true
          nullable: true
          description: |
            [KSeF only] The total amount due for the invoice (P_15 in FA(3) structure).

            **Required** for `ZAL` (advance payment) and `KOR_ZAL` (advance correction) invoices,
            where the invoice total cannot be derived from the invoice lines.

            - For `ZAL`: the advance payment amount.
            - For `KOR_ZAL`: the correction amount.

            Ignored for other invoice types (total is calculated from lines).
          example: 20000
        adjustment_in_cents:
          type: integer
          example: 2
          minimum: -99
          maximum: 99
          description: |
            The amount (in cents) to be added to the invoice total to round the amount to be paid.

            ID: `BT-114`
        subtotal:
          type: number
          format: float
          example: 363.5
          readOnly: true
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/Tax'
          readOnly: true
        total:
          type: number
          format: float
          example: 363.5
          readOnly: true
        currency:
          type: string
          example: EUR
          description: |
            The currency in which all Invoice amounts are given, except for the
            Total VAT amount in accounting currency.


            ID: `BT-5`
          maxLength: 3
        tax_currency_code:
          type: string
          description: |
            The currency used for VAT accounting and reporting purposes as accepted or required in the country of the Seller.
            Shall be used in combination with `tax_amount_in_tax_currency` when the VAT accounting currency differs from the Invoice currency.

            ID: `BT-6`
          maxLength: 3
          nullable: true
          example: PLN
        tax_amount_in_tax_currency:
          type: number
          format: decimal
          description: |
            The VAT total amount expressed in the accounting currency accepted or required in the country of the Seller.
            To be used when the VAT accounting currency (`tax_currency_code`) differs from the Invoice currency (`currency`).

            ID: `BT-111`
          nullable: true
          readOnly: true
          example: 276.23
        exchange_rate:
          type: number
          format: decimal
          nullable: true
          description: |
            Exchange rate used for currency conversion when the invoice currency
            differs from the tax authority's local currency.
            When not provided, the system fetches the rate automatically.
          example: 4.5123
        exchange_date:
          type: string
          format: date
          nullable: true
          description: Date of the exchange rate used for currency conversion.
          example: '2025-04-10'
        amounts_withheld_reason:
          type: string
          maxLength: 255
          description: Withheld reason
          nullable: true
          example: Withheld
        withheld_percent:
          type: number
          nullable: true
          format: decimal
          description: Withheld percent
          example: 10
        amounts_withheld:
          type: number
          description: Withheld amount
          example: 36.35
        payable_amount:
          type: number
          format: float
          description: |
            The outstanding amount that is requested to be paid.

            ID: `BT-115`
          example: 327.15
          readOnly: true
        payments_on_account:
          type: number
          format: float
          description: |
            Total Prepaid Amount

            ID: `BT-113`
          example: 327.15
        payment_method:
          $ref: '#/components/schemas/PaymentMethodCode'
        payment_method_text:
          type: string
          maxLength: 255
          description: |
            The means, expressed as text, by which a payment is expected to be or has been made. This field is used when the invoice payment method is `13` - Other (UBL: ZZZ).

            ID: `BT-82`
          example: Bank transfer
          nullable: true
        payment_terms:
          type: string
          maxLength: 65535
          description: |
            Payment terms. A textual description of the payment terms that apply
            to the amount due for payment (Including description of possible
            penalties).


            ID: `BT-20`
          example: Payment terms
          nullable: true
        bank_assigned_creditor_reference:
          type: string
          description: |
            Bank assigned creditor reference

            ID: `BT-90`
          maxLength: 255
          example: ES6000000000000000000000
          nullable: true
        remittance_information:
          type: string
          maxLength: 180
          description: |
            Remittance information. A textual value used to establish a link
            between the payment and the Invoice, issued by the Seller.


            ID: `BT-83`
          example: Remittance information
          nullable: true
        mandate_reference_identifier:
          type: string
          maxLength: 110
          description: |
            Mandate reference identifier. Unique identifier assigned by the Payee for referencing the direct debit mandate.

            ID: `BT-89`
          example: '321654'
          nullable: true
        bank_account_id:
          type: integer
          description: |
            Unique identifier for an existing bank account in B2Brouter.
            Use this field to reference an existing bank account. To create a new account, use `bank_account` instead.
          example: 402
          writeOnly: true
        bank_account:
          description: |
            Represents a bank account as an object.
            Use this field to create a new bank account.
          type: object
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/BankAccountCommon'
        contact_iban:
          type: string
          description: The IBAN associated with a received invoice.<br>This field is only applicable for received invoices and should be ignored for other invoice types.
          example: ES6000000000000000000000
          nullable: true
        contact_bic:
          type: string
          description: The BIC associated with a received invoice.<br>This field is only applicable for received invoices and should be ignored for other invoice types.
          example: '123'
          nullable: true
        contact_payment_account_name:
          type: string
          description: The payment account name associated with a received invoice.<br>This field is only applicable for received invoices and should be ignored for other invoice types.
          example: BANK NAME
          nullable: true
        card_account_attributes:
          description: |
            Represents the card account of the customer party.
            Use this field to create the card account for this invoice.
          type: object
          allOf:
            - $ref: '#/components/schemas/CardAccountCommon'
            - type: object
              required:
                - account_number
          writeOnly: true
        card_account:
          description: |
            Represents the card account of the customer party.
            Read-only representation returned in responses; use `card_account_attributes` to set it.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CardAccountCommon'
          readOnly: true
        reminder_for_payment:
          type: boolean
          description: Send expiration reminder to customer
          writeOnly: true
          nullable: true
        payment_reminder_days:
          type: integer
          description: payment_reminder_days
          writeOnly: true
          example: 15
        terms:
          type: string
          default: custom
          enum:
            - custom
            - '0'
            - '15'
            - '30'
            - '60'
            - '90'
            - '120'
            - 0m-1
            - 1m-1
            - 1m1
            - 2m1
            - 1m15
            - 1m20
            - 1m10
          description: |
            Term
            * `custom` - Custom
            * `0` - Upon Receipt
            * `15` - 15 days
            * `30` - 30 days
            * `60` - 60 days
            * `90` - 90 days
            * `120` - 120 days
            * `0m-1` - Last day this month
            * `1m-1` - Last day next month
            * `1m1` - 1st day next month
            * `2m1` - 1st day in two months
            * `1m15` - 15th day next month
            * `1m20` - 20th day next month
            * `1m10` - 10th day next month
          nullable: true
          example: 1m1
          writeOnly: true
        extra_info:
          type: string
          maxLength: 65535
          description: |
            A textual note that gives unstructured information that is relevant to the Invoice as a whole.

            ID: `BT-22`
          nullable: true
          example: Some extra info
        tax_report_ids:
          type: array
          description: An array containing the internal IDs of the associated Tax Reports.
          readOnly: true
          items:
            type: integer
        legal_literals:
          type: string
          maxLength: 255
          description: Certification
          example: Legal literals
          nullable: true
        delivery_party_name:
          type: string
          example: Delivery party name
          description: |
            The name of the party to which the goods and services are delivered.

            ID: `BT-70`
          maxLength: 255
          nullable: true
        delivery_location_id:
          type: string
          maxLength: 90
          description: |
            An identifier for the location at which the goods and services are delivered.

            ID: `BT-71`
          example: 83745498753497
          nullable: true
        delivery_location_type:
          type: string
          maxLength: 20
          description: |
            The identification scheme identifier of the Deliver to location identifier.

            ID: `BT-71` (attribute @schemeID)
          example: 88
          nullable: true
        delivery_date:
          type: string
          format: date
          description: |
            The date on which the supply of goods or services was made or completed.

            ID: `BT-72`
          example: '2024-07-07'
          nullable: true
        delivery_address:
          type: string
          maxLength: 160
          description: |
            Deliver to address. The main address line in an address.

            ID: `BT-75`
          example: Invented address, 1
          nullable: true
        delivery_address2:
          type: string
          maxLength: 160
          description: |
            Deliver to addresss line 2. An additional address line in an address that can be used to give further details supplmenting the main line.

            ID: `BT-76`
          example: Invented address, 2
          nullable: true
        delivery_postalcode:
          type: string
          maxLength: 60
          description: |
            The identifier for an addressable group of preperties according to the relevant postal service.

            ID: `BT-78`
          example: '80808'
          nullable: true
        delivery_city:
          type: string
          maxLength: 50
          description: |
            Deliver to city, The common name of the city, town or village, where the deliver to address is located.

            ID: `BT-77`
          example: Barcelona
          nullable: true
        delivery_province:
          type: string
          maxLength: 60
          description: |
            Deliver to country subdivision. The subdivision of a country. Such as a region, a county, a state, a province, etc.

            ID: `BT-79`
          example: Barcelona
          nullable: true
        delivery_country:
          type: string
          maxLength: 2
          description: |
            Deliver to country code. A code that identifies the country.

            ID: `BT-80`
          example: ES
          nullable: true
        download_legal_url:
          type: string
          description: The attachment of the original invoice if sent.
          readOnly: true
          nullable: true
          example: http://example.com
        public_url:
          type: string
          description: |
            The public page of the B2Brouter invoice, visible to the contact if the invoice status allows it.
            For example, a new invoice does not have a public URL, but a sent invoice does.
          readOnly: true
          nullable: true
          example: http://example.com
        apply_to_local_government_unit:
          type: boolean
          description: |
            KSeF: Indicates this invoice is addressed to a Subordinate Local Government Unit (JST).
            When true, a `third_party` with a `tin_value` is required.
            Not included in responses by default. Use `?include=apply_to_local_government_unit` to include it.
          default: false
          nullable: true
        apply_to_vat_group_member:
          type: boolean
          description: |
            KSeF: Indicates this invoice is addressed to a VAT Group member (GV).
            When true, a `third_party` with a `tin_value` is required.
            Not included in responses by default. Use `?include=apply_to_vat_group_member` to include it.
          default: false
          nullable: true
        third_party:
          type: object
          nullable: true
          description: |
            The third party (KSeF Podmiot3) associated with this invoice.
            Required when `apply_to_local_government_unit` or `apply_to_vat_group_member` is true.
            Not included in responses by default. Use `?include=third_party` to include it.
          properties:
            id:
              type: integer
              description: Party identifier. Required when using `_destroy`.
              readOnly: false
            _destroy:
              type: boolean
              description: Set to true to remove the third party from the invoice.
              writeOnly: true
            role:
              type: string
              description: |
                The role of the third party. See KSeF Podmiot3 role codes.
              enum:
                - delivery_recipient
                - original_supplier
                - additional_buyer
                - invoice_issuer
                - payer
                - local_government_unit_issuer
                - local_government_unit_recipient
                - vat_group_member_issuer
                - vat_group_member_recipient
                - employee
              example: local_government_unit_recipient
            name:
              type: string
              maxLength: 255
              description: Name of the third party
              example: Szkoła Podstawowa nr 7
            tin_value:
              type: string
              maxLength: 255
              description: VAT identifier of the third party
              example: PL7654321098
              nullable: true
            tin_scheme:
              type: string
              description: The scheme identifier of the third party's VAT Number
              example: '9945'
              nullable: true
            cin_value:
              type: string
              maxLength: 255
              description: Company identifier of the third party
              nullable: true
            cin_scheme:
              type: string
              description: The scheme identifier of the third party's company identifier
              nullable: true
            address:
              type: string
              maxLength: 255
              description: Address of the third party
              example: ul. Szkolna 12
              nullable: true
            address2:
              type: string
              maxLength: 255
              description: Additional address line
              nullable: true
            city:
              type: string
              maxLength: 255
              description: City
              example: Kraków
              nullable: true
            postalcode:
              type: string
              maxLength: 255
              description: Postal code
              example: 30-010
              nullable: true
            province:
              type: string
              maxLength: 255
              description: Province/Region
              nullable: true
            country:
              type: string
              maxLength: 2
              description: Country code
              example: pl
              nullable: true
        created_at:
          type: string
          format: date-time
          description: Date and time when the invoice was created.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: Date and time when the invoice was last updated.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
        state_updated_at:
          type: string
          format: date-time
          example: '2020-07-06T09:36:18Z'
          description: Date and time when the invoice state last changed.
          readOnly: true
          nullable: true
        ack_at:
          type: string
          format: date-time
          example: '2020-07-06T09:36:18Z'
          description: Date and time when the invoice was acknowledged
          readOnly: true
          nullable: true
        invoice_lines_attributes:
          type: array
          description: |
            A group of business terms providing information on individual invoice
            lines.


            ID: `BG-25`
          items:
            $ref: '#/components/schemas/InvoiceLine'
          writeOnly: true
          minItems: 1
        lines:
          type: array
          description: |
            A group of business terms providing information on individual invoice
            lines.
            Only shown if the query parameter "include" is "lines" or "detailed_lines".

            ID: `BG-25`
          items:
            $ref: '#/components/schemas/InvoiceLine'
          readOnly: true
          nullable: true
        payment_dues_attributes:
          type: array
          items:
            $ref: '#/components/schemas/PaymentDues'
          writeOnly: true
        payment_dues:
          type: array
          description: Represents a payment due as an object
          items:
            $ref: '#/components/schemas/PaymentDues'
          readOnly: true
        invoice_references:
          type: array
          description: |
            References to other invoices. Replaces the deprecated flat fields
            `amended_number`, `amended_series_code`, `amended_date`, `amend_reason`, `correction_method`.

            - `reference_type: "amend"` — corrective invoices referencing the original (max 1 per invoice).
            - `reference_type: "prepayment"` — settlement invoices (ROZ) referencing advance payments (ZAL). Multiple allowed.
          items:
            $ref: '#/components/schemas/InvoiceReference'
        type_code:
          type: string
          description: |
            Value for mapping FatturaPA-specific values to the SDI document types.
            Explanation of each value:
            - TD01: Invoice (Fattura)
            - TD02: Advance payment on invoice (Acconto/Anticipo su fattura)
            - TD03: Advance payment on proforma invoice (Acconto/Anticipo su parcella)
            - TD04: Credit note (Nota di credito)
            - TD05: Debit note (Nota di debito)
            - TD06: Proforma invoice (Parcella)
            - TD16: Local reverse charge (Integrazione per acquisti interni)
            - TD17: Self invoice for EU services (Integrazione o autofattura per acquisti di servizi da soggetto non residente ai sensi dell’articolo 17, comma 2, DPR 633/1972)
            - TD18: EU acquisition reverse charge (Integrazione della fattura del fornitore UE per acquisto intracomunitario di beni)
            - TD19: Not resident acquisition reverse charge (Integrazione o autofattura per acquisti di beni da soggetti non residenti ai sensi dell’articolo 17, comma 2, DPR 633/1972)
            - TD20: Self invoice (Autofattura per regolarizzazione e integrazione delle fatture)
            - TD21: Regulated plafond self invoice (In caso di emissione di autofattura per regolarizzazione dello splafonamento)
            - TD22: VAT deposit (In caso di estrazione beni da Deposito IVA)
            - TD23: VAT deposit with VAT payment (In caso di estrazione beni da Deposito IVA con versamento dell’IVA) 
            - TD24: Deferred invoice with DDT (Fattura differita – art 21, 4 comma, lett. a), del DPR 633/72, quindi fattura differita di beni e servizi collegata a DDT per i beni o da idonea documentazione di prova dell’effettuazione per le prestazioni di servizio)
            - TD25: Deferred invoice for internal triangular operations (Fattura differita di cui all’art. 21, 4 comma, lett. b), del DPR 633/72, quindi fattura differita per operazioni triangolari interne)
            - TD26: Sales of assets (Per la cessione di beni ammortizzabili e per passaggi interni)
            - TD27: Free of charge or self-consumption (In caso di fatture per auto consumo o per cessioni gratuite senza rivalsa)

            Refer to documentation for details: [Italian type document codes](https://developer.b2brouter.net/v2025-01-01/docs/italian_type_document_codes)

            Value for mapping UBL/CII specific values for InvoiceTypeCode / TypeCode
            Refer to documentation for details: [Peppol CII type document codes](https://developer.b2brouter.net/v2025-01-01/docs/peppol_cii_type_document_codes)

            ID: `BT-3`
          enum:
            - TD01
            - TD02
            - TD03
            - TD04
            - TD05
            - TD06
            - TD16
            - TD17
            - TD18
            - TD19
            - TD20
            - TD21
            - TD22
            - TD23
            - TD24
            - TD25
            - TD26
            - TD27
            - 71
            - 80
            - 81
            - 82
            - 83
            - 84
            - 102
            - 218
            - 219
            - 261
            - 326
            - 331
            - 380
            - 381
            - 382
            - 383
            - 384
            - 386
            - 388
            - 389
            - 393
            - 395
            - 396
            - 527
            - 532
            - 553
            - 575
            - 623
            - 780
            - 817
            - 870
            - 875
            - 876
            - 877
            - VAT
            - KOR
            - ZAL
            - ROZ
            - UPR
            - KOR_ZAL
            - KOR_ROZ
            - null
          nullable: true
        tax_report_description:
          type: string
          maxLength: 255
          description: Description of the tax report. Sent to the tax authority.
          example: Tax report for Invoice 1
          writeOnly: true
        allowance_charges_attributes:
          type: array
          description: |
            Invoice-level allowances (discounts) and charges.

            Supports multiple allowances and charges with individual tax settings.
            Replaces the legacy single discount/charge fields.

            ID: `BG-20`, `BG-21`
          items:
            $ref: '#/components/schemas/InvoiceAllowanceCharge'
          writeOnly: true
        allowance_charges:
          type: array
          description: |
            Invoice-level allowances (discounts) and charges.
            Only shown if the query parameter "include" contains "allowance_charges".

            ID: `BG-20`, `BG-21`
          items:
            $ref: '#/components/schemas/InvoiceAllowanceCharge'
          readOnly: true
          nullable: true
        contact_email_override:
          type: string
          maxLength: 200
          description: List of destination emails, separated by commas.
          writeOnly: true
          example: john_doe@example.net, jane_doe@example.net
        company_email_override:
          type: string
          maxLength: 200
          description: Your email
          writeOnly: true
          example: john_doe_override@example.net
        receiver_contract_reference:
          type: string
          maxLength: 255
          description: Assignment code
          writeOnly: true
          example: '123'
        dire:
          type: string
          maxLength: 16
          description: Receiver code (DIRe)
          writeOnly: true
          example: ES12345678
        fa_address:
          type: string
          maxLength: 160
          description: Factoring assignment - Address
          writeOnly: true
          example: Invented address, 1
        fa_bank_code:
          type: string
          maxLength: 30
          description: Factoring assignment - Bank code
          writeOnly: true
          example: ES6000000000000000000000
        fa_bic:
          type: string
          description: Factoring assignment - BIC
          writeOnly: true
          example: '123'
        fa_clauses:
          type: string
          maxLength: 65535
          description: Factoring assignment - Assignment clause
          writeOnly: true
          example: Clauses
        fa_country:
          type: string
          maxLength: 2
          description: Factoring assignment - Country
          writeOnly: true
          example: ES
        fa_duedate:
          type: string
          format: date
          description: Factoring assignment - Due date
          writeOnly: true
          example: '2024-09-12'
        fa_iban:
          type: string
          maxLength: 40
          description: Factoring assignment - IBAN
          writeOnly: true
          example: ES6000000000000000000000
        fa_import:
          type: number
          format: float
          description: Factoring assignment - Amount
          writeOnly: true
          example: 100
        fa_info:
          type: string
          maxLength: 70
          description: Factoring assignment - Information
          writeOnly: true
          example: Information
        fa_name:
          type: string
          maxLength: 60
          description: Factoring assignment - Name
          writeOnly: true
          example: Name
        fa_payment_method:
          type: string
          maxLength: 2
          description: Factoring assignment - Payment method
          writeOnly: true
          example: '2'
        fa_person_type:
          type: string
          maxLength: 1
          description: Factoring assignment - Entity type
          writeOnly: true
          example: J
        fa_postcode:
          type: string
          maxLength: 10
          description: Factoring assignment - Postcode
          writeOnly: true
          example: '80808'
        fa_province:
          type: string
          maxLength: 60
          description: Factoring assignment - Province
          writeOnly: true
          example: Barcelona
        fa_residence_type:
          type: string
          maxLength: 1
          description: Factoring assignment - Residence type
          writeOnly: true
        fa_taxcode:
          type: string
          maxLength: 20
          description: Factoring assignment - VAT ID number
          writeOnly: true
          example: ES12345678
        fa_town:
          type: string
          maxLength: 50
          description: Factoring assignment - City
          writeOnly: true
          example: Barcelona
        accounting_unit:
          type: string
          maxLength: 16
          description: Accounting unit
          writeOnly: true
          example: ES00000000
        managing_unit:
          type: string
          maxLength: 16
          description: Managing unit
          writeOnly: true
          example: ES00000000
        proponent_unit:
          type: string
          maxLength: 16
          description: Proponent unit
          writeOnly: true
          example: ES00000000
        special_regime_key:
          type: string
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - '09'
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
            - '51'
            - '52'
            - '53'
          description: |
            Keys to the VAT regime and operations with tax significance
             * `01` - General Regime Operation
             * `02` - Export
             * `03` - Operations to which the special regime for used goods, objects of art, antiques and collectibles applies
             * `04` - Special investment gold regime
             * `05` - Special scheme for travel agents
             * `06` - Special regime group of entities in VAT
             * `07` - Special cash criterion regime
             * `08` -  Operations subject to the IPSI / IGIC
             * `09` - Invoicing of the provision of services of travel agencies that act as mediators on behalf of and on behalf of another
             * `10` - Collections on behalf of third parties of professional fees or rights derived from industrial property, copyright or others on behalf of its partners, associates or collegiate members made by companies, associations, professional associations or other entities that perform these collection functions.
             * `11` - Leasing operations of business premises subject to withholding
             * `12` - Business premises lease operations not subject to withholding
             * `13` - Leasing operations of business premises subject and not subject to withholding
             * `14` - Invoice with VAT pending accrual in work certifications whose recipient is a Public Administration
             * `15` - Invoice with VAT pending accrual in successive tract operations
             * `51` - Operations in equivalence surcharge
             * `52` - Operations in simplified regime
             * `53` - Operations carried out by persons or entities that are not considered businessmen, businesswomen or professionals for VAT purposes
          writeOnly: true
          example: '01'
        special_regime_key_additional:
          type: string
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - '09'
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
            - '51'
            - '52'
            - '53'
          description: |
            Keys to the VAT regime and operations with tax significance
             * `01` - General Regime Operation
             * `02` - Export
             * `03` - Operations to which the special regime for used goods, objects of art, antiques and collectibles applies
             * `04` - Special investment gold regime
             * `05` - Special scheme for travel agents
             * `06` - Special regime group of entities in VAT
             * `07` - Special cash criterion regime
             * `08` -  Operations subject to the IPSI / IGIC
             * `09` - Invoicing of the provision of services of travel agencies that act as mediators on behalf of and on behalf of another
             * `10` - Collections on behalf of third parties of professional fees or rights derived from industrial property, copyright or others on behalf of its partners, associates or collegiate members made by companies, associations, professional associations or other entities that perform these collection functions.
             * `11` - Leasing operations of business premises subject to withholding
             * `12` - Business premises lease operations not subject to withholding
             * `13` - Leasing operations of business premises subject and not subject to withholding
             * `14` - Invoice with VAT pending accrual in work certifications whose recipient is a Public Administration
             * `15` - Invoice with VAT pending accrual in successive tract operations
             * `51` - Operations in equivalence surcharge
             * `52` - Operations in simplified regime
             * `53` - Operations carried out by persons or entities that are not considered businessmen, businesswomen or professionals for VAT purposes
          writeOnly: true
          example: '01'
        contract_unit:
          type: string
          maxLength: 110
          description: Contracting Unit / SEF
          writeOnly: true
          example: Contracting Unit
        processing_unit:
          type: string
          maxLength: 16
          description: Processing unit.
          writeOnly: true
          example: Processing Unit
        type_operation:
          type: string
          enum:
            - services
            - goods
          description: Type of operation (needed for tax reports)
          writeOnly: true
          example: services
        document_type_code:
          allOf:
            - $ref: '#/components/schemas/DocumentTypeCode'
            - description: |
                Code identifying the document format used to send the invoice.
                For received invoices, this corresponds to the format of the original document.
            - readOnly: true
    ProjectInInvoice:
      type: object
      description: Account object as it appears in invoice responses
      readOnly: true
      properties:
        id:
          type: integer
          example: 12345
          description: Account ID
        name:
          type: string
          example: My Company S.L.
          description: Account name
    CompanyInInvoice:
      type: object
      description: Company object as it appears in invoice responses
      readOnly: true
      properties:
        id:
          type: integer
          example: 12345
          description: Company ID
        name:
          type: string
          example: My Company S.L.
          description: Company name
        tin_value:
          type: string
          description: |
            VAT identifier
            ID: `BT-31` if the company is the Seller Party (in case to be a IssuedInvoice). ID: `BT-48` if the company is the Buyer Party (in case to be a ReceivedInvoice).
          maxLength: 255
          example: ESA13585625
        tin_scheme:
          allOf:
            - $ref: '#/components/schemas/SchemeCode'
          description: |
            The scheme identifier of VAT Number
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          example: 9920
        address:
          type: string
          example: Carrer Example 123
          description: Company address
          nullable: true
        address2:
          type: string
          example: Floor 2
          description: Company secondary address
          nullable: true
        postalcode:
          type: string
          example: 8001
          description: Company postal code
          nullable: true
        city:
          type: string
          example: Barcelona
          description: Company city
          nullable: true
        province:
          type: string
          example: Barcelona
          description: Company province
          nullable: true
        country:
          type: string
          example: es
          description: Company country
          nullable: true
    ContactInInvoice:
      type: object
      nullable: true
      description: Contact object as it appears in invoice responses
      readOnly: true
      properties:
        id:
          type: integer
          example: 133842
          description: Contact ID
          nullable: true
        name:
          type: string
          example: Client Name
          description: Contact name
        tin_value:
          type: string
          description: |
            The Buyer's VAT identifier (also known as Buyer VAT identification number).

            ID: `BT-48`
          maxLength: 255
          example: ESA13585625
          nullable: true
        tin_scheme:
          allOf:
            - $ref: '#/components/schemas/SchemeCode'
          description: |
            The scheme identifier of Company VAT Number
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          example: 9920
        address:
          type: string
          example: Carrer Example 123
          description: Contact address
          nullable: true
        address2:
          type: string
          example: Floor 2
          description: Contact secondary address
          nullable: true
        postalcode:
          type: string
          example: 8001
          description: Contact postal code
          nullable: true
        city:
          type: string
          example: Barcelona
          description: Contact city
          nullable: true
        province:
          type: string
          example: Barcelona
          description: Contact province
          nullable: true
        country:
          type: string
          example: es
          description: Contact country
          nullable: true
        email:
          type: string
          description: |
            An e-mail address for the contact point.

            ID: `BT-58`
          writeOnly: true
          example: example@email.com
          nullable: true
        pin_value:
          type: string
          description: |
            Peppol Identifier Number, identifies the Buyer's electronic address to which the invoice is delivered.

            ID: `BT-49`
          example: '987654321'
          nullable: true
        pin_scheme:
          allOf:
            - $ref: '#/components/schemas/SchemeCode'
          description: |
            The identification scheme identifier of the Buyer electronic address.

            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`). The value has to be in EAS code list
            https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/
          example: 192
        party_identification:
          type: string
          example: '506001234999'
          description: Party identification
          nullable: true
    InvoiceResponse:
      allOf:
        - $ref: '#/components/schemas/Invoice'
        - type: object
          description: Invoice object as returned by V2 API with nested objects
          properties:
            account:
              $ref: '#/components/schemas/ProjectInInvoice'
              nullable: true
              description: Associated account information
            company:
              $ref: '#/components/schemas/CompanyInInvoice'
              nullable: true
              description: Company information
            contact:
              $ref: '#/components/schemas/ContactInInvoice'
              nullable: true
              description: Contact information
            error_message:
              type: string
              readOnly: true
              nullable: true
              description: Error message if invoice is in error state
              example: Connection timeout to network provider
            cancellation_state:
              type: string
              readOnly: true
              nullable: true
              description: Cancellation state for cancelled invoices
    CardAccountUpdate:
      allOf:
        - $ref: '#/components/schemas/CardAccountCommon'
        - type: object
          properties:
            id:
              type: integer
              description: A unique identifier for this CardAccount across all the system.
              readOnly: false
            _destroy:
              type: integer
              description: |
                Deletes the card account of the invoice 
                To delete the card account, set this field to `1`. If set to `0` or null, no action is taken.
              example: 1
              nullable: true
              writeOnly: true
              enum:
                - 1
                - 0
    InvoiceUpdate:
      allOf:
        - $ref: '#/components/schemas/Invoice'
        - type: object
          properties:
            iban:
              writeOnly: false
              readOnly: true
            bic:
              writeOnly: false
              readOnly: true
            bank_account:
              readOnly: true
            card_account_attributes:
              description: |
                Represents the card account of the customer party.
                Use this field to update/create the card account for this invoice.
              type: object
              allOf:
                - $ref: '#/components/schemas/CardAccountUpdate'
            contact:
              readOnly: true
            invoice_lines_attributes:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/InvoiceLine'
                  - type: object
                    properties:
                      id:
                        type: integer
                        description: Unique identifier for the invoice line to update. Do not inform when creating a new line.
                        readOnly: false
                      _destroy:
                        type: integer
                        description: |
                          Marks an existing invoice line for deletion.
                          To delete a line, set this field to `1` and provide the `id` field. If the `id` field is missing or not provided, the deletion will not occur. If set to `0` or null, no action is taken.
                        example: 1
                        nullable: true
                        writeOnly: true
                        enum:
                          - 1
                          - 0
    InvoiceReduced:
      type: object
      description: Represents an invoice with reduced fields as an object
      properties:
        id:
          type: integer
          example: 4053100
          description: |
            A unique internal identifier of the Invoice in B2Brouter.
          readOnly: true
        type:
          type: string
          description: Invoice type
          example: IssuedInvoice
          enum:
            - IssuedInvoice
            - ReceivedInvoice
            - IssuedSelfInvoice
            - IssuedSimplifiedInvoice
          default: IssuedInvoice
        number:
          type: string
          example: '3'
          description: |
            A unique identification of the Invoice.

            ID: `BT-1`
          maxLength: 100
        file_reference:
          type: string
          description: |
            The identification of the project the invoice refers to.

            ID: `BT-11`
          maxLength: 255
          example: PID33
          nullable: true
        series_code:
          type: string
          example: S01
          nullable: true
          description: |
            The series code of the Invoice.
        date:
          type: string
          format: date
          description: |
            The date when the Invoice was issued.

            ID: `BT-2`
          example: '2020-11-12'
        due_date:
          type: string
          format: date
          description: |
            The date when the payment is due.

            ID: `BT-9`
          example: '2021-01-04'
          nullable: true
        contact:
          type: object
          nullable: true
          readOnly: true
          properties:
            id:
              type: integer
              example: 326116
              description: Contact ID
            name:
              type: string
              example: John Doe
              description: Name of the client or provider
            tin_value:
              type: string
              description: |
                The Buyer's VAT identifier (also known as Buyer VAT identification number).

                ID: `BT-48`
              maxLength: 255
              example: ESA13585625
              nullable: true
            tin_scheme:
              allOf:
                - $ref: '#/components/schemas/SchemeCode'
              description: |
                The scheme identifier of Company VAT Number
                You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
              example: 9920
        state:
          $ref: '#/components/schemas/StateOutput'
        total:
          type: number
          format: float
          example: 363.5
          readOnly: true
        currency:
          type: string
          example: EUR
          description: |
            "The currency in which all Invoice amounts are given, except for the Total VAT amount in accounting currency."

            ID: `BT-5`
          maxLength: 3
        created_at:
          type: string
          format: date-time
          description: Date and time when the invoice was created.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: Date and time when the invoice was last updated.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
        state_updated_at:
          type: string
          format: date-time
          example: '2020-07-06T09:36:18Z'
          description: Date and time when the invoice state last changed.
          readOnly: true
          nullable: true
        from_net_id:
          type: string
          readOnly: true
          nullable: true
          example: '123'
        from_net_meta:
          type: string
          readOnly: true
          nullable: true
          example: '123'
        to_net_id:
          type: string
          readOnly: true
          nullable: true
          example: '123'
    SendAfterImport:
      type: boolean
      default: false
      example: true
      enum:
        - true
        - false
      description: |
        Indicates whether the invoice should be automatically processed after creation/import.

        When set to `true` and the invoice passes validations:
          * For sending transports (non-`download`), the invoice is queued to be sent asynchronously.
          * For `download` transport, the invoice is not sent. Instead, if tax report generation is enabled and required for this invoice, the invoice will be issued and the tax report generated 
            (invoice ends in `state=issued` and exposes `tax_report_ids`). Otherwise, the invoice may end in `state=error`.

        **Note:** This option is incompatible with the custom signature configuration.
    Ack:
      type: boolean
      default: false
      description: Mark the invoice as acknowledged.
    Payment:
      type: object
      description: A payment recorded on an invoice. Payments can be total or partial; an invoice may accumulate several. When the recorded payments cover the invoice total, the invoice automatically transitions to `paid`, whatever its current state. On accounts with an active payment-reporting tax authority (e.g. DGFiP), recording a payment automatically triggers the corresponding fiscal report.
      properties:
        id:
          type: integer
          readOnly: true
          example: 981
        invoice_id:
          type: integer
          description: The invoice this payment belongs to. Required when recording a payment; the invoice must belong to the account of the request path.
          example: 12345
        amount:
          type: number
          format: double
          description: Total amount of the payment, taxes included, in the invoice currency. Must be greater than zero. Amounts above the outstanding amount are accepted.
          example: 150.5
        currency:
          type: string
          readOnly: true
          description: ISO 4217 code, inherited from the invoice.
          example: EUR
        date:
          type: string
          format: date
          description: Date of the payment. Defaults to the current date when omitted. Send the real payment date when recording payments after the fact.
          example: '2026-07-01'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodCode'
        payment_method_text:
          type: string
          maxLength: 255
          nullable: true
          description: The means, expressed as free text, by which the payment was settled (e.g. a card brand or a local payment scheme). Shown in listings and available for reconciliation.
          example: Bizum
        reference:
          type: string
          maxLength: 255
          nullable: true
          description: Free-text payment reference (e.g. bank remittance information).
          example: REF-2026-001
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    InvoiceImportBatch:
      type: object
      description: A bulk invoice import batch — the wrapper around a multi-file import request submitted via `POST /accounts/{account_id}/invoices/imports`.
      properties:
        batch_id:
          type: integer
          description: Unique identifier of the batch (a `BulkAction`).
          example: 42
        status:
          type: string
          description: |-
            Current processing status of the batch.
            - `processing`: at least one file is still being imported, or the job has
              not yet finished.
            - `done`: the job finished and every file reached a terminal state
              (`done`, `error`, or `done_with_error`).
            - `failed`: the job aborted before processing every file; some files may
              remain `unfinished`. Use the per-file `results[].status` to see which.

            Per-file outcomes live in `results[].status`.
          enum:
            - processing
            - done
            - failed
          example: done
        status_url:
          type: string
          description: Absolute URL of this batch's status endpoint (`GET /accounts/{account_id}/invoices/imports/{id}`). The same value is delivered in the `invoice_import.finished` webhook, so a subscriber can follow it without rebuilding the URL.
          example: https://api.b2brouter.net/accounts/99/invoices/imports/42
        summary:
          type: object
          description: 'Per-state counts partitioning the batch: mutually exclusive and exhaustive, so `done + done_with_error + error + unfinished == total`. Each count matches the number of `results[]` with that `status`.'
          properties:
            total:
              type: integer
              description: Total files in the batch.
              example: 3
            done:
              type: integer
              description: Files imported cleanly.
              example: 1
            done_with_error:
              type: integer
              description: Files imported, but with send-time validation warnings.
              example: 1
            error:
              type: integer
              description: Files that could not be imported (includes duplicate digests).
              example: 1
            unfinished:
              type: integer
              description: Files not yet processed. Always 0 once `status` is `done`; may be non-zero when `status` is `failed`.
              example: 0
          required:
            - total
            - done
            - done_with_error
            - error
            - unfinished
        results:
          type: array
          description: One entry per uploaded file, in the original upload order. Each result carries an explicit `index` so results can be correlated to the submitted files regardless of array handling.
          items:
            type: object
            properties:
              index:
                type: integer
                description: 'Zero-based position of the file in the original `files[]` upload. The reliable correlation key: it is always present, whereas `filename` is dropped once an item imports successfully.'
                example: 0
              filename:
                type: string
                nullable: true
                description: Original multipart filename. Available for items that have not yet been imported (status `unfinished`) or that errored. For items whose status is `done`/`done_with_error`, the `documentable` polymorphic association has been swapped to the resulting invoice and the filename is no longer accessible — clients correlate those by `index` or by the returned `invoice_id`.
                example: invoice1.xml
              status:
                type: string
                description: Per-file outcome.
                enum:
                  - unfinished
                  - done
                  - done_with_error
                  - error
                example: done
              invoice_id:
                type: integer
                nullable: true
                description: 'ID of the resulting Invoice when status is `done` or `done_with_error`. Also set for a duplicate (`status: error`, `error_message: duplicated_document`), pointing to the existing invoice that matched the digest.'
                example: 8675309
              error_message:
                type: string
                nullable: true
                description: Importer error message, populated when status is `error`.
                example: null
            required:
              - index
              - status
      required:
        - batch_id
        - status
        - status_url
        - summary
        - results
    StateInput:
      type: string
      example: refused
      writeOnly: true
      enum:
        - new
        - sent
        - downloaded
        - accepted
        - registered
        - refused
        - closed
        - paid
        - annotated
      description: |
        Valid states for an issued invoice:
         * `new` - The initial status of an issued invoice.
         * `sent` - The invoice has been sent successfully.
         * `accepted` - When the invoice is marked as accepted.
         * `registered` - When a registered notification has been received or manually marked as registered.
         * `refused` - When a refused notification has been received or manually marked as refused.
         * `paid` - When the invoice has been paid or the invoice is marked manually as paid.
         * `closed` - Is a final state.

        Valid states for a received invoice:
         * `new` - The initial status of a received invoice or manually marked as new.
         * `paid` - When the invoice has been paid or the invoice is marked manually as paid.
         * `accepted` - When the invoice is marked as accepted.
         * `refused` - When the invoice is marked as refused.
         * `annotated` - When the invoice is marked annotated.

        Valid states for an issued simplified invoice:
         * `new` - The initial status of an issued simplified invoice.
         * `sent` - The invoice has been sent successfully.
         * `paid` - When the invoice has been paid or the invoice is marked manually as paid.
         * `downloaded` - When the invoice has been downloaded or manually marked as downloaded.
         * `accepted` - When the invoice is marked as accepted.
         * `refused` - When a refused notification has been received or manually marked as refused.
         * `registered` - When a registered notification has been received or manually marked as registered.
         * `closed` - Is a final state.

        Valid states for an issued self-invoice:
         * `paid` - When the invoice has been paid or the invoice is marked manually as paid.
         * `accepted` - When the invoice is marked as accepted.
         * `registered` - When a registered notification has been received or manually marked as registered.
         * `closed` - Is a final state.
    InvoiceMarkAsCommit:
      type: string
      description: |
        Used to send notification of the state chan via mail to the contact.
        Only for Received Invoices and for states 'accepted', 'refused' & 'paid'.
      example: with_mail
      enum:
        - with_mail
    InvoiceMarkAsReason:
      type: string
      example: Write here the reason of the state change, if you want.
      description: |
        To annotate the reason of the state change, if commit is 'with_mail',
        and the new state is 'accepted', 'refused' or 'paid', the reason will be
        included in the mail sent to the contact.
    ErrorItem:
      type: string
      description: Error message
      example: The invoice cannot be marked as new
    ErrorMessage:
      type: object
      description: Represents an error message as an object
      properties:
        message:
          type: string
          example: Expected attachments to be a ZIP file, found .pdf
    TaxReportGenerated:
      type: object
      description: Response after generating a tax report
      properties:
        id:
          type: integer
          example: 123
      xml:
        name: tax_report
    DocumentValidation:
      type: object
      description: Represents a document validation as an object
      properties:
        validation_result:
          type: object
          description: Contains the information result about the document's validation.
          properties:
            info:
              type: object
              description: Metadata about the validated document.
              properties:
                document_type_code:
                  type: string
                  example: xml.ubl.invoice.bis3
                  description: The document type code of the validated document. If the document type cannot be defined, the value is 'unknown'.
                model:
                  type: string
                  example: Invoice
                  description: Indicates the type of business document that was validated. If the document is not well formed, the value is 'unknown'.
                  enum:
                    - Invoice
                    - ApplicationResponse
                    - DespatchAdvice
                    - Order
                    - OrderResponse
                    - Ledger
                    - TaxReport
                    - unknown
            status:
              type: string
              example: invalid
              enum:
                - valid
                - invalid
                - valid_with_warnings
              description: |
                Status validation of the validated document.
                - If xsd or sch are ´invalid,´ the global status will be ´invalid´.
                - If sch is ´valid_with_warnings´, the global status will be ´valid_with_warnings´.
                - If xsd and sch are ´valid´, the global status will be ´valid´.
            xsd:
              type: object
              description: Representation of the xsd validation.
              properties:
                status:
                  type: string
                  example: invalid
                  enum:
                    - valid
                    - invalid
                    - not_applicable
                  description: Validity status of document validation against the syntax schema (XSD).
                errors:
                  type: array
                  items:
                    type: object
                    description: Representation of an xsd error
                    properties:
                      message:
                        type: string
                        example: 'Element ''ProfileI'': This element is not expected. Expected is one of ( ProfileID, ProfileExecutionID, ID ).'
                        description: Description of the error encountered
            sch:
              type: object
              description: Representation of the sch validation.
              properties:
                status:
                  type: string
                  example: valid_with_warnings
                  enum:
                    - valid
                    - invalid
                    - valid_with_warnings
                    - not_applicable
                  description: Validity status of document validation against the business rules (Schematrons).
                schematrons:
                  type: array
                  example:
                    - CEN-EN16931-UBL.sch
                    - PEPPOL-EN16931-UBL.sch
                  description: Schematrons used to validate the document.
                  items:
                    type: string
                errors:
                  type: array
                  items:
                    type: object
                    description: Representation of an sch error
                    properties:
                      code:
                        type: string
                        example: SE-R-005
                        description: Schematron rule code with which the error was found
                      category:
                        type: string
                        example: PEPPOL-EN16931-UBL.sch
                        description: Schematron model with which the error was found
                      message:
                        type: string
                        example: For Swedish suppliers, when using Seller tax registration identifier, 'Godkänd för F-skatt' must be stated
                        description: Description of the error encountered
                      property_path:
                        type: string
                        example: Invoice/AccountingSupplierParty/Party/PartyTaxScheme/CompanyID
                        description: Path of the property that has given the error
                warnings:
                  type: array
                  items:
                    type: object
                    description: Representation of an sch warning
                    properties:
                      code:
                        type: string
                        example: SE-R-013
                        description: Schematron rule code with which the warning was found
                      category:
                        type: string
                        example: PEPPOL-EN16931-UBL.sch
                        description: Schematron model with which the warning was found
                      message:
                        type: string
                        example: The last digit of a Swedish organization number must be valid according to the Luhn algorithm.
                        description: Description of the warning encountered
                      property_path:
                        type: string
                        example: Invoice/AccountingSupplierParty/Party/PartyLegalEntity
                        description: Path of the property that has given the warning
    OrderId:
      type: integer
      example: 4053100
      title: Order ID
      description: Unique identifier of the **Order** in B2Brouter.
      readOnly: true
    OrderLine:
      type: object
      description: A group of business terms providing information on individual Order lines.
      properties:
        position:
          type: integer
          example: 1
          description: position
          writeOnly: true
        name:
          type: string
          example: Item name
          description: Item name.
          maxLength: 65535
        description:
          type: string
          example: Item description
          description: Item description.
          maxLength: 65535
        quantity:
          type: number
          format: decimal
          example: 1
          description: Item quantity.
          maxLength: 255
        unit_code:
          type: string
          description: Item quantity unit code.
          maxLength: 65535
          example: '1'
        price:
          type: number
          format: decimal
          example: 33.3
          description: The price of an item, exclusive of VAT,after subtracting item price discount.
          maxLength: 255
        total_cost:
          type: number
          format: decimal
          example: 33.3
          description: Price * Quantity
          maxLength: 255
          readOnly: true
        sellers_item_id:
          type: string
          example: BB12KG
          description: Sellers item identifier.
          maxLength: 255
        additional_item_properties:
          type: object
          description: Additional item properties.
          readOnly: true
        standard_item_identification:
          type: string
          description: Standard item identification.
          maxLength: 255
          example: Item identification
        item_document_reference:
          type: string
          description: Item document reference.
          maxLength: 255
          example: Item reference
        delivery_date_start:
          type: string
          format: date
          example: '2020-11-01'
          description: Order line delivery start date.
          maxLength: 255
        delivery_date_end:
          type: string
          format: date
          example: '2020-11-20'
          description: Order line delivery end date.
          maxLength: 255
        note:
          type: string
          example: Note
          description: A note for an order line.
          maxLength: 255
    Order:
      type: object
      description: Represents an order as an object
      properties:
        id:
          $ref: '#/components/schemas/OrderId'
        account:
          type: object
          properties:
            id:
              type: integer
              example: 742
              description: Account ID
            name:
              type: string
              example: B2Brouter Global, S.L.
              description: Account Name
          readOnly: true
        company:
          type: object
          properties:
            id:
              type: integer
              example: 326116
              description: Company ID
            name:
              type: string
              example: John Doe
              description: Name of the client or provider
            tin_value:
              type: string
              description: |
                VAT identifier
                ID: `BT-48`
              example: ESA13585625
            tin_scheme:
              type: string
              description: |
                The scheme identifier of VAT Number
                You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
              example: '9920'
          readOnly: true
        contact:
          type: object
          description: Represents a contact as an object
          properties:
            id:
              type: integer
              example: 326116
              description: Contact ID
            name:
              type: string
              example: John Doe
              description: Name of the client or provider
            tin_value:
              type: string
              description: |
                VAT identifier
                ID: `BT-48`
              example: ESA13585625
            tin_scheme:
              type: string
              description: |
                The scheme identifier of VAT Number
                You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
              example: '9920'
            address:
              type: string
              description: Address
              maxLength: 255
              nullable: true
              example: Carrer de Sant Antoni, 12
            address2:
              type: string
              description: Address 2
              maxLength: 255
              nullable: true
              example: Carrer de Sant Antoni, 13
            postalcode:
              type: string
              example: '80808'
              description: Postcode
              maxLength: 255
              nullable: true
            city:
              type: string
              example: Barcelona
              description: City
              maxLength: 255
              nullable: true
            province:
              type: string
              example: Barcelona
              description: Region/Province/County
              maxLength: 255
              nullable: true
            country:
              type: string
              example: es
              description: Country
              maxLength: 255
          readOnly: true
        accounting_party:
          type: object
          description: Represents an accounting party as an object
          properties:
            id:
              type: integer
              example: 326116
              description: Contact ID
            name:
              type: string
              example: John Doe
              description: Name of the client or provider
            tin_value:
              type: string
              description: |
                VAT identifier
                ID: `BT-48`
              example: ESA13585625
            tin_scheme:
              type: string
              description: |
                The scheme identifier of VAT Number
                You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
              example: '9920'
            address:
              type: string
              description: Address
              maxLength: 255
              nullable: true
              example: Carrer de Sant Antoni, 14
            address2:
              type: string
              description: Address 2
              maxLength: 255
              nullable: true
              example: Carrer de Sant Antoni, 15
            postalcode:
              type: string
              example: '80808'
              description: Postcode
              maxLength: 255
            city:
              type: string
              example: Barcelona
              description: City
              maxLength: 255
              nullable: true
            province:
              type: string
              example: Barcelona
              description: Region/Province/County
              maxLength: 255
              nullable: true
            country:
              type: string
              example: es
              description: Country
              maxLength: 255
          readOnly: true
        number:
          type: string
          example: '3'
          description: |
            A unique identification of the Order.
          maxLength: 100
        issue_datetime:
          type: string
          format: datetime
          description: A datetime when the order was issued.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
        currency:
          type: string
          example: EUR
          description: The currency in which all Invoice amounts are given, except for the Total VAT amount in accounting currency.
          maxLength: 3
          nullable: true
        validity_start:
          type: string
          format: date
          description: Validity start
          example: '2020-11-01'
          nullable: true
        validity_end:
          type: string
          format: date
          description: Validity end
          example: '2020-12-01'
          nullable: true
        contract:
          type: string
          example: Contract
          description: Contract
          maxLength: 255
          nullable: true
        type_code:
          type: string
          example: Type code
          description: Type code
          maxLength: 255
          nullable: true
        state:
          type: string
          description: State of order
          example: received
          maxLength: 255
        is_confirmation:
          type: boolean
          default: false
          example: true
          enum:
            - true
            - false
          description: Is confirmation
        anticipated_amount_in_cents:
          type: integer
          example: 3330
          description: Anticipated amount in cents.
          readOnly: true
        invoice_id:
          type: integer
          example: 4053100
          description: A unique internal identifier of the Invoice in B2Brouter.
          readOnly: true
          nullable: true
        delivery_date_start:
          type: string
          format: date
          description: Delivery date start
          example: '2020-11-01'
          nullable: true
        delivery_date_end:
          type: string
          format: date
          description: Delivery date end
          example: '2020-11-12'
          nullable: true
        delivery_address:
          type: string
          example: Address 1
          description: Delivery address 1
          maxLength: 255
          nullable: true
        delivery_address2:
          type: string
          example: Address 2
          description: Delivery address 2
          maxLength: 255
          nullable: true
        delivery_address3:
          type: string
          example: Address 3
          description: Delivery address 3
          maxLength: 255
          nullable: true
        delivery_city:
          type: string
          example: Barcelona
          description: Delivery city
          maxLength: 255
          nullable: true
        delivery_postalcode:
          type: string
          example: '80808'
          description: Delivery postal code
          maxLength: 255
          nullable: true
        delivery_province:
          type: string
          example: Barcelona
          description: Region/Province/County
          maxLength: 255
          nullable: true
        delivery_country:
          type: string
          example: es
          description: Delivery country
          maxLength: 255
          nullable: true
        delivery_party_id:
          type: string
          example: '111'
          description: Delivery party id
          maxLength: 255
          nullable: true
        delivery_party_scheme:
          type: string
          example: '9920'
          description: Delivery party scheme
          maxLength: 255
          nullable: true
        delivery_party_name:
          type: string
          example: Delivery party name
          description: Delivery party name
          maxLength: 255
          nullable: true
        delivery_location_id:
          type: string
          example: '111'
          description: Delivery location id
          maxLength: 255
          nullable: true
        delivery_location_name:
          type: string
          example: Delivery party name
          description: Delivery location name
          maxLength: 255
          nullable: true
        originator_id:
          type: string
          example: '111'
          description: Originator id
          maxLength: 255
          nullable: true
        originator_name:
          type: string
          example: Originator name
          description: Originator name
          maxLength: 255
          nullable: true
        buyer_contact_name:
          type: string
          example: Buyer contac name
          description: Buyer contac name
          maxLength: 255
          nullable: true
        buyer_contact_phone:
          type: string
          example: '6666666666'
          description: Phone
          maxLength: 255
          nullable: true
        buyer_contact_email:
          type: string
          example: john.doe@example.com
          description: Email
          maxLength: 255
          nullable: true
        notes:
          type: string
          example: Notes
          nullable: true
        order_format:
          type: string
          example: ubl
          nullable: true
        additional_document_references:
          type: object
          description: Additional Order references.
          readOnly: true
          nullable: true
        order_lines:
          type: array
          description: |
            A group of business terms providing information on individual order lines.
          items:
            $ref: '#/components/schemas/OrderLine'
          readOnly: true
        attachments:
          type: array
          description: |
            A group of business terms providing information on attachments.
          items:
            type: object
            properties:
              link:
                type: string
                example: /attachments/download/1/order.xml
              content_type:
                type: string
                example: text/xml
          readOnly: true
        created_at:
          type: string
          format: datetime
          description: A datetime when the object was created in B2Brouter.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
        updated_at:
          type: string
          format: datetime
          description: A datetime of the last time the invoice was updated.
          example: '2020-07-06T09:36:18Z'
          readOnly: true
    OrderState:
      type: string
      example: received
      enum:
        - delivery_confirmed
        - closed
        - accepted
        - refused
        - received
      description: |
        Some states for an order:
         * `delivery_confirmed` - When the order is marked as the order has been confirmed.
         * `closed` - When the order is marked as closed.
         * `accepted` - When the order is marked as accepted.
         * `refused` - When the order is marked as refused.
         * `received` - The initial status of an order or when the order is marked as received.
    Contact:
      type: object
      description: Represents a contact as an object
      properties:
        id:
          type: integer
          example: 133842
          readOnly: true
          description: Internal ID
        parent_id:
          type: integer
          writeOnly: true
          description: |
            ID of the parent contact. Setting this field creates the contact as a child (organisational unit / office) of the specified parent. The parent must belong to the same account.
            Offices inherit TIN (`tin_value`, `tin_scheme`) from the parent contact. If provided, these must match the parent's values exactly; otherwise the request is rejected with a `422 Unprocessable Entity` error (code `parameter_invalid`). CIN (`cin_value`, `cin_scheme`) is not validated against the parent.
          example: 133800
          nullable: true
        tin_value:
          type: string
          description: |
            VAT identifier
            ID: `BT-48`
            When creating an office (`parent_id` is set), this field is inherited from the parent. If provided, it must match the parent's `tin_value`.
          maxLength: 255
          example: ESA13585625
          nullable: true
        tin_scheme:
          type: string
          description: |
            The scheme identifier of VAT Number
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          example: '9920'
          nullable: true
        name:
          type: string
          example: Contact1
          description: Name
          maxLength: 255
          nullable: true
        email:
          type: string
          example: mail@contact1.com
          description: Email
          maxLength: 255
          nullable: true
        phone:
          type: string
          example: '6666666666'
          description: Phone
          maxLength: 255
          nullable: true
        website:
          type: string
          description: Website
          maxLength: 255
          nullable: true
          example: https://www.contact1.com
        address:
          type: string
          description: Address
          maxLength: 255
          nullable: true
          example: Invented Address, 1
        address2:
          type: string
          description: Address 2
          maxLength: 255
          nullable: true
          example: Invented Address, 2
        postalcode:
          type: string
          example: '80808'
          description: Postcode
          maxLength: 255
          nullable: true
        city:
          type: string
          example: Barcelona
          description: City
          maxLength: 255
          nullable: true
        province:
          type: string
          example: Barcelona
          description: Region/Province/County
          maxLength: 255
          nullable: true
        country:
          type: string
          example: es
          description: Country
          maxLength: 255
          nullable: true
        language:
          type: string
          example: es
          default: en
          description: |
            Contact language. It should be a language available inside B2Brouter.
            You can check all available languages  using the **Languages** endpoint in Code lists section (`/languages`)
          enum:
            - en
            - es
            - ca
            - fr
            - it
            - de
            - pt
            - nl
            - pl
            - da
            - sv
            - ar
            - null
          maxLength: 2
          nullable: true
        currency:
          type: string
          example: EUR
          description: |
            Default currency for the electronic documents related to this contact.
            You can check all supported currencies using the **Currencies** endpoint in Code lists section (`/currencies`)
          maxLength: 255
          nullable: true
        is_client:
          type: boolean
          description: Indicates if the contact is a client for your organisation
          default: true
        is_provider:
          type: boolean
          description: Indicates if the contact is a provider for your organisation
          default: true
        transport_type_code:
          $ref: '#/components/schemas/TransportTypeCode'
        document_type_code:
          $ref: '#/components/schemas/DocumentTypeCode'
        cin_value:
          type: string
          description: |
            Company Identifier Number
            Unlike `tin_value`, this field is not validated against the parent contact when creating an office (`parent_id` set).
          nullable: true
          example: '1234567890123'
        cin_scheme:
          type: string
          description: |
            The scheme identifier of Company Identifier Number (not a tax identifier number).
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          nullable: true
          example: '0208'
        pin_value:
          type: string
          description: |
            Peppol Identifier Number, identifies the Buyer's electronic address to which the invoice is delivered.
          nullable: true
          example: ES123456789
        pin_scheme:
          type: string
          description: |
            The identification scheme identifier of the Buyer electronic address.

            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`). The value has to be in EAS code list
            https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/
          nullable: true
          example: '9920'
        party_identification:
          type: string
          maxLength: 12
          description: |
            Seller/Buyer identifier

            ID: `BT-29` if Contact is a Seller
            ID: `BT-46` if Contact is a Buyer
          example: '506001234999'
          nullable: true
        bank_account_number:
          type: string
          description: Contact's bank account number (do not specify if IBAN + BIC is used)
          maxLength: 24
          example: ES6000000000000000000000
          nullable: true
        iban:
          type: string
          description: Contact's IBAN (International Bank Account Number)
          maxLength: 255
          nullable: true
          example: ES6000000000000000000000
        bic:
          type: string
          description: Contact's BIC (Bank Identifier Code)
          maxLength: 255
          nullable: true
          example: 0
        bank_account_id:
          type: integer
          description: Internal Bank Account ID used to link the bank account configured for your account, where the contact deposits payments to you. Must be provided explicitly; it is not populated from the company's default bank account.
          example: 1234
          nullable: true
        payment_method:
          $ref: '#/components/schemas/PaymentMethodCode'
        payment_method_text:
          type: string
          description: Payment method. The means, expressed as text, for how a payment is expected to be or has been settled.
          maxLength: 255
          nullable: true
          example: Credit transfer
        payment_reminder_days:
          type: integer
          description: payment_reminder_days
          maxLength: 4
          example: 4
          nullable: true
        terms:
          type: string
          default: custom
          enum:
            - custom
            - '0'
            - '15'
            - '30'
            - '60'
            - '90'
            - '120'
            - 0m-1
            - 1m-1
            - 1m1
            - 2m1
            - 1m15
            - 1m20
            - 1m10
            - null
          description: |
            Term
            * `custom` - Custom
            * `0` - Upon Receipt
            * `15` - 15 days
            * `30` - 30 days
            * `60` - 60 days
            * `90` - 90 days
            * `120` - 120 days
            * `0m-1` - Last day this month
            * `1m-1` - Last day next month
            * `1m1` - 1st day next month
            * `2m1` - 1st day in two months
            * `1m15` - 15th day next month
            * `1m20` - 20th day next month
            * `1m10` - 10th day next month
          maxLength: 255
          nullable: true
          example: 1m1
        department:
          type: string
          description: Department
          maxLength: 255
          example: Sales
          nullable: true
        description:
          type: string
          description: Description
          maxLength: 65535
          example: Description
          nullable: true
        contact_person:
          type: string
          description: Contact person
          maxLength: 200
          example: John Doe
          nullable: true
        public_sector:
          type: boolean
          description: Indicates if the contact is a public administration
          default: false
        notes:
          type: string
          description: Notes
          maxLength: 65535
          example: Notes for the contact
          nullable: true
        brd_additional_data:
          type: string
          description: Additional data
          maxLength: 255
          example: Additional data
          nullable: true
        vat_payability:
          type: string
          enum:
            - I
            - D
            - S
            - null
          example: I
          description: |
            VAT collection
             * `I` - Immediate
             * `D` - Deferred
             * `S` - Party
          nullable: true
        certified_email:
          type: string
          description: |
            Used as the PEC (Posta Elettronica Certificata) address to send invoice through SDI.
            A certified email guarantees legal certainty of the sender's identity, of the date and time of sending and receiving the email, and of its content.
          maxLength: 255
          example: certified@example.com
          nullable: true
        recipient_code:
          type: string
          pattern: \w{6,7}
          description: |
            The recipient code is a 7-digit alphanumeric code that represents the telematic address of the electronic invoice receiver and is assigned by the SDI (Interchange System).
          maxLength: 7
          example: '1234567'
          nullable: true
        integration_code:
          type: string
          maxLength: 255
          description: |
            Internal code of the contact in the ERP.
            It is used by B2Brouter in the integration process to assign the document to this customer
          example: contact_erpcode12345
          nullable: true
        routing_codes:
          type: object
          description: Routing codes
          properties:
            cin1_scheme:
              type: string
              nullable: true
              example: '9920'
            cin1_value:
              type: string
              nullable: true
              example: '12345678'
            cin2_scheme:
              type: string
              nullable: true
              example: '9920'
            cin2_value:
              type: string
              nullable: true
              example: '12345678'
            cin3_scheme:
              type: string
              nullable: true
              example: '9920'
            cin3_value:
              type: string
              nullable: true
              example: '12345678'
            cin4_scheme:
              type: string
              nullable: true
              example: '9920'
            cin4_value:
              type: string
              nullable: true
              example: '12345678'
            cin5_scheme:
              type: string
              nullable: true
              example: '9920'
            cin5_value:
              type: string
              nullable: true
              example: '12345678'
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
          description: Date and time when the contact record was created
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
          description: Date and time when the contact record was last updated
    ContactReduced:
      type: object
      description: Contact object with reduced attributes
      properties:
        id:
          type: integer
          description: Contact ID
          example: 133842
        tin_value:
          type: string
          description: |
            The Buyer's VAT identifier (also known as Buyer VAT identification number).

            ID: `BT-48`
          maxLength: 255
          example: ESA13585625
          nullable: true
        tin_scheme:
          type: string
          description: |
            The scheme identifier of Company VAT Number
            You can get all schemes codes using the **Schemes* endpoint in Code lists section (`/schemes`).
          example: '9920'
          nullable: true
        name:
          type: string
          description: Name
          example: Contact 1
          nullable: true
        country:
          type: string
          description: Country name to which the company belongs.
          example: es
          nullable: true
        edi_code:
          type: string
          example: '11111'
          nullable: true
        integration_code:
          type: string
          description: |
            Internal code of the contact in the ERP.
            It is used by B2Brouter in the integration process to assign the document to this customer
          example: contact_erpcode12345
          maxLength: 255
          nullable: true
        created_at:
          type: string
          description: Date and time when the contact record was created
          example: '2021-01-16T19:12:44Z'
          format: date-time
        updated_at:
          type: string
          description: Date and time when the contact record was last updated
          example: '2021-01-16T19:12:44Z'
          format: date-time
        contact_offices:
          type: array
          description: List of contact offices
          items:
            type: object
            properties:
              id:
                type: integer
                description: Contact's office ID
                example: 133843
              edi_code:
                type: string
                example: '22222'
                nullable: true
              integration_code:
                type: string
                description: |
                  Internal code of the contact's office in the ERP.
                  It is used by B2Brouter in the integration process to assign the document to this customer
                example: contact_erpcode12345
                nullable: true
          readOnly: true
    Country:
      description: Represents a country as an object
      type: object
      properties:
        code:
          type: string
          example: fr
        name:
          type: string
          example: France
      xml:
        name: country
    Scheme:
      description: Represents a scheme as an object
      type: object
      properties:
        code:
          type: string
          example: '9920'
        name:
          type: string
          example: NIF (CIF)
        country:
          type: string
          example: es
          nullable: true
        eas:
          type: boolean
          nullable: true
          example: 'true'
          description: Indicates whether the scheme is valid for PEPPOL identifiers (EAS - Endpoint Address Scheme). Used, for example, when publishing a PEPPOL participant.
        icd:
          type: boolean
          nullable: true
          example: 'false'
          description: Indicates whether the scheme belongs to the ICD (International Code Designator) list. Relevant for schemes such as GLN, DUNS, and other internationally standardized identifiers.
        taxcode:
          type: boolean
          nullable: true
          example: 'true'
          description: Indicates whether the scheme represents a tax identification code, such as a VAT number or national tax ID. Useful for validating company registration and fiscal data.
      xml:
        name: country
    Currency:
      description: Represents a currency as an object
      type: object
      properties:
        id:
          type: string
          example: eur
          description: The id of the entity.
        priority:
          type: number
          example: 2
        iso_code:
          type: string
          example: EUR
        name:
          type: string
          example: Euro
        symbol:
          type: string
          example: €
        subunit:
          type: string
          example: Cent
          nullable: true
        subunit_to_unit:
          type: integer
          example: 100
        symbol_first:
          type: boolean
          example: true
        html_entity:
          type: string
          example: '&#x20AC;'
        decimal_mark:
          type: string
          example: ','
        thousands_separator:
          type: string
          example: .
        iso_numeric:
          type: string
          example: '987'
      xml:
        name: currency
    Language:
      description: Represents a currency as an object
      type: object
      properties:
        code:
          type: string
          example: de
        name:
          type: string
          example: Deutsch
      xml:
        name: language
    DocumentType:
      type: object
      title: Document Type
      description: Specifies the format of a specific document.
      properties:
        code:
          $ref: '#/components/schemas/DocumentTypeCode'
        name:
          type: string
          description: Name
          example: Peppol BIS3 Invoice
        document:
          type: string
          nullable: true
          description: Document
          example: Invoice
        countries:
          type: array
          items:
            type: string
        can_export:
          type: boolean
          description: True if the document type can be sent.
          example: true
        can_import:
          type: boolean
          description: True if the document type can be received.
          example: true
    TransportType:
      type: object
      title: Transport Type
      description: Specifies the transport method of a specific document.
      properties:
        code:
          $ref: '#/components/schemas/TransportTypeCode'
        name:
          type: string
          description: Name
          example: Chorus PRO
        exportable_document_types:
          type: array
          description: The transport is capable of sending these document types.
          items:
            $ref: '#/components/schemas/DocumentTypeCode'
        importable_document_types:
          type: array
          description: The transport is capable of receiving these document types.
          items:
            $ref: '#/components/schemas/DocumentTypeCode'
        default_document_type:
          allOf:
            - $ref: '#/components/schemas/DocumentTypeCode'
            - description: Default document type.
        category:
          type: string
          description: Category
          example: pge
          nullable: true
        country:
          type: string
          nullable: true
          description: Country
          example: fr
        test_available:
          type: boolean
          description: Indicates if there is test environment available
          example: true
    InvoiceState:
      description: Represents a InvoiceState as an object
      type: object
      properties:
        state:
          type: string
          description: State of invoice
          example: received
        name:
          type: string
          description: State name translated
          example: Received
      xml:
        name: state
    Event:
      description: Represents an event as an object
      type: object
      properties:
        name:
          type: string
          example: delivered_notification
        text:
          type: string
          example: 'Notification: Sent Invoice'
        notes:
          type: string
          example: Description can not be blank
          description: Field that provides descriptive information about the event
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
    InvoiceEvent:
      description: Represents an invoice event as an object
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            invoice:
              type: object
              properties:
                id:
                  type: integer
                  example: 1452334
                number:
                  type: string
                  example: '54'
                state:
                  type: string
                  example: registered
                state_updated_at:
                  type: string
                  format: date-time
                  example: '2019-12-12T09:24:21Z'
      xml:
        name: event
    ContactEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          description: Represents an event for a contact
          properties:
            contact:
              type: object
              properties:
                id:
                  type: integer
                  example: 942
                  description: Contact ID
                name:
                  type: string
                  example: Contact name
                  description: Contact Name
    TransportB2brouter:
      type: object
      description: Represents a configuration for transport B2Brouter
      properties:
        code:
          type: string
          enum:
            - ''
            - b2brouter
        enabled:
          description: Enable or disable the transport configuration.
          type: boolean
          example: true
          default: true
        reception:
          type: boolean
          default: false
          example: true
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
    TransportEmail:
      type: object
      description: Represents a configuration for transport Email
      properties:
        code:
          type: string
          enum:
            - ''
            - email
        enabled:
          description: Enable or disable the transport configuration.
          type: boolean
          example: true
          default: true
        reception:
          type: boolean
          example: true
          default: false
        email_for_reception:
          type: string
          example: tin@b2brouter.email
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
    TransportPeppol:
      type: object
      description: Represents a configuration for Peppol transport
      properties:
        code:
          type: string
          enum:
            - ''
            - peppol
        enabled:
          description: Enable or disable the transport configuration.
          type: boolean
          example: true
          default: true
        reception:
          type: boolean
          default: false
          example: true
          description: |
            Enables receiving documents through this transport channel. For Peppol transports, when reception is enabled (along with enabled=true), we publish your participant ID to the SML/SMP (Service Metadata Locator/Service Metadata Publisher) and the Peppol directory, allowing you to receive documents through the Peppol network.

            The system automatically publishes country-specific Peppol document types based on your enabled document type settings (invoice, credit_note, self_billing, order, application_response).
        invoice:
          description: |
            Enables support for Invoice documents in Peppol SMP. Only available for Peppol transport type.
            **Country-specific formats**: The actual document formats published depend on the Account's country.
          type: boolean
          default: true
          example: true
        credit_note:
          description: |
            Enables support for CreditNote documents in Peppol SMP. Only available for Peppol transport type.
            **Country-specific formats**: The actual document formats published depend on the Account's country.
          type: boolean
          default: true
          example: true
        self_billing:
          description: |
            Enables support for Self-Billing Invoice and Self-Billing CreditNote documents in Peppol SMP. Only available for Peppol transport type.
          type: boolean
          default: false
          example: false
        order:
          description: |
            Enables support for Order documents in Peppol SMP. Only available for Peppol transport type.
            Uses UBL Order format regardless of country.
          type: boolean
          default: true
          example: true
        application_response:
          description: |
            Enables support for ApplicationResponse documents in Peppol SMP. Only available for Peppol transport type.
            Uses UBL Application Response v3 formats regardless of country.
          type: boolean
          default: true
          example: true
        pin_scheme:
          description: pin_scheme
          type: string
          example: '9930'
        pin_value:
          description: pin_value
          type: string
          example: DE123456789
        sml_status:
          type: string
          enum:
            - not_published
            - processing
            - published
          readOnly: true
          description: |
            SML (Service Metadata Locator) registration status. Indicates whether B2Brouter has registered this participant identifier in the Peppol SML. 
            Only reflects the publication state managed by B2Brouter — not the status at third-party SMP providers.
          example: published
        peppol_directory_status:
          type: string
          enum:
            - not_published
            - processing
            - published
          readOnly: true
          description: |
            Peppol Directory publication status. Indicates whether B2Brouter has registered this participant in the Peppol Directory for discovery by other participants. 
            Only reflects the publication state managed by B2Brouter.
          example: published
        reception_document_types:
          type: array
          readOnly: true
          description: |
            List of Peppol document types this transport can receive, based on country
            and enabled document type capabilities (invoice, credit_note, etc.).
            Empty when reception is disabled.
          items:
            type: object
            properties:
              code:
                type: string
                description: Internal document type code. Matches codes from the /document_types endpoint.
                example: xml.ubl.invoice.bis3
              name:
                type: string
                description: Human-readable name of the document type.
                example: Peppol BIS3 Invoice
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
    TransportUserPassword:
      type: object
      description: Represents a configuration for transport UserPassword
      properties:
        code:
          type: string
          enum:
            - ''
            - es.pecam
            - es.eusko_jaurlaritza
          example: es.pecam
        enabled:
          description: Enable or disable the transport configuration.
          type: boolean
          example: true
          default: true
        username:
          description: Username
          type: string
          example: user1234
        password:
          description: Password
          type: string
          example: 1234pass
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
    TransportEdi:
      type: object
      description: Represents a configuration for transport EDI
      properties:
        code:
          type: string
          enum:
            - ''
            - ediversa
            - edicom
        enabled:
          description: Enable or disable the transport configuration.
          type: boolean
          example: true
          default: true
        username:
          description: Username
          type: string
          example: user1234
        password:
          description: Password
          type: string
          example: 1234pass
        edi_identifier:
          description: PO EDI legal
          type: string
          example: 1234edi
        created_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2024-07-07T11:51:57Z'
          readOnly: true
    TaxBreakdowns:
      type: object
      description: |
        Represents a TaxBreakdown, referred to as "Desglose" in the Verifactu system. A TaxBreakdown contains all the detailed information about the tax category applied to a specific operation. It includes the tax base, the tax amount, and other relevant information necessary for tax reporting.
      properties:
        id:
          type: integer
          example: 355040
          description: |
            An internal identifier that is unique to each **Tax Breakdown** within B2Brouter.
          readOnly: true
        kind:
          type: string
          enum:
            - charged
            - withheld
          example: charged
          writeOnly: true
        date:
          type: string
          format: date
          example: '2025-04-10'
          writeOnly: true
        name:
          type: string
          example: IVA
          nullable: true
        currency:
          type: string
          example: EUR
          writeOnly: true
        original_currency:
          type: string
          example: EUR
          writeOnly: true
        category:
          type: string
          enum:
            - E
            - NS
            - Z
            - S
            - H
            - AA
            - AAA
            - AE
            - G
            - O
            - K
            - null
          example: S
          description: |
            Taxes categories
             * `E` - Exempt
             * `NS` - NotSubject
             * `Z` - ZeroRated
             * `S` - Standard
             * `H` - High Rate
             * `AA` - Low Rate
             * `AAA` - Super Low Rate
             * `AE` - Reverse
             * `G` - Free export item, VAT not charged
             * `O` - Services outside scope of tax
             * `K` - VAT exempt for EEA intra-community supply of goods and services
          nullable: true
        special_regime_key:
          type: string
          example: '01'
          nullable: true
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - '09'
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
            - '17'
            - '18'
            - '19'
            - '20'
            - '51'
            - '52'
            - '53'
            - '54'
            - null
          description: |
            VAT regime key and operations with tax significance.

            - [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#special-regime-key-codes).
            - TicketBAI codes: `01`,`02`,`03`,`04`,`05`,`06`,`07`,`08`,`09`,`10`,`11`,`14`,`15`,`17`,`18`,`19`,`51`,`52`,`53`,`54`.
        non_exempt:
          type: boolean
          example: true
        non_exemption_code:
          type: string
          example: S1
          description: |
            Reason code for No Exempt. 
            [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#non-exemption-codes)
          nullable: true
        no_subject:
          type: boolean
          example: false
          default: false
        no_subject_code:
          type: string
          nullable: true
          enum:
            - N1
            - N2
            - OT
            - RL
            - IE
            - VT
            - np II
            - null
          description: |
            Reason code for No Suject. 
            - [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#non-subject-codes)
            - TicketBAI codes: `OT`, `RL`, `IE`, `VT`.

            This field is required when `no_subject` is set to true.
        exempt:
          type: boolean
          example: false
        exemption_code:
          type: string
          nullable: true
          enum:
            - E1
            - E2
            - E3
            - E4
            - E5
            - E6
            - zw
            - null
          description: |
            Reason code for VAT Exemption. 
            [Verifactu and TicketBAI codes](https://developer.b2brouter.net/docs/verifactu#exemption-codes).

            This field is required when `exempt` is set to true.
        kind_equivalence_surcharge:
          type: string
          nullable: true
          writeOnly: true
        scope:
          type: string
          enum:
            - domestic
            - international
          example: domestic
          writeOnly: true
        type_operation:
          type: string
          enum:
            - services
            - goods
            - null
          example: services
          nullable: true
        amend:
          type: boolean
          example: false
          writeOnly: true
        withheld:
          type: boolean
          example: false
          default: false
          writeOnly: true
        investment_good:
          type: boolean
          example: false
          default: false
          writeOnly: true
        comment:
          type: string
          nullable: true
          writeOnly: true
        percent:
          type: number
          format: decimal
          example: 21
          nullable: true
        taxable_base:
          type: number
          format: decimal
          example: 123
        tax_amount:
          type: number
          format: decimal
          example: 25.83
        tax_amount_equivalence_surcharge:
          type: number
          format: decimal
          example: 0
          writeOnly: true
        taxable_base_at_cost:
          type: number
          format: decimal
      xml:
        name: tax_breakdown
    TaxReportLine:
      type: object
      required:
        - quantity
        - description
        - price
        - tax_inclusive_amount
      description: A group of business terms providing information on individual Tax Report lines. This is used when creating TicketBAI and KSeF Tax Reports.
      properties:
        id:
          type: integer
          example: 435453
          description: A unique identifier for this TaxReportLine across all the system.
          readOnly: true
        quantity:
          anyOf:
            - type: number
            - type: string
          description: Invoiced quantity.
          example: 1
        price:
          anyOf:
            - type: number
            - type: string
          description: The price of an item, exclusive of VAT.
          example: 10
        description:
          type: string
          description: Item Name.
          maxLength: 65535
          nullable: true
          example: Item 1
        discount_amount:
          anyOf:
            - type: number
              nullable: true
            - type: string
          description: |
            Discount amount. 
            For KSeF it's the discount unit price.
          example: 1
        charge_amount:
          anyOf:
            - type: number
              nullable: true
            - type: string
          description: Charge amount.
          example: 4
        tax_inclusive_amount:
          anyOf:
            - type: number
              nullable: true
            - type: string
          description: The total amount of the line including taxes.
          example: 121
        tax_exclusive_amount:
          anyOf:
            - type: number
              nullable: true
            - type: string
          description: The total amount of the line excluding taxes.
          example: 100
        tax_amount:
          anyOf:
            - type: number
              nullable: true
            - type: string
          description: The total tax amount of the line.
          example: 21
        position:
          type: integer
          description: Position/sequence number of the line in the document. Specific to KSeF (Polish tax reporting).
          example: 1
          nullable: true
        unit_code:
          type: string
          description: Unit of measure code for the invoiced quantity. Specific to KSeF (Polish tax reporting).
          example: PCE
          nullable: true
        tax_code:
          type: string
          enum:
            - '23'
            - '22'
            - '8'
            - '7'
            - '5'
            - '4'
            - '3'
            - 0 WDT
            - 0 EX
            - 0 KR
            - zw
            - oo
            - np I
            - np II
          description: |
            Tax category/code for this line item. Specific to KSeF (Polish tax reporting).

            Valid values for KSeF:
            * `23` - Standard VAT rate 23%
            * `22` - Standard VAT rate 22%
            * `8` - Reduced VAT rate 8%
            * `7` - Reduced VAT rate 7%
            * `5` - Reduced VAT rate 5%
            * `4` - Reduced VAT rate 4%
            * `3` - Reduced VAT rate 3%
            * `0 WDT` - Intra-Community Supply 0% (Wewnątrzwspólnotowa Dostawa Towarów)
            * `0 EX` - Export 0%
            * `0 KR` - Domestic zero-rated 0%
            * `zw` - Exempt from VAT (zwolniona)
            * `oo` - Reverse charge domestic (odwrotne obciążenie)
            * `np I` - Not subject to VAT - cross-border services (nie podlega)
          example: '23'
          nullable: true
        ksef_amended:
          type: boolean
          description: Indicates if this line is part of an amendment/correction. Specific to KSeF (Polish tax reporting).
          example: false
          nullable: true
        item_seller_identifier:
          type: string
          nullable: true
          description: |-
            An identifier, assigned by the Seller, for the item.
            Used for TicketBAI and KSeF Tax Reports.
          example: SELLER-123
        item_standard_identifier:
          type: string
          nullable: true
          description: |-
            An item identifier based on a registered scheme (e.g. GTIN).
            Used for TicketBAI and KSeF Tax Reports.
          example: '05012345678900'
    TaxReport:
      type: object
      description: Represents a TaxReport object, such as the ones generated by Verifactu
      properties:
        id:
          type: integer
          example: 6560
          description: |
            An internal identifier that is unique to each **Tax report** within B2Brouter.
        type:
          type: string
          example: Verifactu
          enum:
            - Verifactu
            - TicketBai
            - Sdi
            - MyInvois
            - Zatca
            - Ksef
            - SiiDocument
        book_type:
          type: string
          enum:
            - Expedida
            - Recibida
            - Inversion
            - Intracomunitaria
            - Metalico
            - Seguro
            - Viajesagencia
            - Cobro
            - Pago
          description: |-
            Required when `type` is `SiiDocument`. Selects which SII book the record belongs to. Drives both the AEAT envelope (e.g. `SuministroLRFacturasEmitidas` for `Expedida`) and the validation rules applied at create time.
            * `Expedida` — issued invoices * `Recibida` — received invoices * `Inversion` — capital goods (bienes de inversión) * `Intracomunitaria` — intra-EU operations * `Metalico` — cash transactions (≥ €6,000 / counterparty / period) * `Seguro` — insurance operations * `Viajesagencia` — travel agency special regime * `Cobro` — payments received against issued invoices (A0 only;
              PATCH and DELETE return 422 — AEAT XSD has no A1/B variants)
            * `Pago` — payments made against received invoices (A0 only)
        invoice_id:
          type: integer
          example: 77
          description: |
            An internal identifier that is unique to each **Invoice** within B2Brouter.
          nullable: true
        state:
          type: string
          example: registered
          enum:
            - new
            - processing
            - signed
            - sending
            - sent
            - acknowledged
            - deposited
            - clearing
            - registered
            - registered_with_errors
            - error
            - refused
            - annullating
            - annulled
            - invalid
          description: |
            States for a Tax Report (not every authority uses every state):
              * `new` - The TaxReport is created and validated, ready for further actions.
              * `processing` - Initial state of a TaxReport. The report is being signed and validated.
              * `signed` - The report is signed and validated and ready for transmission.
              * `sending` - The report is in the queue for transmission.
              * `sent`  - The report was successfully transmitted.
              * `acknowledged` - The authority acknowledged receipt (e.g. DGFiP deposit ack).
              * `deposited` - The report was deposited on the authority platform (DGFiP Flux 1).
              * `clearing` - The report is awaiting clearance by the authority.
              * `registered` - The TaxReport has been registered by the Tax Authority.
              * `registered_with_errors` - Registered, but the authority returned per-record errors (SII `AceptadoConErrores`).
              * `error` - There was an error during submission, or it was rejected by the Tax Authority.
              * `refused` - The authority refused the submission.
              * `annullating` - An annullation (baja) is in progress.
              * `annulled` - The report was annulled.
              * `invalid` - The report failed validation checks.
          readOnly: true
        qr:
          type: string
          description: |
            The QR code codified in base64 of the tax report.
          readOnly: true
          nullable: true
        xml_base64:
          type: string
          description: |
            The XML representation of the tax report codified in base64.
          readOnly: true
          nullable: true
        identifier:
          type: string
          description: |
            Unique identifier for the tax report, usually assigned or provided by the Tax Authority.
            In the case of Verifactu, this field contains the URL hosted by the AEAT that allows the Buyer to check
            that the invoice has been properly submitted to the TA.
          readOnly: true
          nullable: true
        fingerprint:
          type: string
          description: |
            The unique hash that identifies the tax report.
          readOnly: true
          nullable: true
        previous_id:
          type: integer
          example: 6560
          description: |
            Internal identifier of the **Tax report** in the previous link of the chain.
          readOnly: true
          nullable: true
        sent_at:
          type: string
          format: date-time
          example: '2025-04-10T10:14:31Z'
          nullable: true
          readOnly: true
        digested_at:
          type: string
          format: date-time
          example: '2025-04-10T10:14:31Z'
          nullable: true
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2025-04-10T10:14:21.157690000Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2025-04-10T10:14:29.259065000Z'
          readOnly: true
        label:
          type: string
          example: Verifactu A/1
        has_errors:
          type: boolean
          example: false
          description: Indicates if there are any errors in the report.
          readOnly: true
        errors:
          type: array
          description: |
            Errors associated with the tax report. For tax-authority rejections (e.g. an
            unknown counterparty NIF in SII) this carries the authority's `error_code` and
            `error_description`. Always present in responses; empty when there are no errors.
          readOnly: true
          items:
            type: object
            properties:
              code:
                type: string
                example: '4102'
                description: The authority (or B2Brouter) error code.
                readOnly: true
              description:
                type: string
                example: El NIF del primer registro no está identificado en el censo de la AEAT.
                description: Human-readable description of the error.
                readOnly: true
        has_warnings:
          type: boolean
          nullable: true
          description: Indicates if there are any warnings in the report.
          readOnly: true
        from_net:
          type: string
          nullable: true
          readOnly: true
        from_net_id:
          type: string
          nullable: true
          readOnly: true
        to_net:
          type: string
          example: b2brouter
          readOnly: true
          nullable: true
        to_net_id:
          type: string
          example: A-TGEZLKMKVK9VVN
          readOnly: true
          nullable: true
        ledger_id:
          type: integer
          example: 1096
          description: |
            An internal identifier that is unique to each **Ledger** within B2Brouter.
          readOnly: true
          nullable: true
        tax_report_setting_id:
          type: integer
          example: 624
          description: |
            Internal identifier of the **TaxReportSetting** that governs this report. Resolved
            server-side from the account and tax authority; any value sent on create/update is ignored.
          readOnly: true
        document_type_code:
          type: string
          example: xml.tax_report.verifactu.alta
        transport_type_code:
          type: string
          example: es.verifactu
        annulled_by_id:
          type: integer
          nullable: true
          readOnly: true
          description: |
            Internal identifier of the **Tax report** that annulled this one.
        corrected_by_id:
          type: integer
          nullable: true
          readOnly: true
          description: |
            Internal identifier of the **Tax report** that corrected this one.
        generation_timestamp:
          type: string
          format: date-time
          example: '2025-04-10T10:14:25.337580000Z'
          nullable: true
        tax_point_date:
          type: string
          nullable: true
        invoice_date:
          type: string
          format: date
          example: '2025-04-10'
          nullable: true
        invoice_number:
          type: string
          example: '111234126332'
          nullable: true
        invoice_series_code:
          type: string
          nullable: true
        fiscal_year:
          type: integer
          nullable: true
        fiscal_period:
          type: string
          nullable: true
        amended_number:
          type: string
          nullable: true
        amended_series_code:
          type: string
          nullable: true
        amended_date:
          type: string
          nullable: true
        amended_line_extension:
          type: number
          format: decimal
          nullable: true
        amended_tax_amount:
          type: number
          format: decimal
          nullable: true
        amended_tax_exclusive:
          type: number
          format: decimal
          nullable: true
        amended_tax_inclusive:
          type: number
          format: decimal
          nullable: true
        amended_charge_total:
          type: number
          format: decimal
          nullable: true
        amended_payable:
          type: number
          format: decimal
          nullable: true
        amended_tax_amount_equivalence_surcharge:
          type: number
          format: decimal
          nullable: true
        amend_type:
          type: string
          nullable: true
        invoice_type_code:
          type: string
          example: F1
          nullable: true
          description: |
            Invoice type code. The available codes depend on the tax authority:

            **Verifactu and TicketBAI codes:**
            * `F1` - Factura (art. 6, 7.2 y 7.3 del RD 1619/2012)
            * `F2` - Factura Simplificada y Facturas sin identificación del destinatario (art. 6.1.d) RD 1619/2012
            * `F3` - Factura emitida en sustitución de facturas simplificadas facturadas y declaradas
            * `R1` - Factura Rectificativa (Error fundado en derecho y Art. 80 Uno Dos y Seis LIVA)
            * `R2` - Factura Rectificativa (Art. 80.3)
            * `R3` - Factura Rectificativa (Art. 80.4)
            * `R4` - Factura Rectificativa (Resto)
            * `R5` - Factura Rectificativa en facturas simplificadas

            See [Verifactu documentation](https://developer.b2brouter.net/docs/verifactu#invoice-type-codes)

            **KSeF codes:**
            * `VAT` - Basic invoice
            * `KOR` - Corrective invoice
            * `ZAL` - Advance payment invoice (Article 106f sec. 4)
            * `ROZ` - Invoice per Article 106f sec. 3
            * `UPR` - Simplified invoice (Article 106e sec. 5 item 3)
            * `KOR_ZAL` - Corrective invoice for advance payment
            * `KOR_ROZ` - Corrective invoice for ROZ invoice

            See [KSeF documentation](https://developer.b2brouter.net/docs/ksef#invoice-type-codes)
        special_regime_key:
          type: string
          example: '01'
          description: Special regime key. This is only used when creating TicketBAI Tax Reports.
          nullable: true
        special_regime_key_additional:
          type: string
          example: '05'
          description: Special regime key additional. This is only used when creating TicketBAI Tax Reports.
          nullable: true
        type_operation:
          type: string
          example: services
          description: Type of operation. This is only used when creating TicketBAI Tax Reports.
          nullable: true
        operation_type:
          type: string
          nullable: true
        external_reference:
          type: string
          nullable: true
        description:
          type: string
          example: Factura 111234126332
          nullable: true
        annullation:
          description: |
            Indicates whether the tax report represents an annulment of a previous report.
            To cancel a tax report, use the [annullation endpoint](https://developer.b2brouter.net/v2025-10-13/reference/new-annulate-tax-report).
          type: boolean
          example: false
          default: false
          readOnly: true
        correction:
          description: Indicates whether the tax report is a correction of a previous report
          type: boolean
          example: false
          readOnly: true
        ticket:
          description: Indicates whether the tax report corresponds to a simplified invoice (`invoice_type_code` field is F2 or R5).
          type: boolean
          example: false
          readOnly: true
        issued_by_third_party_or_receiver:
          type: boolean
          example: false
        customer_party_name:
          type: string
          example: Ingent Grup Systems, SL
          nullable: true
        customer_party_id:
          type: string
          nullable: true
        customer_party_scheme:
          type: string
          nullable: true
        customer_party_tax_id:
          type: string
          example: B63354243
          nullable: true
        customer_party_tax_scheme:
          type: string
          nullable: true
        customer_party_country:
          type: string
          example: es
          nullable: true
        customer_party_address:
          type: string
          example: casa seva, 9
          description: Customer party address. This is only used when creating TicketBAI/KSeF Tax Reports.
          nullable: true
        customer_party_postalcode:
          type: string
          example: '08080'
          description: Customer party postal code. This is only used when creating TicketBAI/KSeF Tax Reports.
          nullable: true
        customer_party_city:
          type: string
          example: Warszawa
          description: Customer party city. This is only used when creating KSeF Tax Reports.
          nullable: true
        customer_party_endpoint_id:
          type: string
          nullable: true
        supplier_party_name:
          type: string
          example: B2Brouter Global S.L.
          readOnly: true
          nullable: true
        supplier_party_id:
          type: string
          nullable: true
          readOnly: true
        supplier_party_scheme:
          type: string
          nullable: true
          readOnly: true
        supplier_party_tax_id:
          type: string
          example: B63276174
          readOnly: true
          nullable: true
        supplier_party_tax_scheme:
          type: string
          nullable: true
          readOnly: true
        supplier_party_country:
          type: string
          nullable: true
          readOnly: true
        supplier_party_address:
          type: string
          nullable: true
          readOnly: true
        supplier_party_postalcode:
          type: string
          nullable: true
          readOnly: true
        supplier_party_city:
          type: string
          nullable: true
          readOnly: true
        supplier_party_endpoint_id:
          type: string
          nullable: true
          readOnly: true
        supplier_party_krs:
          type: string
          nullable: true
          description: |-
            KRS (Krajowy Rejestr Sądowy) number of the supplier.
            Specific to KSeF (Polish tax reporting).
        supplier_party_regon:
          type: string
          nullable: true
          description: |-
            REGON (statistical identification number) of the supplier.
            Specific to KSeF (Polish tax reporting).
        supplier_party_bdo:
          type: string
          nullable: true
          description: |-
            BDO (waste database register) number of the supplier.
            Specific to KSeF (Polish tax reporting).
        supplier_contact_phone:
          type: string
          nullable: true
          description: |-
            Supplier contact telephone number (BT-42).
            Specific to KSeF (Polish tax reporting).
        supplier_contact_email:
          type: string
          nullable: true
          description: |-
            Supplier contact email address (BT-43).
            Specific to KSeF (Polish tax reporting).
        third_party_name:
          type: string
          nullable: true
          readOnly: true
        third_party_role:
          type: string
          nullable: true
          readOnly: true
        third_party_id:
          type: string
          nullable: true
          readOnly: true
        third_party_scheme:
          type: string
          nullable: true
          readOnly: true
        third_party_tax_id:
          type: string
          nullable: true
          readOnly: true
        third_party_tax_scheme:
          type: string
          nullable: true
          readOnly: true
        third_party_country:
          type: string
          nullable: true
          readOnly: true
        third_party_address:
          type: string
          nullable: true
          readOnly: true
        third_party_postalcode:
          type: string
          nullable: true
          readOnly: true
        third_party_city:
          type: string
          nullable: true
          readOnly: true
        third_party_endpoint_id:
          type: string
          nullable: true
          readOnly: true
        line_extension_amount:
          type: number
          format: decimal
          nullable: true
        tax_amount:
          type: number
          format: decimal
          example: 2583
        tax_amount_withheld:
          type: number
          format: decimal
          example: 10
          description: Tax amount withheld. This is only used when creating TicketBAI Tax Reports.
          nullable: true
        tax_exclusive_amount:
          type: number
          format: decimal
          nullable: true
        tax_inclusive_amount:
          type: number
          format: decimal
          example: 14883
        charge_total:
          type: number
          format: decimal
          nullable: true
        payable_amount:
          type: number
          format: decimal
          nullable: true
        tax_amount_equivalence_surcharge:
          type: number
          format: decimal
          nullable: true
        currency:
          type: string
          example: EUR
        original_currency:
          type: string
          example: EUR
          nullable: true
        previously_refused:
          type: string
          example: S
          description: Specific of Verifactu
          nullable: true
        simplified_art7273:
          oneOf:
            - type: string
            - type: boolean
          example: S
          description: |-
            `FacturaSimplificadaArticulos7.2_7.3` flag.
            Verifactu: `'S'` or `'N'` (string).
            SII (`type: SiiDocument`, `book_type: Expedida` or `Recibida`): JSON boolean. Render as `<sii:FacturaSimplificadaArticulos7.2_7.3>S</sii:FacturaSimplificadaArticulos7.2_7.3>` when `true`; element is omitted when `false`.
        macrodata:
          oneOf:
            - type: string
            - type: boolean
          example: 'N'
          description: |-
            `Macrodato` flag — invoice total above the AEAT large-amount threshold.
            Verifactu: `'S'` or `'N'` (auto-computed from `tax_inclusive_amount` ≥ €100M).
            SII (`type: SiiDocument`, `book_type: Expedida` or `Recibida`): JSON boolean supplied by the client.
        coupon:
          type: string
          example: 'N'
          description: Specific of Verifactu
        reg_previo_ggee:
          type: boolean
          default: false
          description: |-
            `RegPrevioGGEEoREDEMEoCompetencia` flag. Applies to `Expedida` and `Recibida`. Emits `<sii:RegPrevioGGEEoREDEMEoCompetencia>S</...>` when `true`; omitted when `false`.
            Specific to SII.
        facturacion_disp_adicional_mercado_gas:
          type: boolean
          default: false
          description: |-
            `FacturacionDispAdicionalTerceraYsextayDelMercadoOrganizadoDelGas` flag. Applies to `Expedida` only — the AEAT XSD defines this element on `FacturaExpedidaType`, not on the FacturaType base.
            Specific to SII.
        sin_identif_destinatario_art_6_1_d:
          type: boolean
          default: false
          description: |-
            `FacturaSinIdentifDestinatarioAritculo6.1.d` flag. `Expedida`-only per the AEAT XSD.
            Specific to SII.
        fecha_contable:
          type: string
          format: date
          nullable: true
          example: '2026-04-15'
          description: |-
            Accounting registration date (`FechaRegContable`). `Recibida`-only.
            Distinct from `tax_point_date` (which maps to `FechaOperacion`): the operation/service date can precede the accounting date by weeks if the invoice is booked later. If not set, the modern path falls back to `tax_point_date` then `invoice_date`.
            Specific to SII.
        cuota_deducible_in_cents:
          type: integer
          nullable: true
          example: 2100
          description: |-
            Deductible quota for `Recibida` records (write side). When omitted, derived from the sum of `tax_breakdowns[*].tax_amount`. Real-world Recibida data often diverges from the breakdown sum (partial deductibility, regularization), so an explicit client value wins.
            Specific to SII.
        cuota_deducible:
          type: number
          format: decimal
          readOnly: true
          description: |-
            Read-side response field — deductible quota as decimal (EUR). Mirrors `cuota_deducible_in_cents` / 100.
            Specific to SII Recibida.
        succession_party_name:
          type: string
          nullable: true
          description: |-
            `EntidadSucedida` > `NombreRazon`. Used in business-succession reporting on `Expedida`, `Recibida`, `Inversion`, `Intracomunitaria`, `Metalico`, `Seguro`, `Viajesagencia`. Must be set together with `succession_party_tax_id`.
            Specific to SII.
        succession_party_tax_id:
          type: string
          nullable: true
          description: |-
            `EntidadSucedida` > `NIF`. Pairs with `succession_party_name`.
            Specific to SII.
        billing_agreement_number:
          type: string
          maxLength: 15
          nullable: true
          description: |-
            `NumRegistroAcuerdoFacturacion`. Used on `Expedida`, `Recibida`, `Inversion`, `Intracomunitaria` records that fall under a pre-registered AEAT billing agreement.
            Specific to SII.
        clave_declarado:
          type: string
          enum:
            - D
            - R
          nullable: true
          description: |-
            `ClaveDeclarado` enum. `Intracomunitaria`-only.
            Specific to SII.
        plazo_operacion:
          type: string
          maxLength: 3
          nullable: true
          description: |-
            `PlazoOperacion` AEAT code. `Intracomunitaria`-only.
            Specific to SII.
        facturas_o_documentacion:
          type: string
          maxLength: 150
          nullable: true
          description: |-
            `FacturasODocumentacion` free-text field. `Intracomunitaria`-only.
            Specific to SII.
        identificacion_bien:
          type: string
          maxLength: 40
          nullable: true
          description: |-
            `IdentificacionBien` — capital good identifier. `Inversion`-only. Required when creating an `Inversion` record.
            Specific to SII.
        fecha_inicio_utilizacion:
          type: string
          format: date
          nullable: true
          description: |-
            `FechaInicioUtilizacion` — date the capital good entered use. `Inversion`-only. Required when creating an `Inversion` record.
            Specific to SII.
        prorrata_anual_definitiva:
          type: string
          format: decimal
          nullable: true
          example: 95
          description: |-
            `ProrrataAnualDefinitiva` — definitive annual prorrata (0–100, 2 decimal places). `Inversion`-only. Required when creating an `Inversion` record.
            Specific to SII.
        regularizacion_anual_deduccion_in_cents:
          type: integer
          nullable: true
          description: |-
            `RegularizacionAnualDeduccion` in cents. `Inversion`-only, optional.
            Specific to SII.
        identificacion_entrega:
          type: string
          maxLength: 40
          nullable: true
          description: |-
            `IdentificacionEntrega`. `Inversion`-only, optional.
            Specific to SII.
        regularizacion_deduccion_efectuada_in_cents:
          type: integer
          nullable: true
          description: |-
            `RegularizacionDeduccionEfectuada` in cents. `Inversion`-only, optional.
            Specific to SII.
        csv:
          type: string
          nullable: true
          readOnly: true
          description: |-
            AEAT-assigned CSV (Código Seguro de Verificación) for the registered record. Set asynchronously after the AEAT submission succeeds.
            Specific to SII.
        fecha_presentacion:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: |-
            AEAT-assigned presentation timestamp (Madrid time zone). Set asynchronously after the AEAT submission succeeds.
            Specific to SII.
        estado:
          type: string
          nullable: true
          readOnly: true
          description: |-
            Internal SII state (`Nuevo`, `Enviando`, `Correcto`, `Incorrecto`, `AceptadoConErrores`, `Error`). The CTC `state` field is the authoritative cross-authority signal; `estado` is exposed for SII-specific tooling that mirrors the legacy column.
            Specific to SII.
        payments:
          type: array
          nullable: true
          items:
            type: object
            properties:
              fecha:
                type: string
                format: date
              importe_in_cents:
                type: integer
              medio:
                type: string
              cuenta_o_medio:
                type: string
          description: |-
            Per-record payment events for `Cobro` and `Pago` — collections for `Cobro`, disbursements for `Pago` (the book type disambiguates the direction). Array of `{ fecha, importe_in_cents, medio, cuenta_o_medio }`.
            Not used by other book types — their nested data lives in flat columns above.
            Specific to SII.
        payment_date:
          type: string
          format: date
          example: '2025-04-10'
          nullable: true
          description: |-
            Payment date or payment due date for the invoice.
            Specific to KSeF (Polish tax reporting).
            For already paid invoices (Zaplacono=1), this represents the actual payment date (DataZaplaty). For unpaid invoices, this represents the payment due date (TerminPlatnosci).
        payment_means_type_code:
          type: integer
          nullable: true
          minimum: 1
          maximum: 7
          example: 6
          description: |-
            Payment means type code.
            Specific to KSeF (Polish tax reporting).
            Valid values for KSeF:
             * `1` - Cash 
             * `2` - Card
             * `3` - Voucher
             * `4` - Check
             * `5` - Credit
             * `6` - Bank transfer
             * `7` - Mobile phone payment
        payment_account_identifier:
          type: string
          nullable: true
          example: PL61129030140002071219612874
          description: |-
            Payment account identifier.
            Specific to KSeF (Polish tax reporting).
            A unique identifier of the financial payment account to which payment should be made. Can be an IBAN or local bank account number.
        payment_service_provider_identifier:
          type: string
          nullable: true
          example: WBKPPLPP
          description: |-
            Payment service provider identifier.
            Specific to KSeF (Polish tax reporting).
            BIC/SWIFT code or national clearing code of the payment service provider (bank) where the payment account is located.
        amended_ksef_number:
          type: string
          example: a1b2c3d4-e5f6-4789-ab12-cd34ef567890
          nullable: true
          description: The KSeF number of the original invoice being amended. Used when creating an amendment/correction in KSeF. Specific to KSeF (Polish tax reporting).
        order_total_amount:
          type: number
          format: decimal
          nullable: true
          description: |-
            Total amount of the order (KSeF WartoscZamowienia field).
            Required when `invoice_type_code` is `ZAL` or `KOR_ZAL`. Mapped automatically from the invoice when generating a tax report. Specific to KSeF (Polish tax reporting).
        previous_advance_total:
          type: number
          format: decimal
          nullable: true
          description: |-
            Total amount from the original advance payment invoice (KSeF P_15ZK field).
            Required when `invoice_type_code` is `KOR_ZAL`. Stores the gross total of the ZAL invoice being corrected. Mapped automatically from the invoice's amend reference when generating from an invoice; set explicitly when creating via API.
            Specific to KSeF (Polish tax reporting).
        prepayment_references:
          type: array
          description: |-
            References to advance payment invoices (ZAL) settled by this ROZ invoice. Each entry maps to a `FakturaZaliczkowa` element in the KSeF FA(3) XML.
            Required (non-empty) when `invoice_type_code` is `ROZ` or `KOR_ROZ`. Populated automatically from the invoice's prepayment references when generating from an invoice; set explicitly when creating via API.
            Specific to KSeF (Polish tax reporting).
          items:
            type: object
            properties:
              id:
                type: integer
                readOnly: true
                description: Internal identifier of the reference.
              number:
                type: string
                nullable: true
                description: Invoice number of the advance payment invoice (KSeF NrFaZaliczkowej). Required when `registration_code` is absent.
              registration_code:
                type: string
                nullable: true
                description: KSeF registration number of the advance payment invoice (KSeF NrKSeFFaZaliczkowej). Required when `number` is absent.
              _destroy:
                type: boolean
                writeOnly: true
                description: Set to `true` to delete this reference (use with `id`).
        payment_account_name:
          type: string
          nullable: true
          description: |-
            Name of the payment account holder.
            Specific to KSeF (Polish tax reporting).
        purchase_order_reference:
          type: string
          nullable: true
          description: |-
            Purchase order reference number.
            Specific to KSeF (Polish tax reporting).
        sales_order_reference:
          type: string
          nullable: true
          description: |-
            Sales order reference number.
            Specific to KSeF (Polish tax reporting).
        purchase_order_date:
          type: string
          format: date
          nullable: true
          example: '2025-04-10'
          description: |-
            Purchase order date (BT-92).
            Specific to KSeF (Polish tax reporting).
        despatch_advice_reference:
          type: string
          nullable: true
          description: |-
            Despatch advice reference number (BT-16).
            Specific to KSeF (Polish tax reporting).
        tax_inclusive_amount_before_allowances_and_charges:
          type: number
          format: decimal
          nullable: true
          description: |-
            Total amount including taxes, calculated before applying document-level allowances and charges.
            Specific to KSeF (Polish tax reporting).
        customer_party_jst:
          type: boolean
          default: false
          description: |-
            KSeF Podmiot2 JST flag (Jednostka Samorządu Terytorialnego — Subordinate Local Government Unit).
            true: The buyer is a subordinate local government unit (requires Podmiot3 role=8). false: Does not apply (default).
            Specific to KSeF (Polish tax reporting).
        customer_party_gv:
          type: boolean
          default: false
          description: |-
            KSeF Podmiot2 GV flag (Grupa VAT — VAT Group Member).
            true: The buyer is a member of a VAT group (requires Podmiot3 role=10). false: Does not apply (default).
            Specific to KSeF (Polish tax reporting).
        exchange_rate:
          type: number
          format: decimal
          nullable: true
          description: |-
            Exchange rate used for currency conversion when the invoice currency differs from the  tax authority's local currency (e.g., EUR invoice in Poland where local currency is PLN).
            For KSeF (Poland): Required when invoice currency is not PLN.
          example: 4.5123
        exchange_date:
          type: string
          format: date
          nullable: true
          description: Date of the exchange rate used for currency conversion.
          example: '2025-04-10'
        tax_breakdowns:
          type: array
          description: One or more tax breakdowns ("Desglose IVA" in Verifactu)
          items:
            $ref: '#/components/schemas/TaxBreakdowns'
        tax_report_lines:
          type: array
          description: One or more tax report lines. This is used when creating TicketBAI and KSeF Tax Reports.
          items:
            $ref: '#/components/schemas/TaxReportLine'
        allowance_charges:
          type: array
          description: One or more allowance charges. This is used when creating KSeF Tax Reports.
          items:
            $ref: '#/components/schemas/AllowanceCharge'
    VerifactuTaxReportPatch:
      type: object
      additionalProperties: false
      required:
        - tax_report
      properties:
        tax_report:
          type: object
          additionalProperties: false
          description: Fields allowed to correct a Verifactu Tax Report.
          properties:
            description:
              type: string
              nullable: true
              description: Operation description (internal field).
            customer_party_tax_id:
              type: string
              example: B63354243
            customer_party_tax_scheme:
              type: string
              nullable: true
            customer_party_country:
              type: string
              example: es
            previously_refused:
              type: string
              example: S
            tax_breakdowns:
              type: array
              nullable: true
              description: Tax breakdown corrections (only codification fields are correctable).
              items:
                type: object
                additionalProperties: false
                required:
                  - id
                properties:
                  id:
                    type: integer
                    description: Existing tax breakdown id to correct.
                  non_exemption_code:
                    type: string
                    example: S1
                  exemption_code:
                    type: string
                    nullable: true
                    enum:
                      - E1
                      - E2
                      - E3
                      - E4
                      - E5
                      - E6
                    description: |
                      Reason code for VAT Exemption. 
                      [Verifactu and TicketBAI codes](https://developer.b2brouter.net/docs/verifactu#exemption-codes).

                      This field is required when `exempt` is set to true.
                  no_subject_code:
                    type: string
                    nullable: true
                    enum:
                      - N1
                      - N2
                    description: |
                      Reason code for No Suject. 
                      - [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#non-subject-codes)
                      This field is required when `no_subject` is set to true.
                  special_regime_key:
                    type: string
                    example: '01'
                    nullable: true
                  category:
                    type: string
                    enum:
                      - E
                      - NS
                      - Z
                      - S
                      - H
                      - AA
                      - AAA
                      - AE
                      - G
                      - O
                      - K
                    example: S
                    description: |
                      Taxes categories
                       * `E` - Exempt
                       * `NS` - NotSubject
                       * `Z` - ZeroRated
                       * `S` - Standard
                       * `H` - High Rate
                       * `AA` - Low Rate
                       * `AAA` - Super Low Rate
                       * `AE` - Reverse
                       * `G` - Free export item, VAT not charged
                       * `O` - Services outside scope of tax
                       * `K` - VAT exempt for EEA intra-community supply of goods and services
    ExternalCompanyTransportProperties:
      properties:
        transport_type_code:
          $ref: '#/components/schemas/TransportTypeCode'
        document_type_code:
          $ref: '#/components/schemas/DocumentTypeCode'
        other_document_type_codes:
          type: array
          description: Other document types that the Company can receive
          items:
            type: string
    DirectoryOrgUnits:
      type: object
      description: Organizational unit or Office that belongs to Company
      properties:
        name:
          type: string
          example: Ayuntamiento de Madrid
          description: The name of the office.
        address:
          type: string
          example: CALLE MONTALBAN, 1
          description: Office address.
          nullable: true
        address2:
          type: string
          example: CALLE MONTALBAN, 1
          description: Office additional address.
          nullable: true
        city:
          type: string
          example: Madrid
          description: City name.
        postalcode:
          type: string
          example: '28014'
          description: Postal code. Zip code for USA and Canada
        province:
          type: string
          example: Madrid
        country:
          type: string
          example: es
          description: Country name to which the office belongs.
        routing_codes:
          type: object
          description: Routing codes for the office Company
          properties:
            cin1_scheme:
              type: string
              nullable: true
              example: '9920'
            cin1_value:
              type: string
              nullable: true
              example: '12345678'
            cin2_scheme:
              type: string
              nullable: true
              example: '9920'
            cin2_value:
              type: string
              nullable: true
              example: '12345678'
            cin3_scheme:
              type: string
              nullable: true
              example: '9920'
            cin3_value:
              type: string
              nullable: true
              example: '12345678'
            cin4_scheme:
              type: string
              nullable: true
              example: '9920'
            cin4_value:
              type: string
              nullable: true
              example: '12345678'
            cin5_scheme:
              type: string
              nullable: true
              example: '9920'
            cin5_value:
              type: string
              nullable: true
              example: '12345678'
        required_fields:
          type: array
          description: Fields that are required for the invoice to send to the Company
          items:
            type: string
            example: cin1_scheme
    ExternalCompany:
      type: object
      description: Company from Directory
      properties:
        name:
          type: string
          example: Ayuntamiento de Madrid
          description: The name of the company.
        email:
          type: string
          nullable: true
          example: info@madrid.es
          description: The email of the company.
        website:
          type: string
          example: www.madrid.es
          description: Website address
          nullable: true
        address:
          type: string
          example: CALLE MONTALBAN, 1
          description: Company address.
          nullable: true
        address2:
          type: string
          example: CALLE MONTALBAN, 1
          description: Company additional address.
          nullable: true
        city:
          type: string
          example: Madrid
          description: City name.
          nullable: true
        postalcode:
          type: string
          example: '28014'
          description: Postal code. Zip code for USA and Canada
          nullable: true
        province:
          type: string
          example: Madrid
          nullable: true
        country:
          type: string
          example: es
          description: Country name to which the company belongs.
        language:
          type: string
          nullable: true
          example: es
          maxLength: 2
          description: Contact language.
        currency:
          type: string
          nullable: true
          example: EUR
        tin_scheme:
          type: string
          nullable: true
          example: '9920'
          description: Scheme for the Tax Identification Number
        tin_value:
          type: string
          nullable: true
          example: ESP2807900B
          description: Tax Identification Number
        cin_scheme:
          type: string
          example: '9920'
          description: Scheme for the Company Identification Number
          nullable: true
        cin_value:
          type: string
          example: ESP2807900B
          description: Company Identification Number
          nullable: true
        pin_scheme:
          type: string
          example: '9920'
          description: Scheme for the Peppol Identification Number
          nullable: true
        pin_value:
          type: string
          example: ESP2807900B
          description: Peppol Identification Number
          nullable: true
        invoice:
          type: object
          description: Defines the transport type and document type for sending invoices to the Company
          properties:
            transport_type_code:
              type: string
              nullable: true
              example: peppol
              description: Transport type code defined for the Company
            document_type_code:
              type: string
              nullable: true
              example: xml.ubl.invoice.bis3
              description: Document type code defined for the Company
            other_document_type_codes:
              type: array
              items:
                type: string
                example: xml.ubl.invoice.pint.billing.aunz.v1
        credit_note:
          allOf:
            - type: object
            - description: Defines the transport type and document type for sending credit notes to the Company
            - $ref: '#/components/schemas/ExternalCompanyTransportProperties'
        application_response:
          allOf:
            - type: object
            - description: Defines the transport type and document type for sending application responses to the Company
            - $ref: '#/components/schemas/ExternalCompanyTransportProperties'
        order:
          allOf:
            - type: object
            - description: Defines the transport type and document type for sending orders to the Company
            - $ref: '#/components/schemas/ExternalCompanyTransportProperties'
        order_response:
          allOf:
            - type: object
            - description: Defines the transport type and document type for sending order responses to the Company
            - $ref: '#/components/schemas/ExternalCompanyTransportProperties'
        despatch_advice:
          allOf:
            - type: object
            - description: Defines the transport type and document type for sending despatch advices to the Company
            - $ref: '#/components/schemas/ExternalCompanyTransportProperties'
        despatch_advice_response:
          allOf:
            - type: object
            - description: Defines the transport type and document type for sending despatch advice responses to the Company
            - $ref: '#/components/schemas/ExternalCompanyTransportProperties'
        information_notes:
          type: object
          description: Information notes, can be shown in different languages
          properties:
            language:
              type: string
              description: The content of the information note on the where language is the key
        routing_codes:
          type: object
          description: Routing codes for the parent Company
          properties:
            cin1_scheme:
              type: string
              nullable: true
              example: '9920'
            cin1_value:
              type: string
              nullable: true
              example: '12345678'
            cin2_scheme:
              type: string
              nullable: true
              example: '9920'
            cin2_value:
              type: string
              nullable: true
              example: '12345678'
            cin3_scheme:
              type: string
              nullable: true
              example: '9920'
            cin3_value:
              type: string
              nullable: true
              example: '12345678'
            cin4_scheme:
              type: string
              nullable: true
              example: '9920'
            cin4_value:
              type: string
              nullable: true
              example: '12345678'
            cin5_scheme:
              type: string
              nullable: true
              example: '9920'
            cin5_value:
              type: string
              nullable: true
              example: '12345678'
        required_fields:
          type: array
          description: Fields that are required for the invoice to send to the Company
          items:
            type: string
            example: cin1_scheme
        organizational_units:
          type: array
          description: Organizational units or Offices that Company has.
          items:
            $ref: '#/components/schemas/DirectoryOrgUnits'
    TinVerificationResult:
      type: object
      description: Result of a single TIN+name verification against a tax authority census.
      properties:
        tin:
          type: string
          description: The original TIN value as submitted in the request.
          example: ESB86561412
        normalized_tin:
          type: string
          nullable: true
          description: The TIN after normalization (country prefix stripped, uppercased). Used internally for census lookup.
          example: B86561412
        name:
          type: string
          description: The entity name. If the tax authority returned a canonical name, it is used here instead of the original input.
          example: EMPRESA EXEMPLE SA
        tin_format_valid:
          type: boolean
          nullable: true
          description: Whether the TIN passes format and checksum validation for the given country's scheme. False means the TIN is syntactically invalid.
          example: true
        census_match:
          type: boolean
          nullable: true
          description: |-
            Whether the TIN+name pair was found in the tax authority's census. - `true`: The entity is registered in the census. - `false`: Not registered, or the TIN format is invalid. - `null`: Not yet processed (request still pending or failed before
              this item was reached).
          example: true
      required:
        - tin
        - tin_format_valid
        - census_match
    TinVerificationRequest:
      type: object
      description: A batch TIN verification request with its current status and results.
      properties:
        id:
          type: integer
          description: Unique identifier of the TIN verification request.
          example: 42
        status:
          type: string
          description: 'Current processing status of the request. - `pending`: Request created, not yet processing. - `processing`: Background job is running. - `success`: All verifications completed successfully. - `failed`: An error occurred during processing.'
          enum:
            - pending
            - processing
            - success
            - failed
          example: success
        results:
          type: array
          description: Verification results for each TIN+name pair. Empty while status is `pending` or `processing`.
          items:
            $ref: '#/components/schemas/TinVerificationResult'
        error_message:
          type: string
          nullable: true
          description: Error description when status is `failed`. Null otherwise.
          example: null
      required:
        - id
        - status
        - results
    WebHookEvent:
      type: string
      description: |
        Identifier of an event type a Web Hook can subscribe to.
      enum:
        - issued_invoice.state_change
        - received_invoice.state_change
        - received_invoice.created
        - tax_report.state_change
        - ledger.state_change
        - tin_verification.finished
        - sii_batch.finished
        - invoice_import.finished
    WebHook:
      type: object
      description: Represents a Web Hook configuration used to receive event notifications from the platform.
      properties:
        id:
          type: integer
          example: 123
          description: |
            An internal identifier that is unique to each **Web Hook** within B2Brouter.
          readOnly: true
        url:
          type: string
          format: uri
          example: https://example.com/webhooks/b2brouter
          maxLength: 512
          description: |
            The public HTTPS endpoint where event notifications will be delivered.
            The URL must be publicly accessible and cannot point to private or internal networks.
        description:
          type: string
          example: Webhook for tax report state changes
          nullable: true
          maxLength: 255
          description: |
            A human-readable description of the Web Hook, useful for identification and management purposes.
        enabled:
          type: boolean
          example: true
          default: true
          description: |
            Indicates whether the Web Hook is active.
            Disabled Web Hooks will not receive any event notifications.
        events:
          type: array
          description: |
            List of events this Web Hook is subscribed to.
            Notifications will be sent only when one of these events occurs.
          items:
            $ref: '#/components/schemas/WebHookEvent'
          example:
            - tax_report.state_change
            - issued_invoice.state_change
        signing_secret:
          type: string
          example: F8k2Pz9QxL7mN4YbA1CDeR5T6uVwEJHs
          description: |
            Secret used to sign Web Hook requests sent to the configured URL.
            This value is returned **only when the Web Hook is created** and should be stored securely.
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2025-04-10T10:14:21.157690Z'
          description: |
            Timestamp indicating when the Web Hook was created.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2025-04-10T10:14:29.259065Z'
          description: |
            Timestamp indicating when the Web Hook was last updated.
          readOnly: true
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
