API voor controle van een intracommunautair btw-nummer

Het formaat van het btw-nummer per land

Een btw-nummer begint met de landcode, gevolgd door een nummer waarvan de opbouw per land verschilt. De API controleert het formaat en, wanneer het land dat voorziet, het controlecijfer, voordat er wordt gezocht.

In Frankrijk wordt het controlecijfer berekend op basis van het SIREN-nummer: (12 + 3 × (SIREN modulo 97)) modulo 97. Voor SIREN 652014051 is de rest 14 en is het nummer FR14652014051. Zwitserland is geen lid van de Europese Unie en het Verenigd Koninkrijk heeft de Unie verlaten: hun nummers zijn geen intracommunautaire nummers, en het Verenigd Koninkrijk wordt voor btw niet ondersteund. Voor meer details over de formaten, zie Intracommunautair btw-nummer: formaat en controle.

Geldig of ongeldig: het teruggegeven resultaat

De route GET /v2/validate controleert het btw-nummer alleen of samen met het SIREN- of SIRET-nummer van de klant. Ze antwoordt 200, ook als het nummer ongeldig is: het veld valid is alleen true als alle controles zijn geslaagd, en checks toont elke controle afzonderlijk.

De andere controles die nuttig zijn voor de facturatie zijn vat_format (correct opgebouwd nummer), identifiers_match (het SIREN-nummer, het SIRET-nummer en het btw-nummer horen bij hetzelfde bedrijf) en company_active (het bedrijf is niet gesloten).

Voorbeeld van een verzoek en antwoord

curl "https://api.jsonpage.com/v2/validate?vat=FR14652014051" \
  -H "X-API-Key: $JSONPAGE_API_KEY"

{
  "data": {
    "valid": true,
    "checks": [
      { "code": "vat_format", "ok": true, "value": "FR14652014051" },
      { "code": "company_exists", "ok": true, "value": "FR-652014051" },
      { "code": "company_active", "ok": true, "value": "active" },
      { "code": "vat_registered", "ok": true, "value": "valid" }
    ],
    "company": {
      "id": "FR-652014051",
      "name": "CARREFOUR",
      "status": "active",
      "vat": { "number": "FR14652014051", "status": "valid", "checked_at": "..." },
      "...": "..."
    }
  }
}

Verkort antwoord: de basisvelden van het bedrijfsprofiel zijn weggelaten. Om alleen het btw-blok van een profiel te lezen, voegt u ?include=vat toe aan GET /v2/companies/{id}.

In JavaScript

const url = "https://api.jsonpage.com/v2/validate?vat=" + encodeURIComponent("FR14652014051");
const res = await fetch(url, { headers: { "X-API-Key": process.env.JSONPAGE_API_KEY } });
const { data } = await res.json();
if (!data.valid) console.log(data.checks.filter((c) => !c.ok));

In Python

import os, requests

res = requests.get(
    "https://api.jsonpage.com/v2/validate",
    params={"vat": "FR14652014051"},
    headers={"X-API-Key": os.environ["JSONPAGE_API_KEY"]},
)
data = res.json()["data"]
print(data["valid"], [c for c in data["checks"] if not c["ok"]])

Toepassingen in de facturatie

• Intracommunautaire levering. Vrijstelling van btw veronderstelt een geldig nummer van de klant: controleer het voordat u de factuur uitreikt.
• Een klant of leverancier aanmaken. Controleer het ingevoerde btw- en SIREN-nummer en vul daarna de naam en het adres vooraf in vanuit het bedrijfsprofiel.
• Een leveranciersfactuur betalen. Controleer of het btw-nummer echt van de begunstigde is en of het bedrijf actief is.
• Opvolging op lange termijn. De monitoring waarschuwt u via webhook wanneer een bedrijf sluit of in een collectieve procedure terechtkomt.

Voor een volledig klantenbestand controleert het aanbod voor het opschonen van klantenbestanden elke regel zonder dat u code hoeft te schrijven.

Prijzen en limieten

Kennismaking à € 0, Standard à € 19 excl. btw per maand, Pro à € 129 excl. btw per maand, met 100, 1.000 en 10.000 verzoeken per minuut en 1.000 verzoeken per dag. Vaste prijs, geen credits, geen extra kosten bij overschrijding. Zie de tarieven.

Verder lezen

• SIRENSIREN- en SIRET-APIBedrijfsprofiel, zoeken op naam, autocomplete en controle.
• DOCUMENTATIEValidatie in de documentatieAlle controles van de validatieroute, een voor een.
• GIDSIntracommunautair btw-nummer: formaat en controleWaar het nummer voor dient, veelgemaakte fouten en de vermeldingen op de factuur.