Skip to content

External validators: VIES, GLEIF and the bank registry

Some facts can only be checked against a registry: is this VAT id registered, is this LEI active, does this IBAN belong to a real bank. These are external validators, plugins of the rules engine (kind: external, see Validation rules). Whatever goes wrong with a registry, the answer is inconclusive, never a guessed pass or fail.

{
  "id": "supplier_vat_registered",
  "kind": "external",
  "blocking": true,
  "external": { "validator": "vies", "operation": "check_vat", "params": { "vat_id": "${supplier_vat_id}" } }
}
Validator Operation Params Verdicts
vies check_vat vat_id registered → pass; not registered or fails the country format/check digit → fail (the check digit is local, no call); service down, MS_UNAVAILABLE or timeout → inconclusive
gleif lei_status lei ISSUED → pass; LAPSED, RETIRED, ANNULLED or any other status → fail (registry_status); 404 → fail; 429, 5xx, timeout → inconclusive
bank_registry check_iban iban, optional bic bank found → pass (name and BIC); unknown bank code → fail (bank_not_found); bic ≠ registry BIC (first 8 characters) → fail (bic_mismatch); country without registry → inconclusive (registry_not_available)

compared_values of the verdict holds the parameters, the registry's minimal facts (valid, registry_status, bank, bic), source, checked_at, cache_hit and, when it is not a plain pass or fail, reason: validator_unavailable, validator_timeout, validator_rate_limited, registry_unavailable_for_country, invalid_format, … The inconclusive_reason of the result is connector_unavailable, connector_timeout, connector_rate_limited or registry_not_available. A blocking rule that is inconclusive requires review unless the rule says on_inconclusive: ignore. In all_of / any_of the three-valued logic holds: all_of[inconclusive, pass] is inconclusive, any_of[inconclusive, pass] is pass.

Behaviour common to the network validators

  • Timeout 5 s (at most 15 s) and at most 2 retries, with exponential backoff and jitter, only on 5xx, 429 and timeouts, and never beyond 3× the timeout in total.
  • Rate limit per (tenant, validator): 2 requests per second and 4 in flight, in process; callers over the limit wait in a queue, nothing fails because of it. With several workers the effective limit is per worker.
  • Cache keyed by (tenant, validator, operation, HMAC-SHA256(canonical params)), with a key derived from the tenant's encryption (server) or DX_CACHE_HMAC_KEY (local): the number never appears in the table, the key or the logs. TTL 24 h for VIES and GLEIF; unavailable results live at most 60 s. Only the minimal result is stored (never the holder's name or address). The external_cache setting off (use_tenant(..., external_cache=False)) writes and reads nothing. Disabling it automatically for zero-data-retention projects is T50.
  • HTTP client (rules/external/http.py): HTTPS only, hosts restricted to the configured base URLs (DX_GLEIF_BASE_URL), the host is resolved and refused when any address is private, loopback, link-local or the metadata address, no proxy from the environment, no redirects, responses cut at 1 MiB and only JSON content types.
  • Registry answers are data: they never enter a prompt.

VIES goes through stdnum.eu.vat.check_vies (python-stdnum, LGPL-2.1+, an unmodified dynamic dependency named in NOTICE, version pinned; the SOAP client it needs is optional, and without it VIES is unavailable). Its URL is fixed by the library, so the VIES call does not use the HTTP client above. The bank registry is schwifty (MIT), local and offline.

Writing a validator

Implement ExternalValidatorBase.prepare (local checks, normalized params) and remote (the call), and register it under the extractit.external_validators entry point; the cache, the limiter, the retries and the typed failures come from the base class. Tests use respx for HTTP and a patched check_vies with the synthetic fixtures in tests/fixtures/external/; the tests that would reach the real services are written and marked live and are not run in CI.