Unités légales

Les routes legal-units permettent de créer, lister, consulter et configurer les unités légales racines du tenant.

Une unité légale est une ressource durable de la Tenant Public API. Elle possède son propre identifiant canonique, le legalUnitId, et porte notamment :

ses identifiants métier (rootIdentifiers) ;
sa direction opérateur (operatorDirection) ;
son régime de TVA (vatRegime) ;
un résumé de son parcours d'onboarding lorsqu'un parcours existe.

La création d'une unité légale ne démarre pas automatiquement son onboarding. Le parcours est démarré ensuite avec :

POST /v1/onboarding/legal-units/{legalUnitId}/start

Vue d'ensemble des opérations

Besoin	Opération
Lister les unités légales du tenant	`GET /v1/onboarding/legal-units`
Créer une unité légale	`POST /v1/onboarding/legal-units`
Consulter une unité légale	`GET /v1/onboarding/legal-units/{legalUnitId}`
Modifier son régime de TVA	`PATCH /v1/onboarding/legal-units/{legalUnitId}/vat-regime`

Créer une unité légale

POST /v1/onboarding/legal-units

Cette opération crée une nouvelle unité légale racine dans le tenant courant.

Exemple de requête

{
  "countryCode": "FR",
  "name": "ACME France SAS",
  "identifierScheme": "0002",
  "identifierValue": "123456789",
  "operatorDirection": "BIDIRECTIONAL"
}

Champs de la requête

Champ	Rôle
`countryCode`	Pays de l'unité légale. Exemple : `FR`.
`name`	Nom de l'organisation.
`identifierScheme`	Schéma de l'identifiant métier principal. Pour un SIREN : `0002`.
`identifierValue`	Valeur de l'identifiant métier principal.
`operatorDirection`	Direction d'utilisation de l'unité légale.

Valeurs de `operatorDirection`

Valeur	Signification
`INBOUND`	L'unité légale est utilisée pour la réception.
`OUTBOUND`	L'unité légale est utilisée pour l'émission.
`BIDIRECTIONAL`	L'unité légale est utilisée en émission et en réception.

Lorsque operatorDirection n'est pas fourni, la valeur par défaut est BIDIRECTIONAL.

Pour une entreprise française, l'identifiant principal correspond généralement au SIREN.

L'unité légale constitue également le périmètre à partir duquel les adresses de facturation électronique seront vérifiées et inscrites pendant l'onboarding. Le SIREN principal n'impose pas qu'une seule adresse soit utilisée : des adresses à la maille établissement ou service peuvent être ajoutées au parcours.

Résultat à conserver

La plateforme attribue un legalUnitId. Cet identifiant doit être conservé par l'intégration : il devient l'identifiant canonique utilisé pour consulter l'unité légale, modifier son régime de TVA et piloter son onboarding.

Ne pas remplacer legalUnitId par un SIREN ou SIRET

Dans une route qui attend {legalUnitId}, utilisez l'identifiant retourné par la plateforme.

La création de l'unité légale ne déclenche pas son onboarding. Celui-ci est démarré explicitement avec /start.

Lister les unités légales

GET /v1/onboarding/legal-units

Cette opération restitue les unités légales racines accessibles dans le contexte du tenant courant.

Elle permet notamment de :

initialiser ou réconcilier le référentiel de l'intégrateur ;
retrouver les legalUnitId déjà créés ;
connaître la configuration courante des unités légales ;
récupérer leur régime de TVA ;
obtenir un état synthétique de leur onboarding lorsqu'un parcours existe.

Exemple de réponse

{
  "items": [
    {
      "legalUnitId": "01a0ba6b-d3df-710e-a4fc-c55eac7c54b4",
      "countryCode": "FR",
      "name": "ACME France SAS",
      "operatorDirection": "BIDIRECTIONAL",
      "vatRegime": "REAL_QUARTERLY_TAX_REGIME",
      "nextVatRegime": null,
      "nextVatRegimeEffectiveDate": null,
      "rootIdentifiers": [
        {
          "scheme": "0002",
          "value": "123456789",
          "isPrimary": true
        }
      ],
      "onboarding": {
        "onboardingRequestId": "01a0ba6b-e99b-7228-a21b-6e8ee06eb096",
        "status": "active",
        "expiresAt": null,
        "onboardingUrl": null,
        "availableActions": [
          {
            "rel": "view_history",
            "method": "GET",
            "href": "/v1/onboarding/legal-units/01a0ba6b-d3df-710e-a4fc-c55eac7c54b4/history"
          }
        ]
      },
      "createdAt": "2026-09-19T16:07:03.903Z",
      "updatedAt": "2026-09-19T16:08:18.895Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

Structure d'une unité légale retournée

Champ	Description
`legalUnitId`	Identifiant canonique de l'unité légale dans la plateforme.
`countryCode`	Pays de l'unité légale.
`name`	Nom de l'unité légale.
`operatorDirection`	Direction opérateur configurée pour cette unité légale.
`vatRegime`	Régime de TVA actuellement applicable.
`nextVatRegime`	Prochain régime de TVA lorsqu'un changement futur est enregistré ; `null` sinon.
`nextVatRegimeEffectiveDate`	Date d'effet du prochain régime lorsqu'elle existe ; `null` sinon.
`rootIdentifiers`	Identifiants racines associés à l'unité légale.
`onboarding`	Résumé du parcours d'onboarding courant lorsqu'il existe.
`createdAt`	Date de création de la ressource.
`updatedAt`	Date de dernière mise à jour de la ressource.

`rootIdentifiers`

Une unité légale peut disposer de plusieurs identifiants racines.

L'identifiant principal d'une entreprise française est généralement le SIREN :

{
  "scheme": "0002",
  "value": "123456789",
  "isPrimary": true
}

isPrimary: true identifie l'identifiant principal de l'unité légale.

Des identifiants supplémentaires peuvent correspondre à des adresses de facturation électronique utilisant le scheme 0225.

Exemple :

{
  "rootIdentifiers": [
    {
      "scheme": "0002",
      "value": "123456789",
      "isPrimary": true
    },
    {
      "scheme": "0225",
      "value": "123456789_COMPTA",
      "isPrimary": false
    }
  ]
}

L'adresse complète correspond alors à :

0225:123456789_COMPTA

Les formes principales rencontrées sont :

<SIREN>
<SIREN>_<SIRET>
<SIREN>_<libellé_de_service>

Ne pas confondre présence de l'identifiant et inscription réseau

La présence d'un identifiant 0225 dans rootIdentifiers permet d'identifier une adresse associée à l'unité légale. Elle ne suffit pas, à elle seule, à déterminer son état d'inscription sur le réseau domestique français ou sur Peppol.

L'état d'onboarding, son historique et les données d'annuaire doivent être utilisés pour connaître la situation effective de l'adresse.

➡️ Comprendre les adresses de facturation électronique

Résumé d'onboarding

Le bloc onboarding donne une vue synthétique du parcours associé à l'unité légale :

{
  "onboardingRequestId": "01a0ba6b-e99b-7228-a21b-6e8ee06eb096",
  "status": "active",
  "expiresAt": null,
  "onboardingUrl": null,
  "availableActions": [
    {
      "rel": "view_history",
      "method": "GET",
      "href": "/v1/onboarding/legal-units/{legalUnitId}/history"
    }
  ]
}

Ce bloc est utile pour afficher rapidement la situation d'une unité légale. Pour suivre précisément le parcours, utilisez les routes dédiées :

GET /v1/onboarding/legal-units/{legalUnitId}/state
GET /v1/onboarding/legal-units/{legalUnitId}/history

availableActions décrit les opérations actuellement proposées pour la ressource. L'intégration ne doit pas reconstruire les URLs à partir de onboardingRequestId lorsqu'un href est fourni.

Pagination

La réponse contient un bloc meta :

{
  "total": 3,
  "limit": 50,
  "offset": 0
}

Champ	Description
`total`	Nombre total d'unités légales correspondant à la requête.
`limit`	Nombre maximal d'éléments retournés dans la page.
`offset`	Position du premier élément de la page dans le résultat global.

Consulter une unité légale

GET /v1/onboarding/legal-units/{legalUnitId}

Cette opération restitue l'état courant d'une unité légale racine identifiée par son legalUnitId canonique.

Elle retourne directement la ressource, sans enveloppe items / meta.

Exemple de réponse

{
  "legalUnitId": "01a0ba6b-d3df-710e-a4fc-c55eac7c54b4",
  "countryCode": "FR",
  "name": "ACME France SAS",
  "operatorDirection": "BIDIRECTIONAL",
  "vatRegime": "REAL_QUARTERLY_TAX_REGIME",
  "nextVatRegime": null,
  "nextVatRegimeEffectiveDate": null,
  "rootIdentifiers": [
    {
      "scheme": "0002",
      "value": "123456789",
      "isPrimary": true
    }
  ],
  "onboarding": {
    "onboardingRequestId": "01a0ba6b-e99b-7228-a21b-6e8ee06eb096",
    "status": "active",
    "expiresAt": null,
    "onboardingUrl": null,
    "availableActions": [
      {
        "rel": "view_history",
        "method": "GET",
        "href": "/v1/onboarding/legal-units/01a0ba6b-d3df-710e-a4fc-c55eac7c54b4/history"
      }
    ]
  },
  "createdAt": "2026-09-19T16:07:03.903Z",
  "updatedAt": "2026-09-19T16:08:18.895Z"
}

Utilisez cet appel lorsque vous devez relire la ressource unité légale elle-même : identifiants, direction opérateur, régime de TVA et résumé de l'onboarding.

Pour connaître l'avancement détaillé de son parcours d'onboarding, utilisez à la place :

GET /v1/onboarding/legal-units/{legalUnitId}/state

Pour comprendre la chronologie du parcours :

GET /v1/onboarding/legal-units/{legalUnitId}/history

Mettre à jour le régime de TVA

PATCH /v1/onboarding/legal-units/{legalUnitId}/vat-regime

Cette opération modifie le régime de TVA porté par une unité légale racine existante.

Le régime de TVA est une donnée importante pour le e-Reporting : il détermine notamment la périodicité des périodes de déclaration et les échéances associées.

Exemple de requête

{
  "vatRegime": "REAL_MONTHLY_TAX_REGIME"
}

Régimes de TVA

Les valeurs acceptées par l'API sont :

Régime	Valeur API
Régime réel normal mensuel	`REAL_MONTHLY_TAX_REGIME`
Régime réel normal trimestriel	`REAL_QUARTERLY_TAX_REGIME`
Régime simplifié	`SIMPLIFIED_TAX_REGIME`
Franchise en base de TVA	`VAT_EXEMPTION_REGIME`

Le régime de TVA détermine notamment le planning applicable au traitement des FRR d'e-Reporting.

Quand le changement devient-il effectif ?

Le comportement dépend de l'historique d'e-Reporting de l'unité légale.

Situation de l'unité légale	Effet du `PATCH`	Conséquence pour les FRR
Aucun e-Reporting n'a encore été envoyé	Le nouveau régime est appliqué immédiatement.	Les FRR peuvent être pris en compte immédiatement selon le planning associé au nouveau `vatRegime`.
Au moins un e-Reporting a déjà été envoyé	Le changement est enregistré mais son application est différée à une date future.	Jusqu'à cette date, les FRR restent traités selon le planning du régime actuellement actif. À partir de la date d'effet, ils sont traités selon le planning du nouveau régime.

Changement immédiat

Lorsqu'aucun e-Reporting n'a encore été envoyé pour l'unité légale, le régime demandé devient immédiatement le régime courant :

vatRegime contient la nouvelle valeur ;
nextVatRegime vaut null ;
nextVatRegimeEffectiveDate vaut null.

Le nouveau planning d'e-Reporting est donc applicable immédiatement.

Changement différé

Lorsqu'un ou plusieurs e-Reporting ont déjà été envoyés, le changement ne modifie pas immédiatement le régime courant. La plateforme planifie son application à une date future :

vatRegime continue de représenter le régime actuellement applicable ;
nextVatRegime contient le nouveau régime demandé ;
nextVatRegimeEffectiveDate indique la date à laquelle ce nouveau régime deviendra effectif.

Jusqu'à nextVatRegimeEffectiveDate, les FRR continuent d'être traités selon le planning associé au vatRegime courant. À compter de cette date, le nouveau régime devient applicable et les FRR suivent alors son planning.

Ne pas anticiper le nouveau planning

Lorsqu'un changement de régime est différé, l'intégrateur ne doit pas considérer le nouveau régime comme immédiatement actif. La date portée par nextVatRegimeEffectiveDate constitue la référence pour le basculement vers le nouveau planning d'e-Reporting.

Réponse

Le PATCH retourne l'état mis à jour de l'unité légale. Il n'est donc pas nécessaire d'effectuer immédiatement un GET supplémentaire pour connaître le résultat de la demande.

Selon le cas, cette réponse montre soit le nouveau régime immédiatement actif dans vatRegime, soit un changement planifié via nextVatRegime et nextVatRegimeEffectiveDate.

Exemple :

{
  "legalUnitId": "01a0ba6b-d3df-710e-a4fc-c55eac7c54b4",
  "countryCode": "FR",
  "name": "ACME France SAS",
  "operatorDirection": "BIDIRECTIONAL",
  "vatRegime": "REAL_MONTHLY_TAX_REGIME",
  "nextVatRegime": null,
  "nextVatRegimeEffectiveDate": null,
  "rootIdentifiers": [
    {
      "scheme": "0002",
      "value": "123456789",
      "isPrimary": true
    }
  ],
  "onboarding": {
    "onboardingRequestId": "01a0ba6b-e99b-7228-a21b-6e8ee06eb096",
    "status": "active",
    "expiresAt": null,
    "onboardingUrl": null,
    "availableActions": [
      {
        "rel": "view_history",
        "method": "GET",
        "href": "/v1/onboarding/legal-units/01a0ba6b-d3df-710e-a4fc-c55eac7c54b4/history"
      }
    ]
  },
  "createdAt": "2026-09-19T16:07:03.903Z",
  "updatedAt": "2026-09-20T08:15:12.125Z"
}

Dans cet exemple, le changement a été appliqué immédiatement : vatRegime contient la nouvelle valeur et aucun changement futur n'est planifié.

Lorsque la réponse contient au contraire nextVatRegime et nextVatRegimeEffectiveDate, l'intégrateur doit conserver vatRegime comme régime actif jusqu'à la date d'effet indiquée.

Séquence recommandée

Quel GET utiliser ?

Besoin	API
Lister toutes les unités légales et obtenir leur état synthétique	`GET /v1/onboarding/legal-units`
Relire la configuration complète d'une unité légale	`GET /v1/onboarding/legal-units/{legalUnitId}`
Suivre précisément l'avancement de l'onboarding	`GET /v1/onboarding/legal-units/{legalUnitId}/state`
Comprendre les étapes déjà parcourues	`GET /v1/onboarding/legal-units/{legalUnitId}/history`

➡️ Piloter l'onboarding

Vue d'ensemble des opérations​

Créer une unité légale​

Exemple de requête​

Champs de la requête​

Valeurs de operatorDirection​

Résultat à conserver​

Lister les unités légales​

Exemple de réponse​

Structure d'une unité légale retournée​

rootIdentifiers​

Résumé d'onboarding​

Pagination​

Consulter une unité légale​

Exemple de réponse​

Mettre à jour le régime de TVA​

Exemple de requête​

Régimes de TVA​

Quand le changement devient-il effectif ?​

Changement immédiat​

Changement différé​

Réponse​

Séquence recommandée​

Quel GET utiliser ?​

Vue d'ensemble des opérations

Créer une unité légale

Exemple de requête

Champs de la requête

Valeurs de `operatorDirection`

Résultat à conserver

Lister les unités légales

Exemple de réponse

Structure d'une unité légale retournée

`rootIdentifiers`

Résumé d'onboarding

Pagination

Consulter une unité légale

Exemple de réponse

Mettre à jour le régime de TVA

Exemple de requête

Régimes de TVA

Quand le changement devient-il effectif ?

Changement immédiat

Changement différé

Réponse

Séquence recommandée

Quel GET utiliser ?