# Seqino PDP API - Introduction

![image](https://seqino.com/wp-content/uploads/2022/08/SEQINO-bleu-small.png)

Welcome to the **Seqino PDP API** documentation. This API provides a modern and simplified interface to France's e-Invoicing services, giving you the power of a Platform de Dématérialisation Partenaire (PDP) without the burden of managing one.

For any question, ask on the [Support page](https://help.api-pdp.seqino.com/en).

## Core Concepts

Understanding the relationship between **Sponsors**, **Clients**, and **Mandates** is essential to working with the Seqino PDP API.


```mermaid
graph TB
    seqino[Seqino]
    seqino --> |offers grey-label API to| sponsor_gl[PDP Sponsor]
    seqino --> |offers white-label API to| sponsor_wl[PDP Sponsor]

    subgraph sponsors["𝗦𝗽𝗼𝗻𝘀𝗼𝗿𝘀"]
        sponsor_gl["PDP Sponsor (ERP, OD)"]
        sponsor_wl["PDP Sponsor (Bank, ...)"]
    end
    class sponsors grouping
    class sponsor_gl sponsor
    class sponsor_wl sponsor

    subgraph clients["𝗖𝗹𝗶𝗲𝗻𝘁𝘀"]
        C1[Client A<br/>Company 1]
        C2[Client B<br/>Company 2 - Service X]
        C3[Client C<br/>Company 2 - Service Y]
    end
    class clients grouping
    class C1 client
    class C2 client
    class C3 client

    subgraph mandates["𝗠𝗮𝗻𝗱𝗮𝘁𝗲𝘀"]
        M1[Mandate A]
        M2[Mandate B]
        M3[Mandate C]
        M4[Mandate D]
    end
    class mandates grouping
    class M1 mandate
    class M2 mandate
    class M3 mandate
    class M4 mandate

    subgraph ppf[PPF]
        directory[Directory]
        einvoicing[eInvoicing]
        ereporting[eReporting]
    end

    class directory service
    class einvoincing service
    class ereporting service
    class ppf grouping

    sponsor_gl --> |manages customers| C1
    sponsor_gl --> C2

    C1 --> |grants permission via| M1
    C1 --> M2
    C1 --> M3

    M1 --> |authorizes access to| directory

    classDef sponsor fill:transparent,stroke:green,stroke-width:2px;
    classDef client fill:transparent,stroke:purple,stroke-width:2px;
    classDef mandate fill:transparent,stroke:#E50000,stroke-width:2px;
    classDef service fill:transparent,stroke:blue,stroke-width:2px;
    classDef grouping fill:transparent,color:black,stroke-dasharray: 4 10;
```

## Key Entities

### 🏢 **The Sponsor**

- **Who**: A Client of Seqino that signed up for the grey-label or white-label API. Examples include ERPs, Banks, Accounting Platforms, ODs.
- **Role**: Provides PDP services to their customers using Seqino APIs.
- **Responsibility**: Gather mandates, integrate Seqino's API. Manage invoicing operations on behalf of the **Clients**.
- **Creation process**: Contract between Sponsor and Seqino.


### 👥 **The Clients**

- **Who**: A company or a department that uses the **Sponsor**'s software/service (external to Seqino) for electronic invoicing and other services.
- **Role**: Create, send, receive, pay invoices.
- **Responsibility**:
  - The client will need to sign a mandate or delegate its consent to the PDP Sponsor.
  - 🤍 White label: the client designates the Sponsor as its PDP.
  - 🖤 Grey label: the client designates Seqino as its PDP.
- **Identifier**: `X-PDP-Client-Id` header (required for most operations). Unique identifier.
- **Creation process**: Through the Sponsor dashboard or Onboarding API.


### 📋 **Mandate**

- **What**:
  - A Mandate allows the **Client** to grant the **Sponsor** the right to manage PDP operation on their behalf, specifically receiving invoices and managing their lifecycle.
  - The scope of a mandate reflects the scope of a PPF directory entry (Ligne d'annuaire). The following types of scopes are allowed:
    - SIREN
    - SIREN + suffix (Simple flat way of separating multiple departments without using SIRET)
    - SIREN + SIRET
    - SIREN + SIRET + routing_code (code routage)
- **Purpose**: Materializes the relationship between a PDP (reception PDP) and a business entity.
- **Creation process**: Through the Sponsor dashboard or Onboarding API.


## API Architecture

### Headers & Authentication


```http
X-PDP-Client-Id: client-acme-corp        # Required for client operations
```

### Endpoint Categories

| Category | Purpose | Requires Client ID |
|  --- | --- | --- |
| **Clients** | Manage clients and onboarding |  |
| **Settings** | Configure client preferences |  |
| **Usage** | Gather API usage per client and invoice accordingly |  |
| **Mandates** | Manage legal entities and PPF directory entries |  |
| **Drafts** | Create and validate invoice drafts |  |
| **Invoicing** | Send and receive electronic invoices |  |
| **Reporting** | Send e-reporting information |  |
| **Lifecycle** | Polls or subscribes to lifecycle events |  |


### Typical Workflow

1. **🔗 Onboarding**: Create onboarding link for new client
2. **📋 Mandate Creation**: Client grants permissions via signed mandate
3. **📘 Directory Setup**: Register company routing information
4. **📄 Invoice Processing**: Send/receive electronic invoices
5. **📊 Monitoring**: Track usage and generate reports or invoices for the sponsor's clients


## Getting Started

1. **Obtain Credentials**: Get your `X-PDP-Sponsor-Id` from Seqino
2. **Client Onboarding**: Use onboarding endpoints to register new clients
3. **Directory Management**: Set up company routing information
4. **Start Invoicing**: Begin sending and receiving electronic invoices