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) orDX_CACHE_HMAC_KEY(local): the number never appears in the table, the key or the logs. TTL 24 h for VIES and GLEIF;unavailableresults live at most 60 s. Only the minimal result is stored (never the holder's name or address). Theexternal_cachesetting 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.