# Seqino PDP API

Seqino PDP API - Modern interface to France's e-Invoicing services

Version: 1.0.0

## Servers

Dev server
```
https://pdp.seqino.dev/api
```

Local development server
```
http://localhost:8052
```

## Download OpenAPI description

[Seqino PDP API](https://pdp-api-v250704-iron.seqino.dev/_bundle/openapi.yaml)

## 👥 Clients

### 📋 Get all clients

 - [GET /clients/](https://pdp-api-v250704-iron.seqino.dev/openapi/clients/get_clients_clients__get.md): Get all clients with their details.

### ➕ Create a new client

 - [POST /clients/](https://pdp-api-v250704-iron.seqino.dev/openapi/clients/create_client_clients__post.md): Create a new client with the provided details.

### 🗑️ Delete a client

 - [DELETE /clients/{client_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/clients/delete_client_clients__client_id__delete.md): 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.

### 🔗 Generate onboarding link for a client

 - [POST /clients/onboarding-link](https://pdp-api-v250704-iron.seqino.dev/openapi/clients/generate_client_onboarding_link_clients_onboarding_link_post.md): 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.

### 📊 Get onboarding link status

 - [GET /clients/onboarding-link/status](https://pdp-api-v250704-iron.seqino.dev/openapi/clients/get_client_onboarding_link_status_clients_onboarding_link_status_get.md): Get the status of an onboarding link for a client.

Returns the current progress including KYC and signature completion status.

### ➕ Create new PDP client

 - [POST /clients/pdp-clients](https://pdp-api-v250704-iron.seqino.dev/openapi/clients/create_pdp_client_clients_pdp_clients_post.md): 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.

## 📋 Mandates

### 📋 Get client mandates

 - [GET /mandates](https://pdp-api-v250704-iron.seqino.dev/openapi/mandates/get_client_mandates_mandates_get.md): 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.

### 📋 Create mandate with directory entry

 - [POST /mandates](https://pdp-api-v250704-iron.seqino.dev/openapi/mandates/create_mandate_mandates_post.md): 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).

### 📋 Get mandate details

 - [GET /mandates/{mandate_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/mandates/get_mandate_details_mandates__mandate_id__get.md): Get detailed information about a specific mandate.

### 📋 Revoke mandate

 - [DELETE /mandates/{mandate_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/mandates/revoke_mandate_mandates__mandate_id__delete.md): 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.

### 📋 Create multiple mandates

 - [POST /mandates/batch](https://pdp-api-v250704-iron.seqino.dev/openapi/mandates/create_mandates_batch_mandates_batch_post.md): 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.

### 📘 Get directory entries for SIREN

 - [GET /mandates/directory/{siren}](https://pdp-api-v250704-iron.seqino.dev/openapi/mandates/get_directory_entries_by_siren_mandates_directory__siren__get.md): 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.

## 📝 Drafts

### 🆕 Create invoice draft from EN16931-compatible JSON

 - [POST /drafts](https://pdp-api-v250704-iron.seqino.dev/openapi/drafts/create_draft_drafts_post.md): 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.

### 📄 Get details of a draft invoice

 - [GET /drafts/{draft_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/drafts/get_draft_drafts__draft_id__get.md): 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.

### ✏️ Update a draft invoice

 - [PUT /drafts/{draft_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/drafts/update_draft_drafts__draft_id__put.md): Update an existing draft invoice.

Completely replaces the draft content with the provided data.
The draft will be re-validated after the update.

### 🗑️ Delete an invoice draft

 - [DELETE /drafts/{draft_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/drafts/delete_draft_drafts__draft_id__delete.md): 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.

### ✅ Validate a draft and submit as invoice

 - [POST /drafts/{draft_id}/validate](https://pdp-api-v250704-iron.seqino.dev/openapi/drafts/validate_draft_drafts__draft_id__validate_post.md): 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.

### 🔍 Validate invoice data without creating draft

 - [POST /drafts/validate-data](https://pdp-api-v250704-iron.seqino.dev/openapi/drafts/validate_invoice_data_drafts_validate_data_post.md): 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

## 📘 Directory

### 📘 Get directory entry by SIREN

 - [GET /directory/{siren}](https://pdp-api-v250704-iron.seqino.dev/openapi/directory/get_directory_entry_directory__siren__get.md): Get a directory entry by company ID (SIREN).

## 🧾 Invoicing

### 📄 Get complete invoice data by ID

 - [GET /invoicing/invoice_data/{invoice_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/invoicing/get_invoice_data_invoicing_invoice_data__invoice_id__get.md): 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.

### 📄 Get invoice file download links

 - [GET /invoicing/invoices/{invoice_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/invoicing/get_invoice_download_links_invoicing_invoices__invoice_id__get.md): 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

### 🔍 List invoices with filtering

 - [GET /invoicing/invoices](https://pdp-api-v250704-iron.seqino.dev/openapi/invoicing/list_invoices_invoicing_invoices_get.md): 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

### 📄 Submit invoice file (FacturX, UBL, CII)

 - [POST /invoicing/files/submit](https://pdp-api-v250704-iron.seqino.dev/openapi/invoicing/submit_invoice_file_invoicing_files_submit_post.md): 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.

### ✅ Validate invoice file (FacturX, UBL, CII)

 - [POST /invoicing/files/validate](https://pdp-api-v250704-iron.seqino.dev/openapi/invoicing/validate_invoice_file_invoicing_files_validate_post.md): 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.

## 🔄 Lifecycle

### 📊 Get lifecycle events

 - [GET /lifecycle-events/](https://pdp-api-v250704-iron.seqino.dev/openapi/lifecycle/get_lifecycle_events_lifecycle_events__get.md): 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.

## 📊 Reporting

### 🌍 Submit exempt invoice (international B2B/B2C)

 - [POST /reporting/exempt-invoices](https://pdp-api-v250704-iron.seqino.dev/openapi/reporting/submit_exempt_invoice_reporting_exempt_invoices_post.md): 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.

### 📊 Submit B2C transaction data (daily aggregate)

 - [POST /reporting/b2c-transactions](https://pdp-api-v250704-iron.seqino.dev/openapi/reporting/submit_b2c_transactions_reporting_b2c_transactions_post.md): 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

### 💰 Record payment received

 - [POST /reporting/payments](https://pdp-api-v250704-iron.seqino.dev/openapi/reporting/record_payment_reporting_payments_post.md): Record a payment received by the client.

### 💰 Get client payments

 - [GET /reporting/payments](https://pdp-api-v250704-iron.seqino.dev/openapi/reporting/get_payments_reporting_payments_get.md): Get all payments for a client in a specific period.

### ✏️ Update payment

 - [PUT /reporting/payments/{payment_id}](https://pdp-api-v250704-iron.seqino.dev/openapi/reporting/update_payment_reporting_payments__payment_id__put.md): Update a payment record.

## 📊 Usage

### 📈 Get usage metrics for a company

 - [GET /usage/metrics](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/get_usage_metrics_usage_metrics_get.md): Get detailed usage metrics for a company within a specified period.

### 📋 Get usage summary for a company

 - [GET /usage/summary](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/get_usage_summary_usage_summary_get.md): Get a high-level usage summary for a company.

### ⚡ Get usage limits and current usage for a company

 - [GET /usage/limits](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/get_usage_limits_usage_limits_get.md): Get usage limits and current usage statistics for a company.

### ⚙️ Set usage limits for a company endpoint

 - [POST /usage/limits](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/set_usage_limit_usage_limits_post.md): Set or update usage limits for a specific company endpoint.

### 🚨 Get usage alerts for a company

 - [GET /usage/alerts](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/get_usage_alerts_usage_alerts_get.md): Get usage alerts and warnings for a company.

### 📊 Get mandate statistics

 - [GET /usage/mandates](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/get_mandate_stats_usage_mandates_get.md): 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.

### 📊 Get client statistics

 - [GET /usage/clients](https://pdp-api-v250704-iron.seqino.dev/openapi/usage/get_client_stats_usage_clients_get.md): Get client statistics for a sponsor.

Returns the total number of clients for the sponsor identified by the X-PDP-Sponsor-Id header.

## ⚙️ Settings

### 📅 Set periodicity and VAT regime settings

 - [PUT /settings/periodicity](https://pdp-api-v250704-iron.seqino.dev/openapi/settings/set_periodicity_settings_settings_periodicity_put.md): 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

### 📅 Get periodicity and VAT regime settings

 - [GET /settings/periodicity](https://pdp-api-v250704-iron.seqino.dev/openapi/settings/get_periodicity_settings_settings_periodicity_get.md): Get the current periodicity and VAT regime settings.