Documentation de l'API — v1

POST /api/v1/tenants

Création complète d’un tenant local. Cette route administrative utilise SUPERADMIN_API_KEY et n’appelle pas B2Brouter. Le body JSON n’est pas enveloppé dans account.

Body JSON (recommandé)

{
  "name": "ENTREPRISE EXEMPLE",
  "slug": "entreprise-exemple",
  "companyName": "ENTREPRISE EXEMPLE",
  "siren": "123456789",
  "siret": "12345678900010",
  "vatNumber": "FRXX123456789",
  "rcsCity": "VILLE EXEMPLE",
  "rcsNumber": "123456789",
  "legalRepresentativeName": "NOM EXEMPLE",
  "legalRepresentativeTitle": "Gérant",
  "street": "1 RUE EXEMPLE",
  "city": "VILLE EXEMPLE",
  "zipCode": "35000",
  "province": "Ille-et-Vilaine",
  "country": "FR",
  "phone": "+33 2 99 00 00 00",
  "electronicInvoicingEmail": "facturation@example.fr",
  "dgfipTypeOperation": "services",
  "dgfipEnterpriseSize": "pme",
  "dgfipNafCodePrefix": "62",
  "dgfipAnnuaireOnly": true,
  "dgfipStartDate": "2026-09-01"
}

Les champs métier facultatifs acceptent null ou une chaîne vide, normalisée en null. Le SIRET doit commencer par le SIREN. Avec dgfipAnnuaireOnly=false, la taille et le préfixe NAF sont obligatoires. isActive, b2brouterAccountId, les statuts et l’erreur d’onboarding ne sont pas librement modifiables par ces routes.

La province est obligatoire avant la création du compte B2Brouter. Le téléphone reste facultatif et nullable. La taille et le préfixe NAF à deux chiffres sont à collecter dès l’onboarding ; en mode Annuaire uniquement, ils restent stockés sans être envoyés au réglage DGFiP.

Les valeurs DGFiP officielles sont services, goods, mixed et ge, eti, pme, micro. Les anciennes formes en majuscules restent temporairement acceptées, puis sont normalisées et stockées en minuscules.

curl -X POST "https://facturation.sipco.fr/api/v1/tenants" \
      -H "Authorization: Bearer <SUPERADMIN_API_KEY>" \
      -H "Content-Type: application/json" \
      -d @tenant.json

POST /api/v1/tenants/:slug/b2brouter/account

Crée ou rattache le compte parent français B2Brouter d’un tenant existant. Route protégée par SUPERADMIN_API_KEY. Le tenant doit disposer d’une raison sociale, d’un SIREN, d’un numéro de TVA français et d’une adresse complète, sans compte B2Brouter déjà associé.

Le Hub recherche d’abord un compte compatible par SIREN (cin_scheme=0002). Un résultat unique est rattaché ; sinon le compte parent est créé au niveau SIREN. L’adresse e-mail provient exclusivement de electronicInvoicingEmail, enregistrée au préalable dans le tenant.

curl -X POST "https://facturation.sipco.fr/api/v1/tenants/<TENANT_SLUG>/b2brouter/account" \
-H "Authorization: Bearer <SUPERADMIN_API_KEY>" \
-H "Content-Type: application/json" \
-d '{}'

MVP strict : aucune unité organisationnelle SIRET, aucun transport, aucun utilisateur B2Brouter, aucune activation DGFiP et aucune TenantApiKey ne sont créés. Erreurs principales : 400 validation, 401 authentification, 404 tenant absent, 409 compte lié, ambigu, incompatible ou en conflit, 502 erreur B2Brouter, 503 configuration absente ou résultat de création incertain.

POST /api/v1/tenants/:slug/b2brouter/dgfip

Crée ou retrouve le DgfipTaxReportSetting du compte déjà lié. Cette étape distincte permet de reprendre un onboarding dont le compte existe mais dont l’inscription Annuaire manque. Route protégée par SUPERADMIN_API_KEY.

curl -X POST "https://facturation.sipco.fr/api/v1/tenants/<TENANT_SLUG>/b2brouter/dgfip" \
-H "Authorization: Bearer <SUPERADMIN_API_KEY>" \
-H "Content-Type: application/json" \
-d '{}'

Le réglage est créé avec code=dgfip, enabled=true et annuaire_only=true par défaut. En mode Annuaire uniquement, la taille d’entreprise et le préfixe NAF ne sont pas obligatoires. L’e-mail, le type d’opération et la date de début viennent du tenant.

Aucun transport Peppol n’est créé manuellement. Un 422 DGFIP_DIRECTORY_ALREADY_LINKED_TO_ANOTHER_PA signale une entreprise déjà rattachée à une autre PA ; les autres erreurs 422 sont retournées sous B2BROUTER_VALIDATION_ERROR. Un compte créé ne signifie pas que l’onboarding est actif : le statut devient ACTIVE après création ou détection d’un réglage DGFiP compatible.