API REST
Intégrer le Guichet Unique

Pour les éditeurs de logiciels métier et les cabinets qui développent leurs propres outils, l'API REST du Guichet Unique ouvre des perspectives considérables. Cette documentation technique synthétise notre expérience de 3 ans d'intégration sur plus de 500 000 appels API mensuels.

Présentation de l'API

L'API REST du Guichet Unique est mise à disposition par l'INPI pour permettre aux éditeurs de logiciels d'intégrer directement les formalités d'entreprise dans leurs outils. Elle couvre aujourd'hui environ 85 % des cas d'usage courants.

Caractéristiques principales :

• Architecture RESTful standard avec endpoints versionnés
• Format d'échange : JSON uniquement
• Authentification : OAuth 2.0 avec refresh token
• Rate limiting : 100 requêtes / minute par client
• Disponibilité : 99,5 % contractualisée

Obtenir un accès

L'accès à l'API n'est pas automatique. Il faut :

1. Créer un compte sur le portail développeur de l'INPI
2. Soumettre un dossier d'accréditation (forme juridique, objet, volume attendu, sécurité)
3. Recevoir les credentials (client_id + client_secret) sous 5 à 15 jours ouvrés
4. Passer la certification technique (sandbox puis production)

Pour les cabinets sans ressources techniques internes, une alternative consiste à passer par un intermédiaire déjà certifié comme Demat-Facile.

Authentification OAuth 2.0

L'authentification se fait en deux étapes :

1. Obtention du token d'accès

Requête POST vers /oauth/token avec :

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=VOTRE_CLIENT_ID
client_secret=VOTRE_CLIENT_SECRET
scope=formalities.read formalities.write

Réponse :

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200a1b2c3d4..."
}

2. Utilisation du token

Chaque appel API inclut le header :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Le token est valide 1 heure. Utilisez le refresh_token pour en obtenir un nouveau sans redemander les credentials.

Les endpoints principaux

Formalités

• POST /v1/formalities : créer une nouvelle formalité
• GET /v1/formalities/{id} : consulter une formalité
• PUT /v1/formalities/{id} : modifier une formalité en cours
• POST /v1/formalities/{id}/submit : soumettre pour traitement
• DELETE /v1/formalities/{id} : supprimer une formalité non soumise

Entreprises

• GET /v1/entreprises/{siren} : récupérer les infos d'une entreprise
• GET /v1/entreprises/search?q=... : rechercher une entreprise
• GET /v1/entreprises/{siren}/beneficiaires : liste des BE déclarés

Documents

• POST /v1/documents : uploader un document (PDF uniquement, 25 MB max)
• GET /v1/documents/{id} : télécharger un document
• DELETE /v1/documents/{id} : supprimer un document

Workflow type d'une création de société

1. Authentification (POST /oauth/token)
2. Upload des pièces (projet de statuts, justificatifs dirigeants, etc.)
3. Création de la formalité (POST /v1/formalities avec les métadonnées)
4. Rattachement des documents (PATCH /v1/formalities/{id}/documents)
5. Calcul des frais (GET /v1/formalities/{id}/fees)
6. Paiement via le module dédié (POST /v1/payments)
7. Soumission définitive (POST /v1/formalities/{id}/submit)
8. Suivi du traitement via webhooks ou polling

Webhooks : recevoir les notifications

Plutôt que de faire du polling, utilisez les webhooks pour recevoir les notifications en temps réel :

POST /v1/webhooks
Content-Type: application/json
Authorization: Bearer ...

{
  "url": "https://votre-domaine.com/webhooks/gu",
  "events": ["formality.submitted", "formality.accepted", "formality.rejected"],
  "secret": "votre_secret_pour_signature_HMAC"
}

Les événements notifiés sont signés en HMAC-SHA256 pour garantir l'authenticité.

Gestion des erreurs

L'API utilise les codes HTTP standards avec un corps JSON structuré :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le capital social est obligatoire pour cette forme juridique",
    "field": "capitalSocial",
    "trace_id": "abc123-xyz789"
  }
}

Les erreurs les plus courantes à anticiper :

• 401 : Token expiré ou invalide → refresh automatique
• 403 : Scope insuffisant → vérifier les permissions de votre app
• 409 : Conflit (formalité déjà soumise, entreprise déjà existante)
• 422 : Validation métier échouée (cohérence des données)
• 429 : Rate limit dépassé → back-off exponentiel recommandé
• 503 : Service temporairement indisponible → retry après 30s

Bonnes pratiques

1. Idempotence : utilisez un header X-Idempotency-Key sur les POST pour éviter les doubles soumissions
2. Pagination : les listings sont paginés à 50 éléments par défaut, jusqu'à 200 max
3. Cache : mettez en cache les données entreprises (TTL 1h recommandé)
4. Logs : conservez trace_id dans vos logs pour le support INPI
5. Sandbox : testez toujours vos modifications en sandbox avant la production

Limites actuelles de l'API

Pour être honnête, l'API a encore quelques limitations :

• Certaines formalités rares ne sont pas disponibles (fusions complexes, scissions multi-sociétés)
• Pas de support natif du multi-langues pour les statuts bilingues
• Documentation officielle parfois incomplète ou désynchronisée
• Sandbox moins stable que la production (paradoxalement)
• Temps de réponse variables sur les opérations de grande taille (> 50 Mo de documents)

L'approche Demat-Facile

Nous utilisons cette API en production depuis 2023. Notre plateforme expose à son tour une API unifiée qui :

• Abstrait les particularités de l'API INPI (rate limiting, formats, erreurs)
• Ajoute des endpoints manquants (annonces légales, dépôts de comptes, publications JAL)
• Propose une gestion avancée des webhooks et de la supervision
• Inclut un SDK PHP, Python et JavaScript
• Bénéficie d'un SLA de 99,9 % (vs 99,5 % API INPI)

En résumé

L'API REST du Guichet Unique est un outil puissant mais qui demande une vraie maîtrise technique pour être exploité efficacement. Pour les éditeurs de logiciels et les cabinets avec équipe de développement, l'investissement initial (1 à 3 mois de développement) se rentabilise rapidement.

Pour les autres, une solution intermédiaire comme l'API Demat-Facile permet de profiter de la puissance de l'API INPI sans les complexités techniques associées. Contactez-nous pour une démo technique.