Aller au contenu

Outils

Tous les outils renvoient l'enveloppe. Cette page décrit ce que chacun accepte, quel registre répond, et ce que signifient ses statuts en pratique. Les chemins REST sont sur la page API REST ; les noms d'outils MCP sont identiques.

check_vat — numéro de TVA intracommunautaire

vat, optionnellement country_code, optionnellement requester_vat.

Normalise le numéro (GR devient EL, GB devient XI, préfixes et séparateurs retirés), vérifie sa forme selon le format national, puis interroge VIES. Un numéro qui ne peut pas être un numéro de TVA de ce pays est rejeté localement, sans consommer d'appel au registre.

Statut Quand
valid Enregistré pour les échanges intracommunautaires. data.name / data.address si l'État membre les publie.
invalid Non enregistré, ou forme incorrecte pour le pays, ou pays absent de VIES.
upstream_unavailable La passerelle ou cet État membre est indisponible (MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, TIMEOUT, HTTP 5xx).

Plusieurs États membres renvoient --- au lieu du nom et de l'adresse. C'est leur choix, pas une réponse manquante : le numéro est bien valid.

Preuve d'audit. Passez requester_vat avec votre propre numéro de TVA pour utiliser la consultation authentifiée. VIES renvoie alors data.request_identifier, que vous pouvez conserver pour prouver quand vous avez vérifié un client — l'exigence habituelle pour exonérer une livraison intracommunautaire. Ces appels ne sont jamais servis depuis le cache, chacun devant obtenir son propre identifiant.

lookup_siren — entreprise française

q : un SIREN (9 chiffres), un SIRET (14 chiffres) ou une raison sociale.

Interroge Recherche d'entreprises (DINUM : RNE + données ouvertes Sirene). Un SIREN/SIRET dont la clé est fausse n'atteint jamais le registre.

Renvoie la dénomination, le nom commercial, le code NAF, la forme juridique, la tranche d'effectifs, la date de création, l'établissement visé par la requête (SIRET, adresse, code INSEE, coordonnées) et le numéro de TVA. Une recherche par nom renvoie aussi data.other_matches pour lever l'ambiguïté.

Statut Quand
valid L'unité légale existe et est active (etat_administratif = A).
invalid Aucune correspondance ; ou le SIREN existe mais est fermé ; ou le SIREN existe mais ne porte pas ce SIRET.
upstream_unavailable Registre indisponible, il nous a limités, ou nous nous sommes limités nous-mêmes pour rester sous son plafond.

Les enregistrements déclarés non diffusibles par leur titulaire sont absents des données ouvertes : une vraie entreprise unipersonnelle peut donc revenir invalid. Regardez data.total_results avant d'annoncer à un utilisateur que son entreprise n'existe pas.

normalize_siret — SIREN / SIRET, hors ligne

siret : 9 ou 14 chiffres, espacement libre.

Calcul local, aucun registre : clé de Luhn (y compris l'exception documentée de La Poste, où la somme des chiffres doit être un multiple de 5), découpage SIREN + NIC, forme espacée, et numéro de TVA français dérivé du SIREN.

Le statut est normalized quand tout est cohérent, invalid avec un reason si la longueur ou la clé est fausse. Jamais upstream_unavailable.

check_iban — IBAN et BIC

iban, optionnellement bic.

Clé mod-97, structure BBAN propre au pays, et la banque derrière le numéro quand le pays publie un registre (nom, BIC, code guichet, appartenance SEPA).

Statut Quand
valid Structurellement correct. Si un bic est fourni, il est également valide.
invalid Clé fausse, longueur incorrecte pour le pays, pays inconnu, ou bic mal formé.

Un bic d'un pays différent de l'IBAN ne rend pas le résultat invalid — des entités de groupe le font légitimement — mais c'est signalé dans reason pour que vous décidiez.

Cet outil vérifie le numéro, pas le compte. Il ne dit pas si le compte est ouvert ni à qui il appartient.

normalize_address_eu — adresse postale

address, optionnellement country_code, postal_code, city.

La France est géocodée via la Base Adresse Nationale : voie canonique, code postal, commune, code INSEE, coordonnées et score de correspondance. Un score inférieur à 0,5 revient en normalized avec un avertissement plutôt qu'en valid.

Les autres États membres ne reçoivent qu'une normalisation structurelle en v1 : code pays ISO, forme nationale du code postal et son espacement canonique (1234 AB pour NL, 12-345 pour PL, 1234-567 pour PT…), commune en casse titre. data.geocoded vaut false et aucun registre n'est consulté. Cette limite est assumée et indiquée dans la réponse.

Statut Quand
valid Géocodée avec confiance (FR uniquement).
normalized Forme canonique renvoyée sans correspondance dans un registre.
invalid Code postal incompatible avec le pays, pays hors UE, ou aucune adresse française ne correspond.
upstream_unavailable La BAN n'a pas répondu (FR uniquement).

normalize_phone — numéro de téléphone

phone, optionnellement region.

Métadonnées libphonenumber : formes E.164, internationale, nationale et RFC 3966, indicatif, région, type de ligne (mobile, fixed_line, voip…). region n'est nécessaire que pour les numéros écrits sans préfixe + ; sans elle, un numéro national ne peut pas être résolu et revient invalid.

Le statut est valid si le numéro existe dans ce plan de numérotation, invalid sinon. Jamais upstream_unavailable.

check_email — adresse e-mail

email, optionnellement mx (vrai par défaut).

Syntaxe et forme canonique (compatible IDN), puis les enregistrements MX du domaine par DNS. Un domaine sans MX mais avec un enregistrement A accepte tout de même le courrier (RFC 5321), ce qui est signalé par data.implicit_mx.

Également signalés : data.disposable pour les fournisseurs jetables connus (vérifié avant toute requête DNS) et data.role_account pour les boîtes partagées (info@, noreply@, facturation@…) — utile quand un parcours d'inscription exige un interlocuteur nommé.

Statut Quand
valid Syntaxe correcte et le domaine peut recevoir du courrier.
invalid Syntaxe fausse, fournisseur jetable, domaine inexistant, ou aucun serveur de messagerie.
normalized mx=false : syntaxe vérifiée, rien d'interrogé.
upstream_unavailable Le résolveur DNS n'a pas répondu.

Il n'y a pas de sondage SMTP : un résultat valid signifie que le domaine accepte le courrier, pas que la boîte existe. Sonder les boîtes fait blacklister les serveurs et ce service ne le fait pas.

check_eori — enregistrement douanier

eori.

Le service européen EOS validation en SOAP. Renvoie le nom et l'adresse de l'opérateur enregistré, les dates de validité et la description de statut du service. La forme est vérifiée localement d'abord (code pays sur deux lettres puis jusqu'à 15 caractères alphanumériques).

Statut Quand
valid Enregistré (status 0).
invalid Non enregistré, ou forme incorrecte.
upstream_unavailable Faute SOAP, délai dépassé, ou réponse sans statut.

Cache

Les réponses sont mises en cache pour que la même vérification répétée soit rapide et n'accable pas les registres. Durées par défaut : VIES 24 h si valide et 1 h si invalide, Sirene 24 h, EORI 24 h, adresses 7 jours, MX 1 h. Le champ cached indique quelle réponse vous avez obtenue. Un upstream_unavailable n'est jamais mis en cache, et les consultations VIES authentifiées ne sont jamais servies depuis le cache.