openapi: 3.1.0
info:
  title: Seqino PDP API
  description: Seqino PDP API - Modern interface to France's e-Invoicing services
  contact:
    name: Seqino
    url: https://pdp.seqino.dev/
  version: 1.0.0
servers:
  - url: https://pdp.seqino.dev/api
    description: Dev server for Beta Testers
paths:
  /clients:
    get:
      tags:
        - 👥 Clients
      summary: 📋 Get all clients
      description: Get all clients with their details.
      operationId: get_clients_clients_get
      responses:
        '200':
          description: List of all clients
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Client'
                type: array
                title: Response Get Clients Clients Get
      security:
        - APIKeyHeader: []
    post:
      tags:
        - 👥 Clients
      summary: ➕ Create a new client
      description: Create a new client with the provided details.
      operationId: create_client_clients_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientCreateRequest'
        required: true
      responses:
        '201':
          description: Client created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Client with this external_ref already exists for this sponsor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
  /clients/{client_id}:
    delete:
      tags:
        - 👥 Clients
      summary: 🗑️ Delete a client
      description: >-
        Delete a client by ID.


        **Important:** A client can only be deleted if they have no associated
        mandates.

        Delete all mandates for this client first before attempting to delete
        the client.
      operationId: delete_client_clients__client_id__delete
      security:
        - APIKeyHeader: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            title: Client Id
      responses:
        '204':
          description: Client deleted successfully
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot delete client with associated mandates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /clients/onboarding-link:
    post:
      tags:
        - 👥 Clients
      summary: 🔗 Generate onboarding link for a client
      description: |-
        Generate an onboarding link for a specific client.

        The onboarding experience can be customized with:
        - **include_kyc**: Add a Know Your Customer verification step
        - **include_signature**: Require electronic signature of the PDP mandate

        The generated link is time-limited and client-specific.
      operationId: generate_client_onboarding_link_clients_onboarding_link_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingLinkRequest'
        required: true
      responses:
        '201':
          description: Onboarding link generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Client not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
  /clients/onboarding-link/status:
    get:
      tags:
        - 👥 Clients
      summary: 📊 Get onboarding link status
      description: >-
        Get the status of an onboarding link for a client.


        Returns the current progress including KYC and signature completion
        status.
      operationId: get_client_onboarding_link_status_clients_onboarding_link_status_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: link_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Link Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingLinkStatusResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Onboarding link not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /clients/pdp-clients:
    post:
      tags:
        - 👥 Clients
      summary: ➕ Create new PDP client
      description: >-
        Create a new PDP client and associate it with an external reference.


        This endpoint allows you to create new PDP client IDs that can be used

        with other API endpoints. Each client is associated with an external
        reference

        for easy identification in your systems.


        **Note:** This endpoint does not require the X-PDP-Client-ID header
        since

        it's used to create new client IDs.
      operationId: create_pdp_client_clients_pdp_clients_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdpClientCreateRequest'
        required: true
      responses:
        '201':
          description: PDP client created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdpClientCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: External reference already exists
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
  /mandates:
    get:
      tags:
        - 📋 Mandates
      summary: 📋 Get client mandates
      description: |-
        Get all mandates for a client with their directory information.

        Returns a list of mandates with their associated directory entries,
        including routing information and establishment details.
      operationId: get_client_mandates_mandates_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: status_filter
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/MandateStatus'
              - type: 'null'
            description: Filter by mandate status
            title: Status Filter
          description: Filter by mandate status
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: List of client mandates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Mandate'
                title: Response Get Client Mandates Mandates Get
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - 📋 Mandates
      summary: 📋 Create mandate with directory entry
      description: |-
        Create a new mandate with its associated directory entry.

        This endpoint creates both:
        1. A directory entry for routing invoices to the company
        2. A mandate granting permission to manage invoices for this entity

        The mandate defines the scope of operations the sponsor can perform
        for this legal entity (SIREN, SIRET, or routing code level).
      operationId: create_mandate_mandates_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MandateCreateRequest'
      responses:
        '201':
          description: Mandate created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateResponse'
        '400':
          description: Invalid request data or constraint violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Directory entry already exists
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /mandates/{mandate_id}:
    get:
      tags:
        - 📋 Mandates
      summary: 📋 Get mandate details
      description: Get detailed information about a specific mandate.
      operationId: get_mandate_details_mandates__mandate_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: mandate_id
          in: path
          required: true
          schema:
            type: string
            description: Mandate ID
            title: Mandate Id
          description: Mandate ID
        - name: X-PDP-Client-Id
          in: header
          required: false
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Mandate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mandate'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - 📋 Mandates
      summary: 📋 Revoke mandate
      description: >-
        Revoke a mandate.


        This action permanently deletes the mandate, revoking the sponsor's
        permission to manage

        invoices for this entity. The associated directory entry remains active

        but the sponsor can no longer perform operations on behalf of this
        entity.
      operationId: revoke_mandate_mandates__mandate_id__delete
      security:
        - APIKeyHeader: []
      parameters:
        - name: mandate_id
          in: path
          required: true
          schema:
            type: string
            description: Mandate ID
            title: Mandate Id
          description: Mandate ID
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '204':
          description: Mandate revoked successfully
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /mandates/batch:
    post:
      tags:
        - 📋 Mandates
      summary: 📋 Create multiple mandates
      description: |-
        Create multiple mandates in a single batch operation.

        This endpoint allows creating multiple mandates for a client at once,
        which is useful when onboarding clients with multiple entities or
        when importing existing mandate data.

        All mandates in the batch will use the same client_id from the header.
        If any mandate fails to create, the entire batch will be rolled back.
      operationId: create_mandates_batch_mandates_batch_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchMandateCreateRequest'
      responses:
        '201':
          description: Mandates created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMandateResponse'
        '400':
          description: Invalid request data or constraint violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /mandates/directory/{siren}:
    get:
      tags:
        - 📋 Mandates
      summary: 📘 Get directory entries for SIREN
      description: >-
        Get all directory/routing entries from the directory database for a
        given SIREN.


        This endpoint retrieves routing information for a company identified by
        its SIREN.

        The data includes establishment details and routing configurations for
        electronic invoicing.
      operationId: get_directory_entries_by_siren_mandates_directory__siren__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: siren
          in: path
          required: true
          schema:
            type: string
            description: Company SIREN number
            title: Siren
          description: Company SIREN number
          example: '123456789'
        - name: X-PDP-Client-Id
          in: header
          required: false
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Directory entries found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DirectoryEntry'
                title: >-
                  Response Get Directory Entries By Siren Mandates Directory 
                  Siren  Get
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /drafts:
    post:
      tags:
        - 📝 Drafts
      summary: 🆕 Create invoice draft from EN16931-compatible JSON
      description: |-
        Create a new invoice draft from EN16931-compatible JSON data.

        This endpoint allows you to create a draft invoice that can be validated
        and refined before final submission. Drafts support partial data and
        can be updated multiple times before validation.
      operationId: create_draft_drafts_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceDraftModel-Input'
            example:
              specification_identifier: >-
                urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
              issue_date: '2024-01-15'
              type_code: '380'
              currency_code: EUR
              seller:
                name: Seqino
                postal_address:
                  street_name: 123 Rue de la République
                  city_name: Paris
                  postal_zone: '75001'
                  country_code: FR
                electronic_address:
                  scheme_id: '0088'
                  value: '1234567890123'
                tax_registrations:
                  - scheme_id: VAT
                    value: FR12345678901
                legal_registration_name: Seqino
                trading_name: Seqino Corp
                seller_identifier: SELLER123
                seller_identifier_scheme: GLN
                seller_vat_identifier: FR12345678901
                seller_tax_registration_identifier: SIRET12345678901234
                seller_additional_legal_information: Société par actions simplifiée au capital de 100 000 EUR
              buyer:
                name: Beispiel GmbH
                postal_address:
                  street_name: Musterstraße 42
                  city_name: Berlin
                  postal_zone: '10115'
                  country_code: DE
                tax_registrations:
                  - scheme_id: VAT
                    value: DE123456789
                legal_registration_name: Beispiel GmbH
                buyer_identifier: BUYER456
                buyer_identifier_scheme: GLN
                buyer_legal_registration_identifier: HRB12345
                buyer_vat_identifier: DE123456789
              invoice_lines:
                - line_id: '1'
                  invoiced_quantity: 10
                  unit_of_measure: PCE
                  line_net_amount: 1000
                  item_name: Software License
                  item_description: Enterprise software license for 12 months
                  item_price: 100
                  vat_category_code: S
                  vat_rate: 20
                - line_id: '2'
                  invoiced_quantity: 5
                  unit_of_measure: HUR
                  line_net_amount: 500
                  item_name: Consulting Services
                  item_description: Technical consulting and support
                  item_price: 100
                  vat_category_code: S
                  vat_rate: 20
              vat_breakdowns:
                - category_code: S
                  rate: 20
                  taxable_amount: 1500
                  tax_amount: 300
              document_totals:
                sum_of_line_net_amounts: 1500
                invoice_total_without_vat: 1500
                invoice_total_vat_amount: 300
                invoice_total_with_vat: 1800
                amount_due_for_payment: 1800
              payment_terms:
                description: Payment due within 30 days
                due_date: '2024-02-15'
              order_reference: PO-2024-456
              invoice_note: Sample draft for demonstration purposes
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /drafts/{draft_id}:
    get:
      tags:
        - 📝 Drafts
      summary: 📄 Get details of a draft invoice
      description: >-
        Get the details of a specific draft invoice.


        Returns the complete draft data including all fields and their current
        values.

        This is useful for retrieving draft state before making updates.
      operationId: get_draft_drafts__draft_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: draft_id
          in: path
          required: true
          schema:
            type: string
            title: Draft Id
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDraftModel-Output'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Draft not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
        - 📝 Drafts
      summary: ✏️ Update a draft invoice
      description: |-
        Update an existing draft invoice.

        Completely replaces the draft content with the provided data.
        The draft will be re-validated after the update.
      operationId: update_draft_drafts__draft_id__put
      security:
        - APIKeyHeader: []
      parameters:
        - name: draft_id
          in: path
          required: true
          schema:
            type: string
            title: Draft Id
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceDraftModel-Input'
            example:
              specification_identifier: >-
                urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
              issue_date: '2024-01-15'
              type_code: '380'
              currency_code: EUR
              seller:
                name: Seqino
                postal_address:
                  street_name: 123 Rue de la République
                  city_name: Paris
                  postal_zone: '75001'
                  country_code: FR
                electronic_address:
                  scheme_id: '0088'
                  value: '1234567890123'
                tax_registrations:
                  - scheme_id: VAT
                    value: FR12345678901
                legal_registration_name: Seqino
                trading_name: Seqino Corp
                seller_identifier: SELLER123
                seller_identifier_scheme: GLN
                seller_vat_identifier: FR12345678901
                seller_tax_registration_identifier: SIRET12345678901234
                seller_additional_legal_information: Société par actions simplifiée au capital de 100 000 EUR
              buyer:
                name: Beispiel GmbH
                postal_address:
                  street_name: Musterstraße 42
                  city_name: Berlin
                  postal_zone: '10115'
                  country_code: DE
                tax_registrations:
                  - scheme_id: VAT
                    value: DE123456789
                legal_registration_name: Beispiel GmbH
                buyer_identifier: BUYER456
                buyer_identifier_scheme: GLN
                buyer_legal_registration_identifier: HRB12345
                buyer_vat_identifier: DE123456789
              invoice_lines:
                - line_id: '1'
                  invoiced_quantity: 10
                  unit_of_measure: PCE
                  line_net_amount: 1000
                  item_name: Software License
                  item_description: Enterprise software license for 12 months
                  item_price: 100
                  vat_category_code: S
                  vat_rate: 20
                - line_id: '2'
                  invoiced_quantity: 5
                  unit_of_measure: HUR
                  line_net_amount: 500
                  item_name: Consulting Services
                  item_description: Technical consulting and support
                  item_price: 100
                  vat_category_code: S
                  vat_rate: 20
              vat_breakdowns:
                - category_code: S
                  rate: 20
                  taxable_amount: 1500
                  tax_amount: 300
              document_totals:
                sum_of_line_net_amounts: 1500
                invoice_total_without_vat: 1500
                invoice_total_vat_amount: 300
                invoice_total_with_vat: 1800
                amount_due_for_payment: 1800
              payment_terms:
                description: Payment due within 30 days
                due_date: '2024-02-15'
              order_reference: PO-2024-456
              invoice_note: Sample draft for demonstration purposes
      responses:
        '200':
          description: Draft updated successfully
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Draft not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - 📝 Drafts
      summary: 🗑️ Delete an invoice draft
      description: >-
        Delete a draft invoice.


        Permanently removes the draft from the system. This action cannot be
        undone.

        Once deleted, the draft_id becomes invalid and cannot be reused.
      operationId: delete_draft_drafts__draft_id__delete
      security:
        - APIKeyHeader: []
      parameters:
        - name: draft_id
          in: path
          required: true
          schema:
            type: string
            title: Draft Id
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Draft not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /drafts/{draft_id}/validate:
    post:
      tags:
        - 📝 Drafts
      summary: ✅ Validate a draft and submit as invoice
      description: >-
        Validate a draft and convert it to a structured invoice in the specified
        format.


        This endpoint performs comprehensive validation and converts the draft

        into a final invoice that will be submitted to the PPF platform.

        After successful validation, the draft becomes immutable.
      operationId: validate_draft_drafts__draft_id__validate_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: draft_id
          in: path
          required: true
          schema:
            type: string
            title: Draft Id
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateRequest'
            example:
              format: ubl
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Draft not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /drafts/validate-data:
    post:
      tags:
        - 📝 Drafts
      summary: 🔍 Validate invoice data without creating draft
      description: >-
        Validate invoice data against EN16931 requirements without creating a
        draft.


        Returns detailed validation results with specific error messages and
        suggestions.

        This endpoint helps identify issues before submitting invoice data.


        Use this for:

        - Pre-validation before creating a draft

        - Checking data quality during form input

        - Understanding validation requirements
      operationId: validate_invoice_data_drafts_validate_data_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationOnlyRequest'
            example:
              invoice_data:
                specification_identifier: >-
                  urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
                issue_date: '2024-01-15'
                type_code: '380'
                currency_code: EUR
                seller:
                  name: Seqino
                  postal_address:
                    street_name: 123 Rue de la République
                    city_name: Paris
                    postal_zone: '75001'
                    country_code: FR
                  electronic_address:
                    scheme_id: '0088'
                    value: '1234567890123'
                  tax_registrations:
                    - scheme_id: VAT
                      value: FR12345678901
                  legal_registration_name: Seqino
                  trading_name: Seqino Corp
                  seller_identifier: SELLER123
                  seller_identifier_scheme: GLN
                  seller_vat_identifier: FR12345678901
                  seller_tax_registration_identifier: SIRET12345678901234
                  seller_additional_legal_information: Société par actions simplifiée au capital de 100 000 EUR
                buyer:
                  name: Beispiel GmbH
                  postal_address:
                    street_name: Musterstraße 42
                    city_name: Berlin
                    postal_zone: '10115'
                    country_code: DE
                  tax_registrations:
                    - scheme_id: VAT
                      value: DE123456789
                  legal_registration_name: Beispiel GmbH
                  buyer_identifier: BUYER456
                  buyer_identifier_scheme: GLN
                  buyer_legal_registration_identifier: HRB12345
                  buyer_vat_identifier: DE123456789
                invoice_lines:
                  - line_id: '1'
                    invoiced_quantity: 10
                    unit_of_measure: PCE
                    line_net_amount: 1000
                    item_name: Software License
                    item_description: Enterprise software license for 12 months
                    item_price: 100
                    vat_category_code: S
                    vat_rate: 20
                  - line_id: '2'
                    invoiced_quantity: 5
                    unit_of_measure: HUR
                    line_net_amount: 500
                    item_name: Consulting Services
                    item_description: Technical consulting and support
                    item_price: 100
                    vat_category_code: S
                    vat_rate: 20
                vat_breakdowns:
                  - category_code: S
                    rate: 20
                    taxable_amount: 1500
                    tax_amount: 300
                document_totals:
                  sum_of_line_net_amounts: 1500
                  invoice_total_without_vat: 1500
                  invoice_total_vat_amount: 300
                  invoice_total_with_vat: 1800
                  amount_due_for_payment: 1800
                payment_terms:
                  description: Payment due within 30 days
                  due_date: '2024-02-15'
                order_reference: PO-2024-456
                invoice_note: Sample draft for demonstration purposes
              strict_mode: true
      responses:
        '200':
          description: Validation completed (may contain errors)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /directory/{siren}:
    get:
      tags:
        - 📘 Directory
      summary: 📘 Get directory entry by SIREN
      description: Get a directory entry by company ID (SIREN).
      operationId: get_directory_entry_directory__siren__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: siren
          in: path
          required: true
          schema:
            type: string
            title: Siren
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryEntry'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Directory entry not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /invoicing/invoice_data/{invoice_id}:
    get:
      tags:
        - 🧾 Invoicing
      summary: 📄 Get complete invoice data by ID
      description: >-
        Get the complete EN16931-compliant invoice data by ID.


        Returns the full invoice with all EN16931 business terms populated.

        This endpoint provides the structured data representation of the
        invoice.
      operationId: get_invoice_data_invoicing_invoice_data__invoice_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: invoice_id
          in: path
          required: true
          schema:
            type: string
            title: Invoice Id
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EN16931InvoiceModel'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Invoice not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /invoicing/invoices/{invoice_id}:
    get:
      tags:
        - 🧾 Invoicing
      summary: 📄 Get invoice file download links
      description: >-
        Get download links for invoice files in various e-invoicing formats.


        Returns signed S3 download URLs for the invoice in the requested
        format(s).

        If no format is specified, returns links for all available formats.


        Supported formats:

        - facturx: FacturX PDF with embedded XML (French standard)

        - ubl: Universal Business Language XML

        - cii: Cross Industry Invoice XML


        Args:
            invoice_id: The invoice ID to get download links for
            format: Optional specific format to get download link for

        Returns:
            InvoiceDownloadResponse with signed download URLs
      operationId: get_invoice_download_links_invoicing_invoices__invoice_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: invoice_id
          in: path
          required: true
          schema:
            type: string
            title: Invoice Id
        - name: format
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/EInvoicingFormat'
              - type: 'null'
            title: Format
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDownloadResponse'
        '400':
          description: Invalid format parameter
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Invoice not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /invoicing/invoices:
    get:
      tags:
        - 🧾 Invoicing
      summary: 🔍 List invoices with filtering
      description: >-
        List invoices with time-based filtering options.


        This endpoint allows you to query invoices using various time-based
        filters

        to find invoices that match your criteria.


        Args:
            updated_after: ISO timestamp to get invoices updated after this time
            updated_before: ISO timestamp to get invoices updated before this time
            created_after: ISO timestamp to get invoices created after this time
            created_before: ISO timestamp to get invoices created before this time
            limit: Maximum number of invoices to return (default: 50, max: 100)
            offset: Number of invoices to skip for pagination (default: 0)

        Returns:
            List of invoices with metadata including timestamps and status
      operationId: list_invoices_invoicing_invoices_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: updated_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Updated After
        - name: updated_before
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Updated Before
        - name: created_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Created After
        - name: created_before
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Created Before
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            title: Offset
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: List of invoices matching filters
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Invoices Invoicing Invoices Get
        '400':
          description: Invalid filter parameters
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /invoicing/files/submit:
    post:
      tags:
        - 🧾 Invoicing
      summary: 📄 Submit invoice file (FacturX, UBL, CII)
      description: >-
        Submit an invoice file for processing.


        Supports multiple e-invoicing formats:

        - FacturX: Franco-German standard with embedded XML in PDF

        - UBL: Universal Business Language XML

        - CII: Cross Industry Invoice XML


        The endpoint automatically detects the format and processes accordingly.

        The returned `invoice_id` can be used with `/lifecycle-events` to track
        lifecycle updates.
      operationId: submit_invoice_file_invoicing_files_submit_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_submit_invoice_file_invoicing_files_submit_post
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileSubmissionResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Invalid file format
  /invoicing/files/validate:
    post:
      tags:
        - 🧾 Invoicing
      summary: ✅ Validate invoice file (FacturX, UBL, CII)
      description: >-
        Validate an invoice file without submitting it for processing.


        Supports validation of multiple e-invoicing formats:

        - FacturX: Validates PDF structure and embedded XML against FacturX
        standards

        - UBL: Validates XML against UBL schema

        - CII: Validates XML against Cross Industry Invoice schema


        All formats are checked for EN16931 compliance.

        Returns detailed validation results with specific error messages and
        suggestions.
      operationId: validate_invoice_file_invoicing_files_validate_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_validate_invoice_file_invoicing_files_validate_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileValidationResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Invalid file format
  /lifecycle-events:
    get:
      tags:
        - 🔄 Lifecycle
      summary: 📊 Get lifecycle events
      description: |-
        Get lifecycle events with optional filtering.

        - Without parameters: Returns all lifecycle events for the PDP client
        - With object_type only: Returns all events for that object type
        - With both parameters: Returns events for a specific object

        Use `invoice` for both structured and exempt invoices.
      operationId: get_lifecycle_events_lifecycle_events_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: object_type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ObjectType'
            description: Filter by object type
          description: Filter by object type
        - name: object_id
          in: query
          required: false
          schema:
            type: string
            description: Filter by object ID
            title: Object Id
          description: Filter by object ID
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LifecycleEvent'
                title: Response Get Lifecycle Events Lifecycle Events Get
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /reporting/exempt-invoices:
    post:
      tags:
        - 📊 Reporting
      summary: 🌍 Submit exempt invoice (international B2B/B2C)
      description: >-
        Submit an exempt invoice for international B2B/B2C transactions.


        This endpoint is used for e-reporting individual international invoices

        that are exempt from mandatory electronic invoice exchange but still

        require reporting to the government system via F10 flow.


        The returned `invoice_id` can be used with `/lifecycle-events` to track
        lifecycle updates.
      operationId: submit_exempt_invoice_reporting_exempt_invoices_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExemptInvoiceRequest'
            example:
              direction: outgoing
              country_code: DE
              model:
                specification_identifier: >-
                  urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
                issue_date: '2024-01-15'
                type_code: '380'
                currency_code: EUR
                seller:
                  name: Seqino
                  postal_address:
                    street_name: 123 Rue de la République
                    city_name: Paris
                    postal_zone: '75001'
                    country_code: FR
                  electronic_address:
                    scheme_id: '0088'
                    value: '1234567890123'
                  tax_registrations:
                    - scheme_id: VAT
                      value: FR12345678901
                  legal_registration_name: Seqino
                  trading_name: Seqino Corp
                  seller_identifier: SELLER123
                  seller_identifier_scheme: GLN
                  seller_vat_identifier: FR12345678901
                  seller_tax_registration_identifier: SIRET12345678901234
                  seller_additional_legal_information: Société par actions simplifiée au capital de 100 000 EUR
                buyer:
                  name: Beispiel GmbH
                  postal_address:
                    street_name: Musterstraße 42
                    city_name: Berlin
                    postal_zone: '10115'
                    country_code: DE
                  tax_registrations:
                    - scheme_id: VAT
                      value: DE123456789
                  legal_registration_name: Beispiel GmbH
                  buyer_identifier: BUYER456
                  buyer_identifier_scheme: GLN
                  buyer_legal_registration_identifier: HRB12345
                  buyer_vat_identifier: DE123456789
                invoice_lines:
                  - line_id: '1'
                    invoiced_quantity: 10
                    unit_of_measure: PCE
                    line_net_amount: 1000
                    item_name: Software License
                    item_description: Enterprise software license for 12 months
                    item_price: 100
                    vat_category_code: S
                    vat_rate: 20
                  - line_id: '2'
                    invoiced_quantity: 5
                    unit_of_measure: HUR
                    line_net_amount: 500
                    item_name: Consulting Services
                    item_description: Technical consulting and support
                    item_price: 100
                    vat_category_code: S
                    vat_rate: 20
                vat_breakdowns:
                  - category_code: S
                    rate: 20
                    taxable_amount: 1500
                    tax_amount: 300
                document_totals:
                  sum_of_line_net_amounts: 1500
                  invoice_total_without_vat: 1500
                  invoice_total_vat_amount: 300
                  invoice_total_with_vat: 1800
                  amount_due_for_payment: 1800
                payment_terms:
                  description: Payment due within 30 days
                  due_date: '2024-02-15'
                order_reference: PO-2024-456
                invoice_note: Sample draft for demonstration purposes
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /reporting/b2c-transactions:
    post:
      tags:
        - 📊 Reporting
      summary: 📊 Submit B2C transaction data (daily aggregate)
      description: >-
        Submit aggregated B2C transaction data for a specific date.


        This endpoint collects daily B2C transaction summaries that will be

        processed into F10 format for government e-reporting. Data should be

        aggregated by category (goods vs services) and VAT rate.


        Required for domestic B2C operations under French e-invoicing
        regulation.

        Data is reported as daily totals rather than individual transactions.


        Args:
            transaction_date: Date of the transactions (YYYY-MM-DD)
            currency: Transaction currency (typically EUR)
            store_location: Optional store/location identifier
            goods_sales: Aggregated data for goods sales (TLB1 category)
            services: Aggregated data for services (TPS1 category)

        Returns:
            Confirmation of submission with reference ID for tracking
      operationId: submit_b2c_transactions_reporting_b2c_transactions_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Request
            example:
              transaction_date: '2024-01-15'
              currency: EUR
              store_location: Paris - Champs Elysées
              goods_sales:
                tax_exclusive_amount: 5000
                tax_amount: 1000
                tax_rate: 20
                transaction_count: 150
                payment_data:
                  cash_amount: 1500
                  card_amount: 4500
                  payment_date: '2024-01-15'
              services:
                tax_exclusive_amount: 2000
                tax_amount: 400
                tax_rate: 20
                transaction_count: 75
                payment_data:
                  cash_amount: 500
                  card_amount: 1900
                  payment_date: '2024-01-15'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: >-
                  Response Submit B2C Transactions Reporting B2C Transactions
                  Post
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
  /reporting/payments:
    post:
      tags:
        - 📊 Reporting
      summary: 💰 Record payment received
      description: Record a payment received by the client.
      operationId: record_payment_reporting_payments_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
    get:
      tags:
        - 📊 Reporting
      summary: 💰 Get client payments
      description: Get all payments for a client in a specific period.
      operationId: get_payments_reporting_payments_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: client_siren
          in: query
          required: true
          schema:
            type: string
            pattern: ^\d{9}$
            description: Client's SIREN number
            title: Client Siren
          description: Client's SIREN number
        - name: period
          in: query
          required: true
          schema:
            type: string
            pattern: ^\d{4}-\d{2}$
            description: Period (YYYY-MM)
            title: Period
          description: Period (YYYY-MM)
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentResponse'
                title: Response Get Payments Reporting Payments Get
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /reporting/payments/{payment_id}:
    put:
      tags:
        - 📊 Reporting
      summary: ✏️ Update payment
      description: Update a payment record.
      operationId: update_payment_reporting_payments__payment_id__put
      security:
        - APIKeyHeader: []
      parameters:
        - name: payment_id
          in: path
          required: true
          schema:
            type: string
            title: Payment Id
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          description: Payment not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage/metrics:
    get:
      tags:
        - 📊 Usage
      summary: 📈 Get usage metrics for a company
      description: Get detailed usage metrics for a company within a specified period.
      operationId: get_usage_metrics_usage_metrics_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/UsagePeriod'
            description: Period for usage metrics
            default: monthly
          description: Period for usage metrics
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: Start date for custom period
            title: Start Date
          description: Start date for custom period
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: End date for custom period
            title: End Date
          description: End date for custom period
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageMetrics'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          description: Access denied for company
        '404':
          description: Company not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage/summary:
    get:
      tags:
        - 📊 Usage
      summary: 📋 Get usage summary for a company
      description: Get a high-level usage summary for a company.
      operationId: get_usage_summary_usage_summary_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummary'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          description: Access denied for company
        '404':
          description: Company not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage/limits:
    get:
      tags:
        - 📊 Usage
      summary: ⚡ Get usage limits and current usage for a company
      description: Get usage limits and current usage statistics for a company.
      operationId: get_usage_limits_usage_limits_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: endpoint
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by specific endpoint
            title: Endpoint
          description: Filter by specific endpoint
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageLimitResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          description: Access denied for company
        '404':
          description: Company not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - 📊 Usage
      summary: ⚙️ Set usage limits for a company endpoint
      description: Set or update usage limits for a specific company endpoint.
      operationId: set_usage_limit_usage_limits_post
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageLimit'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageLimit'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          description: Access denied
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage/alerts:
    get:
      tags:
        - 📊 Usage
      summary: 🚨 Get usage alerts for a company
      description: Get usage alerts and warnings for a company.
      operationId: get_usage_alerts_usage_alerts_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: active_only
          in: query
          required: false
          schema:
            type: boolean
            description: Return only active alerts
            default: true
            title: Active Only
          description: Return only active alerts
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageAlertListResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          description: Access denied for company
        '404':
          description: Company not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage/mandates:
    get:
      tags:
        - 📊 Usage
      summary: 📊 Get mandate statistics
      description: >-
        Get mandate statistics for a sponsor.


        Returns the total number of mandates and average number of mandates per
        client

        for the sponsor identified by the X-PDP-Sponsor-Id header.
      operationId: get_mandate_stats_usage_mandates_get
      responses:
        '200':
          description: Mandate statistics for the sponsor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateStatsResponse'
      security:
        - APIKeyHeader: []
  /usage/clients:
    get:
      tags:
        - 📊 Usage
      summary: 📊 Get client statistics
      description: >-
        Get client statistics for a sponsor.


        Returns the total number of clients for the sponsor identified by the
        X-PDP-Sponsor-Id header.
      operationId: get_client_stats_usage_clients_get
      responses:
        '200':
          description: Client statistics for the sponsor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientStatsResponse'
      security:
        - APIKeyHeader: []
  /settings/periodicity:
    put:
      tags:
        - ⚙️ Settings
      summary: 📅 Set periodicity and VAT regime settings
      description: |-
        Set the VAT regime and periodicity settings for the company.

        VAT regime affects data transmission periodicity:
        - `real_normal_monthly`: Régime réel normal mensuel
        - `real_normal_quarterly`: Régime réel normal trimestriel
        - `simplified`: Régime simplifié d'imposition
        - `franchise`: Franchise en base de TVA
      operationId: set_periodicity_settings_settings_periodicity_put
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeriodicitySettings'
      responses:
        '200':
          description: Periodicity settings saved successfully
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
        - ⚙️ Settings
      summary: 📅 Get periodicity and VAT regime settings
      description: Get the current periodicity and VAT regime settings.
      operationId: get_periodicity_settings_settings_periodicity_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: X-PDP-Client-Id
          in: header
          required: true
          schema:
            type: string
            description: ID of the PDP Client for which the operation is performed
            title: X-Pdp-Client-Id
          description: ID of the PDP Client for which the operation is performed
          examples:
            sandbox:
              summary: Sandbox client
              value: sandbox-client-seqino
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeriodicitySettings'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /health:
    get:
      summary: Health Check
      description: Health check endpoint.
      operationId: health_check_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      servers:
        - url: https://pdp.seqino.dev
components:
  schemas:
    AdministrativeStatus:
      type: string
      enum:
        - A
        - F
      title: AdministrativeStatus
      description: Administrative status of the establishment.
    ApiEndpointUsage:
      properties:
        endpoint:
          type: string
          title: Endpoint
          description: API endpoint path
        method:
          type: string
          title: Method
          description: HTTP method
        call_count:
          type: integer
          minimum: 0
          title: Call Count
          description: Number of calls made
        success_count:
          type: integer
          minimum: 0
          title: Success Count
          description: Number of successful calls (2xx status)
        error_count:
          type: integer
          minimum: 0
          title: Error Count
          description: Number of failed calls (4xx/5xx status)
        avg_response_time_ms:
          type: number
          minimum: 0
          title: Avg Response Time Ms
          description: Average response time in milliseconds
      type: object
      required:
        - endpoint
        - method
        - call_count
        - success_count
        - error_count
        - avg_response_time_ms
      title: ApiEndpointUsage
    BatchMandateCreateRequest:
      properties:
        mandates:
          items:
            $ref: '#/components/schemas/BatchMandateItemRequest'
          type: array
          maxItems: 50
          minItems: 1
          title: Mandates
          description: List of mandates to create
      type: object
      required:
        - mandates
      title: BatchMandateCreateRequest
      description: Request model for creating multiple mandates at once.
    BatchMandateItemRequest:
      properties:
        start_date:
          type: string
          format: date-time
          title: Start Date
          description: When the mandate should become active
          example: '2024-01-15T00:00:00Z'
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Date
          description: When the mandate should expire (optional)
          example: '2024-12-31T23:59:59Z'
        directory_entry:
          $ref: '#/components/schemas/DirectoryEntry'
          description: Directory entry information for the mandated entity
        file_attachment:
          anyOf:
            - type: string
            - type: 'null'
          title: File Attachment
          description: Optional file attachment for the mandate
      type: object
      required:
        - start_date
        - directory_entry
      title: BatchMandateItemRequest
      description: >-
        Request model for individual mandate in batch operation (without
        client_id).
    BatchMandateResponse:
      properties:
        mandates:
          items:
            $ref: '#/components/schemas/Mandate'
          type: array
          title: Mandates
          description: Created mandates
        message:
          type: string
          title: Message
          description: Success message
        created_count:
          type: integer
          title: Created Count
          description: Number of mandates created
      type: object
      required:
        - mandates
        - message
        - created_count
      title: BatchMandateResponse
      description: Response model for batch mandate creation.
    Body_submit_invoice_file_invoicing_files_submit_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: Invoice file (FacturX PDF, UBL XML, CII XML)
      type: object
      required:
        - file
      title: Body_submit_invoice_file_invoicing_files_submit_post
    Body_validate_invoice_file_invoicing_files_validate_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: Invoice file (FacturX PDF, UBL XML, CII XML)
      type: object
      required:
        - file
      title: Body_validate_invoice_file_invoicing_files_validate_post
    Buyer:
      properties:
        name:
          type: string
          title: Name
          description: Party name
        postal_address:
          $ref: '#/components/schemas/models__invoicing__Address'
        electronic_address:
          anyOf:
            - $ref: '#/components/schemas/ElectronicAddress'
            - type: 'null'
        tax_registrations:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaxRegistration'
              type: array
            - type: 'null'
          title: Tax Registrations
        legal_registration_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Legal Registration Name
        trading_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Trading Name
        party_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Party Identifier
          description: Party identifier
        party_identifier_scheme:
          anyOf:
            - type: string
            - type: 'null'
          title: Party Identifier Scheme
          description: Party identifier scheme
        buyer_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Identifier
          description: Buyer identifier (BT-46)
        buyer_identifier_scheme:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Identifier Scheme
          description: Buyer identifier scheme (BT-47)
        buyer_legal_registration_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Legal Registration Identifier
          description: Buyer legal registration identifier (BT-47)
        buyer_vat_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Vat Identifier
          description: Buyer VAT identifier (BT-48)
      type: object
      required:
        - name
        - postal_address
      title: Buyer
      description: Buyer party information (BG-7).
    Client:
      properties:
        client_id:
          type: string
          title: Client Id
          description: Unique client identifier
        organization_name:
          type: string
          title: Organization Name
          description: Name of the organization
        contact_email:
          type: string
          title: Contact Email
          description: Contact email for the organization
        external_ref:
          type: string
          title: External Ref
          description: External reference identifier
        sponsor_id:
          type: string
          title: Sponsor Id
          description: PDP sponsor ID from the X-PDP-Sponsor-Id header
        status:
          $ref: '#/components/schemas/ClientStatus'
          description: Current status of the client
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the client was created
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: When the client was last updated
      type: object
      required:
        - organization_name
        - contact_email
        - external_ref
        - sponsor_id
        - status
        - created_at
      title: Client
      description: Client model with all information.
    ClientCreateRequest:
      properties:
        organization_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Organization Name
          description: Name of the organization
          example: Acme Corporation
        contact_email:
          type: string
          maxLength: 255
          title: Contact Email
          description: Contact email for the organization
          example: contact@acme.com
        external_ref:
          type: string
          maxLength: 100
          minLength: 1
          title: External Ref
          description: External reference identifier
          example: EXT-12345
      type: object
      required:
        - organization_name
        - contact_email
        - external_ref
      title: ClientCreateRequest
      description: Request model for creating a new client.
    ClientResponse:
      properties:
        client:
          $ref: '#/components/schemas/Client'
        message:
          type: string
          title: Message
          description: Response message
          example: Client created successfully
      type: object
      required:
        - client
        - message
      title: ClientResponse
      description: Response model for client operations.
    ClientStatsResponse:
      properties:
        total_clients:
          type: integer
          title: Total Clients
          description: Total number of clients for the sponsor
      type: object
      required:
        - total_clients
      title: ClientStatsResponse
      description: Response model for client statistics.
    ClientStatus:
      type: string
      enum:
        - active
        - inactive
        - pending
        - suspended
      title: ClientStatus
      description: Status of the client.
    Direction:
      type: string
      enum:
        - incoming
        - outgoing
      title: Direction
    DirectoryEntry:
      properties:
        siren:
          type: string
          minLength: 1
          title: Siren
          description: Company identification number (SIREN)
        name:
          type: string
          minLength: 1
          title: Name
          description: Company name
        suffix:
          anyOf:
            - type: string
            - type: 'null'
          title: Suffix
          description: Service suffix - when using simple SIREN+suffix nomenclature
        siret:
          anyOf:
            - type: string
            - type: 'null'
          title: Siret
          description: Establishment identification number (SIRET)
        routing_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Routing Identifier
          description: Routing identifier
        routing_identifier_type:
          anyOf:
            - $ref: '#/components/schemas/RoutingIdentifierType'
            - type: 'null'
          description: Type of routing identifier
        routing_code_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Routing Code Label
          description: Label for the routing code
        establishment_nature:
          anyOf:
            - $ref: '#/components/schemas/EstablishmentNature'
            - type: 'null'
          description: Nature of the establishment
        legal_commitment_management:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Legal Commitment Management
          description: Legal commitment management status
        administrative_status:
          anyOf:
            - $ref: '#/components/schemas/AdministrativeStatus'
            - type: 'null'
          description: Administrative status
        addressable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Addressable
          description: Whether the company is addressable
        address:
          anyOf:
            - $ref: '#/components/schemas/models__directory__Address'
            - type: 'null'
          description: Establishment address
        created_at:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Created At
          description: When the entry was created
        updated_at:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Updated At
          description: When the entry was last updated
      type: object
      required:
        - siren
        - name
      title: DirectoryEntry
      description: Complete directory entry with all information.
    DocumentTotals-Input:
      properties:
        sum_of_line_net_amounts:
          anyOf:
            - type: number
            - type: string
          title: Sum Of Line Net Amounts
          description: Sum of Invoice line net amount (BT-106)
        sum_of_allowances:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Sum Of Allowances
          description: Sum of allowances on document level
        sum_of_charges:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Sum Of Charges
          description: Sum of charges on document level
        invoice_total_without_vat:
          anyOf:
            - type: number
            - type: string
          title: Invoice Total Without Vat
          description: Invoice total amount without VAT (BT-109)
        invoice_total_vat_amount:
          anyOf:
            - type: number
            - type: string
          title: Invoice Total Vat Amount
          description: Invoice total VAT amount (BT-110)
        invoice_total_with_vat:
          anyOf:
            - type: number
            - type: string
          title: Invoice Total With Vat
          description: Invoice total amount with VAT (BT-112)
        paid_amount:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Paid Amount
          description: Paid amount
        rounding_amount:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Rounding Amount
          description: Rounding amount
        amount_due_for_payment:
          anyOf:
            - type: number
            - type: string
          title: Amount Due For Payment
          description: Amount due for payment (BT-115)
      type: object
      required:
        - sum_of_line_net_amounts
        - invoice_total_without_vat
        - invoice_total_vat_amount
        - invoice_total_with_vat
        - amount_due_for_payment
      title: DocumentTotals
    DocumentTotals-Output:
      properties:
        sum_of_line_net_amounts:
          type: string
          title: Sum Of Line Net Amounts
          description: Sum of Invoice line net amount (BT-106)
        sum_of_allowances:
          anyOf:
            - type: string
            - type: 'null'
          title: Sum Of Allowances
          description: Sum of allowances on document level
        sum_of_charges:
          anyOf:
            - type: string
            - type: 'null'
          title: Sum Of Charges
          description: Sum of charges on document level
        invoice_total_without_vat:
          type: string
          title: Invoice Total Without Vat
          description: Invoice total amount without VAT (BT-109)
        invoice_total_vat_amount:
          type: string
          title: Invoice Total Vat Amount
          description: Invoice total VAT amount (BT-110)
        invoice_total_with_vat:
          type: string
          title: Invoice Total With Vat
          description: Invoice total amount with VAT (BT-112)
        paid_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Paid Amount
          description: Paid amount
        rounding_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Rounding Amount
          description: Rounding amount
        amount_due_for_payment:
          type: string
          title: Amount Due For Payment
          description: Amount due for payment (BT-115)
      type: object
      required:
        - sum_of_line_net_amounts
        - invoice_total_without_vat
        - invoice_total_vat_amount
        - invoice_total_with_vat
        - amount_due_for_payment
      title: DocumentTotals
    DraftResponse:
      properties:
        draft_id:
          type: string
          title: Draft Id
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - draft_id
        - status
        - created_at
      title: DraftResponse
    EInvoicingFormat:
      type: string
      enum:
        - facturx
        - ubl
        - cii
      title: EInvoicingFormat
      description: Supported e-invoicing formats for file downloads.
    EN16931InvoiceModel:
      properties:
        specification_identifier:
          type: string
          title: Specification Identifier
          description: Specification identifier (BT-24)
          default: >-
            urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
        issue_date:
          type: string
          format: date
          title: Issue Date
          description: Invoice issue date (BT-2)
        due_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Due Date
          description: Payment due date (BT-9)
        type_code:
          $ref: '#/components/schemas/InvoiceTypeCode'
          description: Invoice type code (BT-3)
        currency_code:
          type: string
          title: Currency Code
          description: Invoice currency code (BT-5) - ISO 4217
        tax_point_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Tax Point Date
          description: Tax point date (BT-7)
        value_added_tax_point_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Value Added Tax Point Date
          description: Value added tax point date (BT-8)
        business_process_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Process Type
          description: Business process type (BT-23)
        purchase_order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Purchase Order Reference
          description: Purchase order reference (BT-13)
        sales_order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Sales Order Reference
          description: Sales order reference (BT-14)
        receiving_advice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Receiving Advice Reference
          description: Receiving advice reference (BT-15)
        despatch_advice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Despatch Advice Reference
          description: Despatch advice reference (BT-16)
        tender_or_lot_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Tender Or Lot Reference
          description: Tender or lot reference (BT-17)
        invoice_object_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Object Identifier
          description: Invoiced object identifier (BT-18)
        buyer_accounting_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Accounting Reference
          description: Buyer accounting reference (BT-19)
        project_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Reference
          description: Project reference (BT-11)
        contract_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Reference
          description: Contract reference (BT-12)
        seller:
          $ref: '#/components/schemas/Seller'
          description: Seller party information (BG-4)
        buyer:
          $ref: '#/components/schemas/Buyer'
          description: Buyer party information (BG-7)
        invoice_lines:
          items:
            $ref: '#/components/schemas/InvoiceLine-Output'
          type: array
          minItems: 1
          title: Invoice Lines
          description: Invoice lines (BG-25)
        vat_breakdowns:
          items:
            $ref: '#/components/schemas/VATBreakdown-Output'
          type: array
          title: Vat Breakdowns
          description: VAT breakdown (BG-23)
        document_totals:
          $ref: '#/components/schemas/DocumentTotals-Output'
          description: Document level totals (BG-22)
        payment_terms:
          anyOf:
            - $ref: '#/components/schemas/PaymentTerms'
            - type: 'null'
          description: Payment instructions (BG-16)
        order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Order Reference
          description: 'Deprecated: use purchase_order_reference instead'
        invoice_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Note
          description: Invoice note (BT-22)
        preceding_invoice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Preceding Invoice Reference
          description: For credit notes - reference to original invoice (BT-25)
        invoice_number:
          type: string
          title: Invoice Number
          description: Invoice number (BT-1)
        processing_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Processing Timestamp
          description: When the invoice was processed by the system
        invoice_period_start_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Invoice Period Start Date
          description: Invoice period start date (BT-73)
        invoice_period_end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Invoice Period End Date
          description: Invoice period end date (BT-74)
        delivery_location_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Delivery Location Identifier
          description: Deliver to location identifier (BT-71)
        actual_delivery_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Actual Delivery Date
          description: Actual delivery date (BT-72)
        payment_means_type_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Means Type Code
          description: Payment means type code (BT-81)
        payment_means_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Means Text
          description: Payment means text (BT-82)
        remittance_information:
          anyOf:
            - type: string
            - type: 'null'
          title: Remittance Information
          description: Remittance information (BT-83)
        payment_account_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Account Identifier
          description: Payment account identifier (BT-84)
        payment_account_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Account Name
          description: Payment account name (BT-85)
        payment_service_provider_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Service Provider Identifier
          description: Payment service provider identifier (BT-86)
        document_level_allowance_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Level Allowance Amount
          description: Sum of allowances on document level (BT-107)
        document_level_charge_amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Level Charge Amount
          description: Sum of charges on document level (BT-108)
        en16931_validation_status:
          anyOf:
            - type: string
            - type: 'null'
          title: En16931 Validation Status
          description: EN16931 validation status (system field)
        validation_errors:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Validation Errors
          description: List of validation errors if any (system field)
      type: object
      required:
        - issue_date
        - type_code
        - currency_code
        - seller
        - buyer
        - invoice_lines
        - vat_breakdowns
        - document_totals
        - invoice_number
      title: EN16931InvoiceModel
      description: >-
        Final invoice model with system-generated invoice number and full
        EN16931 compliance.
    ElectronicAddress:
      properties:
        scheme_id:
          type: string
          title: Scheme Id
          description: Electronic address scheme identifier
        value:
          type: string
          title: Value
          description: Electronic address
      type: object
      required:
        - scheme_id
        - value
      title: ElectronicAddress
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        code:
          type: integer
          title: Code
        trace_id:
          type: string
          title: Trace Id
      type: object
      required:
        - error
        - code
        - trace_id
      title: ErrorResponse
    EstablishmentNature:
      type: string
      enum:
        - Private
        - Public
      title: EstablishmentNature
      description: Nature of the establishment.
    ExemptInvoiceRequest:
      properties:
        direction:
          $ref: '#/components/schemas/Direction'
          description: Whether this is a purchase (incoming) or sales (outgoing) invoice
        country_code:
          type: string
          title: Country Code
          description: ISO country code of the counterparty
        model:
          $ref: '#/components/schemas/InvoiceDraftModel-Input'
      type: object
      required:
        - direction
        - country_code
        - model
      title: ExemptInvoiceRequest
    FileSubmissionResponse:
      properties:
        invoice_id:
          type: string
          title: Invoice Id
          description: Generated invoice ID
        status:
          $ref: '#/components/schemas/InvoiceStatus'
          description: Current invoice status
        file_name:
          type: string
          title: File Name
          description: Original file name
        file_size:
          type: integer
          title: File Size
          description: File size in bytes
        extracted_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extracted Data
          description: Extracted invoice data from invoice file
        en16931_invoice:
          anyOf:
            - $ref: '#/components/schemas/EN16931InvoiceModel'
            - type: 'null'
          description: Complete EN16931-compliant invoice if processing succeeded
      type: object
      required:
        - invoice_id
        - status
        - file_name
        - file_size
      title: FileSubmissionResponse
      description: Response for invoice file submission.
    FileValidationResponse:
      properties:
        is_valid:
          type: boolean
          title: Is Valid
          description: Whether the invoice file is valid
        file_name:
          type: string
          title: File Name
          description: Original file name
        file_size:
          type: integer
          title: File Size
          description: File size in bytes
        detected_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Detected Format
          description: Detected file format (FacturX, UBL, CII)
        format_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Format Version
          description: Detected format version
        pdf_valid:
          type: boolean
          title: Pdf Valid
          description: Whether the PDF component is valid
        xml_valid:
          type: boolean
          title: Xml Valid
          description: Whether the XML component is valid
        issues:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          type: array
          title: Issues
          description: List of validation issues found
        total_errors:
          type: integer
          title: Total Errors
          description: Total number of errors
        total_warnings:
          type: integer
          title: Total Warnings
          description: Total number of warnings
        extracted_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extracted Data
          description: Extracted invoice data if validation succeeds
        en16931_invoice:
          anyOf:
            - $ref: '#/components/schemas/EN16931InvoiceModel'
            - type: 'null'
          description: Complete EN16931-compliant invoice if validation succeeds
        summary:
          type: string
          title: Summary
          description: Human-readable validation summary
      type: object
      required:
        - is_valid
        - file_name
        - file_size
        - pdf_valid
        - xml_valid
        - issues
        - total_errors
        - total_warnings
        - summary
      title: FileValidationResponse
      description: Response for invoice file validation.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InvoiceDownloadLink:
      properties:
        format:
          $ref: '#/components/schemas/EInvoicingFormat'
          description: Invoice format
        download_url:
          type: string
          title: Download Url
          description: Signed S3 download URL
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: When the download link expires
        file_name:
          type: string
          title: File Name
          description: Suggested filename for download
        file_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: File Size
          description: File size in bytes
        content_type:
          type: string
          title: Content Type
          description: MIME content type
      type: object
      required:
        - format
        - download_url
        - expires_at
        - file_name
        - content_type
      title: InvoiceDownloadLink
      description: Download link for a specific invoice format.
    InvoiceDownloadResponse:
      properties:
        invoice_id:
          type: string
          title: Invoice Id
          description: Invoice ID
        available_formats:
          items:
            $ref: '#/components/schemas/InvoiceDownloadLink'
          type: array
          title: Available Formats
          description: List of available download formats
        generated_at:
          type: string
          format: date-time
          title: Generated At
          description: When the download links were generated
      type: object
      required:
        - invoice_id
        - available_formats
        - generated_at
      title: InvoiceDownloadResponse
      description: Response containing download links for invoice in various formats.
    InvoiceDraftModel-Input:
      properties:
        specification_identifier:
          type: string
          title: Specification Identifier
          description: Specification identifier (BT-24)
          default: >-
            urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
        issue_date:
          type: string
          format: date
          title: Issue Date
          description: Invoice issue date (BT-2)
        due_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Due Date
          description: Payment due date (BT-9)
        type_code:
          $ref: '#/components/schemas/InvoiceTypeCode'
          description: Invoice type code (BT-3)
        currency_code:
          type: string
          title: Currency Code
          description: Invoice currency code (BT-5) - ISO 4217
        tax_point_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Tax Point Date
          description: Tax point date (BT-7)
        value_added_tax_point_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Value Added Tax Point Date
          description: Value added tax point date (BT-8)
        business_process_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Process Type
          description: Business process type (BT-23)
        purchase_order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Purchase Order Reference
          description: Purchase order reference (BT-13)
        sales_order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Sales Order Reference
          description: Sales order reference (BT-14)
        receiving_advice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Receiving Advice Reference
          description: Receiving advice reference (BT-15)
        despatch_advice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Despatch Advice Reference
          description: Despatch advice reference (BT-16)
        tender_or_lot_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Tender Or Lot Reference
          description: Tender or lot reference (BT-17)
        invoice_object_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Object Identifier
          description: Invoiced object identifier (BT-18)
        buyer_accounting_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Accounting Reference
          description: Buyer accounting reference (BT-19)
        project_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Reference
          description: Project reference (BT-11)
        contract_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Reference
          description: Contract reference (BT-12)
        seller:
          $ref: '#/components/schemas/Seller'
          description: Seller party information (BG-4)
        buyer:
          $ref: '#/components/schemas/Buyer'
          description: Buyer party information (BG-7)
        invoice_lines:
          items:
            $ref: '#/components/schemas/InvoiceLine-Input'
          type: array
          minItems: 1
          title: Invoice Lines
          description: Invoice lines (BG-25)
        vat_breakdowns:
          items:
            $ref: '#/components/schemas/VATBreakdown-Input'
          type: array
          title: Vat Breakdowns
          description: VAT breakdown (BG-23)
        document_totals:
          $ref: '#/components/schemas/DocumentTotals-Input'
          description: Document level totals (BG-22)
        payment_terms:
          anyOf:
            - $ref: '#/components/schemas/PaymentTerms'
            - type: 'null'
          description: Payment instructions (BG-16)
        order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Order Reference
          description: 'Deprecated: use purchase_order_reference instead'
        invoice_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Note
          description: Invoice note (BT-22)
        preceding_invoice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Preceding Invoice Reference
          description: For credit notes - reference to original invoice (BT-25)
      type: object
      required:
        - issue_date
        - type_code
        - currency_code
        - seller
        - buyer
        - invoice_lines
        - vat_breakdowns
        - document_totals
      title: InvoiceDraftModel
      description: Invoice draft model - invoice number will be generated when finalized.
    InvoiceDraftModel-Output:
      properties:
        specification_identifier:
          type: string
          title: Specification Identifier
          description: Specification identifier (BT-24)
          default: >-
            urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
        issue_date:
          type: string
          format: date
          title: Issue Date
          description: Invoice issue date (BT-2)
        due_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Due Date
          description: Payment due date (BT-9)
        type_code:
          $ref: '#/components/schemas/InvoiceTypeCode'
          description: Invoice type code (BT-3)
        currency_code:
          type: string
          title: Currency Code
          description: Invoice currency code (BT-5) - ISO 4217
        tax_point_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Tax Point Date
          description: Tax point date (BT-7)
        value_added_tax_point_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Value Added Tax Point Date
          description: Value added tax point date (BT-8)
        business_process_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Process Type
          description: Business process type (BT-23)
        purchase_order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Purchase Order Reference
          description: Purchase order reference (BT-13)
        sales_order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Sales Order Reference
          description: Sales order reference (BT-14)
        receiving_advice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Receiving Advice Reference
          description: Receiving advice reference (BT-15)
        despatch_advice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Despatch Advice Reference
          description: Despatch advice reference (BT-16)
        tender_or_lot_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Tender Or Lot Reference
          description: Tender or lot reference (BT-17)
        invoice_object_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Object Identifier
          description: Invoiced object identifier (BT-18)
        buyer_accounting_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyer Accounting Reference
          description: Buyer accounting reference (BT-19)
        project_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Reference
          description: Project reference (BT-11)
        contract_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Reference
          description: Contract reference (BT-12)
        seller:
          $ref: '#/components/schemas/Seller'
          description: Seller party information (BG-4)
        buyer:
          $ref: '#/components/schemas/Buyer'
          description: Buyer party information (BG-7)
        invoice_lines:
          items:
            $ref: '#/components/schemas/InvoiceLine-Output'
          type: array
          minItems: 1
          title: Invoice Lines
          description: Invoice lines (BG-25)
        vat_breakdowns:
          items:
            $ref: '#/components/schemas/VATBreakdown-Output'
          type: array
          title: Vat Breakdowns
          description: VAT breakdown (BG-23)
        document_totals:
          $ref: '#/components/schemas/DocumentTotals-Output'
          description: Document level totals (BG-22)
        payment_terms:
          anyOf:
            - $ref: '#/components/schemas/PaymentTerms'
            - type: 'null'
          description: Payment instructions (BG-16)
        order_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Order Reference
          description: 'Deprecated: use purchase_order_reference instead'
        invoice_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Note
          description: Invoice note (BT-22)
        preceding_invoice_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Preceding Invoice Reference
          description: For credit notes - reference to original invoice (BT-25)
      type: object
      required:
        - issue_date
        - type_code
        - currency_code
        - seller
        - buyer
        - invoice_lines
        - vat_breakdowns
        - document_totals
      title: InvoiceDraftModel
      description: Invoice draft model - invoice number will be generated when finalized.
    InvoiceFormat:
      type: string
      enum:
        - factur-x
        - ubl
        - cii
      title: InvoiceFormat
    InvoiceLine-Input:
      properties:
        line_id:
          type: string
          title: Line Id
          description: Invoice line identifier
        invoiced_quantity:
          anyOf:
            - type: number
            - type: string
          title: Invoiced Quantity
          description: Invoiced quantity
        unit_of_measure:
          type: string
          title: Unit Of Measure
          description: Unit of measure code
        line_net_amount:
          anyOf:
            - type: number
            - type: string
          title: Line Net Amount
          description: Invoice line net amount
        item_name:
          type: string
          title: Item Name
          description: Item name
        item_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Item Description
        item_price:
          anyOf:
            - type: number
            - type: string
          title: Item Price
          description: Item net price
        vat_category_code:
          $ref: '#/components/schemas/VATCategoryCode'
        vat_rate:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Vat Rate
          description: VAT rate as percentage
      type: object
      required:
        - line_id
        - invoiced_quantity
        - unit_of_measure
        - line_net_amount
        - item_name
        - item_price
        - vat_category_code
      title: InvoiceLine
    InvoiceLine-Output:
      properties:
        line_id:
          type: string
          title: Line Id
          description: Invoice line identifier
        invoiced_quantity:
          type: string
          title: Invoiced Quantity
          description: Invoiced quantity
        unit_of_measure:
          type: string
          title: Unit Of Measure
          description: Unit of measure code
        line_net_amount:
          type: string
          title: Line Net Amount
          description: Invoice line net amount
        item_name:
          type: string
          title: Item Name
          description: Item name
        item_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Item Description
        item_price:
          type: string
          title: Item Price
          description: Item net price
        vat_category_code:
          $ref: '#/components/schemas/VATCategoryCode'
        vat_rate:
          anyOf:
            - type: string
            - type: 'null'
          title: Vat Rate
          description: VAT rate as percentage
      type: object
      required:
        - line_id
        - invoiced_quantity
        - unit_of_measure
        - line_net_amount
        - item_name
        - item_price
        - vat_category_code
      title: InvoiceLine
    InvoiceResponse:
      properties:
        invoice_id:
          type: string
          title: Invoice Id
        status:
          $ref: '#/components/schemas/InvoiceStatus'
      type: object
      required:
        - invoice_id
        - status
      title: InvoiceResponse
    InvoiceStatus:
      type: string
      enum:
        - draft
        - submitted
        - validated
        - rejected
        - processed
      title: InvoiceStatus
    InvoiceTypeCode:
      type: string
      enum:
        - '380'
        - '381'
        - '383'
        - '384'
      title: InvoiceTypeCode
    LifecycleEvent:
      properties:
        status_code:
          $ref: '#/components/schemas/LifecycleStatusCode'
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        emitter:
          type: string
          title: Emitter
          description: Platform or system that emitted the status (PDPE, PDPR, PPF, etc.)
          example: PDPE
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Optional free-text reason or comment
        rejection_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Rejection Reason
          description: Structured rejection reason code when status indicates rejection
        is_mandatory:
          type: boolean
          title: Is Mandatory
          description: Whether this status must be reported to PPF within 24 hours
          default: false
      type: object
      required:
        - status_code
        - timestamp
        - emitter
      title: LifecycleEvent
      description: Lifecycle event with all required fields for PPF compliance.
    LifecycleStatusCode:
      type: string
      enum:
        - InvoiceLifecycleStatus.DEPOSITED
        - InvoiceLifecycleStatus.TRANSMITTED_BY_PLATFORM
        - InvoiceLifecycleStatus.RECEIVED_BY_PLATFORM
        - InvoiceLifecycleStatus.MADE_AVAILABLE
        - InvoiceLifecycleStatus.ACKNOWLEDGED
        - InvoiceLifecycleStatus.APPROVED
        - InvoiceLifecycleStatus.PARTIALLY_APPROVED
        - InvoiceLifecycleStatus.IN_DISPUTE
        - InvoiceLifecycleStatus.SUSPENDED
        - InvoiceLifecycleStatus.COMPLETED
        - InvoiceLifecycleStatus.REFUSED
        - InvoiceLifecycleStatus.PAYMENT_TRANSMITTED
        - InvoiceLifecycleStatus.COLLECTED
        - InvoiceLifecycleStatus.REJECTED
        - RegulatoryDataStatus.DEPOSITED
        - RegulatoryDataStatus.REJECTED
        - RegulatoryDataStatus.MADE_AVAILABLE
        - RegulatoryDataStatus.ACCEPTED_BY_ADMINISTRATION
        - RegulatoryDataStatus.REFUSED_BY_ADMINISTRATION
        - FlowStatus.RECEIVABLE
        - FlowStatus.UNACCEPTABLE
        - DirectoryEntryStatus.ACCEPTED
        - DirectoryEntryStatus.REJECTED
        - TransactionDataStatus.DEPOSITED
        - TransactionDataStatus.REJECTED
        - TransactionDataStatus.REFUSED_BY_ADMINISTRATION
        - TransactionDataStatus.ACCEPTED_BY_ADMINISTRATION
        - LifecycleStatusReporting.REJECTED
        - MandateLifecycleStatus.CREATED
        - MandateLifecycleStatus.ACTIVATED
        - MandateLifecycleStatus.REVOKED
      title: LifecycleStatusCode
      description: Unified lifecycle status codes for all object types.
    Mandate:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: Unique mandate identifier
        client_id:
          type: string
          title: Client Id
          description: Reference to the client who owns this mandate
        start_date:
          type: string
          format: date-time
          title: Start Date
          description: When the mandate becomes active
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Date
          description: When the mandate expires (optional)
        file_attachment:
          anyOf:
            - type: string
            - type: 'null'
          title: File Attachment
          description: Optional file attachment for the mandate
        status:
          $ref: '#/components/schemas/MandateStatus'
          description: Current status of the mandate
        directory_entry:
          $ref: '#/components/schemas/DirectoryEntry'
          description: Directory entry information for the mandated entity
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the mandate was created
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: When the mandate was last updated
      type: object
      required:
        - client_id
        - start_date
        - status
        - directory_entry
        - created_at
      title: Mandate
      description: Mandate model with all information.
    MandateCreateRequest:
      properties:
        start_date:
          type: string
          format: date-time
          title: Start Date
          description: When the mandate should become active
          example: '2024-01-15T00:00:00Z'
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Date
          description: When the mandate should expire (optional)
          example: '2024-12-31T23:59:59Z'
        directory_entry:
          $ref: '#/components/schemas/DirectoryEntry'
          description: Directory entry information for the mandated entity
        file_attachment:
          anyOf:
            - type: string
            - type: 'null'
          title: File Attachment
          description: Optional file attachment for the mandate
      type: object
      required:
        - start_date
        - directory_entry
      title: MandateCreateRequest
      description: >-
        Request model for creating a new mandate.


        Note: client_id is provided via X-PDP-Client-Id header, not in request
        body.
    MandateResponse:
      properties:
        mandate:
          $ref: '#/components/schemas/Mandate'
        message:
          type: string
          title: Message
          description: Response message
          example: Mandate created successfully
      type: object
      required:
        - mandate
        - message
      title: MandateResponse
      description: Response model for mandate operations.
    MandateStatsResponse:
      properties:
        total_mandates:
          type: integer
          title: Total Mandates
          description: Total number of mandates for the sponsor
        average_mandates_per_client:
          type: number
          title: Average Mandates Per Client
          description: Average number of mandates per client
      type: object
      required:
        - total_mandates
        - average_mandates_per_client
      title: MandateStatsResponse
      description: Response model for mandate statistics.
    MandateStatus:
      type: string
      enum:
        - created
        - pending_kyc
        - active
        - expired
      title: MandateStatus
      description: Status of the mandate.
    ObjectType:
      type: string
      enum:
        - invoice
        - mandate
        - directory_entry
        - regulatory_data
        - flow
        - transaction_data
        - lifecycle_status
      title: ObjectType
    OnboardingLinkRequest:
      properties:
        include_kyc:
          type: boolean
          title: Include Kyc
          description: Include KYC (Know Your Customer) step in the onboarding experience
          default: false
        include_signature:
          type: boolean
          title: Include Signature
          description: Require electronic signature of the PDP mandate during onboarding
          default: false
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Callback Url
          description: URL to redirect to after onboarding completion
          example: https://your-app.com/onboarding-complete
      type: object
      title: OnboardingLinkRequest
      description: Request model for generating onboarding links.
    OnboardingLinkStatus:
      type: string
      enum:
        - not_opened
        - opened
        - kyc_in_progress
        - kyc_completed
        - completed
        - expired
      title: OnboardingLinkStatus
    OnboardingLinkStatusResponse:
      properties:
        link_id:
          type: string
          title: Link Id
        company_id:
          type: string
          title: Company Id
        status:
          $ref: '#/components/schemas/OnboardingLinkStatus'
        created_at:
          type: string
          format: date-time
          title: Created At
        last_updated:
          type: string
          format: date-time
          title: Last Updated
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
        completion_percentage:
          type: integer
          maximum: 100
          minimum: 0
          title: Completion Percentage
          description: Completion percentage (0-100)
        includes_kyc:
          type: boolean
          title: Includes Kyc
          description: Whether KYC step is included in this onboarding
        includes_signature:
          type: boolean
          title: Includes Signature
          description: Whether electronic signature is required
        kyc_completed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Kyc Completed
          description: Whether KYC has been completed (if applicable)
        signature_completed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Signature Completed
          description: Whether signature has been completed (if applicable)
      type: object
      required:
        - link_id
        - company_id
        - status
        - created_at
        - last_updated
        - completion_percentage
        - includes_kyc
        - includes_signature
      title: OnboardingLinkStatusResponse
    OnboardingResponse:
      properties:
        onboarding_url:
          type: string
          format: uri
          title: Onboarding Url
          description: Generated onboarding URL
        link_id:
          type: string
          title: Link Id
          description: Unique identifier for this onboarding link
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: When this onboarding link expires
        includes_kyc:
          type: boolean
          title: Includes Kyc
          description: Whether KYC step is included
        includes_signature:
          type: boolean
          title: Includes Signature
          description: Whether electronic signature is required
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Callback Url
          description: Callback URL for redirection after completion
      type: object
      required:
        - onboarding_url
        - link_id
        - expires_at
        - includes_kyc
        - includes_signature
      title: OnboardingResponse
      description: Response model for onboarding link generation.
    Payment:
      properties:
        client_siren:
          type: string
          pattern: ^\d{9}$
          title: Client Siren
          description: Client's SIREN number
        payment_date:
          type: string
          format: date
          title: Payment Date
          description: Date payment was received
        amount:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
          title: Amount
          description: Payment amount
        currency:
          type: string
          title: Currency
          description: Currency code
          default: EUR
        invoice_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Number
          description: Related invoice number (if applicable)
      type: object
      required:
        - client_siren
        - payment_date
        - amount
      title: Payment
      description: Payment received by client.
    PaymentPeriodicity:
      type: string
      enum:
        - monthly
        - bimonthly
      title: PaymentPeriodicity
    PaymentResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
          description: System-generated payment ID
        client_siren:
          type: string
          pattern: ^\d{9}$
          title: Client Siren
          description: Client's SIREN number
        payment_date:
          type: string
          format: date
          title: Payment Date
          description: Date payment was received
        amount:
          type: string
          title: Amount
          description: Payment amount
        currency:
          type: string
          title: Currency
          description: Currency code
          default: EUR
        invoice_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Number
          description: Related invoice number (if applicable)
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        period:
          type: string
          title: Period
          description: Reporting period (YYYY-MM)
      type: object
      required:
        - payment_id
        - client_siren
        - payment_date
        - amount
        - created_at
        - period
      title: PaymentResponse
      description: Payment with system-generated fields.
    PaymentTerms:
      properties:
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        due_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Due Date
      type: object
      title: PaymentTerms
    PdpClientCreateRequest:
      properties:
        external_reference:
          type: string
          title: External Reference
          description: External reference to associate with the PDP client
          example: CUST-12345
        client_name:
          type: string
          title: Client Name
          description: Human-readable name for the client
          example: ACME Corporation
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Optional description of the client
          example: Main client for ACME Corp operations
      type: object
      required:
        - external_reference
        - client_name
      title: PdpClientCreateRequest
      description: Request model for creating a new PDP client.
    PdpClientCreateResponse:
      properties:
        pdp_client_id:
          type: string
          title: Pdp Client Id
          description: Generated PDP client ID
          example: pdp_abc123def456
        external_reference:
          type: string
          title: External Reference
          description: Associated external reference
          example: CUST-12345
        client_name:
          type: string
          title: Client Name
          description: Client name
          example: ACME Corporation
        status:
          type: string
          title: Status
          description: Client status
          example: active
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        message:
          type: string
          title: Message
          description: Success message
      type: object
      required:
        - pdp_client_id
        - external_reference
        - client_name
        - status
        - created_at
        - message
      title: PdpClientCreateResponse
      description: Response model for PDP client creation.
    PeriodicitySettings:
      properties:
        vat_regime:
          $ref: '#/components/schemas/VATRegime'
          description: VAT regime of the company. Affects data transmission periodicity.
        transaction_periodicity:
          $ref: '#/components/schemas/TransactionPeriodicity'
          description: Frequency for transaction data (Flux 4)
        payment_periodicity:
          $ref: '#/components/schemas/PaymentPeriodicity'
          description: Frequency for payment data (Flux 10)
      type: object
      required:
        - vat_regime
        - transaction_periodicity
        - payment_periodicity
      title: PeriodicitySettings
    RoutingIdentifierType:
      type: string
      enum:
        - '0224'
        - '0088'
        - '0060'
        - Internal
      title: RoutingIdentifierType
      description: Type of routing identifier.
    Seller:
      properties:
        name:
          type: string
          title: Name
          description: Party name
        postal_address:
          $ref: '#/components/schemas/models__invoicing__Address'
        electronic_address:
          anyOf:
            - $ref: '#/components/schemas/ElectronicAddress'
            - type: 'null'
        tax_registrations:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaxRegistration'
              type: array
            - type: 'null'
          title: Tax Registrations
        legal_registration_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Legal Registration Name
        trading_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Trading Name
        party_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Party Identifier
          description: Party identifier
        party_identifier_scheme:
          anyOf:
            - type: string
            - type: 'null'
          title: Party Identifier Scheme
          description: Party identifier scheme
        seller_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Seller Identifier
          description: Seller identifier (BT-29)
        seller_identifier_scheme:
          anyOf:
            - type: string
            - type: 'null'
          title: Seller Identifier Scheme
          description: Seller identifier scheme (BT-30)
        seller_vat_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Seller Vat Identifier
          description: Seller VAT identifier (BT-31)
        seller_tax_registration_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Seller Tax Registration Identifier
          description: Seller tax registration identifier (BT-32)
        seller_additional_legal_information:
          anyOf:
            - type: string
            - type: 'null'
          title: Seller Additional Legal Information
          description: Seller additional legal information (BT-33)
      type: object
      required:
        - name
        - postal_address
      title: Seller
      description: Seller party information (BG-4).
    TaxRegistration:
      properties:
        scheme_id:
          type: string
          title: Scheme Id
          description: Tax registration scheme (e.g., 'VAT')
        value:
          type: string
          title: Value
          description: Tax registration number
      type: object
      required:
        - scheme_id
        - value
      title: TaxRegistration
    TransactionPeriodicity:
      type: string
      enum:
        - monthly
        - decade
      title: TransactionPeriodicity
    UsageAlert:
      properties:
        company_id:
          type: string
          title: Company Id
        alert_type:
          type: string
          title: Alert Type
          description: Type of alert (e.g., 'rate_limit_approaching', 'quota_exceeded')
        threshold_percentage:
          type: number
          maximum: 100
          minimum: 0
          title: Threshold Percentage
          description: Threshold percentage that triggered the alert
        current_usage:
          type: integer
          minimum: 0
          title: Current Usage
          description: Current usage count
        limit:
          type: integer
          minimum: 1
          title: Limit
          description: Usage limit
        endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Endpoint
          description: Specific endpoint if applicable
        created_at:
          type: string
          format: date-time
          title: Created At
        message:
          type: string
          title: Message
          description: Human-readable alert message
      type: object
      required:
        - company_id
        - alert_type
        - threshold_percentage
        - current_usage
        - limit
        - endpoint
        - message
      title: UsageAlert
    UsageAlertListResponse:
      properties:
        alerts:
          items:
            $ref: '#/components/schemas/UsageAlert'
          type: array
          title: Alerts
        total_count:
          type: integer
          title: Total Count
      type: object
      required:
        - alerts
        - total_count
      title: UsageAlertListResponse
    UsageLimit:
      properties:
        company_id:
          type: string
          title: Company Id
        endpoint:
          type: string
          title: Endpoint
        method:
          type: string
          title: Method
        limit_per_minute:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit Per Minute
          description: Rate limit per minute
        limit_per_hour:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit Per Hour
          description: Rate limit per hour
        limit_per_day:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit Per Day
          description: Rate limit per day
        limit_per_month:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit Per Month
          description: Rate limit per month
        current_usage_minute:
          type: integer
          minimum: 0
          title: Current Usage Minute
          description: Current usage in the current minute
        current_usage_hour:
          type: integer
          minimum: 0
          title: Current Usage Hour
          description: Current usage in the current hour
        current_usage_day:
          type: integer
          minimum: 0
          title: Current Usage Day
          description: Current usage in the current day
        current_usage_month:
          type: integer
          minimum: 0
          title: Current Usage Month
          description: Current usage in the current month
      type: object
      required:
        - company_id
        - endpoint
        - method
        - current_usage_minute
        - current_usage_hour
        - current_usage_day
        - current_usage_month
      title: UsageLimit
    UsageLimitResponse:
      properties:
        limits:
          items:
            $ref: '#/components/schemas/UsageLimit'
          type: array
          title: Limits
        total_count:
          type: integer
          title: Total Count
      type: object
      required:
        - limits
        - total_count
      title: UsageLimitResponse
    UsageMetrics:
      properties:
        company_id:
          type: string
          title: Company Id
        period:
          $ref: '#/components/schemas/UsagePeriod'
        start_date:
          type: string
          format: date
          title: Start Date
        end_date:
          type: string
          format: date
          title: End Date
        total_api_calls:
          type: integer
          minimum: 0
          title: Total Api Calls
          description: Total number of API calls
        total_successful_calls:
          type: integer
          minimum: 0
          title: Total Successful Calls
          description: Total successful API calls
        total_failed_calls:
          type: integer
          minimum: 0
          title: Total Failed Calls
          description: Total failed API calls
        success_rate:
          type: number
          maximum: 100
          minimum: 0
          title: Success Rate
          description: Success rate percentage
        endpoint_usage:
          items:
            $ref: '#/components/schemas/ApiEndpointUsage'
          type: array
          title: Endpoint Usage
          description: Usage breakdown by endpoint
        generated_at:
          type: string
          format: date-time
          title: Generated At
      type: object
      required:
        - company_id
        - period
        - start_date
        - end_date
        - total_api_calls
        - total_successful_calls
        - total_failed_calls
        - success_rate
        - endpoint_usage
      title: UsageMetrics
    UsagePeriod:
      type: string
      enum:
        - daily
        - weekly
        - monthly
        - yearly
      title: UsagePeriod
    UsageSummary:
      properties:
        company_id:
          type: string
          title: Company Id
        current_month_calls:
          type: integer
          minimum: 0
          title: Current Month Calls
          description: API calls in current month
        previous_month_calls:
          type: integer
          minimum: 0
          title: Previous Month Calls
          description: API calls in previous month
        month_over_month_change:
          type: number
          title: Month Over Month Change
          description: Percentage change from previous month
        most_used_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Most Used Endpoint
          description: Most frequently used endpoint
        least_used_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Least Used Endpoint
          description: Least frequently used endpoint
        peak_usage_day:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Peak Usage Day
          description: Day with highest usage
        peak_usage_count:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Peak Usage Count
          description: Highest daily usage count
      type: object
      required:
        - company_id
        - current_month_calls
        - previous_month_calls
        - month_over_month_change
        - most_used_endpoint
        - least_used_endpoint
        - peak_usage_day
        - peak_usage_count
      title: UsageSummary
    VATBreakdown-Input:
      properties:
        category_code:
          $ref: '#/components/schemas/VATCategoryCode'
        rate:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Rate
          description: VAT rate as percentage
        taxable_amount:
          anyOf:
            - type: number
            - type: string
          title: Taxable Amount
          description: VAT taxable amount
        tax_amount:
          anyOf:
            - type: number
            - type: string
          title: Tax Amount
          description: VAT amount
        exemption_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Exemption Reason
      type: object
      required:
        - category_code
        - taxable_amount
        - tax_amount
      title: VATBreakdown
    VATBreakdown-Output:
      properties:
        category_code:
          $ref: '#/components/schemas/VATCategoryCode'
        rate:
          anyOf:
            - type: string
            - type: 'null'
          title: Rate
          description: VAT rate as percentage
        taxable_amount:
          type: string
          title: Taxable Amount
          description: VAT taxable amount
        tax_amount:
          type: string
          title: Tax Amount
          description: VAT amount
        exemption_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Exemption Reason
      type: object
      required:
        - category_code
        - taxable_amount
        - tax_amount
      title: VATBreakdown
    VATCategoryCode:
      type: string
      enum:
        - S
        - Z
        - E
        - AE
        - K
        - O
      title: VATCategoryCode
    VATRegime:
      type: string
      enum:
        - real_normal_monthly
        - real_normal_quarterly
        - simplified
        - franchise
      title: VATRegime
    ValidateRequest:
      properties:
        format:
          $ref: '#/components/schemas/InvoiceFormat'
      type: object
      required:
        - format
      title: ValidateRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ValidationIssue:
      properties:
        field_path:
          type: string
          title: Field Path
          description: >-
            JSON path to the problematic field (e.g.,
            'seller.postal_address.country_code')
        error_code:
          type: string
          title: Error Code
          description: Machine-readable error code (e.g., 'INVALID_COUNTRY_CODE')
        error_message:
          type: string
          title: Error Message
          description: Human-readable error message
        severity:
          type: string
          title: Severity
          description: 'Issue severity: ''error'', ''warning'', or ''info'''
        suggested_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggested Value
          description: Suggested correct value if applicable
      type: object
      required:
        - field_path
        - error_code
        - error_message
        - severity
      title: ValidationIssue
      description: Single validation issue with detailed explanation.
    ValidationOnlyRequest:
      properties:
        invoice_data:
          $ref: '#/components/schemas/InvoiceDraftModel-Input'
          description: Invoice data to validate
        strict_mode:
          type: boolean
          title: Strict Mode
          description: Whether to apply strict EN16931 validation
          default: true
      type: object
      required:
        - invoice_data
      title: ValidationOnlyRequest
      description: Request to validate invoice data without creating a draft.
    ValidationResponse:
      properties:
        is_valid:
          type: boolean
          title: Is Valid
          description: Whether the invoice data is valid
        issues:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          type: array
          title: Issues
          description: List of validation issues found
        total_errors:
          type: integer
          title: Total Errors
          description: Total number of errors
        total_warnings:
          type: integer
          title: Total Warnings
          description: Total number of warnings
        en16931_compliant:
          type: boolean
          title: En16931 Compliant
          description: Whether the invoice meets EN16931 requirements
        summary:
          type: string
          title: Summary
          description: Human-readable validation summary
      type: object
      required:
        - is_valid
        - issues
        - total_errors
        - total_warnings
        - en16931_compliant
        - summary
      title: ValidationResponse
      description: Detailed validation response with all found issues.
    models__directory__Address:
      properties:
        address_line_1:
          type: string
          maxLength: 200
          title: Address Line 1
          description: First line of address
          example: 16 BIS RUE HENRI BARBUSSE
        address_line_2:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Address Line 2
          description: Second line of address
          example: CEDEX 1
        address_line_3:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Address Line 3
          description: Third line of address
          example: Bâtiment le Callipso
        postal_code:
          type: string
          maxLength: 5
          pattern: '[0-9]*'
          title: Postal Code
          description: Postal code
          example: '38100'
        subdivision:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Subdivision
          description: Country subdivision (region/state)
          example: Bretagne
        city:
          type: string
          maxLength: 100
          pattern: ^.+$
          title: City
          description: City or locality
          example: Grenoble
        country_code:
          type: string
          maxLength: 2
          minLength: 2
          pattern: ^.+$
          title: Country Code
          description: Country code (ISO 3166-1 alpha-2)
          example: FR
      type: object
      required:
        - address_line_1
        - postal_code
        - city
        - country_code
      title: Address
      description: Address information for the establishment.
    models__invoicing__Address:
      properties:
        street_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Street Name
        additional_street_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Additional Street Name
        city_name:
          type: string
          title: City Name
        postal_zone:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Zone
        country_subdivision:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Subdivision
        country_code:
          type: string
          title: Country Code
          description: ISO 3166-1 alpha-2 country code
      type: object
      required:
        - city_name
        - country_code
      title: Address
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization
tags:
  - name: 👥 Clients
    description: Manage clients
  - name: 📘 Directory
    description: Directory operations
  - name: 📝 Drafts
    description: Create and validate invoice drafts
  - name: 🧾 Invoicing
    description: Send and receive electronic invoices
  - name: 🔄 Lifecycle
    description: Polls or subscribes to lifecycle events
  - name: 📋 Mandates
    description: Manage legal entities and PPF directory entries
  - name: 🚀 Company Onboarding
    description: Manage onboarding
  - name: 📊 Reporting
    description: Send e-reporting information
  - name: ⚙️ Settings
    description: Configure client preferences
  - name: 📊 Usage
    description: Gather API usage per client and invoice
