API REST

URL de base https://verify.orvel.dev. Interface OpenAPI interactive : /api. Schéma exploitable : /openapi.json.

Authentification

Authorization: Bearer ev.<votre clé>

X-API-Key: <clé> fonctionne aussi. Sans clé, les endpoints de vérification répondent tout de même, dans la limite de 20 requêtes par minute et par IP. Obtenez une clé sur la page Tarifs.

Endpoints

Méthode	Chemin	Outil
GET	/v1/vat/{vat}	check_vat. Query : country_code, requester_vat.
GET	/v1/siren/{q}	lookup_siren. q = SIREN, SIRET ou nom.
GET	/v1/siret/{siret}/normalize	normalize_siret
GET	/v1/iban/{iban}	check_iban. Query : bic.
POST	/v1/address/normalize	normalize_address_eu. Corps : address, country_code, postal_code, city.
GET	/v1/phone/{phone}	normalize_phone. Query : region.
GET	/v1/email/{email}	check_email. Query : mx (défaut true).
GET	/v1/eori/{eori}	check_eori
GET	/v1/statuses	Signification de chaque valeur de status. Gratuit.
GET	/v1/usage	Votre compteur mensuel. Gratuit.
GET	/v1/plans	Catalogue des plans et liens de paiement. Gratuit.
GET	/health	Version et état du magasin de compteurs. Gratuit.

Tous renvoient l'enveloppe. Les arguments sont repris dans input.

Exemples

# TVA, avec preuve d'audit
curl -H "Authorization: Bearer $EV_KEY" \
  "https://verify.orvel.dev/v1/vat/FR03552081317?requester_vat=FR40303265045"

# Entreprise française par nom
curl -H "Authorization: Bearer $EV_KEY" \
  "https://verify.orvel.dev/v1/siren/electricite%20de%20france"

# IBAN et le BIC saisi par le client
curl -H "Authorization: Bearer $EV_KEY" \
  "https://verify.orvel.dev/v1/iban/DE89370400440532013000?bic=COBADEFFXXX"

# Adresse
curl -X POST -H "Authorization: Bearer $EV_KEY" -H "Content-Type: application/json" \
  -d '{"address":"22 avenue de wagram","postal_code":"75008","city":"Paris","country_code":"FR"}' \
  https://verify.orvel.dev/v1/address/normalize

# E-mail sans la requête DNS
curl -H "Authorization: Bearer $EV_KEY" \
  "https://verify.orvel.dev/v1/email/bob@example.com?mx=false"

En-têtes de réponse

En-tête	Signification
X-Plan	Plan associé à la clé, ou anonymous.
X-Usage-Used, X-Usage-Quota, X-Usage-Remaining	Compteur mensuel après cet appel.
Retry-After	Uniquement avec upstream_unavailable : secondes à attendre.

Erreurs

Les erreurs sont en JSON, jamais l'enveloppe :

{ "code": "quota_exceeded", "message": "Monthly quota of 500 calls reached for plan 'free'. Upgrade at /docs/pricing/", "used": 500, "quota": 500 }

Code	HTTP	Signification
invalid_input	400	Un argument obligatoire était vide.
validation_error	422	Le corps ne correspond pas au schéma ; voir details.
invalid_api_key	401	Clé inconnue, expirée ou résiliée.
api_key_required	401	L'endpoint exige une clé (/v1/usage, espace client).
quota_exceeded	402	Quota mensuel épuisé. Passez au plan supérieur ou attendez la remise à zéro.
rate_limited	429	Limite anonyme atteinte ; utilisez une clé.

Un identifiant faux n'est pas une erreur : c'est un 200 avec status: "invalid". Un registre hors service est également un 200, avec status: "upstream_unavailable".

Règles de facturation

Un appel réussi = une unité sur le quota mensuel. Non décomptés : upstream_unavailable, 4xx, 5xx, /v1/usage, /v1/plans, /v1/statuses, /health. Les compteurs repartent de zéro le 1er du mois (UTC).