Validation de TVA B2B sur Shopify pour les clients néerlandais

Ce que Shopify permet de scripter, et ce qu’il interdit

C’est le cœur de toute intégration de données d’entreprise sur Shopify, et la plupart des guides l’esquivent : le paiement est fermé.

Une Function de validation du panier ou du paiement est du WebAssembly sans accès réseau. Elle ne peut jamais appeler elle-même VIES ni notre endpoint. Elle peut en revanche lire un metafield ou un attribut de panier renseigné plus tôt, et bloquer le paiement lorsqu’il indique vatValid: false. C’est la seule voie vers un blocage ferme dans le paiement, et elle suppose que la validation ait eu lieu en amont.

Où ranger les données

• Attribut de panier pour la commande en cours. Il apparaît comme détail supplémentaire de la commande et suit jusqu’à l’expédition.
• Metafield client pour les achats répétés, par exemple custom.kvk_number et custom.vat_valid_at. Stockez un horodatage avec la valeur, sinon dans un an personne ne sait plus ce que signifie ce true.
• Site de l’entreprise si vous faites du B2B. C’est là que va l’identifiant fiscal et là que se rattache l’exonération.
• Metafield de commande pour la preuve au moment de la commande. Pour la facturation électronique et tout audit ultérieur, vous voulez ce que vous avez vu à ce moment-là, pas ce qui est vrai aujourd’hui.

Le proxy d’application, concrètement

Un proxy d’application vous donne une route sous le domaine de votre boutique, que Shopify transmet à votre serveur. La clé d’API reste côté serveur et vous évitez totalement CORS.

# shopify.app.toml
[app_proxy]
url = "https://your-app.example.com/proxy"
subpath = "kvk"
prefix = "apps"

La boutique appelle /apps/kvk/lookup?kvk=68750110, Shopify le transmet à votre endpoint avec les paramètres de requête plus une signature. Vérifiez toujours cette signature avec le secret de votre application avant de consommer une recherche. Si vous la sautez, votre proxy est un tuyau ouvert vers votre quota pour quiconque connaît le chemin.

Votre gestionnaire effectue ensuite l’appel réel :

const r = await fetch(`https://api.kvkbase.nl/v1/lookup/${kvk}?enrich=true`, {
  headers: { Authorization: `Bearer ${process.env.KVKBASE_KEY}` },
});
if (r.status === 404) return json({ ok: false, reason: "not_found" }, 200);
const c = await r.json();
return json({
  ok: c.isActive,
  name: c.statutoryName ?? c.name,
  vat: c.vat?.number ?? null,
  vatValid: c.vat?.valid ?? null,
});

Remarquez le 200 renvoyé sur notre 404. Un front qui transforme tout code hors 2xx en erreur générique dit au client « une erreur est survenue » alors que la vraie réponse est « ce numéro n’existe pas ».

Si vous voulez seulement une aide à la saisie sur la page du panier ou du compte sans construire d’application, le widget peut aller directement dans votre thème. Il remplit les champs nom, adresse et TVA à partir d’une recherche, avec une clé publique. Pour la validation qui compte, restez sur le proxy.

Ce qui casse réellement en production

VIES est en panne. Les vérifications de TVA passent par le service de l’État membre, qui tombe régulièrement. Vous recevez UPSTREAM_ERROR au lieu d’un verdict. Si vous bloquez strictement sur ce résultat, votre paiement B2B est hors ligne aussi longtemps qu’un service public étranger. Stockez unknown, laissez passer la commande avec la TVA appliquée, et réévaluez dans le webhook.

Le client saisit le numéro de TVA de la holding. Au sein d’un groupe, la holding est souvent connue de VIES alors que l’entité qui passe commande ne l’est pas, ou l’inverse. Le numéro est valide, mais le nom de l’entreprise ne correspond pas aux données de livraison. Conservez les deux et signalez l’écart plutôt que de faire confiance aveuglément.

Le rattrapage des clients existants s’enlise. Enrichir des milliers de fiches clients par des appels unitaires atteint la limite de débit en moins d’une minute. Utilisez POST /v1/lookup/batch et traitez par blocs avec une pause entre chacun.

Les attributs de panier ne survivent pas à toutes les sessions. Si le client vide son panier ou revient dans une nouvelle session, votre attribut a disparu alors qu’il est convaincu de l’avoir déjà renseigné. Écrivez la validation dans le metafield client dès sa connexion, et reconstituez le panier à partir de là.