DEV Community: Iurii Rogulia

When a Human Is Your Integration

Iurii Rogulia — Mon, 10 Aug 2026 10:00:50 +0000

Most businesses don't buy disconnected systems on purpose. They arrive one tool at a time. You start with a spreadsheet. You add a CRM because the spreadsheet stopped scaling. Accounting software because the taxman insisted. A shipping portal because you started sending parcels. Each choice was sensible on its own day.

Then one morning you look up and realize that none of these tools talk to each other — and the thing holding them together is a person. Someone reads a number off one screen and types it into another. That person is your integration. And that's a cost you're paying every day without ever seeing it on an invoice.

The Cost You Don't Get Billed For

Here's the trap. The cost of a disconnected system doesn't show up anywhere you look. It's not a subscription. It's not a line item. It's hidden inside a job title.

Someone on your team spends the first hour of every day taking yesterday's orders and copying them, one at a time, from the checkout into the accounting system, then into the CRM, then into the shipping portal. It feels like work, because it is. Nobody questions it, because it's always been done that way.

But watch what actually happens as you grow. At ten orders a day, that copying is an hour. At thirty, it's most of a morning. At sixty, it's a full-time role whose entire purpose is retyping data that already exists somewhere else. You never made a decision to create that role. It grew on its own, one order at a time, and now it sets a limit: you can only take as many orders as one person can hand-transcribe before they burn out or start making mistakes.

That's the real shape of the cost. It isn't the minutes. It's the ceiling. When a human is your integration, your growth is capped at the throughput of that human — and you'll experience the cap not as a cost, but as a vague sense that "we can't handle more right now."

Where the Errors Live

The second cost is quieter and more expensive: the mistakes.

Anything a person copies by hand between two systems will eventually be copied wrong. Not because they're careless — because they're human, and it's the fiftieth address of the day. A digit drops off a VAT number. A shipping address goes to the old one. A price on the invoice doesn't match the price in the contract. Each of these is small until it isn't: an order stuck at a border, a parcel sent to the wrong city, a customer who now trusts you a little less.

I built a shipping automation for a manufacturer where, before the work, every parcel was booked by hand — a staff member copied the name, address and phone from one system into the carrier's portal, generated a label, and emailed the tracking number back to the customer. Five to seven minutes each, twenty to fifty times a day. The minutes were bad enough. But the real problem was the country codes: the UK arrives written as "UK" in one system and the carrier only accepts "GB". A human catches that most of the time. Most of the time is exactly the problem. Once the systems were connected, that translation happened the same way every time, and shipment errors dropped to a handful of isolated cases a month.

The pattern generalizes. Every seam where a person hand-carries data between two tools is a place errors are born. Connecting the systems doesn't just save the copying — it removes the entire category of mistake.

slug="api-integrations"
text="Most 'we can't handle more volume' problems are really a person hand-carrying data between two systems that were never introduced to each other. I connect them — checkout to accounting, CRM to shipping — so the data moves once, correctly, without anyone retyping it."
/>

What "Connected" Actually Buys You

When systems talk to each other directly, the human stops being the glue. The data moves once, on its own, correctly.

On another project — an international e-commerce build for a manufacturer expanding across Europe — the order workflow used to be six manual steps across four tools: confirm the payment, create the deal in the CRM, log the accounting entry, book the shipment, generate the invoice, email it out. About thirty minutes per order, by hand, every time. Fine at a dozen orders a week. Impossible at the volume a European launch would bring.

The fix wasn't a better spreadsheet or a faster typist. It was connecting the tools so that the moment a payment cleared, one flow fired: the CRM got the deal, the accounting system got the entry, the shipment got booked, the invoice generated, and the confirmation email landed — with no one touching any of it. Payment to invoice in the customer's inbox dropped from about thirty minutes to under two.

Notice what that number really unlocks. The thirty-minute saving per order is nice. But the point is that opening a new market stopped requiring more people. A business that used to grow by hiring transcribers could now grow by changing a setting. The ceiling moved from "how many orders can one person process" to "how many can the system handle" — which is a much higher ceiling.

That's what connecting systems actually buys: not saved minutes, but a removed limit.

When Manual Is Genuinely Fine

Here's the part most articles on this topic won't tell you, because they're usually written by someone selling the integration: not every gap between two tools is worth closing. Sometimes a human copying data by hand is exactly the right answer, and automating it would be a waste of your money.

Leave it manual when:

It happens rarely. If you move data between two systems twice a month, connecting them is a hobby, not an investment. The build will cost more than a decade of copying ever would. A person and a spreadsheet is the correct tool for genuinely occasional work.
The judgment is the point. Some steps look like data entry but are actually a person deciding something — whether this order looks fraudulent, whether this customer gets an exception, whether these two records are really the same company. Automating the copying is fine; automating the judgment produces fast, confident mistakes.
The process is still changing. If you're not sure the workflow is right yet, don't cement it in code. You'll pay to automate a process you abandon in three months. Let it stabilize by hand first, then connect it.
The volume is flat and low, and it's staying there. A connection earns its cost by removing a ceiling. If there's no ceiling — if you're not trying to grow past what one person can handle — there's less to gain.

The test is simple. A gap between two systems is worth closing when the copying is frequent, error-prone, and standing between you and more business. If it's rare, judgment-heavy, or genuinely not blocking anything, leave it alone. Connecting it would be complexity for its own sake, and you'd be paying to maintain a machine that solves a problem you didn't have.

How to Find Yours

You don't need an audit to spot the integration you're missing. You need to answer one question honestly: if your volume doubled next month, whose job would break first?

Whatever you just pictured — some person, some spreadsheet, some end-of-day ritual of moving numbers between screens — that's where a human is currently doing the work two systems should be doing for each other. It's usually the thing everyone has quietly accepted as "just how it works around here." Nobody's counting the hours, because the hours were never the point. The ceiling was.

If that seam is frequent, error-prone, and capping how much business you can take, connecting the two systems is one of the highest-return things you can do — not because it saves time, but because it takes the limit off. And if the honest answer is "actually, that's fine by hand" — then you've just saved yourself a project. Knowing the difference is most of the value.

If you can name the person who'd drown first when your volume doubles, you've already found the two systems that need to start talking. Let's look at what that gap is costing you.

PDF Generator Fingerprints: What Software Made This File (And Where It Lies)

Iurii Rogulia — Mon, 10 Aug 2026 10:00:41 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

Two bank statements land in your underwriting queue. Both look like they came from the same bank. Both open cleanly. Both show the account holder you expect. One was generated by the bank’s statement engine. The other was rebuilt in a desktop editor, with the closing balance quietly raised by a few thousand. From the outside, they are indistinguishable. From the inside, they were made by entirely different software — and that software left its name behind.

Every PDF carries a fingerprint of the tool that produced it. Not a watermark you can see, but a set of structural habits: how the file lays out its objects, how it embeds fonts, what it writes into its own metadata, how it joins pages together. A risk team that learns to read these fingerprints gains a powerful, content-independent question to ask of any document: does the software that claims to have made this file actually behave like that software?

This article walks through the major server-side PDF generation libraries, explains what the Producer and Creator fields really tell you (and where they lie), and shows how a structural analysis reads all of it automatically.

The two fields everyone looks at first

Open any PDF’s properties and you will find two metadata fields that name software:

Creator — the application a human used to author the document. Microsoft Word, Adobe InDesign, LaTeX, a bank’s internal reporting tool.
Producer — the library that wrote the final PDF bytes. Adobe PDF Library, iText, ReportLab, the print-to-PDF subsystem of an operating system.

In a clean pipeline these tell a coherent story. A document authored in Word and saved to PDF reports Creator: Microsoft Word and Producer: Microsoft® Word. A LaTeX paper reports Creator: TeX and Producer: pdfTeX-1.40.26. The two fields together describe a real, plausible toolchain.

The problem: both fields are just strings inside the file. Nothing in the PDF format forces them to be true. Anyone with a hex editor or a one-line script can set Producer to whatever they like. A forger who knows their target bank uses a particular reporting engine can simply type that engine’s name into the field. So the naive check — “does the Producer string match what this institution uses?” — catches the lazy forger and misses the competent one.

That is exactly why the string is the beginning of the analysis, not the end. The far more interesting question is whether the rest of the file is consistent with the tool it names.

Why generators are distinguishable in the first place

A PDF is not a picture of a page. It is a small program: a tree of objects that describe fonts, text-positioning operators, images, and page structure, wrapped in a cross-reference table (the xref) that tells a reader where each object lives. Turning a page into that object tree involves a thousand small decisions, and every generation library makes those decisions differently and consistently.

Think of it like handwriting. Two people can both write the word “balance,” but the way they form their letters, space their words, and dot their i’s is habitual and hard to fake on purpose. PDF libraries are the same. The shape of the object tree, the way fonts are subset and embedded, the structure of the content stream, the defaults written into metadata — these are the library’s built-in habits. They are not settings the operator thinks about; they are byproducts of how that specific codebase was written.

So when the Producer field claims one library but the file is built with the structural habits of another, that contradiction is the signal. The claimed identity says “institutional reporting engine.” The construction says “desktop editor that re-saved this file.” They cannot both be true.

A field guide to the major generators

Here is how the most common server-side and desktop pipelines behave, and what their presence tells a fraud team. This is descriptive — it is the same knowledge any developer who has shipped PDF features already has — not a recipe for evasion.

iText (Java / .NET)

iText is a programmatic library: developers build the document object by object in code. It is heavily used inside enterprise systems — invoicing platforms, government portals, contract tools — precisely because it produces clean, predictable, single-pass files. A genuine iText document tends to be born in one operation, with no editing history layered on top. When you see iText behaving like iText, you are usually looking at machine-generated output from an institutional pipeline. The catch: iText is also freely available, so a forger can use it to build a fake document from scratch. That is a different problem — fabrication, not modification — and we are honest about it below.

Apache PDFBox (Java)

PDFBox both reads and writes PDFs, which makes it a common engine inside document-processing services and, unfortunately, inside re-save tools. A file that was loaded, altered, and written back out through PDFBox carries the structural signature of a rebuild — the original construction is gone, replaced by PDFBox’s own layout. When an institution’s documents normally come from a specific reporting engine and one arrives bearing the habits of a generic read-write library, that mismatch is worth a closer look.

ReportLab (Python)

ReportLab is the workhorse behind a huge share of Python-generated PDFs: invoices, reports, tickets, and — because it is so easy to script — a huge share of fabricated documents too. Like iText, a clean ReportLab file is single-pass and tidy. The forensic value is comparative: if you know the genuine issuer uses an enterprise reporting suite and the document in front of you is built the ReportLab way, the document did not come from where it claims.

Apache FOP

FOP renders XSL-FO into PDF and is common in formal publishing pipelines — regulated statements, structured financial documents, legal filings. Its output is distinctive and rigid. FOP is rarely what a casual forger reaches for, so its presence is more often a sign of a genuine formatting pipeline than of tampering — but, as always, the question is whether the rest of the file agrees.

wkhtmltopdf and Puppeteer / headless Chrome

These render HTML to PDF. They power an enormous range of legitimate systems — payroll portals, HR platforms, SaaS invoice generators — and an equally enormous range of forgery operations, because building a fake payslip as an HTML template and rendering it is easy. This is the single most important honesty point in PDF forensics: an HTML-rendered PDF is structurally identical whether the data inside it is real or fabricated. There is no byte-level signal that separates a genuine payroll PDF from a forged one when both came out of the same renderer. We return these as inconclusive for exactly this reason — more on that below.

LibreOffice and Microsoft Office

These are consumer software. They exist so that anyone can author any document. A bank statement that reports Creator: Microsoft Word is not evidence of tampering — but it is evidence that there is no meaningful “original” to verify against, because the whole document could have been typed from nothing. Real banks do not export your statement from Word. So an Office origin on a document that should have come from an institutional engine is itself a routing signal.

Ghostscript

Ghostscript distills and rewrites PDFs. It is a legitimate part of many print and archival pipelines, but it is also a classic laundering step: load a forged or modified file, run it through Ghostscript, and the output is a clean, single-xref file that no longer shows the incremental edits underneath. The rewrite itself leaves Ghostscript’s own habits in the file — which is why a re-distilled document claiming an institutional origin is a recognizable pattern rather than an invisible one.

Born institutional vs. rebuilt by a consumer editor

Step back from individual tools and the landscape splits cleanly in two.

An institutional document is born from an automated pipeline that does the same thing for every customer, every day. The bank’s statement engine, the payroll system, the government portal’s certificate generator. These produce files with a consistent, single-pass construction and a Producer that matches an enterprise toolchain. There is a genuine “original” — the file the institution actually emitted — and the question “was this modified after that institution made it?” has a real answer.

A consumer software document is one anyone can make: Word, an online editor, a desktop PDF tool. There is no canonical original because the whole thing could have been authored from scratch. Asking “was this modified?” is the wrong question — there was never an authoritative version to deviate from.

The fraud-relevant move is almost always a consumer tool impersonating an institutional one. The forger takes a real statement, opens it in a desktop editor, changes a number, and saves. Or builds a lookalike from a template and renders it. The output claims an institutional Producer, but it was built by consumer tools — and consumer tools have different habits than the engine they are pretending to be.

Want to see this on a real file right now? Drop any PDF into the free PDF check on the homepage and read back its origin classification — institutional, consumer software, online editor, or scanned — along with any modification markers. No signup needed for a single check.

What a structural analysis actually reads

This is where HTPBE comes in. Instead of trusting the Producer string, the analysis cross-examines it against the file’s construction and against the file’s own internal records. Several independent checks contribute. In outcome terms, HTPBE flags things like:

HTPBE_TOOL_VS_STRUCTURE_MISMATCH — the declared authoring software does not match how the file is actually built. The string says one thing; the bytes say another.
HTPBE_FONT_VS_TOOL_MISMATCH — font handling that is inconsistent with the tool the document claims to come from. Generators have characteristic ways of embedding type; a mismatch here is hard to fake.
HTPBE_PRODUCER_IDENTITY_FORGED — evidence that a declared institutional generator was spoofed by a third-party tool to disguise the file’s real origin.
HTPBE_RESIDUAL_PRIOR_GENERATOR — residual identity left behind by a tool that tried to claim a different origin. The file remembers who really made it, even when the visible field was overwritten.
HTPBE_EDITING_TOOL_FINGERPRINT — fingerprints of a known PDF editing tool on a document that should never have passed through one.
HTPBE_ONLINE_EDITOR_ORIGIN — the document carries the identity of an online editing or conversion service, which strips and rewrites original provenance.

Underneath these, the timestamp and revision-history layers add more: HTPBE_DATES_DISAGREE when the modification date postdates the declared creation date, HTPBE_MULTIPLE_REVISION_LAYERS when the file was saved repeatedly after it claims to have been freshly generated, and the signature checks HTPBE_POST_SIGNATURE_EDIT and HTPBE_SIGNATURE_REMOVED when a digital signature was edited around or stripped.

The important point for a risk team: you do not need to know what any of these mechanisms are internally. You read the named markers in the response and route on them. The detection logic stays on our side; your side stays a simple decision tree.

The verdict you get back

HTPBE returns one of three statuses, and the third is the one most people misread.

intact — no modification detected and the origin looks institutional. The file behaves like what it claims to be.
modified — forensic evidence of post-creation change. One or more markers fired. This takes priority over everything else: a modified Word document is still modified.
inconclusive — the document came from consumer software, an online editor, an HTML renderer, or a scanner. This is not a failure and not a pass. It is a routing signal that says: PDF structure alone cannot answer the integrity question here, because this kind of file can be created from scratch by anyone.

That last one is the honest core of generator forensics. If you expected a bank statement straight from a banking system and you got back inconclusive with a consumer-software or HTML-renderer origin, the document was not generated the way a real statement is generated — so verify it directly with the issuer or reject it. The inconclusive verdict is doing real work: it tells you the tooling is wrong for the claim, even when no tampering marker fired.

There is no numeric risk score in the response. You get a status, a modification_confidence (certain, high, or none), and an ordered modification_markers array. That is deliberate — a named marker you can branch on is more useful than an opaque 0–100 number nobody can audit.

Reading the fingerprint over the API

Submitting a file is a two-step flow: post a URL, get a check ID, then fetch the result. Here is the whole thing in Python.

import os
import requests

API = "https://api.htpbe.tech/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['HTPBE_API_KEY']}"}

# Step 1 — submit the PDF URL for analysis
submit = requests.post(
    f"{API}/analyze",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"url": "https://your-bucket.example.com/statements/applicant-42.pdf"},
)
check_id = submit.json()["id"]

# Step 2 — retrieve the verdict
result = requests.get(f"{API}/result/{check_id}", headers=HEADERS).json()

status = result["status"]            # "intact" | "modified" | "inconclusive"
markers = result["modification_markers"]
producer = result["producer"]
creator = result["creator"]
origin = result["origin"]["type"]    # institutional | consumer_software | online_editor | scanned | unknown

print(f"status={status} origin={origin} producer={producer!r} creator={creator!r}")
print("markers:", markers)

And the routing logic a fraud team actually cares about:

if status == "modified":
    # Generator identity contradicts construction, dates disagree,
    # signature stripped, etc. The named markers say which.
    if "HTPBE_PRODUCER_IDENTITY_FORGED" in markers:
        reason = "Declared institutional generator was spoofed"
    elif "HTPBE_TOOL_VS_STRUCTURE_MISMATCH" in markers:
        reason = "Claimed authoring tool does not match file construction"
    else:
        reason = markers[0]  # strongest marker first
    route_to_manual_review(check_id, reason)

elif status == "inconclusive":
    # Consumer/online-editor/HTML-renderer/scanned origin.
    # If you expected an institutional document, this is itself a red flag.
    if origin in ("consumer_software", "online_editor"):
        request_issuer_confirmation(check_id)
    else:
        flag_for_human_eyes(check_id)

else:  # intact
    accept(check_id)

Notice that the consumer-vs-institutional split drives the workflow. A modified verdict routes to review. An inconclusive verdict on a document that should have been institutional triggers an issuer callback rather than a silent pass. That is the generator fingerprint doing its job: not catching every forgery on its own, but telling you when the toolchain is wrong for the claim.

What this approach cannot do — and we will not pretend otherwise

Generator fingerprinting is structural. It reads how the file was built, not what the file says. That boundary matters:

It cannot validate the data. If a forger builds a fake payslip in an HTML renderer that real payroll systems also use, the structure is genuine even though the numbers are invented. That is why those files come back inconclusive, not intact. PDF forensics is the wrong layer to catch a born-fake document; content verification with the issuer is the right one.
It cannot read cryptographic signature validity. It detects whether a signature is present, was edited around, or was removed — not whether the certificate chains to a trusted authority. Pair it with a signature-validation library if you need that.
It cannot OCR or compare visual content. Two files that look identical but differ by a single pixel-painted digit are out of scope for structural analysis unless that edit also disturbed the file’s construction.

Being clear about these limits is the point. A tool that claims to catch everything catches your trust first and your fraud never. Generator fingerprinting catches a specific, common, and expensive class of fraud — consumer tools impersonating institutional pipelines — and is honest about the rest.

Who should be reading these signals

If you run risk or fraud operations at a lender, an insurer, an HR or payroll platform, or a legal-tech company, your queue is full of documents claiming institutional origins. A meaningful share of the fraudulent ones were not made by the institution they name — they were rebuilt in a consumer editor and re-stamped. The generator fingerprint is the cheapest, fastest way to surface that mismatch before a human ever opens the file. For the lending-specific version of this problem, see how this plays out in bank statement fraud in lending, or the dedicated fake bank statement detection workflow.

The structural layer reads every one of these signals automatically and returns a verdict you can branch on in a few lines of code. Wire it into the HTPBE API, route on the named markers, and let the documents that claim to be institutional prove that the software which made them actually was.

Build vs Buy: VAT Validation via VIES or an API

Iurii Rogulia — Mon, 10 Aug 2026 09:00:49 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

Build vs Buy: Should You Call VIES Yourself or Use an API?

VIES is free and public, so the first instinct is almost always the same: we'll just call it ourselves. That instinct is not wrong. For some teams it is exactly the right call. But "free" describes the endpoint, not the integration, and the gap between the two is where the real decision lives.

This is a build-vs-buy framework, not a pitch. The scope is the EU-27 plus XI (Northern Ireland), which is what VIES covers. The goal here is to enumerate the actual work honestly — what you own when you build, what you offload when you buy — so you can decide which side of the line your case falls on. For most low-stakes, low-volume cases, building is fine. The point is to know that before you commit, not after.

The "we'll just call VIES" assumption

VIES is a system run by the European Commission that routes a validation query to the relevant national VAT database and reports back what that database says. The Commission does not hold the data centrally — each member state answers for its own numbers. You can read the plain-language version on the Commission's Your Europe VIES page, and the integration details on the VIES technical information page.

The happy path really is simple: send a VAT number, get back valid or invalid, sometimes with a trader name and address. If that is all you need, and you need it rarely, you may not need anything else. The assumption only breaks down when you look at what happens off the happy path — when a national database is down, when you validate the same number a thousand times a day, or when an auditor asks you to prove a check you ran eight months ago. None of that is in the "just call VIES" mental model, and all of it is work.

What building it yourself really includes

Here is the honest inventory. None of these are dealbreakers on their own; together they are the actual scope of "building VAT validation."

The SOAP client and parsing

VIES exposes two upstream interfaces: the legacy SOAP endpoint and, more recently, an unauthenticated REST endpoint that returns JSON. Picking REST saves you the XML parsing, but nothing else about the scope below changes — you still own the error mapping, the per-country downtime and throttling, the caching, and the audit capture. Either interface offers the same two checks. checkVat gives you the basic yes/no (with a name and address depending on the member state). checkVatApprox additionally accepts requester details — requesterCountryCode and requesterVatNumber — and, on a completed lookup, returns a requestIdentifier, which is the consultation number you keep as evidence.

So even the "simple" call, on the SOAP path, means building and maintaining a SOAP envelope, posting it as XML, and parsing an XML response into something your application can use:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:urn="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
  <soapenv:Body>
    <urn:checkVatApprox>
      <urn:countryCode>DE</urn:countryCode>
      <urn:vatNumber>123456789</urn:vatNumber>
      <urn:requesterCountryCode>FI</urn:requesterCountryCode>
      <urn:requesterVatNumber>12345678</urn:requesterVatNumber>
    </urn:checkVatApprox>
  </soapenv:Body>
</soapenv:Envelope>

That is the request. You then parse the response XML, pull out valid, the trader fields, and requestIdentifier, and map SOAP faults onto your own error model. The checkVatService WSDL is the contract. It is not hard code, but it is code you own, forever, in a serialization format most of your stack no longer speaks natively.

Downtime and retries

This is the part that surprises people. VIES has no SLA and no uptime guarantee, and because it routes per member state, availability is per-country: one national database can be down for maintenance while every other country answers fine. The Commission's own materials note that national databases go offline during backups. So "is VIES up?" is not a yes/no question — it is "is the specific country you need up right now?"

Building this well means retries with backoff, distinguishing a transport failure from a genuine invalid, and deciding what your application does when the answer is neither valid nor invalid but simply unavailable. Do you block the signup? Queue the check? Fail open or closed? Those are product decisions you have to make and encode. There is also undocumented rate/abuse throttling — hammer VIES and you can get soft-blocked, which turns "just retry" into its own failure mode. We wrote up the shape of this problem in the guide on handling VIES downtime.

Caching without breaking compliance

At any real volume you cannot call VIES on every request — for latency, for throttling, and out of basic courtesy to a shared public system. So you cache. But a VAT validation result is time-sensitive evidence: a number that was valid in March can be deregistered by August. Cache too aggressively and your "proof" is stale; cache too little and you are back to hammering VIES.

The compliance-safe version means a deliberate TTL, storing the original check timestamp (not the cache-hit time), and never letting a cached row masquerade as a fresh contemporaneous check when audit evidence is what matters. It is a small system, but it is a system with correctness rules, not a one-line memoize. More on the trade-offs in caching VIES responses.

Audit evidence you have to persist

If you validate VAT IDs to support intra-EU B2B treatment, the check is not the deliverable — the evidence is. The strongest piece VIES itself gives you is the consultation number: the requestIdentifier returned by checkVatApprox, which is contemporaneous proof that you checked a specific number, at a specific time, and got a specific reply, in a form a tax administration can accept.

Worth being precise about what it is and is not. It is evidence of the lookup. It is not a tax certification, it does not adjudicate the transaction, and it does not by itself guarantee exemption — that treatment depends on the full set of conditions for the supply, not on one reference string. Getting the consultation number requires the requester-qualified checkVatApprox path, and storing it correctly (immutable rows, requester VAT ID alongside, source recorded, nullable where a national source answered) is more work than the call that produced it. The full breakdown is in audit evidence.

National-registry fallback and enrichment

When VIES can't answer for a given country, some national tax-authority and company-registry APIs can — either as a fallback while VIES is down, or as enrichment where they return richer trader data. Each of those sources is its own interface, its own auth, its own field mapping, and its own reliability profile. Coverage changes over time as authorities publish or retire endpoints, so this is not a "write once" component either. Building it means a per-source client layer and a policy for reconciling a national answer with a VIES answer — including the fact that a national confirmation is not the same evidence as a VIES consultation number.

Ongoing maintenance

Everything above is not a one-time build. VIES changes; national endpoints appear and disappear; throttling behaviour shifts; the SOAP contract gets revised. Someone on your team owns this indefinitely, and it is the kind of infrastructure that is invisible until it breaks during a customer's checkout or an audit. The honest cost of building is not the week you spend writing it — it is the year you spend keeping it correct.

When building in-house is the right call

Building is genuinely the right answer when the shape of your need is narrow:

You validate rarely — occasional one-off checks, not a hot path.
You do not need audit evidence, or your risk on a wrong answer is low.
You can tolerate VIES being down, because a failed check just means "try again later" with no business consequence.
You have the in-house appetite to own a small SOAP integration and keep it alive.
You want zero external dependencies for regulatory, procurement, or data-residency reasons.

Even here, "build" rarely means what it sounds like. If you validate rarely, don't need audit evidence, and can shrug off VIES being down, you could write a thin checkVat call — but the free plan does the exact same job at this volume for nothing (100 checks a month, no SOAP client to keep alive, a consultation number and source on every result, no card), so you get the resilient version without maintaining anything. The one case where you genuinely should wire VIES up yourself is a hard zero-external-dependency, data-residency, or procurement constraint that forbids an external call at all — there the public, free endpoint is the end of the story. For everyone else, "the right call" still starts with registering.

When buying wins

Buying starts to pay off when the off-happy-path work stops being hypothetical:

Validation is on a hot path — every signup, every invoice, every checkout — where VIES downtime becomes your downtime.
You need audit evidence you can produce months later: consultation number, timestamp, and source, stored reproducibly.
Per-country availability gaps are unacceptable, so you need national fallback rather than a shrug when one member state is offline.
The maintenance time — SOAP, retries, caching correctness, fallback clients — costs more than the API does.
You want a plain REST interface your whole stack can call without anyone learning SOAP.

An API does not replace VIES — VIES is still the underlying source. What it does is wrap VIES (and national registries where available) with reliability, caching, evidence, and a REST contract, so the six sections above become someone else's problem. Against the vatnode contract the same lookup is three lines:

const res = await fetch('https://api.vatnode.dev/v1/vat/DE123456789', {
  headers: { Authorization: `Bearer ${process.env.VATNODE_API_KEY}` },
})
const data = await res.json()

The response is structured JSON — valid, vatId, countryCode, countryName, companyName, companyAddress, checkId, verifiedAt, source, and consultationNumber — with no SOAP envelope to build or parse. The differentiators are narrow and worth stating plainly rather than overselling: a zero-config path (set your own EU VAT once as requester in dashboard Settings and every subsequent call returns the consultation number, without wiring up checkVatApprox yourself), and a never-null result contract (you always get a structured answer with a source, even when the call fell back to a national database). That is it. If you want to size it against the build cost, here is what an API costs; if you want a broader look at the reliability layer, there's a production VIES alternative and the VIES API reference.

A simple decision checklist

Run down this list. More boxes on the left, build. More on the right, buy.

Volume — occasional lookups → build; hot path → buy.
Evidence — no audit need → build; you must produce proof later → buy.
Downtime tolerance — a failed check is harmless → build; VIES down means revenue or signups blocked → buy.
Country gaps — EU-average coverage is fine → build; you can't accept one member state being offline → buy.
Maintenance appetite — you'll own SOAP and fallback indefinitely → build; that time is better spent elsewhere → buy.
Data residency / procurement — external dependency is disallowed → build; no such constraint → buy.

The checklist is honest, but notice where it actually lands in 2026. The only boxes that point cleanly at building are the hard constraints — a zero-external-dependency, data-residency, or procurement rule that forbids calling anyone. Everywhere else, the maintenance you would be signing up for outweighs what an API costs, because for most teams that API costs nothing: vatnode is free at low volume (100 checks a month, no card) and low cost above it, with company-data enrichment, national fallback, and the consultation number in a single request. So unless you have that hard constraint, the pragmatic answer is not "it depends" — it is register, wire up one REST call, and stop thinking about VIES.

This is general information about EU VAT and VIES, not tax advice. Whether a specific transaction qualifies for zero-rating, exemption, or reverse charge depends on facts we can't assess here — confirm the treatment of your own transactions with a qualified tax adviser.

FAQ

Can I just call VIES directly for free?

Yes, VIES is free and public, but "free" only covers the endpoint — you still own the SOAP client, downtime handling, caching, audit storage, and national fallback, which is where the real cost sits.

What's the hardest part of building VAT validation in-house?

Usually resilience and evidence — VIES nodes go down per-country regularly, and storing reproducible audit proof (consultation number, timestamp, source) correctly is more work than the happy-path call.

Is a VAT validation API worth it for low volume?

If you validate rarely and don't need audit evidence or uptime guarantees, a thin in-house call may be enough; the API pays off once downtime, compliance evidence, or maintenance time start to matter.

Does an API replace VIES?

No — VIES is the underlying source. An API wraps VIES (and national registries where available) to add reliability, caching, evidence, and a simple REST interface on top.

Try the buy side before you build it

If you're weighing the maintenance cost, the fastest way to price it is to call the API once and see what you'd otherwise be building. Try it free — free plan, 100 requests/month, consultation number and source on every result.

PDF Integrity Report: July 2026

Iurii Rogulia — Sat, 08 Aug 2026 10:00:39 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

Every month we look at aggregate, anonymized data from checks processed by HTPBE and write up what the structural signals tell us about the state of PDF tampering. No file contents, no personally identifiable information — only the structural and metadata patterns the algorithm uses to classify documents.

This report is about proportions and movement, not raw counts. What share of documents came back flagged, which signals fired more or less often than the month before, which origins shifted, and what the recurring tampering shapes looked like. Those are the numbers that mean something; an absolute file count for a single month is noise by comparison.

July is the month where that distinction earns its keep. The flagged share moved up sharply — and almost none of that movement is about documents getting more tampered.

What the Denominator Is, Before Any Number

Every share below is a share of processed checks — completed analyses, not unique documents and not unique users. That denominator includes our own internal self-check runs, owner testing, fixture regressions, and retries; it is not deduped. On top of that, the classifier itself changed repeatedly within July (see the algorithm section — it was our second-heaviest release month on record), so the same file submitted early and late in the month can land on different sides of the line. A July detector-output number is therefore a blend of a moving population and a moving ruler.

So this is not a population fraud rate, and no single figure here should be read as one. It is a description of what reached our pipeline and how our pipeline classified it. Keep that in view for the headline, which needs it most.

The Shape of the Verdicts

The flagged share rose to approaching six in ten, reversing June's dip back below half — but the two things that moved it are both instrumentation, not tampering. First, July was a record release cadence: twenty-seven algorithm versions shipped across the month, several of them redefining the "modified" and confidence classes mid-month, which mechanically expands what gets flagged. Second, the traffic mix flipped back to API-heavy testing after June's web-dominated month, and API traffic skews toward files that are already suspected — integration tests against known-bad documents and uploads that appear to be testing whether a fake gets caught. A wider net over a more pre-selected population lifts the flagged share on its own. Neither lever says anything about how often documents in the world are being altered.

Verdict	Direction vs. June
Not flagged	▼ eased to just over two in five
High-confidence modification	► flat, around three in ten
Certain modification	▲ up — but a calibration effect, see below

Same forensic questions, a heavier and differently-aimed instrument, a different-looking headline. Read the flagged share every month as a statement about who submitted and how the pipeline changed — and in July, more than any month we have published, both of those changed at once.

A note on the "certain" tier, which also moved up this month: treat it as a calibration reading, not a trend. "Certain" describes how confidently the engine made the modification call — never certainty about intent or fraud — and this month's shift is a direct product of the same two forces above. A heavy run of coverage-broadening releases adds converging second signals to files that previously scraped a "high," and an API-skewed population stacks more unambiguous evidence per file. The confidence mix followed the releases and the population; it is not an independent finding.

Source & Origin Mix

The submission channel flipped back to a near-even split, with the API nominally the largest — a near-reversal of June, when roughly four in five checks came through the browser-based free checker. Read this as processed checks including internal testing, not as organic API-customer growth: our own automated self-check and fixture runs go through the API path, and July was a heavy build month, so a chunk of that API weight is us exercising the engine, not the market discovering it.

On origin, consumer-software exports overtook institutional documents as the largest class, with institutional slipping from the plurality it held in June. This is a classifier output on a testing-inclusive population, and it is not "more consumer fraud." Consumer-software and scanned files both fall into a "Cannot Verify" bucket, where the structural layer deliberately returns a conservative inconclusive verdict rather than forcing an intact-or-modified call — a larger consumer-software slice means more files we decline to certify either way, not more tampering. Several July releases also re-routed origin classification (sharpening scan and fake-scanner recognition in both directions), so part of the reshuffle is the ruler moving, not the population.

Scanned documents held at roughly a ninth of submissions — essentially flat, within noise, and itself touched by the reclassification work above. Treat that as marginal, not a decline. A scan can still never earn an "intact" verdict here: capture-origin formats simply carry too little structural history to certify either way, so they route to a conservative inconclusive rather than a clean pass.

Signals That Moved

The cleanest reads this month are the ones that do not depend on the detector at all — pure structural composition of what showed up.

Missing creation date eased again. Files arriving with no creation timestamp at all slipped from about a fifth to about a sixth. This is a detector-independent carrier — it is just what the submitted files contained — and it reflects the changed submission mix, not a real-world change in how documents are authored. Still worth watching, but the direction this month is down.

The suppressed slices stayed suppressed: signed documents, post-signature edits, signature removals, embedded files and JavaScript were each too thin a base this month to quote a rate, so we keep them qualitative. The one signed-document pattern worth repeating is the standing one — a signature valid in the viewer does not guarantee the bytes were not altered, because incremental updates appended after signing fall outside the signed scope. Integrity checked at the structural layer, not the signature-validation layer, is what catches that.

Incremental Updates: Two Rates, Kept Apart

The incremental-update signal splits into two separate numbers this month, and they should not be blurred together.

The first is prevalence — how many of all files carried incremental updates at all. That ran about one in ten, a structural share that ticked up modestly and is safe to read at face value. The average revision chain on those files also shortened, to under three appends, down from a little over three in June — fewer post-write layers stacked per file.

The second is the flag rate among them — of the files that did carry incremental updates, how many came back flagged. In July that sat at very nearly all of them. Read this as a July snapshot only: it was lower in June, so this is not a "near-total all along" continuity claim, and it is not a real-world trend. The mechanism is unchanged — incremental updates let content be appended after the original write, and while legitimate workflows produce them (signature application, annotation, form-fill), those clean cases are a small minority of the population that reaches a tamper-detection tool.

Representative Cases

These are composite, anonymized illustrations of the recurring shapes the engine resolved this month — not specific files. Each maps to the structural markers that actually drove the verdict, and each describes a modification, not proven fraud.

The reconstructed statement (verdict: modified). A "bank statement" looks like one coherent document. Structurally, its pages were assembled from more than one separate source rather than produced as a single original — so it can be reported as an assembled file, but never certified as an untouched original. July broadened this multi-source coverage to catch a wider range of assembled packages that previously slipped through.

The rebuilt-elsewhere document (verdict: modified). A file presented as an untouched institutional original was, structurally, re-saved and rebuilt by a second tool after its original creation, rather than issued and released once by an institution. The public outcome is exactly that: rebuilt by a second tool after the file was first created. It reads as an original; the structure records the later rebuild.

The cover-and-replace patch (verdict: modified). A page reads correctly, line by line. Structurally, the page shows content added after the original was produced — for example, a blackout or cover box placed over part of the page. That is reported as a modification regardless of why it was applied: the fact of the edit is what we record, not the intent behind it.

The render dressed as a scan (verdict: modified). A file arrives looking like a scanner or OCR capture, but structurally it is a software-rendered document presented as a capture origin it cannot genuinely have. Genuine device scans and ordinary phone captures are unaffected — those route to a conservative inconclusive and are never flagged on this basis; only a render claiming to be a scan trips it.

Algorithm Development

July was a very heavy release month — twenty-seven versions shipped, second only to May's twenty-nine and well above June's sixteen. The work spanned new coverage and false-positive reduction at once, described here in outcome terms only.

New and broadened detection categories — a software render dressed as a scanner or OCR capture; content added over the original page, such as blackout or cover boxes; fabricated and assembled documents dressed up as institutional originals; documents rebuilt by a second tool after their original creation; broadened multi-source page assembly reaching a wider range of assembled packages; and strengthened detection of post-creation edits. Several of these closed cases that had previously passed, certified as originals.
False-positive reduction and confidence demotion — releases that pushed the other way, narrowing misfires on genuine templated documents, signed-document workflows, and minor date discrepancies, and demoting the confidence of borderline calls rather than flagging them outright.

Here is the part that matters for the headline: wider coverage pushes the flagged share up. A share of the documents flagged in July would have passed under the algorithm as it stood on the first of the month. That compounds the traffic-mix effect from the top of the report — and it is precisely why the rise in the flagged share is a statement about our instrument and our intake, not a fraud trend.

PDF Version Landscape

Concentration kept loosening. PDF 1.7 fell from roughly 45% to about a third of the sample, with 1.4 a close second, and 1.3 and 1.6 tied for third. PDF 1.5 took a smaller slice, and PDF 2.0, despite nearly a decade of availability, stayed a rounding-error share. Like the missing-creation-date read, this is a detector-independent carrier — it reflects the changed submission mix this month, not a shift in real-world version adoption.

Summary

July 2026, in relative terms:

The flagged share rose to approaching six in ten — but the drivers are a record twenty-seven-version release cadence broadening what gets caught and a traffic mix that flipped back to API-heavy testing, not more tampering.
The channel split returned to near-even with the API nominally largest — processed checks including internal testing, not organic API growth — and consumer-software origin overtook institutional inside a "Cannot Verify" population, which is not a consumer-fraud signal.
Scanned share held at roughly a ninth, flat and reclassification-affected; the "certain" tier moved up as a calibration effect of the releases and population, not a standalone trend.
Incremental-update files ran about one in ten of all files, with shorter chains, and their July flag rate was near-total — read as a snapshot, not a continuity claim.
The clean, detector-independent carriers pointed down and loosened: missing creation dates eased from about a fifth to about a sixth, and PDF 1.7 loosened from roughly 45% to about a third — both reflecting the submission mix, not real-world adoption.

Every pattern here comes from the same forensic engine that teams run on their own intake stream through the PDF tamper detection API. If you want to run a single document through the same analysis by hand, the free checker does it in the browser.

See the full aggregate dataset on the PDF statistics page. Previous report: PDF Integrity Report: June 2026.

This report covers checks processed by HTPBE in July 2026. We analyze only file structure, never document content; web uploads may be retained in anonymized form to improve detection. All figures are aggregate and anonymized.

Preventing Overselling: Inventory Locks Under Concurrent Checkouts

Iurii Rogulia — Fri, 07 Aug 2026 10:00:49 +0000

Two customers are looking at the same product. One unit left. Within the same second, both click Pay. If your checkout reads the stock count, decides there's enough, and then writes the decrement, both requests pass the check and both succeed. You've now sold two units of something you had one of.

That's overselling, and it's not a rare edge case — it's the default behaviour of any checkout that treats "check stock" and "reduce stock" as two separate steps. The window is small, but on a product that's nearly sold out, or during a launch when everyone hits the same SKU at once, small windows fire constantly.

I've built the order pipeline for two production e-commerce platforms — pikkuna.fi and pi-pi.ee — where concurrent webhooks and concurrent checkouts hit the same order and product rows. This is the layer I reach for when a store sells finite stock. I covered the bare SELECT ... FOR UPDATE primitive briefly in PostgreSQL Production Patterns; this article is the whole system built on top of it — reservations, multi-line carts, the payment window, and the parts that actually bite you in production.

When You Don't Need Any of This

Start with the honest disclaimer, because it decides everything downstream.

Both pikkuna.fi and pi-pi.ee are made-to-order. A vinyl curtain is cut to the customer's dimensions; a waterless urinal system ships from a supply chain, not a shelf with a hard unit count. When there's no fixed quantity to run out of, overselling isn't a failure mode — you can't sell the tenth unit of something you manufacture on demand. So neither of those platforms needs a row lock on a stock column, and I didn't build one there.

You need this article when you sell discrete, finite stock: limited runs, event tickets, one-off items, anything where "5 left" is a real number and selling the sixth is a promise you can't keep. If your catalogue is print-on-demand, made-to-order, or backed by effectively unlimited supply, stop here — the locking below is complexity you'd be maintaining for a race that can't happen. Building the reservation layer for a store that can't run out of stock is exactly the kind of over-engineering I'd talk a client out of.

The rest of this assumes you genuinely have finite stock and concurrent buyers.

The Race, Precisely

Here's the naive version. It looks correct in every code review and passes every test that runs requests one at a time.

// DO NOT SHIP THIS
async function buy(productId: string) {
  const product = await db.query.products.findFirst({
    where: eq(products.id, productId),
  });

  if (!product || product.stock < 1) {
    throw new Error("Out of stock");
  }

  // Another request can run this exact block between the read above
  // and the write below. Both read stock = 1. Both pass the check.
  await db
    .update(products)
    .set({ stock: product.stock - 1 })
    .where(eq(products.id, productId));
}

The bug lives in the gap between the read and the write. Two requests interleave: both read stock = 1, both pass stock < 1 as false, both compute 1 - 1 = 0, both write 0. Two orders, one unit. The database did exactly what you told it — you told it wrong.

There are two independent things to fix here, and people often conflate them:

The decrement must be atomic — the new value has to be computed from the value at write time, not from a value you read earlier and held in a variable.
The availability check and the decrement must be serialized — no two transactions may both pass the "is there stock?" check for the last unit.

Fix One: Never Decrement From a Read Value

The first fix is cheap and you should do it unconditionally. Let the database compute the new value in the UPDATE, and put the guard in the WHERE clause so the write itself refuses to go below zero:

// Atomic conditional decrement — the check and the write are one statement
const result = await db
  .update(products)
  .set({ stock: sql`${products.stock} - 1` })
  .where(and(eq(products.id, productId), gte(products.stock, 1)))
  .returning({ stock: products.stock });

if (result.length === 0) {
  // WHERE matched nothing: stock was already 0 at write time
  throw new Error("Out of stock");
}

This is a single atomic statement. Postgres takes a row lock for the duration of the UPDATE automatically, so two concurrent writers can't both satisfy stock >= 1 on the last unit — one wins, the other's WHERE no longer matches and it updates zero rows. The .returning() tells you which happened.

For a single-line, decrement-at-checkout store, this alone prevents overselling. No explicit FOR UPDATE, no transaction block. Reach for the atomic conditional UPDATE before anything heavier — it's the smallest thing that's correct.

So why does the rest of this article exist? Because two realities break the one-statement approach:

Carts have multiple lines, and you need all-or-nothing across them.
Payment isn't instant. You confirm availability at checkout, but the money lands seconds — or with SEPA and bank transfer, days — later. What happens to the stock in between?

Fix Two: Reservations vs Hard Decrements

There are two models for holding stock, and choosing between them is the real design decision.

Hard decrement subtracts from stock the moment the order is placed. Simple, one column, no background jobs. It works when payment is synchronous and near-instant — card payments that succeed or fail in the same request. Its weakness: if the payment then fails, or the customer abandons a redirect-based method, you've decremented stock for a sale that never happened. You need a compensating restock, and if that compensation is missed, the unit is silently locked away forever.

Reservation splits the count in two. You don't decrement stock; you increment reserved. Available stock is a derived value:

CREATE TABLE products (
  id          UUID PRIMARY KEY,
  stock       INTEGER NOT NULL CHECK (stock >= 0),
  reserved    INTEGER NOT NULL DEFAULT 0 CHECK (reserved >= 0),
  CONSTRAINT reserved_within_stock CHECK (reserved <= stock)
);
-- available = stock - reserved

A reservation raises reserved. On successful payment, you convert it: stock down, reserved down, net available unchanged. On failure or expiry, you just drop reserved and the unit is available again — no separate restock path to forget. The reserved <= stock check constraint is your last line of defence: even if the application logic has a bug, the database physically cannot record more reservations than you have units.

Reservation is more moving parts — a reserved column, an expiry mechanism, a sweep job. But it's the model that survives asynchronous payment, and asynchronous payment is normal in European B2B. On pi-pi.ee the checkout accepts SEPA Direct Debit, bank transfer, and Multibanco alongside cards. Those settle later: the Stripe webhook arrives as payment_intent.requires_action first and payment_intent.succeeded only once the money moves. A hard decrement can't model "held but not yet paid" — a reservation can.

For a store with scarce stock and any async payment method, use reservations. If you're card-only and want the simplest thing that's correct, the atomic conditional decrement above is enough — just make sure your payment-failure webhook restocks.

Reserving a Multi-Line Cart Atomically

A real cart is several products at once, and the requirement is all-or-nothing: reserve every line or none. Reserving three of four items and failing the fourth leaves you holding stock for a sale that can't complete.

This is where you need an explicit transaction and row locking. Lock each product row, verify availability, then reserve — all inside one transaction that either commits whole or rolls back whole:

// lib/reservations.ts
export async function reserveCart(
  cart: { productId: string; qty: number }[],
  orderId: string,
  ttlMinutes = 15
) {
  // Lock rows in a deterministic order to avoid deadlocks (see below)
  const ids = cart.map((l) => l.productId).sort();

  return db.transaction(async (tx) => {
    // Lock all involved product rows up front, in sorted order
    const locked = await tx
      .select({ id: products.id, stock: products.stock, reserved: products.reserved })
      .from(products)
      .where(inArray(products.id, ids))
      .for("update");

    const byId = new Map(locked.map((p) => [p.id, p]));

    // Verify availability for every line before writing anything
    for (const line of cart) {
      const p = byId.get(line.productId);
      if (!p) throw new OutOfStockError(line.productId);
      if (p.stock - p.reserved < line.qty) {
        throw new OutOfStockError(line.productId); // rolls back the whole tx
      }
    }

    // All lines fit — now reserve
    const expiresAt = new Date(Date.now() + ttlMinutes * 60_000);
    for (const line of cart) {
      await tx
        .update(products)
        .set({ reserved: sql`${products.reserved} + ${line.qty}` })
        .where(eq(products.id, line.productId));

      await tx.insert(reservations).values({
        orderId,
        productId: line.productId,
        qty: line.qty,
        expiresAt,
      });
    }
  });
}

Two things are doing the work here.

.for("update") locks every product row for the transaction's lifetime. Any concurrent reserveCart touching the same product blocks at the SELECT until this transaction commits or rolls back — so it reads post-reservation numbers, never stale ones. The availability check and the reservation write can't be interleaved by another cart.

We check all lines before writing any. If line four doesn't fit, the exception rolls the transaction back and the reservations we already wrote for lines one through three never persist. All-or-nothing falls out of transaction semantics for free.

The Deadlock You Will Otherwise Hit

The .sort() on ids is not cosmetic. If two carts lock overlapping products in different orders, you deadlock: cart A locks product X and waits for Y; cart B locked Y and waits for X. Postgres detects the cycle and kills one transaction with a deadlock error — a checkout failure you caused yourself.

The fix is a discipline, not a feature: always acquire row locks in a consistent global order. Sorting by primary key before locking guarantees every transaction grabs shared rows in the same sequence, so a cycle can't form. This is the single most common way a "correct" locking implementation still falls over under load, and it never shows up in single-threaded tests.

The Payment-Confirmation Window

Here's the part the naive decrement can't touch at all. Between reserving stock at checkout and confirming payment, there's a window. For cards it's seconds. For SEPA or bank transfer it can be days. During that window the unit is held but not sold, and three things can happen: payment succeeds, payment fails, or nothing happens because the customer walked away.

You handle all three, and the reservation model makes each one a small, obvious operation.

Payment succeeds. The Stripe webhook fires payment_intent.succeeded. Convert the reservation into a real decrement, atomically:

// In the Stripe webhook, on payment_intent.succeeded
await db.transaction(async (tx) => {
  const rows = await tx
    .select()
    .from(reservations)
    .where(and(eq(reservations.orderId, orderId), eq(reservations.status, "held")))
    .for("update");

  for (const r of rows) {
    await tx
      .update(products)
      .set({
        stock: sql`${products.stock} - ${r.qty}`,
        reserved: sql`${products.reserved} - ${r.qty}`,
      })
      .where(eq(products.id, r.productId));
  }

  await tx
    .update(reservations)
    .set({ status: "committed" })
    .where(eq(reservations.orderId, orderId));
});

stock and reserved drop together, so available stock is unchanged — the unit was already accounted for at reservation time. This is the moment the sale becomes real.

Payment fails (payment_intent.payment_failed, or the async method is declined). Release the reservation — drop reserved, leave stock alone — and the unit is instantly available to the next buyer. No restock arithmetic, no risk of double-restocking, because you never touched stock.

Nothing happens. The customer closed the tab. This is why reservations carry expiresAt. A background sweep releases anything past its expiry:

// Runs on a schedule — release stale reservations
await db.transaction(async (tx) => {
  const stale = await tx
    .select()
    .from(reservations)
    .where(and(eq(reservations.status, "held"), lt(reservations.expiresAt, new Date())))
    .for("update", { skipLocked: true }); // don't fight the webhook for rows it's committing

  for (const r of stale) {
    await tx
      .update(products)
      .set({ reserved: sql`${products.reserved} - ${r.qty}` })
      .where(eq(products.id, r.productId));
  }

  await tx
    .update(reservations)
    .set({ status: "expired" })
    .where(
      inArray(
        reservations.id,
        stale.map((r) => r.id)
      )
    );
});

SKIP LOCKED matters here. The sweep and the success-webhook can race for the same reservation: the customer pays at the very moment the sweep runs. FOR UPDATE SKIP LOCKED tells the sweep to skip any row another transaction is already holding, rather than block on it. The webhook wins, commits the sale, and the sweep simply moves on — it never expires a reservation that's mid-commit. Without SKIP LOCKED you either block the sweep behind the webhook (fine, but slower) or, worse, if you got the ordering wrong, expire a paid order.

Match the reservation TTL to the payment method. Fifteen minutes is reasonable for cards. For bank transfer, where settlement legitimately takes days, a 15-minute reservation would release stock out from under a paying customer — you either extend the TTL for those methods or don't reserve scarce stock for them at all and accept the backorder. A backorder the buyer agrees to up front is a business choice; silently overselling stock you don't have is not. That decision belongs to the business, not to the code.

Where This Still Bites

I'd rather name the limits than pretend the pattern is bulletproof.

Lock contention on a single hot SKU. If ten thousand people hit one product at launch, they all queue on that one row's lock and serialize. Correct, but slow — checkout latency climbs as the queue grows. Row locking prevents overselling; it does not make a flash sale fast. Genuinely extreme concurrency wants a different tool: decrement a Redis counter first as a fast admission gate, and treat Postgres as the durable source of truth behind it. That's a real increase in moving parts, and only worth it when you've measured the contention — not by default.

The webhook must be idempotent. Stripe retries webhooks. If payment_intent.succeeded is delivered twice and you decrement twice, you've corrupted your stock in the opposite direction. The status transition (held → committed) above is the guard: a second delivery finds no held reservation and does nothing. Getting that exactly right is its own problem — I wrote it up in Idempotency Keys for API Retries.

Reservations leak if the sweep dies. If your background job stops running, expired reservations pile up and reserved creeps toward stock, choking availability for real buyers. The sweep is infrastructure, and it needs the same monitoring as anything else you depend on. A reservation system without a working expiry sweep is worse than a hard decrement, not better.

Read replicas lie. If you check availability against a read replica for speed, it may lag behind the primary and show stock that's already reserved. Availability checks that gate a purchase must hit the primary. Display counts on a product page can tolerate lag; the checkout decision cannot.

Overselling is a race condition, not an inventory problem. The fix is the same discipline every time: make the decision and the write one indivisible operation, serialize the transactions that compete for the last unit, and model the gap between "reserved" and "paid" explicitly so no unit is ever both sold and available. Start with the atomic conditional decrement, move to reservations only when async payment or multi-line carts force it, and don't build any of it for a store that can't run out of stock.

This is the correctness work under a checkout that sells real, finite stock — the difference between a store that quietly holds its promises and one that emails customers to apologise for a unit it can't ship. It's the kind of thing I build into e-commerce projects from the start, because retrofitting it after the first oversold order is always more expensive than getting it right up front. If your store sells scarce stock and you want the checkout to survive its own busiest day, get in touch.

How Lenders Verify Bank Statements — and the Forgery Layer They Miss

Iurii Rogulia — Fri, 07 Aug 2026 10:00:40 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

A borrower submits a three-month bank statement to support a loan application. The deposits line up with the stated salary. The running balance never dips below the threshold. The bank logo is crisp, the columns are aligned, the totals add up. Your underwriter cross-checks the numbers, sees nothing out of place, and clears the file.

Every step of that review was done correctly. And the document could still be forged.

The reason is that the manual verification process checks whether the content of a statement is plausible. It was never designed to check whether the file itself was edited after the bank produced it. Those are two different questions, and a borrower who opens the real PDF in an editor and types over one number defeats the second one completely — while passing the first without trouble.

This article walks through how lenders and underwriters actually verify bank statements today, exactly where that process breaks on a well-altered PDF, and the structural forensic layer that closes the gap. It is written for risk and fraud operations teams, not developers — though there is a short integration section at the end.

How Lenders Verify Bank Statements Today

Bank statement verification in lending is a layered process. No single check carries the decision; underwriters build confidence by stacking several. Here is what a competent manual review actually does.

Cross-check deposits against the pay cycle. The underwriter confirms that the income claimed on the application actually lands in the account, on a regular cadence, in amounts consistent with the stated salary. A borrower claiming $6,000/month in W-2 income should show roughly that, roughly twice a month, on predictable dates. Irregular timing or amounts that don’t match the employer’s pay schedule are flagged.

Trace large or irregular deposits. Most lenders require any non-payroll deposit above a set threshold — often around $200 for mortgages — to be sourced and seasoned. Sourced means the borrower can prove where the money came from. Seasoned means it has been in the account long enough (commonly 60 days) to rule out a last-minute borrowed lump sum dressed up as savings.

Check the running balance math. The closing balance of one day should equal the opening balance of the next. Each line should move the balance by exactly the transaction amount. Underwriters scan for arithmetic that doesn’t reconcile — a balance that jumps without a matching transaction, or a total that doesn’t follow from the lines above it.

Look for round numbers and patterns that look wrong. Genuine spending is messy: $4.37 here, $112.94 there. Suspiciously clean figures — a deposit of exactly $5,000.00, a balance that always ends in round hundreds — get a second look, because fabricated numbers tend to be tidy.

Verify against the source. The strongest manual checks reach outside the document. The underwriter may call the issuing bank, request a verification of deposit, or confirm employment directly with the employer. Increasingly, lenders skip the document entirely and pull the data through an open-banking connection like Plaid — connecting straight to the bank’s own API so the borrower never hands over a PDF at all.

Each of these is a real, valuable control. Stacked together they catch a great deal of fraud — clumsy fakes, inconsistent stories, deposits that don’t reconcile. The question is not whether this process works. It is what it was built to verify.

The One Thing the Checklist Doesn’t Verify

Read that list again and notice the common thread: every check verifies whether the numbers on the page are plausible. Do the deposits match the pay cycle? Does the balance reconcile? Is the large deposit sourced? These are content questions. They ask, “Could a real account have produced these figures?”

None of them ask the other question: “Was this file edited after the bank generated it?”

That is the gap a competent forger lives in. Consider what actually happens in the most common bank statement fraud case in lending:

The borrower logs into their real bank portal and downloads their real statement as a PDF.
They open it in a desktop or online PDF editor.
They change one number — inflate a balance, raise a deposit, delete an overdraft line.
They re-save and upload.

The result is a document where the layout is the bank’s real template, the logo is the bank’s real logo, the fonts are right, and — critically — the forger had every opportunity to make the edited numbers internally consistent. They can recompute the running balance by hand so it reconciles. They can pick a deposit amount that matches the stated pay cycle. They can avoid round numbers. A patient borrower produces a file that passes every content check on the underwriter’s list, because the content was tuned specifically to pass those checks.

Visual review fares no better. On screen, an edited number is indistinguishable from an original one — the editor renders it in the same font, at the same position. The human eye has nothing to catch.

This is why bank statement fraud is so persistent. According to fraud-analytics firm SEON, bank statements are the single most commonly falsified document in lending applications, cited in a majority of fraudulent loan files. They are easy to obtain, trivial to edit with free tools, and — once edited carefully — invisible to a process designed to verify content rather than file integrity.

What Open Banking Solves, and What It Doesn’t

Open-banking connectors like Plaid are the strongest answer to this problem, and it would be dishonest to pretend otherwise. When a borrower links their account through Plaid, the lender pulls transaction data straight from the bank’s API. There is no PDF in the loop, so there is nothing to edit. For applicants whose institution is supported and who consent to connect, this is the gold standard for income source-of-truth checks. HTPBE does not replace it, and you should keep it.

But open banking has a coverage boundary, and fraud concentrates exactly at that boundary.

Unsupported institutions. Plaid and its peers connect to a large but finite set of banks. Borrowers at smaller credit unions, regional banks, or non-US institutions often can’t connect at all.
International income. Lenders serving immigrants, expats, and cross-border earners routinely see statements from banks no open-banking network reaches.
Applicants who simply won’t connect. Some borrowers decline the bank link — out of privacy concern, friction, or because they have something to hide — and fall back to uploading a PDF.
Product types that lean on documents. BNPL, merchant cash advance, and many alternative-lending products still take PDF statements as a primary input.

In every one of these cases, the lender is back to a human reviewing an uploaded PDF — the exact scenario where content checks can’t see an edit. Open banking removes the document for the applicants it covers. For everyone else, the document is the only evidence, and its integrity goes unchecked. KYC and identity platforms don’t fill this gap either: they confirm who is applying — face match, ID document, watchlist — not whether a submitted financial PDF was altered.

That uploaded-PDF case is precisely where a structural layer earns its place. It is additive: it catches what open banking sidesteps and what the manual checklist can’t see.

The Missing Layer: Structural File Forensics

A PDF is not a flat picture. It is a structured file with an internal record of how it was built and saved — when it was created, what software produced it, whether it carries a digital signature, and how many times it was written to disk. When someone opens a bank’s original PDF and saves an edit, that act leaves traces in the file’s structure, regardless of how plausible the visible numbers are.

Structural forensics reads that internal record and returns a verdict. It never looks at whether $6,000 is a believable salary — that’s the underwriter’s job and the content layer’s job. It looks at whether the file’s own construction is consistent with a clean, single-pass export from an institutional banking system, or whether it bears the marks of having been opened and re-saved in an editing tool after the fact.

HTPBE is a self-serve API that performs exactly this analysis. You send it a PDF; it returns one of three verdicts plus a list of named markers describing what it found. Crucially, it is not a KYC or identity vendor and was never meant to be one — it answers a single, narrow question: was this file altered after it was created?

The three verdicts

intact — no evidence of post-creation modification, and the file looks like a genuine institutional export. The structural layer found nothing to flag.
modified — the file carries forensic evidence that it was changed after it was first generated. This is the case that matters most for fraud: a statement that should be a clean bank export but instead shows the fingerprints of an editing session.
inconclusive — the file was produced by consumer software, an online editor, or a scanner, so there is no institutional baseline to check integrity against. This is not a pass. It is a routing signal, and in lending it is often the most useful verdict of all (more on that below).

What it actually catches — in plain terms

Without turning this into a how-to for forgers, here is the kind of structural evidence the analysis surfaces, described as outcomes rather than recipes:

Editing-tool fingerprints. Genuine bank statements are produced by server-side institutional systems. When a file instead carries the signature of a consumer PDF editor or an online conversion service, that origin is inconsistent with a real bank pipeline. The marker HTPBE_EDITING_TOOL_FINGERPRINT flags this.
Disagreeing internal timestamps. A clean export’s creation and modification timestamps line up. When they contradict each other — the file claims to have been created on one date but was last written days later — that gap is recorded structurally even though it’s invisible on the page. HTPBE_DATES_DISAGREE covers this.
Multiple revision layers. Each time a PDF is edited and saved, the change is appended as a new layer on top of the original. A document that should have been generated in a single pass but instead shows several stacked write sessions reveals that it was modified after creation. The marker is HTPBE_MULTIPLE_REVISION_LAYERS.
Producer identity that’s been overwritten or spoofed. Some tools try to disguise their involvement by rewriting the file’s stated generator. When that identity has been blanked or forged, the analysis flags it (HTPBE_IDENTITY_OVERWRITTEN, HTPBE_PRODUCER_IDENTITY_FORGED).
Tampering around a digital signature. Where a statement is digitally signed, the analysis detects content changed after signing (HTPBE_POST_SIGNATURE_EDIT) or a signature stripped off entirely (HTPBE_SIGNATURE_REMOVED). These are among the most conclusive signals there are.

None of these depend on the visible numbers being implausible. A perfectly reconciled, perfectly tidy forged balance still sits inside a file that was edited — and the edit is what gets caught.

Want to see it on a real document? You can drop a PDF into the free check on this site and get a verdict in a few seconds — no account needed. It’s the same engine the API runs, and it’s a fast way to sanity-check a single suspicious statement before you decide whether to wire it into your intake.

What `inconclusive` Means in a Lending Context

The inconclusive verdict is the one that trips people up, so it’s worth being precise.

inconclusive means the file was created in software that anyone can use to build a document from scratch — Word, Excel, an online editor, a scanner. Because there’s no institutional baseline, the structural layer can’t say whether the content was tampered with. It’s telling you, honestly, “I can’t verify integrity here.”

The power of that verdict comes from context — specifically, what bank the borrower claims it’s from.

Major retail banks generate their statements on server-side institutional systems. A statement that genuinely came from one of them should look like an institutional export. So if a borrower hands you a statement claiming to be from a large bank, and the analysis returns inconclusive because the file was actually built in a word processor or run through an online editor, the verdict is doing real work: a real statement from that bank would not look like that. That mismatch is a reason to escalate, not to wave through.

The same inconclusive verdict on a statement from a small credit union or a fintech neobank — where consumer-style export is genuinely normal — is routine, and you’d treat it as such. The verdict is identical; the action depends on whether the claimed issuer is supposed to produce institutional files. Used this way, inconclusive isn’t a dead end. It’s a fork in your workflow.

Honest Limits — What This Layer Cannot Catch

Structural forensics is a powerful additional control, not a fraud oracle. Two scenarios sit outside its reach, and a serious fraud team should know them.

Documents fabricated entirely from scratch in the right kind of software. If a forger doesn’t edit a real bank export but instead builds a fake statement from zero using a tool that produces institutional-looking output, there is no “original” to compare against and no editing event to detect. The file may look clean structurally because, structurally, it is a clean single-pass file — it just contains invented data. This is why the layer complements rather than replaces content checks and source verification: open-banking data, verification of deposit, and calling the bank remain the right controls for fabricated-from-scratch fraud. The structural layer’s strength is the far more common case — editing a real document.

Legitimately consumer-generated statements. Some smaller institutions really do export through generic print drivers or consumer tools. For those, inconclusive is the correct and expected verdict, and reading it as guilt would generate false positives. The signal only carries weight when the claimed issuer has an institutional baseline to deviate from.

Being upfront about these limits is the point. The structural layer is designed to slot alongside your existing verification process — catching the altered-PDF case that content checks and open banking can’t — not to be a single switch that decides applications on its own. The same mechanics apply to income documents: altered paystubs and W-2s slip past underwriting in exactly the same way.

Wiring It Into Your Intake

For teams that decide the structural layer belongs in their workflow, integration is deliberately small. The pattern is three steps.

1. Analyze the uploaded PDF. When a borrower uploads a statement, send its URL to the analyze endpoint. There is no numeric risk score to interpret — you get a verdict and named markers.

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.example.com/statements/applicant-7821.pdf"}'

The response is just the check ID:

{ "id": "506a6b1b-1360-48a2-b389-abb346f85d04" }

2. Fetch the verdict. Retrieve the result by ID. The response is a flat object — the two fields your policy cares about are status and modification_markers.

curl https://api.htpbe.tech/v1/result/506a6b1b-1360-48a2-b389-abb346f85d04 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "modified",
  "modification_markers": ["HTPBE_EDITING_TOOL_FINGERPRINT", "HTPBE_DATES_DISAGREE"],
  "modification_confidence": "certain"
}

3. Route on the verdict. Wire the three outcomes into your existing review queue rather than auto-deciding on any single marker:

modified → route to manual review, request a fresh download direct from the bank portal, or — for the most conclusive markers like a post-signature edit — reject.
inconclusive → branch on the claimed issuer. A consumer-software origin on a statement claimed to be from a major bank is worth escalating; the same verdict from a neobank is routine.
intact → no structural evidence of alteration; proceed with your normal content verification.

Store the check ID against the application record. If a credit decision is ever disputed, the forensic result is retrievable as a permanent audit trail showing exactly which structural signals fired — useful for both compliance and chargeback defense.

Who Should Add This Layer

If you run risk or fraud operations at an alternative lender, a fintech, a BNPL or MCA provider — anywhere a meaningful share of applicants upload PDF bank statements instead of connecting through open banking — this is the gap in your stack worth closing. Your underwriters are already verifying content well. What they cannot see, by design, is whether the file in front of them was edited after the bank made it. That blind spot is exactly where careful borrowers operate, and it’s exactly what a structural layer covers.

For a deeper look at how this works as a workflow rather than a single call, see the fake bank statement detection use case. When you’re ready to put a verdict behind your intake, the self-serve API is documented end-to-end with test keys you can wire up before you spend a credit.

How to Bulk Re-Validate Customer VAT IDs

Iurii Rogulia — Fri, 07 Aug 2026 09:00:50 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

How to Bulk Re-Validate Your Customer VAT IDs (and Keep Them Fresh)

Most teams validate a customer's VAT number once — at signup, or the first time they issue a reverse-charge invoice — and then never look at it again. That is fine until an auditor asks whether the number was still valid at the time of each supply, or until a customer who deregistered eighteen months ago is still being invoiced without VAT. A VAT registration is not a permanent fact. This post is the practical version of fixing that: how to validate a whole existing customer base in one backfill pass, survive VIES going down partway through, spot the numbers that quietly flipped from valid to invalid, and then stop doing it by hand.

The scope here is the EU-27 plus Northern Ireland (XI), which is what VIES covers. Everything below uses the vatnode VAT API — a single GET /v1/vat/:vatId call with a Bearer key — but the batching and requeue logic applies to any VIES client you build yourself.

Why a stored VAT ID goes stale

A number that returned valid last year can return invalid today. Businesses deregister, get struck off, restructure into a new entity, or have their intra-EU (VIES) registration disabled while the domestic registration lives on. None of that generates a notification. The value sitting in your customers table is a snapshot of a moment that has already passed.

This matters because the customer's valid VAT ID is a substantive condition for zero-rating intra-Community supplies of goods — Article 138 of the EU VAT Directive (2006/112/EC), as amended by the 2020 Quick Fixes. For goods, the linked condition is the valid VAT ID plus a correct recapitulative statement (your EC Sales List). "Reverse charge" in the strict sense is the services case. Either way, the defensible position is the same: you want timestamped evidence that the condition held at the time of each supply, not just at signup.

There is no single EU-mandated re-check frequency. Cadence is a risk decision — set it with your tax adviser. But the mechanism for keeping the evidence current is the same regardless of the interval you land on, and that mechanism is what the rest of this post builds.

This is general information about EU VAT and VIES, not tax advice. Whether a specific transaction
qualifies for zero-rating, exemption, or reverse charge depends on facts we can't assess here —
confirm the treatment of your own transactions with a qualified tax adviser.

Step 1 — dedupe and format-filter before you call anything

The first pass never touches the network. A real customer base has the same VAT ID stored against multiple contacts, the same number written five different ways (DE123456789, DE 123 456 789, de123456789), and a long tail of junk that will never validate — blank strings, phone numbers pasted into the wrong field, national tax numbers that are not VIES-format at all.

Every one of those is a wasted VIES call if you send it. Normalise first, dedupe second, then discard anything that cannot be a well-formed EU/XI VAT ID before you spend a single request:

type CustomerRow = { customerId: string; rawVatId: string }

// Uppercase, strip everything that isn't a letter or digit.
function normalizeVatId(raw: string): string {
  return raw.toUpperCase().replace(/[^A-Z0-9]/g, '')
}

// Cheap structural gate: two-letter country prefix + at least one alphanumeric.
// This is a coarse filter, NOT full per-country validation — the API does that.
const VAT_SHAPE = /^[A-Z]{2}[A-Z0-9]{2,}$/

function prepareBatch(rows: CustomerRow[]) {
  const byVatId = new Map<string, string[]>() // vatId -> customerIds
  const skipped: CustomerRow[] = []

  for (const row of rows) {
    const vatId = normalizeVatId(row.rawVatId)
    if (!VAT_SHAPE.test(vatId)) {
      skipped.push(row) // malformed — flag for manual review, don't call VIES
      continue
    }
    const ids = byVatId.get(vatId) ?? []
    ids.push(row.customerId)
    byVatId.set(vatId, ids)
  }

  // One network call per distinct number; fan the result back out to customers.
  const toCheck = [...byVatId.entries()].map(([vatId, customerIds]) => ({
    vatId,
    customerIds,
  }))

  return { toCheck, skipped }
}

On a base of any real size this collapses the work dramatically — it is common to see tens of thousands of customer rows resolve to a few thousand distinct numbers. You validate each distinct number once and fan the answer back out to every customer that shares it. The skipped list is not garbage; it is a work queue for a human, because a malformed stored VAT ID is often a data-entry bug worth fixing at the source.

Step 2 — batch the base at a sane throughput

VIES is not one service. It is a thin EC gateway in front of national tax-authority nodes, and those nodes are per-country and rate-sensitive. Firing ten thousand requests in parallel is the fastest way to get throttled and turn a clean backfill into a mess of transient failures. The goal is steady, bounded throughput — a small concurrency limit, running continuously — not a thundering herd.

A simple worker-pool pattern keeps a fixed number of checks in flight and refills as each one finishes:

const API = 'https://api.vatnode.dev/v1/vat'
const KEY = process.env.VATNODE_API_KEY

type CheckJob = { vatId: string; customerIds: string[] }
type Outcome =
  | { vatId: string; status: 'checked'; data: VatResult }
  | { vatId: string; status: 'requeue'; reason: string }

async function runBatch(jobs: CheckJob[], concurrency = 4): Promise<Outcome[]> {
  const queue = [...jobs]
  const results: Outcome[] = []

  async function worker() {
    let job: CheckJob | undefined
    while ((job = queue.shift())) {
      results.push(await checkOne(job))
    }
  }

  // A handful of workers, not thousands of parallel fetches.
  await Promise.all(Array.from({ length: concurrency }, () => worker()))
  return results
}

Keep the concurrency low — a handful of workers is plenty for a background job that is allowed to take minutes or hours. There is no prize for finishing a backfill in ten seconds, and being polite to the national nodes is what keeps your error rate near zero. If you are running your own VIES client rather than the VAT API, the same discipline applies, plus you own the caching and retry layer that the API otherwise handles for you — see re-validation cadence and TTLs for how to think about that.

Step 3 — surviving a VIES outage mid-run

This is the step people get wrong, and it is the one that does real damage. Partway through a long backfill, a country node will go down. Those rows cannot be confirmed in this run — and that is all it means. A could-not-check outcome is not a negative result. If you store VIES_UNAVAILABLE or a timeout as valid: false, you have just marked a batch of real, paying customers as having invalid VAT numbers, and someone downstream will act on it.

The rule is simple: only valid: true and valid: false are real outcomes. Everything else — VIES_UNAVAILABLE (503), UPSTREAM_TIMEOUT (504), RATE_LIMITED (429) — is pending. Requeue it and try again later. Never let it touch the stored status.

type VatResult = {
  valid: boolean
  vatId: string
  countryCode: string
  countryName: string
  companyName: string | null
  companyAddress: string | null
  checkId: string
  verifiedAt: string
  source: string // 'VIES' | 'CACHE' | national registry code
  consultationNumber: string | null
}

async function checkOne(job: CheckJob): Promise<Outcome> {
  let res: Response
  try {
    res = await fetch(`${API}/${encodeURIComponent(job.vatId)}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    })
  } catch {
    // Network/transport error — temporary, requeue.
    return { vatId: job.vatId, status: 'requeue', reason: 'NETWORK' }
  }

  // A node being down is not the customer's fault. Requeue, never store invalid.
  if (res.status === 429 || res.status === 503 || res.status === 504) {
    return { vatId: job.vatId, status: 'requeue', reason: `HTTP_${res.status}` }
  }

  if (!res.ok) {
    // Genuine client errors (malformed input etc.) — surface, don't loop forever.
    return { vatId: job.vatId, status: 'requeue', reason: `HTTP_${res.status}` }
  }

  const data = (await res.json()) as VatResult
  // Only here do we have a real valid/invalid answer worth persisting.
  return { vatId: job.vatId, status: 'checked', data }
}

Run the requeue list as a second pass after a backoff — a down node is usually back within minutes to hours. Because VIES failures are country-scoped, a single unreachable member state should not stall the rest of the run; the healthy nodes keep answering while the affected prefix cools off. The full retry-and-backoff pattern, including per-country failure tracking, is in the handling VIES downtime guide. The one non-negotiable: a pending row keeps its previous stored status until a real answer replaces it.

Step 4 — recording what changed (and what to do about it)

A backfill that overwrites the old value with the new one and moves on has thrown away the interesting part. The point of re-validation is the diff — which numbers flipped since the last time you checked. Compare each fresh result against the last stored outcome and act only on the transitions:

type StoredOutcome = {
  customerId: string
  vatId: string
  valid: boolean
  source: string
  consultationNumber: string | null
  verifiedAt: string
}

function diffOutcome(
  previous: StoredOutcome,
  fresh: VatResult
): 'unchanged' | 'went_invalid' | 'became_valid' {
  if (previous.valid === fresh.valid) return 'unchanged'
  return fresh.valid ? 'became_valid' : 'went_invalid'
}

// Persist an APPEND-ONLY row for every real check — never mutate the old one.
async function recordCheck(customerId: string, fresh: VatResult) {
  await db.insert('vat_checks', {
    customerId,
    vatId: fresh.vatId,
    valid: fresh.valid,
    source: fresh.source, // 'VIES' vs a national registry code — keep it
    consultationNumber: fresh.consultationNumber, // null on national-fallback rows
    checkId: fresh.checkId,
    verifiedAt: fresh.verifiedAt,
  })
}

A few things hold up in practice here. Store an append-only row per check, never an overwrite — the timestamped history is the audit trail. Keep the source on every row: a VIES result and a national-registry result are not equivalent evidence. National-fallback rows carry no consultationNumber — that field is a VIES-only artefact — so do not treat a populated and a null consultation number as the same weight. When source is VIES, the consultation number is your externally-attested evidence for each re-check; when the answer came from a national registry, you still have a timestamped result, just of a different kind.

The went_invalid list is your action queue. Those are the customers to stop reverse-charging until the number is fixed — but do it as a quiet outreach, not an automatic billing change. A flip to invalid can mean a genuine deregistration or a customer who restructured and simply needs to give you the new number.

Step 5 — from one-off backfill to continuous monitoring

Steps 1–4 are a batch job you run once to clean up the base you already have. The obvious next question is how often to run it again — and the better answer is usually "don't run it by hand at all". A backfill is the one-time version of a loop that wants to be continuous: re-check on a cadence, diff against the last stored outcome, and get told when something flips.

That is exactly what monitoring is. Instead of scheduling a manual bulk pass, you register the numbers you care about and let re-checks run automatically, with a webhook firing when a number's status changes so the went_invalid case lands in your systems the day it happens rather than at your next quarterly sweep. The setup and payload shape are in the VAT monitoring and webhooks guide.

The practical split: run the bulk backfill once to establish a clean baseline and catch everything that already went stale, then hand the ongoing job to monitoring so you never have to schedule the manual cadence again. Bulk re-validation answers "is my existing base clean right now?"; monitoring answers "tell me the moment it stops being clean."

FAQ

How often should I re-validate stored VAT numbers?

There's no legal fixed interval, but because registrations get cancelled, re-checking on a periodic cadence (and before high-value events like renewals or invoicing) keeps your data defensible; continuous monitoring removes the manual cadence entirely.

Can I validate thousands of VAT numbers at once?

Yes, but pace the run — dedupe and format-filter first to avoid wasted calls, then batch at a steady throughput rather than firing everything in parallel, since the underlying VIES nodes are per-country and rate-sensitive.

What happens if VIES goes down partway through a bulk run?

Treat unreachable results as pending, not invalid, and requeue them; a per-country node being offline is temporary and should not mark real customers as failed.

How do I know which customers' VAT IDs went invalid?

Compare each re-check against the last stored outcome and flag only the numbers whose status flipped, keeping the timestamp and evidence for each so the change is auditable.

Is bulk re-validation different from monitoring?

Bulk re-validation is a one-time backfill of your existing base; monitoring is the ongoing version that re-checks automatically and notifies you (via webhooks) when a number changes.

Validate your whole base against one endpoint

vatnode is a single GET /v1/vat/:vatId call with a Bearer key — it runs the requester-qualified VIES lookup, falls back to national registries when a node is down, and returns structured errors so your requeue logic works exactly as above. Free plan, 100 requests/month.

Get a free API key · API reference

Programmatic SEO with hreflang: One Joke, 17 Languages, Server-Rendered

Iurii Rogulia — Wed, 05 Aug 2026 10:00:49 +0000

People type 2+2 into Google. They type 9+10. They type 7*8 when they can't remember whether it's 54 or 56. Each of those is a real, high-volume search query — and most of the results are identical calculator widgets. So when I built Wrongulator, a calculator that returns a confidently wrong answer on purpose, I had a question worth asking: what if every expression were its own page, ranking for the exact arithmetic people already search?

That is programmatic SEO — generating a page per parameter instead of writing pages by hand. And doing it across 17 languages means programmatic SEO with hreflang, where each generated page also declares its 16 translated siblings. The trap is that most programmatic surfaces are thin, duplicative, and get buried by Google. This one isn't, for a specific reason: every page has a real, unique answer baked into the HTML before any JavaScript runs. This post is about how — and the honest costs nobody mentions.

Why a Permalink Per Expression Is Even Possible

A page per expression only works if /2+2 reproduces the same result for everyone, forever, with no database behind it. That property isn't free — it's the result of one design decision I cover in detail in why a viral toy must be wrong the same way every time: the wrong answer is a pure function of the expression, seeded by a stable hash, with no per-user state.

The relevant consequence here is what that property unlocks for SEO. Because f("2+2") always returns the same wrong answer, the server can compute that answer on demand for any expression in the URL, with zero storage. There's no pages table, no CMS, no pre-generation job. A request for /64+5 runs the engine, gets 67 ("the only correct number"), and renders a complete page around it. The programmatic surface is, in effect, infinite — but it costs nothing to hold, because nothing is stored. The pure function is what makes thousands of unique pages possible without a database.

That's the foundation. Everything below is about putting real, crawlable content on top of it.

Why the SEO Has to Be Server-Side

Here's the thing people building client-side toys get wrong: search crawlers and social unfurlers don't run your JavaScript.

When Googlebot fetches /9+10, it reads the raw HTML response. Modern Googlebot can render JS in a second pass, but it's queued, delayed, and unreliable — and social crawlers (Twitterbot, facebookexternalhit, Slack's unfurler) don't render JS at all. They read the HTML once and stop. If your wrong answer only appears after the engine runs in the browser, then to every crawler the page is blank — a generic splash with no content to index and no answer to unfurl.

So the entire indexable payload has to exist in the server's first response: the localized <title> and description, the canonical URL, hreflang alternates for all 17 languages, OpenGraph and Twitter tags, structured data, and — critically — the actual wrong answer as real text in the body. The page has to be done the moment it arrives.

The OG image is part of this story too, but it's its own problem — rendering the share card identically in the browser and on the server is covered in isomorphic Canvas rendering. This article is about the text side: the meta tags, the alternates, the structured data, and the indexable answer in the HTML body.

The Programmatic Surface: Meta, hreflang, and JSON-LD

Three things get computed server-side, per link, before the response goes out.

First, the structured data. Each expression page carries a JSON-LD FAQPage with the real (wrong) answer as the accepted answer. This is what can earn a rich result in search and gives the crawler an unambiguous, machine-readable statement of what the page says:

// server.js — JSON-LD FAQ with the real (wrong) answer, per expression
const jsonld = {
  "@context": "https://schema.org",
  "@type": "FAQPage",
  mainEntity: [
    {
      "@type": "Question",
      name: `What is ${disp}?`,
      acceptedAnswer: {
        "@type": "Answer",
        text: `Wrongulator says ${disp} = ${r.answer}. ${r.reason}`,
      },
    },
  ],
};

Note r.answer and r.reason come straight from the engine, run server-side for this expression. The structured data isn't a static template — it contains the specific wrong answer and its deadpan justification, unique to this page. That's the difference between a FAQPage that helps and one Google ignores as boilerplate. (The FAQPage type is defined by schema.org; whether it shows as a rich result is up to Google.)

Second, the localized meta and hreflang set. A request resolves a locale, and the server emits a localized <title>/description plus a canonical and a full hreflang block pointing at all 17 language variants of the same expression. The shape, reconstructed from the server's response, is:

<!-- per-expression head, computed server-side (illustrative reconstruction) -->
<link rel="canonical" href="https://wrongulator.com/9+10?lang=en" />
<link rel="alternate" hreflang="en" href="https://wrongulator.com/9+10?lang=en" />
<link rel="alternate" hreflang="th" href="https://wrongulator.com/9+10?lang=th" />
<link rel="alternate" hreflang="ja" href="https://wrongulator.com/9+10?lang=ja" />
<!-- … 13 more locales … -->
<link rel="alternate" hreflang="fi" href="https://wrongulator.com/9+10?lang=fi" />
<link rel="alternate" hreflang="x-default" href="https://wrongulator.com/9+10" />

The rule Google documents for hreflang is that the set must be reciprocal — every variant has to list every other variant, including itself, or Google ignores the whole cluster. With 17 languages that's a 17-entry block on each of 17 pages, all generated from one function so they can't fall out of sync. The x-default is the fallback Google serves when none of the listed locales match the user's language.

Third, the sitemap that seeds the surface. Crawlers won't discover /9+10 on their own — nothing links to every arithmetic expression. So a curated sitemap.xml lists the highest-search expressions (2+2, 9+10, 7*8, and so on), each with its hreflang alternates. That's the deliberate part: I don't list every possible expression — that's a combinatorial explosion and a quality problem (more on that below). I list the ones people actually search, and let the long tail be reachable but unseeded.

The payoff of the whole stack: the toy can rank for the exact arithmetic queries people type, in their language, with a result that unfurls into the joke. The pure-function engine is what makes each of those pages cheap; the server-side meta is what makes them indexable.

slug="seo-audit"
text="Programmatic SEO lives or dies on details crawlers see and you don't — reciprocal hreflang, canonical consistency, whether your generated content reads as unique or thin. A technical SEO audit checks exactly that, with a written report."
/>

Localizing a Joke Without Killing It

Seventeen languages is where most products either skip localization or ruin it. A joke run through a translation API isn't funny — it's a sentence that used to be funny. So the i18n layer doesn't translate uniformly. It splits the copy by what the text does.

Prose that merely carries the joke gets translated: the deadpan justifications ("the only correct number"), the UI prompts, the void and malfunction lines. Those need to read naturally in the reader's language, because their job is to set up the punchline, not be it.

But text that is the joke gets left alone. The universal number-memes — skibidi, Ohio, 6-7, 300, 9+10=21 — travel as-is and are funnier untouched. Translating "skibidi" into Finnish would be vandalism. These memes are internet-native; they already crossed languages on their own, and the engine respects that by never touching them.

Then there's the third category, the one that makes the localization feel native rather than merely translated: locale-gated memes that only fire in their own language, because the number means something only in that culture.

// public/i18n.js — split by what the text DOES
// translate: deadpan/ai reasons, void/malfunction lines, UI prompts
// leave alone: universal number-memes; brand labels ("100% WRONG", "HALL OF FAME")
const MEMES = {
  meme555: ['ห้า ห้า ห้า. ตลกจนเครื่องคิดเลขขำ.', ...], // th — only ever shown for th
  meme39:  ['サンキュー。3-9。電卓からの感謝です。', ...],     // ja
  meme666: ['PERKELE. Tämä on ainoa oikea vastaus.', ...],  // fi
};

Each of those is a number-pun that lands in exactly one language. Thai 555 reads as "hahaha" because 5 is pronounced ha. Japanese 39 reads as "thank you" (san-kyū). Finnish 666 triggers perkele, the national curse word, written natively — not "the devil's number" politely translated. A non-speaker would never know these are jokes; a speaker recognizes them instantly. That's the whole point: the toy feels like it was made by someone who actually speaks your language, in 17 languages, because for the locale-gated memes, it effectively was. All 17 — including RTL Arabic — went through a native-speaker, meme-aware review pass. This is the same discipline I apply to production EU storefronts in Next.js i18n at 30 languages: translate the prose, respect what doesn't translate.

The Honest Cost

Programmatic SEO and 17-language localization both sound like pure leverage. They aren't. Here's what they actually cost.

The thin-pages risk is real. Google penalizes mass-produced, low-value pages — "doorway pages" in its terms — and a page-per-parameter surface is exactly the pattern that triggers it. The only reason Wrongulator's pages aren't doorways is that each one has genuinely unique content: a specific wrong answer, a specific deadpan reason, a real FAQPage describing them. If the pages were empty shells with only the expression swapped in the title, this would be a textbook thin-content surface and deserve to be buried. Programmatic SEO is not a trick for ranking empty pages — it's a way to scale pages that would each be worth publishing on their own. Get that backwards and Google is right to punish you.

Seventeen hreflang sets are fragile and expensive. Reciprocity means every page references every locale; one broken or non-reciprocal link can invalidate the cluster. Generating the block from a single function is the only sane way to keep it consistent — hand-maintaining 17×17 alternates would be a guaranteed source of silent bugs.

Native review doesn't scale and doesn't stay done. A locale-gated meme is only funny if a native speaker confirmed it's funny — and idioms drift, slang ages, and a pun that lands today can feel dated in a year. You need a real speaker per language, both to write the joke and to catch the cultural misfire that a translation tool would happily ship. That's 17 people's worth of cultural knowledge, and it's a recurring cost, not a one-time one. Skip it and you don't get a worse joke; you get a dead one, and the reader can tell.

The curated sitemap is manual, on purpose. I could generate a sitemap of millions of expressions. I don't, because most of them have zero search volume and listing them would dilute the surface into exactly the thin-content pattern above. Choosing which expressions to seed is editorial work — you have to know (or look up) what people actually search — and it has to be revisited as search trends shift. The combinatorial space is infinite; the worthwhile slice is small and hand-picked.

None of these are reasons not to do it. They're the reasons it works when most programmatic-SEO attempts don't: the surface is built on real per-page content, the alternates are machine-generated for consistency, and the human parts (memes, sitemap curation) are done by humans who know the domain.

Results

Aspect	Approach
Page per	Expression — `/2+2`, `/9+10`, `/7*8` each its own indexable URL
Storage	None — pure-function engine computes each page on demand, no database
Indexable content	Real wrong answer + deadpan reason in the HTML body before any JS runs
Structured data	JSON-LD `FAQPage` per expression, with the actual wrong answer as the answer
Localized meta	`<title>`, description, canonical computed server-side per locale
hreflang	Reciprocal set × 17 languages + `x-default`, generated from one function
Sitemap	Curated — highest-search expressions only, each with hreflang alternates
i18n split	Translate carrier prose; leave universal memes; locale-gate native puns
Locale-gated memes	Thai `555`, Japanese `39`, Finnish `666` — fire only in their own language
Review	Native-speaker, meme-aware pass on all 17 languages, including RTL Arabic

Takeaways

A pure function is what makes programmatic SEO cheap. If each page's content is computed deterministically from the URL, you need no database and no pre-generation — the surface is effectively infinite and costs nothing to hold. The hard part isn't volume; it's making each page genuinely worth indexing.
If a crawler can't see it without JS, it isn't indexed. Social unfurlers run no JavaScript and search rendering is queued and unreliable. Anything you need ranked — meta, structured data, the actual answer — has to be in the server's first HTML response.
hreflang must be reciprocal and generated, not hand-written. Every locale variant lists every other, including itself, or Google drops the cluster. With many languages, the only maintainable approach is to emit the whole block from one function so it can't drift.
Localize by what the text does, not uniformly. Translate the prose that carries the joke; leave the universal memes alone; locale-gate the puns that only work in one language. Uniform translation flattens humor — and the same principle applies to any voice-driven content, not just jokes.
Programmatic SEO is a quality multiplier, not a quantity trick. It scales pages that would each be worth publishing. Point it at empty shells and you've built a doorway-page farm Google is right to bury. Curate the sitemap, keep each page real, and accept that the native-review cost is the price of doing it well.

The full project — the deterministic Wrong Engine, isomorphic Canvas rendering, this programmatic-SEO surface, and a spoof-proof Hall of Fame — is written up in the Wrongulator project card. For the engine that makes every permalink reproducible, see deterministic wrong; for the share image that unfurls beside this meta, see isomorphic Canvas rendering.

PDF Tamper Detection API for Ruby on Rails: Integration Guide

Iurii Rogulia — Wed, 05 Aug 2026 10:00:40 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

A large share of fintech still ships on Rails. Stripe, Gusto, GitHub, Shopify, Instacart — the generation of companies that defined modern payments and payroll built their backends on Ruby, and the startups following them keep reaching for the same stack. So when a forged bank statement, an altered payslip, or a doctored invoice lands in an underwriting queue, more often than you would guess it lands on a Rails controller. Your KYC provider already confirmed the applicant is a real person with a valid identity. It said nothing about whether the PDF they uploaded was edited after the bank generated it. That structural-tampering layer is invisible to identity verification, and the right place to catch it is at ingress — before your Document model saves, before the row reaches underwriting, before any downstream system trusts the file.

This guide walks through integrating the PDF tamper detection API into a Ruby on Rails application: from the first curl command to an idiomatic HtpbeClient service object built on Faraday, a Data-class result struct, configuration-bound credentials, a typed error class, an ActiveJob that analyzes an uploaded document and routes on the verdict, and a request spec that stubs the API with WebMock. The patterns target Rails 7.x and Ruby 3.x, but they map cleanly onto Sinatra, Hanami, or a plain Ruby worker. Treat the code as a reference architecture: it runs the real request flow against the documented error codes, but you should adapt and harden it for your own traffic profile and threat model. If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically. Integrating from another stack? See the Python, Node.js, Go, Java / Spring Boot, Laravel / PHP, and C# / .NET guides.

TL;DR

Two API calls, three verdicts: POST /analyze returns a top-level id, then GET /result/{id} returns the flat verdict object whose status is one of intact, modified, or inconclusive.
The minimum integration is Faraday and two calls. No dependency beyond the gem you already have.
Production shape: an HtpbeClient service object that reads the key from Rails credentials, parses the response into an immutable Data result, raises a typed HtpbeError carrying the HTTP status, and retries on 5xx and 429 only.
An ActiveJob that analyzes an uploaded document off the request thread and maps the verdict to an accept / reject / review decision.
This is structural PDF tamper and forgery detection — not KYC, not OCR, not AI-text detection. It complements an identity stack; it does not replace one.

Prerequisites

Ruby 3.x (for Data.define, pattern matching, and endless methods) and Rails 7.x
An HTPBE API key (Dashboard → copy key)
The Faraday gem: gem "faraday" in your Gemfile, then bundle install. Faraday is already a transitive dependency of many Rails apps, and it is the de facto standard HTTP client in the Ruby ecosystem. If you would rather not add it, the standard-library Net::HTTP works too — this guide uses Faraday for its cleaner middleware and timeout handling, and keeps to one client throughout.

Step 1: Test the API with curl

Before writing any Ruby, confirm your key works. The API uses a two-step flow: POST /analyze submits a PDF URL and returns a check id, then GET /result/{id} retrieves the full verdict. (For a language-agnostic overview of what the API detects, see how PDF tamper detection works.)

Step 1a — submit for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.htpbe.tech/v1/test/clean.pdf"}'

You will receive a flat object with a single field: {"id": "00000000-0000-4000-8000-000000000001"}

Step 1b — retrieve the result:

curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

You will receive a flat JSON object with "status": "intact" and the full set of analysis fields:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "filename": "clean.pdf",
  "status": "intact",
  "origin": { "type": "institutional", "software": null },
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "modification_confidence": "none",
  "has_incremental_updates": false,
  "update_chain_length": 1,
  "signature_removed": false,
  "modifications_after_signature": false,
  "modification_markers": []
}

The same shape comes back for modified and inconclusive verdicts — only the values change. Two fields are conditional: status_reason appears only when status is inconclusive, and outdated_warning only when the check ran against an older algorithm version. Note that there is no data wrapper and no numeric risk score — the response is the flat object above, and the whole signal is the verdict plus the named markers.

The URL https://api.htpbe.tech/v1/test/clean.pdf is a test mock — it returns a predictable response without consuming quota. Test keys (prefix htpbe_test_) accept only these mock URLs; live keys (prefix htpbe_live_) accept any public PDF URL.

Step 2: Bind the Key to Credentials, Not Constants

Keep the key and base URL out of code. Rails ships an encrypted credentials store for exactly this. Run rails credentials:edit and add a block:

htpbe:
  api_key: htpbe_live_your_key_here
  base_url: https://api.htpbe.tech/v1
  timeout_seconds: 35

The encrypted file is safe to commit; the config/master.key that decrypts it is not, and Rails already gitignores it. In containers where mounting the master key is awkward, set RAILS_MASTER_KEY as an environment variable instead. Read the values through a small config object so a missing key fails fast at boot rather than on the first document that arrives at 2 a.m.:

# config/initializers/htpbe.rb
module Htpbe
  Config = Data.define(:api_key, :base_url, :timeout_seconds)

  def self.config
    @config ||= begin
      creds = Rails.application.credentials.htpbe || {}
      api_key = creds[:api_key] || ENV["HTPBE_API_KEY"]
      raise "HTPBE api_key is not configured (credentials.htpbe.api_key or ENV['HTPBE_API_KEY'])" if api_key.blank?

      Config.new(
        api_key: api_key,
        base_url: creds[:base_url] || "https://api.htpbe.tech/v1",
        timeout_seconds: creds.fetch(:timeout_seconds, 35),
      )
    end
  end
end

Reading from ENV as a fallback keeps the same code working in CI and on platforms that prefer environment variables. Either way the key never lands in source control as a bare literal.

Step 3: The Result Struct

Model the GET /result/{id} response as an immutable Data class. Ruby 3.2’s Data.define gives you a frozen value object with keyword initialization — the right shape for a response you parse once and never mutate. Map only the fields you branch on; the API returns more, and ignoring the rest means a newly added field never breaks your parser.

# app/services/htpbe/result.rb
module Htpbe
  Result = Data.define(
    :id,
    :filename,
    :status,                       # "intact" | "modified" | "inconclusive"
    :status_reason,                # present only when status == "inconclusive"
    :origin_type,
    :origin_software,
    :modification_confidence,      # "certain" | "high" | "none" | nil
    :creator,
    :producer,
    :signature_removed,
    :modifications_after_signature,
    :has_incremental_updates,
    :update_chain_length,
    :modification_markers,         # array of stable HTPBE_* ids
  ) do
    def self.from_response(body)
      origin = body["origin"] || {}
      new(
        id: body.fetch("id"),
        filename: body["filename"],
        status: body.fetch("status"),
        status_reason: body["status_reason"],
        origin_type: origin["type"],
        origin_software: origin["software"],
        modification_confidence: body["modification_confidence"],
        creator: body["creator"],
        producer: body["producer"],
        signature_removed: body.fetch("signature_removed", false),
        modifications_after_signature: body.fetch("modifications_after_signature", false),
        has_incremental_updates: body.fetch("has_incremental_updates", false),
        update_chain_length: body.fetch("update_chain_length", 0),
        modification_markers: Array(body["modification_markers"]),
      )
    end

    def intact? = status == "intact"
    def modified? = status == "modified"
    def inconclusive? = status == "inconclusive"
  end
end

Two fields deserve a closer look. status_reason is populated only when status is inconclusive, and it carries one of several values — consumer_software_origin, online_editor_origin, scanned_document, and a few more. The difference matters: a scanned document is benign for a user-submitted handwritten form, but a consumer_software_origin on something that claims to be a payslip is the kind of origin you would not expect from a real payroll system — that class covers both consumer apps and freely available HTML-to-PDF renderers, so it is a strong signal to route for review. Branch on the specific reason, not just on the top-level inconclusive.

modification_markers returns stable, machine-readable ids prefixed HTPBE_ — for example HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_POST_SIGNATURE_EDIT, and HTPBE_MULTIPLE_REVISION_LAYERS. Branch your integration logic on the id; render the human-readable label from the dictionary published on htpbe.tech/how. These ids are part of the public contract and never change once shipped. The API does not return a numeric risk score — the verdict plus the named markers are the whole signal, by design, so there is no threshold to tune on your side.

Step 4: A Typed Error

A 401 means your key is wrong; a 402 means the credit pool is dry; a 500 is transient. Both the retry layer and your business logic need to branch on the status code, so wrap every non-success response in one error type that carries it.

# app/services/htpbe/error.rb
module Htpbe
  class HtpbeError < StandardError
    attr_reader :status, :code, :retry_after

    def initialize(message, status:, code: "unknown", retry_after: nil)
      super(message)
      @status = status
      @code = code
      @retry_after = retry_after
    end

    # Only 5xx and 429 are transient. Every other 4xx is permanent —
    # retrying it burns latency and, for 402, can never succeed until
    # the account is topped up.
    def retryable? = status >= 500 || status == 429
  end
end

Step 5: The Service Object

Here is the complete client. It is a plain service object — instantiate it once and reuse it, or resolve it per request. It builds a Faraday connection with the base URL, the Authorization header, and a JSON request/response middleware, exposes one public method verify, and converts every non-success response into an HtpbeError in one place.

# app/services/htpbe/client.rb
require "faraday"

module Htpbe
  class Client
    MAX_RESULT_POLLS = 5

    def initialize(config = Htpbe.config)
      @config = config
      @conn = Faraday.new(url: config.base_url) do |f|
        f.request :json
        f.response :json, content_type: /\bjson$/
        f.headers["Authorization"] = "Bearer #{config.api_key}"
        f.headers["Accept"] = "application/json"
        f.options.timeout = config.timeout_seconds
        f.options.open_timeout = 10
      end
    end

    # Submits a PDF URL and returns a parsed Result. The two steps are kept
    # separate on purpose: POST /analyze is the billable, job-creating call;
    # GET /result/{id} is a free read.
    def verify(pdf_url:, original_filename: nil)
      id = submit_analysis(pdf_url, original_filename)
      fetch_result(id)
    end

    private

    def submit_analysis(pdf_url, original_filename)
      body = { url: pdf_url }
      body[:original_filename] = original_filename if original_filename

      response = with_retries { @conn.post("analyze", body) }
      raise_for_status(response) unless response.success?

      id = response.body["id"]
      raise HtpbeError.new("analyze response missing id", status: 502, code: "bad_response") if id.to_s.empty?

      id
    end

    def fetch_result(id)
      # POST /analyze runs the analysis synchronously, so the result is normally
      # ready on the first GET. The bounded poll below is defensive: it tolerates
      # a brief replication lag and re-reads on a transient 404 before giving up.
      last_error = nil

      MAX_RESULT_POLLS.times do |attempt|
        response = with_retries { @conn.get("result/#{id}") }
        return Result.from_response(response.body) if response.success?

        last_error = error_for(response)
        # Only a 404 is worth re-reading (the row may not be visible yet).
        # Every other error is terminal — surface it without burning attempts.
        raise last_error unless response.status == 404

        sleep(0.3 * (attempt + 1))
      end

      raise last_error || HtpbeError.new("result not ready after polling", status: 504, code: "result_timeout")
    end

    # Retry transient failures (5xx, 429, connection errors) with backoff.
    # Permanent 4xx codes short-circuit immediately — a 402 can never succeed
    # until the account is topped up.
    def with_retries(max: 3)
      attempt = 0
      begin
        attempt += 1
        response = yield
        if !response.success? && transient_status?(response.status) && attempt < max
          sleep(retry_delay(response, attempt))
          raise Faraday::Error, "retrying transient #{response.status}"
        end
        response
      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
        raise HtpbeError.new(e.message, status: 503, code: "network_error") if attempt >= max

        sleep(2**(attempt - 1))
        retry
      rescue Faraday::Error
        retry if attempt < max
        raise
      end
    end

    def transient_status?(status) = status >= 500 || status == 429

    def retry_delay(response, attempt)
      retry_after = parse_retry_after(response.headers["retry-after"])
      retry_after || 2**(attempt - 1) # 1s, 2s, 4s
    end

    def raise_for_status(response) = raise(error_for(response))

    def error_for(response)
      body = response.body.is_a?(Hash) ? response.body : {}
      code = body["code"] || "unknown"
      retry_after = parse_retry_after(response.headers["retry-after"])

      message =
        case response.status
        when 400 then "Bad request: #{body["error"] || "check the url field"}"
        when 401 then "Invalid API key — check credentials.htpbe.api_key"
        when 402 then "No credits available for this key — top up or subscribe"
        when 403 then "Test key sent to a live URL, or vice versa"
        when 413 then "PDF exceeds the 10 MB size limit"
        when 422 then "The URL did not return a valid PDF file"
        when 429 then "Server is at analysis capacity — honour Retry-After before retrying"
        else body["error"] || "HTPBE error #{response.status}"
        end

      HtpbeError.new(message, status: response.status, code: code, retry_after: retry_after)
    end

    # RFC 7231 Retry-After: delay-seconds or an HTTP-date. Clamped to [1, 600]
    # so a hostile or misconfigured value cannot stall a worker indefinitely.
    def parse_retry_after(header)
      return nil if header.blank?

      seconds =
        if header.to_s.match?(/\A\d+\z/)
          header.to_i
        else
          ((Time.httpdate(header) - Time.now).round rescue nil)
        end
      return nil if seconds.nil?

      seconds.clamp(1, 600)
    end
  end
end

Two status codes deserve explicit handling in your own code:

402 (Payment Required) — the key has no credit source left. Credits are universal: a subscription’s monthly quota, a one-time top-up batch, and the welcome credits all draw from one pool. A 402 means all three are exhausted (or there is no active plan on a live key). HtpbeError#retryable? returns false for it — surface it to your billing path rather than retrying, because retrying fails identically until the account is topped up at the pricing page.
429 (Too Many Requests) — this is server-wide concurrency, not per-key rate limiting. The response carries a Retry-After header, which parse_retry_after reads (both delay-seconds and HTTP-date forms, clamped to [1, 600]) so the retry loop waits the server-suggested interval before falling back to exponential backoff.

Step 6: The Verdict Gate

The client returns facts. Turning those facts into an accept / reject / review decision is a policy choice that depends on what the document claims to be. A bank statement, a payslip, or a diploma claims institutional origin, so anything other than intact should stop the automated path. A user-generated form is held to a looser standard. Ruby’s pattern matching makes the mapping readable:

# app/services/htpbe/document_gate.rb
module Htpbe
  module DocumentGate
    # Maps a verdict to a decision for documents that claim institutional
    # origin (bank statements, payslips, diplomas). For these, "inconclusive"
    # is treated as strictly as "modified": a document that should have come
    # from a bank's own system but looks like it was built in Word does not
    # get the benefit of the doubt.
    def self.for_institutional(result)
      case result.status
      when "modified"      then :reject
      when "inconclusive"  then :review
      when "intact"        then :accept
      else :review
      end
    end
  end
end

An inconclusive result should not be auto-accepted — it typically indicates the file came from consumer software, an online editor, an HTML renderer, or a scanner rather than an institutional generator. That is a signal to route for review, not proof of tampering. For a deeper explanation, see what “inconclusive” really means. For documents that claim institutional origin, treat inconclusive with the same caution as modified: do not accept automatically, route to a human reviewer. Inverting that policy — treating inconclusive as a pass — is the single most common integration mistake, because it hands an automatic accept to exactly the consumer-software-built documents a bank statement should never be.

Step 7: An ActiveJob, Not a Blocking Controller

Analysis takes 2–5 seconds for a typical document. Blocking a Rails request handler for that long is fine for an internal admin tool, but for any user-facing upload flow you want to return immediately and resolve the verdict on a worker. ActiveJob is the idiomatic place. The controller stores the upload on a private bucket, records a pending Document, and enqueues; the job mints a short-lived URL, calls the API, and routes on the verdict.

# app/jobs/verify_document_job.rb
class VerifyDocumentJob < ApplicationJob
  queue_as :verification

  # Retry on transient failures with growing delay; ActiveJob handles the backoff.
  retry_on Htpbe::HtpbeError, wait: :polynomially_longer, attempts: 5 do |job, error|
    # Out of attempts. If it was a billing failure, retrying never helps —
    # flag the document for an operator rather than silently dropping it.
    job.arguments.first.then do |document_id|
      Document.find_by(id: document_id)&.update(verdict: "error", review_reason: error.code)
    end
  end

  def perform(document_id)
    document = Document.find(document_id)
    # Idempotency: a re-queued job from a worker crash must not double-charge credits.
    return if document.verdict.present?

    # A 5-minute presigned URL keeps the bucket private; the file is reachable
    # only for the few seconds the analysis takes.
    pdf_url = document.file.url(expires_in: 5.minutes)

    begin
      result = Htpbe::Client.new.verify(
        pdf_url: pdf_url,
        original_filename: document.original_filename,
      )
    rescue Htpbe::HtpbeError => e
      # 402 (no credits) is permanent — stop retrying immediately and alert billing.
      raise e if e.retryable?

      document.update(verdict: "error", review_reason: e.code)
      Rails.logger.warn("HTPBE verification failed for ##{document_id}: #{e.message}")
      return
    end

    apply_verdict(document, result)
  end

  private

  def apply_verdict(document, result)
    decision = Htpbe::DocumentGate.for_institutional(result)

    document.update(
      htpbe_check_id: result.id,
      verdict: result.status,
      status_reason: result.status_reason,
      producer: result.producer,
      modification_markers: result.modification_markers,
      requires_review: decision == :review,
    )

    case decision
    when :reject
      DocumentMailer.flagged(document).deliver_later
    when :review
      ReviewQueue.enqueue(document)
    when :accept
      document.approve!
    end
  end
end

Enqueue it from the controller after storing the upload, and return without waiting:

# app/controllers/documents_controller.rb
class DocumentsController < ApplicationController
  def create
    document = current_user.documents.create!(
      file: params.require(:file),
      original_filename: params[:file].original_filename,
      verdict: nil,
    )

    VerifyDocumentJob.perform_later(document.id)

    render json: { id: document.id, status: "verification_pending" }, status: :accepted
  end
end

A few production details worth getting right (the broader patterns are covered in the async queue guide):

Idempotency. The job returns early when document.verdict is already set, so a re-queue after a worker crash never double-charges credits.
A dedicated queue. Run verification on its own queue (queue_as :verification) so a backlog of PDFs cannot starve other jobs.
Permanent vs. transient. retry_on handles 5xx and 429 with backoff; the raise e if e.retryable? line lets those bubble up, while permanent codes (401, 402, 422) are caught and recorded so the document does not loop forever.

Step 8: Giving the API a Reachable URL

The API does not accept file uploads — it downloads the PDF from a URL you supply, so the file must be publicly reachable for the few seconds the analysis takes. The cleanest pattern is a short-lived presigned URL from your object store. With Active Storage on S3, GCS, or Cloudflare R2, document.file.url(expires_in: 5.minutes) mints exactly that: the bucket stays private, the link expires in minutes, and passing original_filename keeps the audit trail readable instead of showing an opaque storage key.

One security note: the API fetches whatever URL you give it, so if a URL ever comes from untrusted input (a user-pasted link, a webhook payload), validate that it resolves to a public host first — reject localhost, 169.254.169.254 (cloud metadata), and the RFC 1918 private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) to close the SSRF surface. When you mint the URL yourself from a private bucket the risk is minimal, but the validation belongs in the request flow either way. A presigned URL is also a bearer token — anyone who sees it inside the five-minute window can fetch the PDF, so do not log full URLs and scope the signing policy to read the one object and nothing else.

Step 9: Testing Without Burning Quota

Every plan includes a test API key (prefix htpbe_test_) that accepts only mock URLs of the form https://api.htpbe.tech/v1/test/{filename}.pdf and returns deterministic responses — like Stripe test cards, with no quota cost. For unit specs you do not even need the network: stub the two endpoints with WebMock and assert that your gate branches correctly. Here is an RSpec job spec covering all three verdicts:

# spec/jobs/verify_document_job_spec.rb
require "rails_helper"

RSpec.describe VerifyDocumentJob, type: :job do
  let(:document) { create(:document, verdict: nil, original_filename: "statement.pdf") }

  before do
    allow_any_instance_of(Document)
      .to receive_message_chain(:file, :url).and_return("https://files.example.test/doc.pdf")
  end

  def stub_flow(status:, markers: [], status_reason: nil, signature_removed: false)
    stub_request(:post, "https://api.htpbe.tech/v1/analyze")
      .to_return(
        status: 201,
        headers: { "Content-Type" => "application/json" },
        body: { id: "00000000-0000-4000-8000-000000000001" }.to_json,
      )

    stub_request(:get, "https://api.htpbe.tech/v1/result/00000000-0000-4000-8000-000000000001")
      .to_return(
        status: 200,
        headers: { "Content-Type" => "application/json" },
        body: {
          id: "00000000-0000-4000-8000-000000000001",
          filename: "statement.pdf",
          status: status,
          status_reason: status_reason,
          origin: { type: "institutional", software: nil },
          signature_removed: signature_removed,
          modification_markers: markers,
        }.to_json,
      )
  end

  it "accepts an intact document" do
    stub_flow(status: "intact")
    described_class.perform_now(document.id)

    expect(document.reload.verdict).to eq("intact")
    expect(document.requires_review).to be(false)
  end

  it "rejects a modified document and surfaces the markers" do
    stub_flow(status: "modified", markers: ["HTPBE_SIGNATURE_REMOVED"], signature_removed: true)
    described_class.perform_now(document.id)

    expect(document.reload.verdict).to eq("modified")
    expect(document.modification_markers).to include("HTPBE_SIGNATURE_REMOVED")
  end

  it "routes an inconclusive document to review, not accept" do
    stub_flow(status: "inconclusive", status_reason: "consumer_software_origin")
    described_class.perform_now(document.id)

    expect(document.reload.verdict).to eq("inconclusive")
    expect(document.requires_review).to be(true)
  end
end

For an end-to-end smoke test against the live mock fixtures, point a request spec at the real test key and the real test URLs. Useful fixtures: clean.pdf → intact, signature-removed.pdf → modified, dates-mismatch.pdf → modified, modified-critical.pdf → modified, and inconclusive.pdf → inconclusive. A direct client spec is the smallest version:

# spec/services/htpbe/client_spec.rb
require "rails_helper"

RSpec.describe Htpbe::Client do
  # Requires HTPBE_TEST_API_KEY in the environment — test keys consume no quota.
  subject(:client) { described_class.new }

  it "returns inconclusive for a consumer-software fixture", :external do
    result = client.verify(pdf_url: "https://api.htpbe.tech/v1/test/inconclusive.pdf")

    expect(result.status).to eq("inconclusive")
    expect(result.status_reason).not_to be_nil
    expect(Htpbe::DocumentGate.for_institutional(result)).to eq(:review)
  end

  it "flags a stripped signature as modified", :external do
    result = client.verify(pdf_url: "https://api.htpbe.tech/v1/test/signature-removed.pdf")

    expect(result.status).to eq("modified")
    expect(result.signature_removed).to be(true)
    expect(Htpbe::DocumentGate.for_institutional(result)).to eq(:reject)
  end
end

Keep test and live keys in separate credentials environments and never commit either. For audit dashboards, GET /v1/checks returns a paginated list of every result for your key — filter by status and limit (/checks?status=modified&limit=50, same Authorization header). When you reach your monthly quota, further requests return 402 until it resets — add a one-time credit pack or move to a higher tier, and handle the 402 so a quota boundary never silently drops a check.

What the Verdicts Mean

The whole signal is three verdicts and a list of named markers. Encoding them correctly in your DocumentGate matters more than any other choice in the integration:

intact — no post-creation modification was detected and the origin looks institutional. Safe to accept on the automated path.
modified — forensic evidence of an edit after the document was created. The modification_markers array names the signal: HTPBE_DATES_DISAGREE for inconsistent internal timestamps, HTPBE_SIGNATURE_REMOVED for a stripped digital signature, HTPBE_POST_SIGNATURE_EDIT for changes made after signing, HTPBE_MULTIPLE_REVISION_LAYERS for a document saved repeatedly after creation. Reject, or route to fraud review.
inconclusive — the document was built with consumer software, an online editor, an HTML renderer, or a scanner, so there is no institutional “original” to verify integrity against. This is not a failure and not a clean pass — it is a routing signal. For a document that should have come from an institution (a bank statement, a payslip), inconclusive means it did not, which is exactly why DocumentGate.for_institutional routes it to a human reviewer.

What This Does Not Catch

Structural analysis has honest limits, and a Rails service making automated decisions should encode them rather than overstate the verdict:

Content fabricated in one pass. If someone opens Word, types a false salary, and exports once, the file was never modified after creation — it is structurally consistent. The fraud happened at authorship, not at the byte level. This is exactly why a payslip from a consumer tool tends to return inconclusive rather than intact: the analysis cannot vouch for a document anyone could have produced from scratch.
Born-synthetic forgeries. A fake document generated programmatically with a valid-looking account number and a real logo — never derived from a genuine original — has no post-creation edit to detect. Catching that is a content-verification problem (does this account number exist, does this employer match payroll records), a different product category from structural tamper detection.
Documents rebuilt from scratch in the original’s software. A determined attacker who recreates a document in the same institutional tool and matches the metadata leaves few structural signals. This is rare and high-effort, but possible.
Encrypted or password-protected PDFs. The service cannot parse a file it cannot open; remove the password before submitting.

These limits are why structural tamper detection works as one layer in a fraud-detection stack, not the whole stack. Pair the structural verdict with domain checks — amount validation, account-number lookups, sender authentication, and your KYC or OCR provider — for a layered defense. The structural layer answers a question identity verification cannot: was this file edited after it was issued? See PDF Fraud Prevention Best Practices.

Decisions Before You Ship

The integration surface is intentionally small: one POST, one GET, three verdicts, the typed error above. The complexity lives on the Rails side, and two choices matter most:

Where verification runs. Synchronous inside the controller gives the caller an immediate decision but blocks for a few seconds; an ActiveJob on a dedicated queue returns instantly and defers the verdict. Sync suits low-volume internal tools; async suits any user-facing upload flow, which is why the job is the default above.
inconclusive routing. For documents that claim institutional origin (bank statements, diplomas, payslips), treat inconclusive with the same caution as modified and route to human review — that is what DocumentGate.for_institutional encodes. For genuinely user-generated content it may be acceptable as-is, so you may want a second gate with a looser policy.

To start, sign up for HTPBE — new accounts get five checks to try, then pay-per-check credits or a subscription (see current pricing) — copy your test key, and run the curl call from Step 1. The full API reference documents every response field, error code, and the marker dictionary the Rails client branches on.

What Is a VAT ID? A Plain Guide

Iurii Rogulia — Wed, 05 Aug 2026 09:00:49 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

What Is a VAT ID (VAT Identification Number)?

A VAT ID is the number a tax authority gives a business when it registers for value-added tax, and it identifies that business for VAT everywhere it trades. In the EU it is written as a two-letter country prefix followed by a country-specific string — DE123456789, for example — and it shows up on invoices and in cross-border B2B transactions.

This guide covers what a VAT ID actually is, what it is used for, how it is structured, and how to confirm one is real. The scope here is the EU-27 plus XI (Northern Ireland), which is the area VIES covers.

If you just want to confirm a number right now, you can jump to checking whether a VAT ID is valid. Otherwise, start from the top.

What a VAT ID actually is

A VAT ID (VAT identification number) is issued by a national tax authority when a business registers for VAT. From that point on, the number is how the business is recognised in the VAT system: it goes on the invoices it issues, it is quoted when trading with other VAT-registered businesses, and it is the value other parties look up to confirm the business is registered.

A VAT ID is tied to VAT specifically. It is not a general-purpose company identifier, and it is not the number your bank or a supplier's accounts-payable team would use for anything else.

VAT ID vs VAT registration number vs local tax number

These three phrases cause most of the confusion, so to be direct: "VAT ID", "VAT number", and "VAT registration number" are the same thing. Different documents and different countries use different wording, but they all refer to the one identifier a business uses for VAT.

What a VAT ID is not is a domestic tax number or a company registration number:

A local tax number is what the domestic tax office uses to administer a business internally. In several countries it looks different from the VAT ID and is used for filings that have nothing to do with cross-border trade. It usually has no country prefix, so it will not validate as an EU VAT ID.
A company registration number is issued by a company register (the equivalent of Companies House, the Handelsregister, and so on) when the entity is incorporated. It identifies the legal entity, not its VAT status.

A business can have all three, and they are typically different values. On an intra-EU invoice, the one that belongs there is the VAT ID with its country prefix.

What a VAT ID is used for

Intra-EU B2B trade

The VAT ID's main job is cross-border business-to-business trade inside the EU. When two VAT-registered businesses in different member states trade, they exchange VAT IDs so each side can establish that the other is a registered taxable person. That single fact changes how VAT is handled on the transaction.

Invoicing

A VAT ID belongs on VAT invoices. For intra-EU B2B supplies, both the supplier's and the customer's VAT IDs generally appear on the invoice — and the customer's number being present and valid is part of what supports the correct VAT treatment of the supply.

Reverse charge

When a valid buyer VAT ID is present on a cross-border B2B supply, the seller can often avoid charging local VAT — but the exact mechanism depends on what is sold. For goods, the sale can be an exempt (zero-rated) intra-Community supply, with the buyer accounting for VAT on the acquisition in their own country. For services, the place of supply generally shifts to the buyer, who accounts for the VAT under the reverse-charge mechanism. Either way, a valid buyer VAT ID is one of the conditions that has to hold — the full set of conditions is its own topic; see how reverse charge works for cross-border B2B. The point for this guide is that the buyer's VAT ID is central to that treatment, which is exactly why sellers care whether it is valid.

How a VAT ID is structured

At a glance, an EU VAT ID is:

[2-letter country prefix] + [up to ~12 alphanumeric characters]

For example, a German VAT ID looks like DE123456789: the DE prefix, then the national portion. The national portion varies by country — some are all digits, some include letters, and lengths differ — so the "up to ~12 characters" is a rough envelope, not a single fixed pattern.

Two prefixes catch people out:

Greece uses EL, not GR. The VAT system uses EL even though the ISO country code is GR.
Northern Ireland uses XI. Under the Northern Ireland arrangements (Windsor Framework), NI VAT IDs for goods carry the XI prefix and are validatable through VIES.

Per-country patterns are worth a reference when you need them, but there is no reason to memorise 27 of them. The full breakdown is here: VAT number formats for all 27 EU countries.

VAT ID vs other identifiers people confuse it with

A VAT ID gets mixed up with several other business numbers. Quick disambiguation, staying strictly on VAT:

It is not an EORI number. An EORI number identifies businesses for customs, not VAT.
It is not an IOSS or OSS registration. Those are separate VAT special-scheme registrations (IOSS even issues its own IM-prefixed number), distinct from the VAT ID itself.
It is not a company registration number. That comes from the company register and identifies the legal entity, not its VAT status.

If a number has a two-letter country prefix and validates in VIES, it is a VAT ID. The others do not behave that way.

How to check whether a VAT ID is valid

For EU VAT IDs, validity is confirmed against VIES, the European Commission's system that routes a query to the relevant national VAT database and reports back whether the number is registered; some numbers can also be cross-checked against national registries.

A valid format is not the same as a valid number. A string can match a country's pattern
perfectly and still not be a registered, active VAT ID — the difference between the two, and the
third state most people miss, is spelled out in VAT ID format vs
valid. Only a live check against VIES or a national source tells
you whether the number actually exists and is active — never infer registration from the shape of
the string alone.

For a single number, the fastest route is a free VAT number checker — paste the VAT ID in and you get the live result. If you want to understand what sits behind that result, including why VIES sometimes can't answer, read what VIES is and how it works.

When a business needs to validate other companies' VAT IDs

Checking one number by hand is fine. Checking VAT IDs on every signup, every invoice, or across an existing customer base is not — that is where you validate programmatically.

At that point you call a validation service from your own application: a VIES API for EU-wide lookups, or a per-country VAT validation API when you need a specific national source. The other half of the job is keeping evidence: storing the result of each check — when it ran, what came back, and which source answered — so you can show your work later. Auditors on intra-EU supplies may ask for it; a lightweight record such as the VIES consultation number alongside your own logs is the kind of trail that holds up.

If you're building this in, the API documentation covers the request and response shape, and pricing has the plan limits. You can get a free API key and validate against VIES from your own code.

FAQ

What is a VAT ID?

A VAT ID is the number a tax authority assigns to a business when it registers for value-added tax. It identifies that business for VAT purposes and is used on invoices and in intra-EU trade. Across the EU it takes the form of a two-letter country prefix followed by a country-specific string of characters.

Is a VAT ID the same as a VAT number?

Yes. "VAT ID", "VAT number", and "VAT registration number" all refer to the same identifier — the number that identifies a business for VAT. The different names are just wording; they point at the same value on your invoices and in VIES.

What is the difference between a VAT ID and a tax number?

A VAT ID identifies a business specifically for VAT and, in the EU, carries a country prefix so it works across borders. A local tax number (or company registration number) identifies the business to the domestic tax office or company register for other purposes. They are issued for different reasons and are usually different values, so they are not interchangeable on an intra-EU invoice.

How do I check if a VAT ID is valid?

For EU VAT IDs, validity is confirmed against VIES, the European Commission's system that routes the query to the relevant national database; some numbers are cross-checked against national registries. Note that a correct format is not the same thing as a registered, active number — only a live check confirms that. You can run a one-off check with a free VAT number checker.

Do I need a VAT ID to sell in the EU?

It depends on your situation — where you're established, what and to whom you sell, and whether you cross a registration threshold. Some businesses are required to register for VAT and some are not, and the rules differ by member state. This is not tax advice; check your national tax authority's guidance or a qualified advisor for your specific case.

What is the format of an EU VAT ID?

An EU VAT ID is a two-letter country prefix followed by up to roughly 12 alphanumeric characters, with the exact pattern set by each country. The prefix is the country code — for example Greece uses EL rather than GR, and Northern Ireland uses XI. A German VAT ID looks like DE123456789.

Check any EU VAT number free

Confirm a single VAT ID against VIES in seconds with the free VAT number checker. Validating VAT IDs in your app instead? Get a free API key and call the VIES API from your own code — free plan, 100 requests/month.

Your Software Works, But Nobody Can Safely Change It

Iurii Rogulia — Mon, 03 Aug 2026 10:00:46 +0000

Most business owners describe the problem the same way. "The system works. Customers use it every day. But every time we ask for a change, it takes forever, costs more than we expected, and something else breaks that we didn't touch."

That's the real problem. Not that the software is old. That nobody can safely change it anymore.

Those are two completely different situations, and confusing them costs companies a lot of money. Old software that works and can be changed safely is an asset — leave it alone. Software you're afraid to touch is a liability, and it stays a liability whether you rebuild it or not. The question that matters isn't "is this old?" It's "can we still move?"

Age Is Not the Reason

I want to be blunt about this, because the software industry has a financial interest in the opposite message.

Software being old is not a reason to replace it. There are systems quietly running businesses today on technology that was current a decade or two ago, and they run fine. They process orders, send invoices, handle payments, and nobody thinks about them — which is exactly what good infrastructure is supposed to do. Replacing one of those because it's "outdated" is like demolishing a warehouse because the architecture is unfashionable. It's still keeping the rain off your inventory.

The pressure to modernize usually comes from one of a few places, and most of them are bad reasons:

A developer doesn't enjoy working in it. Legitimate feeling, not a legitimate business case. "I'd build it differently" is an aesthetic preference, not an economic argument.
It's not the newest technology. Newer is not the same as better for your situation. The newest stack still has to be built, tested, and learned by whoever maintains it next.
A vendor told you it's "legacy." Vendors sell replacements. That's the whole business. When the person diagnosing the problem also sells the cure, get a second opinion.

None of these mean your software is holding you back. So what does?

The Real Symptom: Change Has Become Dangerous

Here's how you actually know something is wrong. It isn't the age of the code — it's what happens when you try to change it.

Watch for these:

Every change takes far longer than it should, and the estimates keep growing. A small request — a new field on a form, a change to how a discount is calculated — turns into weeks. And the number goes up each time, not down.
Changing one thing breaks something unrelated. You update the checkout page and the invoicing breaks. Nobody can explain why those two things are connected, which is precisely the problem: the connections aren't understood anymore.
Only one person can touch it — and you're afraid of losing them. If a single developer is the only human who understands how the system works, you don't have software. You have a hostage situation, and the ransom is their salary and their continued good mood.
Nobody can safely say what will happen if you deploy a change. In a healthy system, you can predict the effect of a change and verify it before it reaches customers. When every deployment is a held breath, the system has stopped being controllable.

Notice what all four have in common. None of them is about the technology being old. They're about the system having become unpredictable and unsafe to modify. That's the condition worth spending money to fix. Age is a coincidence; danger is the diagnosis.

Why Rewriting Is the Wrong Instinct

When change becomes dangerous, the instinct is to start over. Throw it all out, build it clean, no more inherited mess. It feels decisive. It's usually a mistake.

The reason is uncomfortable but consistent: your working software knows things nobody wrote down. Over the years, it accumulated fixes for edge cases you've forgotten — the customer whose address broke the shipping label, the tax rule that only applies in one country, the payment that occasionally arrives twice and must not be charged twice. None of that is in a document. It's baked into the code that currently works.

A rewrite starts without any of that knowledge and has to rediscover it — the hard way, through real failures, with real customers. Meanwhile, your business keeps running on the old system, which still needs maintenance and still breaks, while the new one consumes budget and ships nothing customers can use. The common ending is a replacement that arrives late, missing features the old system had, and that the next team will describe as "the legacy system" within two years.

Rewrites can be justified. But "it's old" and "it's hard to work in" are not the justifications — those describe most software that has ever earned money.

slug="rescue-projects"
text="If change has become dangerous, you usually don't need a rewrite — you need someone to read the system carefully and make it safe to change again. That's the work I take on, and I'll tell you honestly if a rewrite really is the answer."
/>

What Modernization Actually Means (When It's Worth It)

Modernization done well is rarely a demolition. It's making a working system safe to change again — and most of that work is invisible to your customers, which is exactly why it gets skipped until it's a crisis.

In practice it looks like this. Someone reads the system carefully and writes down what it actually does, so the knowledge lives in more than one head. They add a safety net that catches breakage before it reaches customers, so a change to checkout can't silently break invoicing without someone being warned. They add visibility, so when something goes wrong at 2am, you find out before your customers do. And where one specific part is genuinely beyond saving, they replace that part gradually — building the new alongside the old and switching over piece by piece — instead of betting the whole business on a big-bang cutover.

The result you're paying for isn't "modern technology." It's the ability to change your own software again — quickly, cheaply, and without fear. That's the asset that got lost, and that's the asset worth buying back.

When Modernizing Is Genuinely Worth It

There are real cases where the investment pays for itself. They're rarer than the sales pitch suggests, but they exist:

The technology is genuinely dead, not just old. Not "an older version" — abandoned. No security updates, no way to hire anyone who knows it, constant workarounds just to keep it alive. At that point the cost of keeping it running exceeds the cost of replacing it, and the security exposure alone can force your hand.
What your business does has fundamentally changed. If you've pivoted, acquired another company, or moved from serving consumers to serving other businesses, the old system may have been built for a company that no longer exists. When every new feature is a fight against how the software was originally shaped, that's a real reason — but notice it's a business reason, not a code-quality one.
The system is actively costing you money you can count. Not vague frustration — actual, countable losses. Support hours spent on the same recurring failure. Orders lost when it goes down. A developer's time consumed by workarounds instead of new work. When you can put a monthly number on what the current situation costs, and that number is larger than the cost of fixing it, the decision makes itself.

That last one is the honest test. If you can't name what the current situation is costing you in euros, you don't yet have a business case for spending euros to change it. You have a feeling. Feelings are worth listening to — they're often the first signal that something's wrong — but they're not yet a decision.

When to Leave It Alone

This is the part most articles on the subject skip, because most are written by people who profit from you saying yes. So I'll say the uncomfortable thing plainly: often the right answer is to do nothing.

Leave your software alone when:

It works, changes are still safe, and it isn't blocking anything. Boring, reliable, and old is not a problem. It's the goal. Don't manufacture a crisis to justify a project.
The pain is real but small. If the annoyance costs you a few hours a month, spending a large sum and months of disruption to remove it is a bad trade. The math has to work, and for small pain it usually doesn't.
You can't yet say what "fixed" looks like. If nobody can describe what the system should do differently, no amount of rebuilding will produce it. That's a clarity problem to solve first — on paper, cheaply — before anyone writes code.
The real problem isn't the software at all. Sometimes "we need to rebuild the system" is standing in for an unresolved business decision — unclear direction, a team that isn't aligned, a strategy that hasn't been made. A rewrite provides the feeling of action while the actual problem waits. That's the most expensive way to avoid a hard conversation.

A rewrite is one of the largest and riskiest bets a company makes with its technology. The default answer should be no, and the burden of proof should sit with whoever wants to say yes.

How to Decide

You don't need to be technical to make the right call. You need to answer three questions honestly.

Can we still change it safely and affordably? If yes, you almost certainly have an asset, not a liability. Age is irrelevant. Leave it alone and spend the money on something that grows the business.

If not, what is that costing us — in euros, per month? Support time, downtime, developer hours spent fighting the system instead of improving it. If you can't count it, get someone to help you count it before you commit to anything. The number is the decision.

Is the software actually the problem? If a clean, safe version of the system existed tomorrow, would you know exactly what to build next? If yes, the technical work is worth investing in. If no, fix the clarity first — that's cheaper, faster, and it might turn out the software was never the real obstacle.

The goal was never modern technology. The goal is a business that can change its own software as fast as it needs to, without fear and without a fortune. Sometimes that means modernizing. Often it means leaving good software alone. The skill — and the honesty — is telling those two apart before you spend a euro.

If your software works but every change has become slow, expensive, and frightening, that's the situation worth a careful look — not a reflexive rebuild. Let's figure out which one you're actually in.

PDF Tamper Detection API for C#: ASP.NET Core Integration Guide

Iurii Rogulia — Mon, 03 Aug 2026 10:00:38 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

PDF fraud is a backend problem, and in enterprise fintech a great deal of that backend runs on .NET. An ASP.NET Core service ingests an uploaded bank statement, a payslip, or a claim packet, writes a row, and hands the document to underwriting — and by the time your controller has returned 201 Created, the document’s claims have already propagated into your business logic. Your KYC provider confirmed the applicant is a real person with a valid identity. It said nothing about whether the PDF they uploaded was edited after the bank generated it. That structural-tampering layer is invisible to identity verification, and the right place to catch it is at ingress: before your service trusts the file, not after.

This guide walks through integrating the PDF tamper detection API into an ASP.NET Core application — from the first curl command to an idiomatic typed HtpbeClient built on IHttpClientFactory, with System.Text.Json record DTOs, configuration-bound options for the API key, polling with backoff, error handling that distinguishes a configuration failure from a transient one, and a small bank-statement gate that decides accept / reject / review. The patterns target .NET 8 (the current LTS) and use minimal APIs, but everything maps cleanly to a controller-based project. Treat the code as a reference architecture — it runs the real request flow against the documented error codes, but you should adapt and harden it for your own traffic profile and threat model. (If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically. Integrating from another stack? See the Java / Spring Boot, Go, Node.js, Python, and Laravel / PHP guides.)

TL;DR

Two API calls, three verdicts: POST /analyze returns a top-level id, then GET /result/{id} returns the flat verdict object whose status is one of intact, modified, or inconclusive.
The minimum integration is a typed HttpClient and two awaited calls. No dependency beyond the framework and System.Text.Json.
Production shape: an HtpbeClient typed client registered with IHttpClientFactory, record DTOs with snake_case naming, a custom exception carrying the status code, and a Polly retry policy that backs off on 5xx and 429 only.
A DocumentGate that maps the three verdicts to an Accept / Reject / Review decision for documents that claim institutional origin.
This is structural PDF tamper and forgery detection — not KYC, not OCR, not AI-text detection. It complements an identity stack; it does not replace one.

Prerequisites

.NET 8 SDK (records, required members, IHttpClientFactory, minimal APIs)
An HTPBE API key (Dashboard → copy key)
Optionally Microsoft.Extensions.Http.Polly for the resilience policy in Step 6 (the framework HttpClient works without it)

Step 1: Test the API with curl

Before writing any C#, confirm your key works. The API uses a two-step flow: POST /analyze submits a PDF URL and returns a check id, then GET /result/{id} retrieves the full verdict. (For a language-agnostic overview of what the API detects, see how PDF tamper detection works.)

Step 1a — submit for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.htpbe.tech/v1/test/clean.pdf"}'

You will receive a flat object with a single field: {"id": "00000000-0000-4000-8000-000000000001"}

Step 1b — retrieve the result:

curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

You will receive a flat JSON object with "status": "intact" and the full set of analysis fields:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "filename": "clean.pdf",
  "status": "intact",
  "origin": { "type": "institutional", "software": null },
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "modification_confidence": "none",
  "has_incremental_updates": false,
  "update_chain_length": 1,
  "signature_removed": false,
  "modifications_after_signature": false,
  "modification_markers": []
}

Step 2: Bind Configuration, Not Constants

Keep the key and base URL out of code. Bind them to a typed options record so they are validated at startup and overridable per environment. The key resolves from configuration — appsettings.json, an environment variable, or a secrets store — never a hard-coded literal.

namespace Htpbe;

public sealed class HtpbeOptions
{
    public const string SectionName = "Htpbe";

    public required string ApiKey { get; init; }
    public string BaseUrl { get; init; } = "https://api.htpbe.tech/v1/";
    public int TimeoutSeconds { get; init; } = 35;
    public int MaxResultPollAttempts { get; init; } = 5;
}

Provide the values in appsettings.json, leaving the key itself empty so it is supplied by an environment variable or user-secret at runtime:

{
  "Htpbe": {
    "ApiKey": "",
    "BaseUrl": "https://api.htpbe.tech/v1/",
    "TimeoutSeconds": 35,
    "MaxResultPollAttempts": 5
  }
}

In development, store the key with dotnet user-secrets set "Htpbe:ApiKey" "htpbe_live_...". In production, set the environment variable Htpbe__ApiKey (the double underscore maps to the nested section). Either way the key never lands in source control. Bind and validate the options in Program.cs so a missing key fails the application at boot, not on the first document that arrives at 2 a.m.:

builder.Services
    .AddOptions<HtpbeOptions>()
    .Bind(builder.Configuration.GetSection(HtpbeOptions.SectionName))
    .Validate(o => !string.IsNullOrWhiteSpace(o.ApiKey),
        "Htpbe:ApiKey is not configured. Set the Htpbe__ApiKey environment variable.")
    .ValidateOnStart();

Step 3: The Result DTO

Model the GET /result/{id} response as C# records. System.Text.Json maps snake_case JSON to PascalCase members when you set JsonNamingPolicy.SnakeCaseLower on the serializer options (available since .NET 8). Reference types stay nullable so “absent” remains distinguishable from a genuine zero, and unknown fields are ignored by default so a newly added API field never breaks deserialization.

using System.Text.Json.Serialization;

namespace Htpbe;

public sealed record AnalysisResult
{
    public required string Id { get; init; }
    public string? Filename { get; init; }
    public long? FileSize { get; init; }
    public int? PageCount { get; init; }

    public string? AlgorithmVersion { get; init; }
    public string? CurrentAlgorithmVersion { get; init; }
    public string? OutdatedWarning { get; init; } // present only on an outdated check

    // Primary verdict: "intact" | "modified" | "inconclusive"
    public required string Status { get; init; }

    // Present only when Status == "inconclusive":
    // "consumer_software_origin" | "online_editor_origin" |
    // "scanned_document" | "unverifiable_metadata"
    public string? StatusReason { get; init; }

    public Origin? Origin { get; init; }

    // "certain" | "high" | "none" | null
    public string? ModificationConfidence { get; init; }

    public string? Creator { get; init; }
    public string? Producer { get; init; }
    public long? CreationDate { get; init; }     // Unix seconds
    public long? ModificationDate { get; init; } // Unix seconds
    public string? PdfVersion { get; init; }

    public bool DateSequenceValid { get; init; }
    public int MetadataCompletenessScore { get; init; }

    public int XrefCount { get; init; }
    public bool HasIncrementalUpdates { get; init; }
    public int UpdateChainLength { get; init; }

    public bool HasDigitalSignature { get; init; }
    public int SignatureCount { get; init; }
    public bool SignatureRemoved { get; init; }
    public bool ModificationsAfterSignature { get; init; }

    public int ObjectCount { get; init; }
    public bool HasJavascript { get; init; }
    public bool HasEmbeddedFiles { get; init; }

    // Stable HTPBE_* marker ids, e.g. ["HTPBE_SIGNATURE_REMOVED"].
    // Empty when Status is "intact" or "inconclusive".
    public IReadOnlyList<string> ModificationMarkers { get; init; } = [];

    [JsonIgnore] public bool IsIntact => Status == "intact";
    [JsonIgnore] public bool IsModified => Status == "modified";
    [JsonIgnore] public bool IsInconclusive => Status == "inconclusive";
}

public sealed record Origin
{
    // "consumer_software" | "institutional" | "unknown" |
    // "online_editor" | "scanned"
    public string? Type { get; init; }
    public string? Software { get; init; }
}

// The /analyze response carries only the check id.
public sealed record AnalyzeResponse
{
    public required string Id { get; init; }
}

Two fields deserve a closer look. StatusReason is populated only when Status is inconclusive, and it carries one of several values — consumer_software_origin, online_editor_origin, scanned_document, and a few more. The difference matters: a scanned document is benign for a user-submitted handwritten form, but a consumer_software_origin on something that claims to be a payslip is the kind of origin you would not expect from a real payroll system — that class covers both consumer apps and freely available HTML-to-PDF renderers, so it is a strong signal to route for review. Branch on the specific reason, not just on the top-level inconclusive.

ModificationMarkers returns stable, machine-readable ids prefixed HTPBE_ — for example HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_POST_SIGNATURE_EDIT, HTPBE_MULTIPLE_REVISION_LAYERS. Branch your integration logic on the id; render the human-readable label from the dictionary published on htpbe.tech/how. These ids are part of the public contract and never change once shipped. The API does not return a numeric risk score — the verdict plus the named markers are the whole signal, by design, so there is no threshold to tune on your side.

A small enum keeps the rest of your codebase from comparing against bare string literals:

namespace Htpbe;

public enum Verdict { Intact, Modified, Inconclusive }

public static class VerdictParser
{
    public static Verdict Parse(string status) => status switch
    {
        "intact" => Verdict.Intact,
        "modified" => Verdict.Modified,
        "inconclusive" => Verdict.Inconclusive,
        _ => throw new ArgumentOutOfRangeException(
            nameof(status), status, "unknown status from HTPBE"),
    };
}

Step 4: A Typed Exception

namespace Htpbe;

public sealed class HtpbeApiException : Exception
{
    public int StatusCode { get; }
    public string Code { get; }                 // machine-readable code from the JSON body
    public int? RetryAfterSeconds { get; }      // parsed from Retry-After on 429; null if absent

    public HtpbeApiException(int statusCode, string code, string message, int? retryAfterSeconds = null)
        : base($"htpbe: {statusCode} {code}: {message}")
    {
        StatusCode = statusCode;
        Code = code;
        RetryAfterSeconds = retryAfterSeconds;
    }

    // Only 5xx and 429 are transient. Every other 4xx is permanent —
    // retrying it burns latency and, for 402, can never succeed until
    // the account is topped up.
    public bool Retryable => StatusCode >= 500 || StatusCode == 429;
}

Step 5: The Typed HttpClient

Here is the complete client. It is a typed HttpClient — registered with IHttpClientFactory in Step 6 — so the factory owns the connection pool and the Authorization header is set once at registration. The client exposes one public method, VerifyAsync, that runs both steps of the flow; a private ParseErrorAsync converts every non-success response into an HtpbeApiException, reading the JSON error body and the Retry-After header in one place.

using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.Extensions.Options;

namespace Htpbe;

public sealed class HtpbeClient
{
    private readonly HttpClient _http;
    private readonly int _maxPollAttempts;

    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
        PropertyNameCaseInsensitive = true,
    };

    public HtpbeClient(HttpClient http, IOptions<HtpbeOptions> options)
    {
        _http = http;
        _maxPollAttempts = options.Value.MaxResultPollAttempts;
    }

    /// <summary>
    /// Submits a PDF URL and returns the full verdict. The two steps are kept
    /// separate on purpose: POST /analyze is the billable, job-creating call,
    /// GET /result/{id} is a free read. The resilience policy (Step 6) wraps
    /// the whole client, but only transient failures are retried — a permanent
    /// 402 short-circuits immediately.
    /// </summary>
    public async Task<AnalysisResult> VerifyAsync(
        string pdfUrl, string? originalFilename = null, CancellationToken ct = default)
    {
        var id = await SubmitAnalysisAsync(pdfUrl, originalFilename, ct);
        return await GetResultAsync(id, ct);
    }

    private async Task<string> SubmitAnalysisAsync(
        string pdfUrl, string? originalFilename, CancellationToken ct)
    {
        // The API accepts a JSON body with the PDF URL; original_filename is optional.
        var body = originalFilename is null
            ? new Dictionary<string, string> { ["url"] = pdfUrl }
            : new Dictionary<string, string> { ["url"] = pdfUrl, ["original_filename"] = originalFilename };

        using var response = await _http.PostAsJsonAsync("analyze", body, JsonOptions, ct);

        if (!response.IsSuccessStatusCode)
            throw await ParseErrorAsync(response, ct);

        var payload = await response.Content.ReadFromJsonAsync<AnalyzeResponse>(JsonOptions, ct);
        if (payload is null || string.IsNullOrEmpty(payload.Id))
            throw new HtpbeApiException(502, "BAD_RESPONSE", "analyze response missing id");

        return payload.Id;
    }

    private async Task<AnalysisResult> GetResultAsync(string id, CancellationToken ct)
    {
        // POST /analyze runs the analysis synchronously, so the result is normally
        // ready on the first GET. The bounded poll below is defensive: it tolerates
        // a brief replication lag and re-reads on a transient 404 before giving up.
        HtpbeApiException? lastError = null;

        for (var attempt = 1; attempt <= _maxPollAttempts; attempt++)
        {
            using var response = await _http.GetAsync($"result/{id}", ct);

            if (response.IsSuccessStatusCode)
            {
                var result = await response.Content.ReadFromJsonAsync<AnalysisResult>(JsonOptions, ct);
                return result ?? throw new HtpbeApiException(502, "BAD_RESPONSE", "empty result body");
            }

            lastError = await ParseErrorAsync(response, ct);

            // Only a 404 is worth re-reading (the row may not be visible yet).
            // Every other error is terminal — surface it without burning attempts.
            if (response.StatusCode != HttpStatusCode.NotFound)
                throw lastError;

            await Task.Delay(TimeSpan.FromMilliseconds(300 * attempt), ct);
        }

        throw lastError ?? new HtpbeApiException(504, "RESULT_TIMEOUT", "result not ready after polling");
    }

    private static async Task<HtpbeApiException> ParseErrorAsync(
        HttpResponseMessage response, CancellationToken ct)
    {
        var statusCode = (int)response.StatusCode;
        var code = "UNKNOWN";
        var message = response.ReasonPhrase ?? statusCode.ToString();

        try
        {
            var error = await response.Content.ReadFromJsonAsync<ErrorBody>(JsonOptions, ct);
            if (error is not null)
            {
                code = error.Code ?? code;
                message = error.Error ?? message;
            }
        }
        catch (JsonException)
        {
            // body was not JSON — keep the status-derived defaults
        }

        message = statusCode switch
        {
            401 => "invalid API key — check Htpbe:ApiKey",
            402 => "no credits available for this key — top up or subscribe",
            403 => "test key sent to a live URL, or vice versa",
            413 => "PDF exceeds the 10 MB size limit",
            422 => "the URL did not return a valid PDF file",
            _ => message,
        };

        int? retryAfter = null;
        if (statusCode == 429 && response.Headers.RetryAfter is { } ra)
            retryAfter = ParseRetryAfter(ra);

        return new HtpbeApiException(statusCode, code, message, retryAfter);
    }

    // Handles both the delta-seconds form and the HTTP-date form,
    // clamped to [1, 600]. Returns null when neither is present.
    private static int? ParseRetryAfter(System.Net.Http.Headers.RetryConditionHeaderValue ra)
    {
        if (ra.Delta is { } delta)
            return Math.Clamp((int)delta.TotalSeconds, 1, 600);
        if (ra.Date is { } date)
            return Math.Clamp((int)(date - DateTimeOffset.UtcNow).TotalSeconds, 1, 600);
        return null;
    }

    private sealed record ErrorBody
    {
        public string? Error { get; init; }
        public string? Code { get; init; }
    }
}

Two status codes deserve explicit handling in your own code:

402 (Payment Required) — the key has no credit source left. Credits are universal: a subscription’s monthly quota, a one-time top-up batch, and the welcome credits all draw from one pool. A 402 means all three are exhausted (or there is no active plan on a live key). HtpbeApiException.Retryable returns false for it — surface it to your billing path rather than retrying, because retrying fails identically until the account is topped up at the pricing page.
429 (Too Many Requests) — this is server-wide concurrency, not per-key rate limiting. The response carries a Retry-After header, which ParseRetryAfter reads (both delta-seconds and HTTP-date forms, clamped to [1, 600]) and stashes on the exception. Your retry policy reads that value before falling back to exponential backoff.

Step 6: Register the Client and Retry on Transient Failures Only

Register HtpbeClient as a typed client. IHttpClientFactory manages the underlying handler pool, sets the base address and default headers once, and lets you attach a resilience policy. The policy retries only on the transient codes — 5xx and 429 — and never on the permanent 4xx codes like 401, 402, or 422, where retrying would burn latency and credits without ever succeeding.

using System.Net;
using Microsoft.Extensions.Options;
using Polly;
using Polly.Extensions.Http;

// In Program.cs

builder.Services
    .AddHttpClient<HtpbeClient>((sp, http) =>
    {
        var opts = sp.GetRequiredService<IOptions<HtpbeOptions>>().Value;
        http.BaseAddress = new Uri(opts.BaseUrl);
        http.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", opts.ApiKey);
        http.DefaultRequestHeaders.Accept.Add(
            new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
        http.Timeout = TimeSpan.FromSeconds(opts.TimeoutSeconds);
    })
    .AddPolicyHandler(TransientRetryPolicy());

static IAsyncPolicy<HttpResponseMessage> TransientRetryPolicy() =>
    HttpPolicyExtensions
        // Network failures and 5xx are handled by HandleTransientHttpError;
        // add 429 explicitly so a capacity signal also backs off and retries.
        .HandleTransientHttpError()
        .OrResult(r => r.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(
            retryCount: 3,
            sleepDurationProvider: (attempt, response, _) =>
            {
                // Honour a server-supplied Retry-After when present (429 capacity),
                // otherwise fall back to exponential backoff: 1s, 2s, 4s.
                var retryAfter = response.Result?.Headers.RetryAfter?.Delta;
                return retryAfter ?? TimeSpan.FromSeconds(Math.Pow(2, attempt - 1));
            },
            onRetryAsync: (_, _, _, _) => Task.CompletedTask);

If you would rather not take a Polly dependency, the bounded poll inside GetResultAsync already handles the most common transient case (a result that is not yet visible), and you can wrap VerifyAsync in a small for loop that re-throws when HtpbeApiException.Retryable is false. For most integrations the Polly handler is the cleanest fit, because it sits at the HttpClient layer and applies to both the submit and the read uniformly.

Step 7: The Bank-Statement Gate

The client returns facts. Turning those facts into an Accept / Reject / Review decision is a policy choice that depends on what the document claims to be. A bank statement, a payslip, or a diploma claims institutional origin, so anything other than intact should stop the automated path. A user-generated form is held to a looser standard.

namespace Htpbe;

public enum Decision { Accept, Reject, Review }

public static class DocumentGate
{
    /// <summary>
    /// Maps a verdict to a decision for documents that claim institutional
    /// origin (bank statements, payslips, diplomas). For these, "inconclusive"
    /// is treated as strictly as "modified": a document that should have come
    /// from a bank's own system but looks like it was built in Word does not
    /// get the benefit of the doubt.
    /// </summary>
    public static Decision ForInstitutional(AnalysisResult r) =>
        VerdictParser.Parse(r.Status) switch
        {
            Verdict.Modified => Decision.Reject,
            // A bank statement that comes back inconclusive should not be
            // auto-accepted: it typically came from consumer software rather
            // than a bank's own system — a signal to route for review, not
            // proof of tampering. Send it to a human.
            Verdict.Inconclusive => Decision.Review,
            Verdict.Intact => Decision.Accept,
            _ => Decision.Review,
        };
}

Wire the client and the gate into a minimal-API endpoint that accepts a JSON body with a reachable URL. The handler runs the check before any business logic touches the file:

// In Program.cs, after building the app

app.MapPost("/api/documents/verify", async (
    VerifyRequest req, HtpbeClient client, CancellationToken ct) =>
{
    if (string.IsNullOrWhiteSpace(req.DocumentUrl))
        return Results.BadRequest(new { error = "documentUrl is required" });

    AnalysisResult result;
    try
    {
        result = await client.VerifyAsync(req.DocumentUrl, req.OriginalFilename, ct);
    }
    catch (HtpbeApiException e)
    {
        return MapApiError(e);
    }

    return DocumentGate.ForInstitutional(result) switch
    {
        Decision.Reject => Results.UnprocessableEntity(new
        {
            decision = "reject",
            reason = "document modified after creation",
            modification_markers = result.ModificationMarkers,
        }),
        Decision.Review => Results.Accepted(value: new
        {
            decision = "review",
            status_reason = result.StatusReason,
        }),
        _ => Results.Ok(new { decision = "accept", check_id = result.Id }),
    };
});

static IResult MapApiError(HtpbeApiException e) => e.StatusCode switch
{
    // Configuration / billing errors — never leak the cause to the caller.
    401 or 402 => Results.Problem(
        "verification temporarily unavailable", statusCode: 503),
    422 => Results.UnprocessableEntity(
        new { error = "the URL did not return a valid PDF" }),
    413 => Results.Problem("PDF must be under 10 MB", statusCode: 413),
    _ => Results.Problem("verification failed", statusCode: 502),
};

public sealed record VerifyRequest(string DocumentUrl, string? OriginalFilename);

Step 8: Giving the API a Reachable URL

The API does not accept file uploads — it downloads the PDF from a URL you supply, so the file must be publicly reachable for the few seconds the analysis takes. The cleanest pattern is a short-lived presigned URL from your object store: you never expose the bucket, the link expires in minutes, and passing originalFilename keeps the audit trail readable instead of showing an opaque storage key.

// Store the upload privately, mint a 5-minute presigned GET URL, verify.
var key = $"incoming/{Guid.NewGuid()}.pdf";

await s3.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = key,
    InputStream = pdfStream,
    ContentType = "application/pdf",
}, ct);

var presignedUrl = await s3.GetPreSignedURLAsync(new GetPreSignedUrlRequest
{
    BucketName = bucket,
    Key = key,
    Expires = DateTime.UtcNow.AddMinutes(5),
    Verb = HttpVerb.GET,
});

var result = await client.VerifyAsync(presignedUrl, originalFilename, ct);

The same pattern works with Azure Blob Storage (a SAS token via BlobClient.GenerateSasUri), Google Cloud Storage (UrlSigner), or Cloudflare R2 (S3-compatible — reuse the AWS SDK with the R2 endpoint). One security note: the API fetches whatever URL you give it, so if a URL ever comes from untrusted input (a user-pasted link, a webhook payload), validate that it resolves to a public host first — reject localhost, 169.254.169.254 (cloud metadata), and the RFC 1918 private ranges to close the SSRF surface. When you mint the URL yourself from a private bucket the risk is minimal, but the validation belongs in the request flow either way.

Step 9: Testing Without Burning Quota

Every plan includes a test API key (prefix htpbe_test_) that accepts only mock URLs of the form https://api.htpbe.tech/v1/test/{filename}.pdf and returns deterministic responses — like Stripe test cards, with no quota cost. Point an integration test at these fixtures to cover every branch of the gate. With WebApplicationFactory<Program> you exercise the real HtpbeClient, configured with the test key:

using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.Extensions.DependencyInjection;
using Xunit;

public sealed class HtpbeClientTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HtpbeClient _client;

    public HtpbeClientTests(WebApplicationFactory<Program> factory)
    {
        var configured = factory.WithWebHostBuilder(builder =>
            builder.UseSetting("Htpbe:ApiKey",
                Environment.GetEnvironmentVariable("HTPBE_TEST_API_KEY")!));
        _client = configured.Services.GetRequiredService<HtpbeClient>();
    }

    [Fact]
    public async Task CleanDocumentReturnsIntact()
    {
        var r = await _client.VerifyAsync("https://api.htpbe.tech/v1/test/clean.pdf");

        Assert.Equal("intact", r.Status);
        Assert.Empty(r.ModificationMarkers);
        Assert.Equal(Decision.Accept, DocumentGate.ForInstitutional(r));
    }

    [Fact]
    public async Task SignatureRemovedIsRejected()
    {
        var r = await _client.VerifyAsync("https://api.htpbe.tech/v1/test/signature-removed.pdf");

        Assert.Equal("modified", r.Status);
        Assert.True(r.SignatureRemoved);
        Assert.Equal(Decision.Reject, DocumentGate.ForInstitutional(r));
    }

    [Fact]
    public async Task InconclusiveIsRoutedToReview()
    {
        var r = await _client.VerifyAsync("https://api.htpbe.tech/v1/test/inconclusive.pdf");

        Assert.Equal("inconclusive", r.Status);
        Assert.NotNull(r.StatusReason);
        Assert.Equal(Decision.Review, DocumentGate.ForInstitutional(r));
    }
}

Useful fixtures: clean.pdf → intact, signature-removed.pdf → modified, dates-mismatch.pdf → modified, and inconclusive.pdf → inconclusive. For pure unit tests of the endpoint and gate without any network, inject a fake HttpMessageHandler into the HtpbeClient and return canned JSON, or test DocumentGate.ForInstitutional directly against a hand-built AnalysisResult. Keep test and live keys in separate configuration sources and never commit either.

For audit dashboards, GET /api/v1/checks returns a paginated list of every result for your key — filter by status and limit (/checks?status=modified&limit=50, same Authorization header). When you reach your monthly quota, further requests return 402 PAYMENT_REQUIRED until it resets — add a one-time credit pack or move to a higher tier to keep going, and handle the 402 so a quota boundary never silently drops a check.

What the Verdicts Mean

The whole signal is three verdicts and a list of named markers. Encoding them correctly in your DocumentGate matters more than any other choice in the integration:

intact — no post-creation modification was detected and the origin looks institutional. Safe to accept on the automated path.
modified — forensic evidence of an edit after the document was created. The modification_markers array names the signal: HTPBE_DATES_DISAGREE for inconsistent internal timestamps, HTPBE_SIGNATURE_REMOVED for a stripped digital signature, HTPBE_POST_SIGNATURE_EDIT for changes made after signing, HTPBE_MULTIPLE_REVISION_LAYERS for a document saved repeatedly after creation. Reject, or route to fraud review.
inconclusive — the document was built with consumer software, an online editor, an HTML renderer, or a scanner, so there is no institutional “original” to verify integrity against. This is not a failure and not a clean pass — it is a routing signal. For a document that should have come from an institution (a bank statement, a payslip), inconclusive means it did not, which is exactly why DocumentGate.ForInstitutional routes it to a human reviewer.

What This Does Not Catch

Structural analysis has honest limits, and an ASP.NET Core service making automated decisions should encode them rather than overstate the verdict:

Content fabricated in one pass. If someone opens Word, types a false salary, and exports once, the file was never modified after creation — it is structurally consistent. The fraud happened at authorship, not at the byte level. This is exactly why a payslip from a consumer tool tends to return inconclusive rather than intact: the analysis cannot vouch for a document anyone could have produced from scratch.
Born-synthetic forgeries. A fake document generated programmatically with a valid-looking account number and a real logo — never derived from a genuine original — has no post-creation edit to detect. Catching that is a content-verification problem (does this account number exist, does this employer match payroll records), a different product category from structural tamper detection.
Documents rebuilt from scratch in the original’s software. A determined attacker who recreates a document in the same institutional tool and matches the metadata leaves few structural signals. This is rare and high-effort, but possible.
Encrypted or password-protected PDFs. The service cannot parse a file it cannot open; remove the password before submitting.

Decisions Before You Ship

The integration surface is intentionally small: one POST, one GET, three verdicts, the typed exception above. The complexity lives on the .NET side, and two choices matter most:

Where verification runs. Synchronous inside the request handler gives the caller an immediate decision but blocks for a few seconds; a background IHostedService or a message-driven consumer (Azure Service Bus, RabbitMQ) returns instantly and defers the verdict. Sync suits low-volume B2B onboarding; async suits high-volume portals. Because the call is fully async/await and the analysis takes 2–5 seconds, the synchronous path is cheap enough for most onboarding flows.
inconclusive routing. For documents that claim institutional origin (bank statements, diplomas, payslips), treat inconclusive with the same caution as modified and route to human review — that is what DocumentGate.ForInstitutional encodes. For genuinely user-generated content it may be acceptable as-is, so you may want a second gate with a looser policy.

DEV Community: Iurii Rogulia

When a Human Is Your Integration

The Cost You Don't Get Billed For

Where the Errors Live

What "Connected" Actually Buys You

When Manual Is Genuinely Fine

How to Find Yours

PDF Generator Fingerprints: What Software Made This File (And Where It Lies)

The two fields everyone looks at first

Why generators are distinguishable in the first place

A field guide to the major generators

iText (Java / .NET)

Apache PDFBox (Java)

ReportLab (Python)

Apache FOP

wkhtmltopdf and Puppeteer / headless Chrome

LibreOffice and Microsoft Office

Ghostscript

Born institutional vs. rebuilt by a consumer editor

What a structural analysis actually reads

The verdict you get back

Reading the fingerprint over the API

What this approach cannot do — and we will not pretend otherwise

Who should be reading these signals

Build vs Buy: VAT Validation via VIES or an API

Build vs Buy: Should You Call VIES Yourself or Use an API?

The "we'll just call VIES" assumption

What building it yourself really includes

The SOAP client and parsing

Downtime and retries

Caching without breaking compliance

Audit evidence you have to persist

National-registry fallback and enrichment

Ongoing maintenance

When building in-house is the right call

When buying wins

A simple decision checklist

FAQ

Can I just call VIES directly for free?

What's the hardest part of building VAT validation in-house?

Is a VAT validation API worth it for low volume?

Does an API replace VIES?

Try the buy side before you build it

PDF Integrity Report: July 2026

What the Denominator Is, Before Any Number

The Shape of the Verdicts

Source & Origin Mix

Signals That Moved

Incremental Updates: Two Rates, Kept Apart

Representative Cases

Algorithm Development

PDF Version Landscape

Summary

Preventing Overselling: Inventory Locks Under Concurrent Checkouts

When You Don't Need Any of This

The Race, Precisely

Fix One: Never Decrement From a Read Value

Fix Two: Reservations vs Hard Decrements

Reserving a Multi-Line Cart Atomically

The Deadlock You Will Otherwise Hit

The Payment-Confirmation Window

Where This Still Bites

How Lenders Verify Bank Statements — and the Forgery Layer They Miss

How Lenders Verify Bank Statements Today

The One Thing the Checklist Doesn’t Verify

What Open Banking Solves, and What It Doesn’t

The Missing Layer: Structural File Forensics

The three verdicts

What it actually catches — in plain terms

What inconclusive Means in a Lending Context

Honest Limits — What This Layer Cannot Catch

Wiring It Into Your Intake

Who Should Add This Layer

How to Bulk Re-Validate Customer VAT IDs

How to Bulk Re-Validate Your Customer VAT IDs (and Keep Them Fresh)

Why a stored VAT ID goes stale

Step 1 — dedupe and format-filter before you call anything

Step 2 — batch the base at a sane throughput

Step 3 — surviving a VIES outage mid-run

Step 4 — recording what changed (and what to do about it)

What `inconclusive` Means in a Lending Context