Recherche d'entreprise

GET /api/company/lookup renvoie l'identité légale d'une entreprise française à partir d'un SIREN, d'un SIRET, d'un numéro de TVA FR ou d'un nom, en synchrone. Conçu pour préremplir un formulaire.

Recherche d'entreprise

GET /api/company/lookup transforme ce que saisit un utilisateur en fiche d'entreprise contrôlée, en un seul appel synchrone : raison sociale, forme juridique, code NAF, adresse du siège, numéro de TVA intracommunautaire et son statut VIES, dirigeant, contrôles de clé.

Usage type : un formulaire d'inscription ou de facturation où l'utilisateur tape un SIREN, un SIRET ou le début d'un nom d'entreprise, et votre code remplit tous les autres champs.

Fonctionne avec les clés API comme avec la session navigateur.

Sources

GET /api/company/lookup

Lecture de q :

• FR + 11 chiffres : numéro de TVA. La clé à 2 chiffres doit correspondre au SIREN qu'il contient, puis la recherche porte sur ce SIREN.
• 9 chiffres : SIREN. 14 chiffres : SIRET. Les deux doivent passer leur contrôle de clé (voir Contrôles).
• Toute autre suite de chiffres : refusée (format_invalide).
• Tout le reste : recherche par nom, de 2 à 120 caractères. Les candidats sont des entreprises distinctes (une par SIREN), meilleure correspondance d'abord.

curl -s "https://outsend.xyz/api/company/lookup?q=410409460" \
  -H "Authorization: Bearer osk_..."

Réponse : 200 OK

Réponse réelle pour le SIREN 410409460 :

{
  "requete": "410409460",
  "type_requete": "siren",
  "nb_resultats": 1,
  "resultats": [
    {
      "siren": "410409460",
      "siret_siege": "41040946000756",
      "raison_sociale": "AUCHAN HYPERMARCHE",
      "sigle": null,
      "forme_juridique": {
        "code": "5710",
        "libelle": "SAS, société par actions simplifiée"
      },
      "naf": {
        "code": "47.11F",
        "libelle": "Hypermarchés"
      },
      "date_creation": "1997-01-03",
      "etat": "actif",
      "adresse_siege": {
        "rue": "200 RUE DE LA RECHERCHE",
        "code_postal": "59491",
        "ville": "VILLENEUVE-D'ASCQ",
        "code_commune": "59009"
      },
      "etablissement": null,
      "dirigeant": {
        "type": "personne_morale",
        "nom": "AUCHAN RETAIL FRANCE",
        "prenoms": null,
        "qualite": "Président de SAS"
      },
      "tva_intracom": "FR20410409460",
      "tva_statut": "inconnu",
      "tva_verifiee_le": null,
      "controles": {
        "siren_luhn": true,
        "siret_siege_luhn": true
      }
    }
  ]
}

tva_statut vaut ici inconnu parce que le service VIES français était saturé au moment de l'appel ; voir Statut TVA.

Une recherche sans correspondance renvoie 200 avec nb_resultats: 0 et une liste resultats vide.

Champs

dirigeant n'est renseigné que :

• pour un entrepreneur individuel (personne_physique, qualite: "Entrepreneur individuel"), quel que soit le type de requête ;
• pour une société, quand la requête est un SIREN, un SIRET ou un numéro de TVA : le premier dirigeant inscrit au registre.

Sur une recherche par nom, dirigeant vaut null pour les sociétés. Il peut aussi valoir null quand le registre n'indique aucun dirigeant, ou quand l'information n'a pas pu être obtenue à temps.

Statut TVA

tva_intracom est toujours calculé (FR + clé + SIREN). Ce calcul ne dit rien de l'attribution réelle du numéro : chaque numéro est donc vérifié auprès de VIES.

Dans la requête, VIES dispose de 0,8 seconde au plus. S'il n'a pas répondu dans ce délai, la vérification en arrière-plan continue ses relances pendant 20 secondes au plus. Les réponses définitives sont conservées 24 h (valide) et 6 h (non_attribue) ; inconnu n'est jamais conservé.

Sur une recherche par nom, VIES n'est pas interrogé dans la requête : le statut de chaque candidat vient de ce cache, il vaut donc souvent inconnu, et une vérification en arrière-plan part pour chaque candidat absent du cache. Flux recommandé : recherche par nom, choix du candidat par l'utilisateur, puis nouvel appel avec le SIREN de ce candidat pour obtenir le statut vérifié.

Contrôles

Les mêmes contrôles s'appliquent à q avant toute recherche : un identifiant qui échoue est refusé en 400.

Cache

Les données du registre pour une requête donnée sont gardées 10 minutes. Le statut TVA suit son propre cache (ci-dessus) : un résultat dont le statut était inconnu est revérifié à l'appel suivant.

Erreurs

400 Bad Request

{
  "detail": {
    "code": "siret_invalide",
    "message": "Ce SIRET n'est pas valide : sa clé de contrôle est incorrecte. Vérifiez les 14 chiffres.",
    "suggestion": {
      "siret_siege": "41040946000756",
      "raison_sociale": "AUCHAN HYPERMARCHE"
    }
  }
}

C'est la réponse réelle à q=41040946000750 (dernier chiffre erroné). Basez votre logique sur detail.code, qui est stable ; detail.message est une phrase lisible que vous pouvez afficher à l'utilisateur.

401 / 403

401 sans identifiants valides. Voir Authentification.

429 Too Many Requests

Les limites s'appliquent par compte (toutes clés et session navigateur confondues) :

• 60 requêtes par minute ;
• 5 000 requêtes par jour.

Chaque appel compte, y compris ceux qui sont refusés. La réponse porte un en-tête Retry-After (en secondes) :

{ "detail": "Trop de requêtes. Réessayer dans 43s." }

Temps de réponse

Pour un SIREN, un SIRET ou un numéro de TVA, la vérification TVA attend VIES 0,8 s au plus, puis indique un statut inconnu. La première recherche d'une entreprise peut prendre jusqu'à 2 s environ, car son dirigeant est obtenu à ce moment ; la même entreprise est ensuite servie depuis le cache. Une recherche par nom n'attend pas VIES. Mesurée sur 15 noms via l'API publique, mots très courants compris, une recherche par nom a répondu en 0,09 à 0,44 s de bout en bout au premier appel, et en 0,04 à 0,11 s quand elle est répétée.

Et ensuite

• Authentification : créer une clé API
• Module SIRENE : extraction en volume depuis le même registre