DEV Community: Iurii Rogulia

PDF Tamper Detection API for Node.js: Complete Integration Guide

Iurii Rogulia — Fri, 12 Jun 2026 10:00:37 +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. The fraud happens before your business logic runs — at the moment a user uploads a document your system treats as trustworthy. By the time a human reviewer looks at a bank statement, invoice, or diploma, the data from that document may already have influenced a decision.

This guide walks through integrating the PDF tamper detection API into a Node.js application: from the first curl command to a production-ready TypeScript client with retry logic, typed errors, and an Express middleware layer. All code is complete and working — no pseudocode. (If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically. If you are using Python instead of Node.js, see the Python integration guide.)

Prerequisites

Node.js 18+ (for native fetch)
An HTPBE API key (sign up → Dashboard → copy key)
TypeScript 5.0+ (optional but recommended)

Step 1: Test the API with curl

Before writing any code, 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: {"id": "some-uuid-here"}

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 all analysis fields. This confirms authentication works and your network can reach the API.

The URL https://api.htpbe.tech/v1/test/clean.pdf is a test mock URL — it returns a predictable response without consuming quota. We will cover all available test URLs in the testing section below.

Step 2: Define Types

Start with the TypeScript interfaces that match the API response structure:

// POST /analyze response — just the check ID
export interface HTPBEAnalyzeResponse {
  id: string;
}

// GET /result/{id} response — flat object with all analysis fields
export interface HTPBEResult {
  id: string;
  filename: string;
  check_date: number | null;
  file_size: number;
  page_count: number;

  // Algorithm version tracking
  algorithm_version: string;
  current_algorithm_version: string;
  outdated_warning?: string;

  // Primary verdict
  status: 'intact' | 'modified' | 'inconclusive';
  // Only present when status === 'inconclusive' — tells you WHY
  status_reason?:
    | 'consumer_software_origin'
    | 'online_editor_origin'
    | 'scanned_document'
    | 'html_renderer_origin';
  origin: {
    type: 'consumer_software' | 'institutional' | 'unknown' | 'online_editor' | 'scanned';
    software: string | null;
  };

  // Detection results
  modification_confidence: 'certain' | 'high' | 'none' | null;

  // Metadata
  creator: string | null;
  producer: string | null;
  creation_date: number | null; // Unix timestamp
  modification_date: number | null; // Unix timestamp
  pdf_version: string | null;

  // Metadata analysis
  date_sequence_valid: boolean;
  metadata_completeness_score: number;

  // Structure analysis
  xref_count: number;
  has_incremental_updates: boolean;
  update_chain_length: number;

  // Signature analysis
  has_digital_signature: boolean;
  signature_count: number;
  signature_removed: boolean;
  modifications_after_signature: boolean;

  // Content analysis
  object_count: number;
  has_javascript: boolean;
  has_embedded_files: boolean;

  // Findings — stable HTPBE_* marker ids, e.g. ["HTPBE_SIGNATURE_REMOVED"]
  modification_markers: string[];
}

// GET /checks response item — summary with fewer fields than full result
export interface HTPBECheckSummary {
  id: string;
  filename: string;
  check_date: number | null;
  status: 'intact' | 'modified' | 'inconclusive';
  metadata_completeness_score: number;
  creator: string | null;
  producer: string | null;
  file_size: number;
  page_count: number;
  pdf_version: string | null;
  creation_date: number | null;
  modification_date: number | null;
  has_javascript: boolean;
  has_digital_signature: boolean;
  has_embedded_files: boolean;
  has_incremental_updates: boolean;
  update_chain_length: number;
  object_count: number;
}

export interface HTPBEErrorResponse {
  error: string;
  code: string;
  details?: string;
}

Two fields deserve a closer look. status_reason is only present when status is inconclusive, and it has four possible values — not one. The difference matters: scanned_document and consumer_software_origin are benign for user-generated content, but html_renderer_origin (a tool like wkhtmltopdf) is used by both legitimate payroll systems and forgery operations producing fake payslips from scratch. Branch on the specific reason, not just on inconclusive.

modification_markers returns stable machine-readable ids prefixed HTPBE_ — for example HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_MULTIPLE_REVISION_LAYERS, HTPBE_POST_SIGNATURE_EDIT. 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.

Step 3: Build the Client Class

Here is a complete HTPBEClient implementation with exponential backoff retry logic, timeout handling, and typed error responses. The client handles the two-step flow internally — callers call verify() and get back the full result:

export class HTPBEError extends Error {
  constructor(
    message: string,
    public readonly statusCode: number,
    public readonly code: string,
  ) {
    super(message);
    this.name = 'HTPBEError';
  }
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export class HTPBEClient {
  private readonly apiKey: string;
  private readonly baseUrl = 'https://api.htpbe.tech/v1';
  private readonly timeoutMs: number;

  constructor(apiKey: string, options: { timeoutMs?: number } = {}) {
    if (!apiKey) throw new Error('HTPBE API key is required');
    this.apiKey = apiKey;
    this.timeoutMs = options.timeoutMs ?? 30_000;
  }

  async verify(pdfUrl: string, retries = 3): Promise<HTPBEResult> {
    let lastError: HTPBEError | null = null;

    for (let attempt = 0; attempt < retries; attempt++) {
      if (attempt > 0) {
        // Exponential backoff: 1s, 2s, 4s
        await sleep(Math.pow(2, attempt - 1) * 1_000);
      }

      try {
        // Step 1: submit the PDF URL, get back a check ID
        const { id } = await this.submitAnalysis(pdfUrl);
        // Step 2: retrieve the full flat result
        return await this.getResult(id);
      } catch (err) {
        if (!(err instanceof HTPBEError)) throw err;

        // Retry on 5xx and on 429 (server at capacity); never on other 4xx.
        // A 402/401/422 will fail identically on retry.
        if (err.statusCode < 500 && err.statusCode !== 429) throw err;

        lastError = err;
      }
    }

    throw lastError!;
  }

  private async submitAnalysis(pdfUrl: string): Promise<HTPBEAnalyzeResponse> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeoutMs);

    let response: Response;

    try {
      response = await fetch(`${this.baseUrl}/analyze`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ url: pdfUrl }),
        signal: controller.signal,
      });
    } catch (err) {
      if ((err as Error).name === 'AbortError') {
        throw new HTPBEError(
          `Request timed out after ${this.timeoutMs}ms`,
          408,
          'TIMEOUT',
        );
      }
      throw err;
    } finally {
      clearTimeout(timer);
    }

    if (!response.ok) {
      await this.handleErrorResponse(response);
    }

    return response.json() as Promise<HTPBEAnalyzeResponse>;
  }

  private async getResult(id: string): Promise<HTPBEResult> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeoutMs);

    let response: Response;

    try {
      response = await fetch(`${this.baseUrl}/result/${id}`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
        signal: controller.signal,
      });
    } catch (err) {
      if ((err as Error).name === 'AbortError') {
        throw new HTPBEError(
          `Request timed out after ${this.timeoutMs}ms`,
          408,
          'TIMEOUT',
        );
      }
      throw err;
    } finally {
      clearTimeout(timer);
    }

    if (!response.ok) {
      await this.handleErrorResponse(response);
    }

    return response.json() as Promise<HTPBEResult>;
  }

  private async handleErrorResponse(response: Response): Promise<never> {
    let body: HTPBEErrorResponse = { error: response.statusText, code: 'UNKNOWN' };

    try {
      body = (await response.json()) as HTPBEErrorResponse;
    } catch {
      // Body is not JSON — use statusText
    }

    switch (response.status) {
      case 400:
        throw new HTPBEError(
          `Bad request: ${body.error}`,
          400,
          'BAD_REQUEST',
        );
      case 401:
        throw new HTPBEError(
          'Invalid API key. Check your HTPBE_API_KEY environment variable.',
          401,
          'UNAUTHORIZED',
        );
      case 402:
        // No credit source: out of monthly quota, no paid batch, no welcome
        // credits — or no active plan on a live key. Top up or subscribe.
        throw new HTPBEError(
          'Payment required. No credits available for this key. See htpbe.tech/pricing.',
          402,
          'PAYMENT_REQUIRED',
        );
      case 403:
        throw new HTPBEError(
          'Access forbidden. Your API key may not have permission for this resource.',
          403,
          'FORBIDDEN',
        );
      case 404:
        throw new HTPBEError(
          'Check not found.',
          404,
          'NOT_FOUND',
        );
      case 413:
        throw new HTPBEError(
          'PDF exceeds the 10 MB size limit.',
          413,
          'FILE_TOO_LARGE',
        );
      case 422:
        throw new HTPBEError(
          'The URL did not return a valid PDF file.',
          422,
          'INVALID_PDF',
        );
      case 429:
        // Server-wide capacity, not per-key rate limiting. Respect Retry-After.
        throw new HTPBEError(
          'Server is at analysis capacity. Retry after the Retry-After interval.',
          429,
          'SERVER_AT_CAPACITY',
        );
      case 500:
        throw new HTPBEError(
          'HTPBE server error. The request will be retried.',
          500,
          'SERVER_ERROR',
        );
      default:
        throw new HTPBEError(
          `Unexpected error ${response.status}: ${body.error}`,
          response.status,
          body.code ?? 'UNKNOWN',
        );
    }
  }
}

The retry logic only fires on 5xx responses. A 401 means your key is wrong — retrying it would not help. 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). Surface this to your billing logic rather than retrying — retrying will fail identically until the account is topped up at the pricing page.
429 SERVER_AT_CAPACITY — this is server-wide concurrency, not per-key rate limiting. The response carries a Retry-After header (in seconds). Wait that long, then retry the same request. The retry loop below treats 429 like a transient failure, but reading Retry-After instead of fixed backoff is more polite under sustained load.

Step 4: Production Integration Pattern

The typical flow in any backend application that accepts document uploads:

User uploads PDF to your backend
You store it in S3, GCS, Vercel Blob, or similar — getting a publicly accessible URL
You call the HTPBE API with that URL
You route the request based on the verdict

import { HTPBEClient, HTPBEResult } from './htpbe-client';

// Placeholder — replace with your actual storage upload logic
async function uploadToStorage(file: Buffer, filename: string): Promise<string> {
  // Returns a publicly accessible URL, e.g. from S3 presigned URL or Vercel Blob
  throw new Error('Implement uploadToStorage for your storage provider');
}

type DocumentAction = 'accept' | 'reject' | 'manual_review';

interface DocumentVerificationResult {
  action: DocumentAction;
  result: HTPBEResult;
}

async function handleDocumentUpload(
  file: Buffer,
  filename: string,
): Promise<DocumentVerificationResult> {
  const url = await uploadToStorage(file, filename);

  const client = new HTPBEClient(process.env.HTPBE_API_KEY!);
  const result = await client.verify(url);

  switch (result.status) {
    case 'intact':
      return { action: 'accept', result };

    case 'modified':
      return { action: 'reject', result };

    case 'inconclusive':
      // Consumer software origin — flag for manual review
      return { action: 'manual_review', result };
  }
}

The inconclusive verdict means the document was created with consumer software, an online editor, an HTML renderer, or a scanner rather than institutional document management software. For a deeper explanation, see what “inconclusive” really means. For documents that claim institutional origin — bank statements, diplomas, contracts — inconclusive warrants the same treatment as modified: do not accept automatically, route to a human reviewer.

Step 4b: 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 live somewhere publicly reachable for the duration of the analysis (typically 2–5 seconds). The cleanest pattern is a short-lived presigned URL from your object store. You never expose the bucket, and the link expires minutes later.

Here is the full round-trip with AWS S3: store the upload, mint a presigned GET URL valid for five minutes, hand it to the client, then let the link expire.

import {
  S3Client,
  PutObjectCommand,
  GetObjectCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { randomUUID } from 'node:crypto';
import { HTPBEClient, HTPBEResult } from './htpbe-client';

const s3 = new S3Client({ region: process.env.AWS_REGION });
const htpbe = new HTPBEClient(process.env.HTPBE_API_KEY!);
const BUCKET = process.env.UPLOAD_BUCKET!;

export async function verifyUploadedPdf(
  file: Buffer,
  originalFilename: string,
): Promise<HTPBEResult> {
  const key = `incoming/${randomUUID()}.pdf`;

  // 1. Store the upload privately — no public ACL needed.
  await s3.send(
    new PutObjectCommand({
      Bucket: BUCKET,
      Key: key,
      Body: file,
      ContentType: 'application/pdf',
    }),
  );

  // 2. Mint a presigned GET URL valid for 5 minutes.
  const presignedUrl = await getSignedUrl(
    s3,
    new GetObjectCommand({ Bucket: BUCKET, Key: key }),
    { expiresIn: 300 },
  );

  // 3. Hand the temporary URL to the API. The original filename is
  //    preserved in the result instead of the opaque UUID key.
  return htpbe.verify(presignedUrl);
}

The original_filename parameter on POST /analyze is worth setting whenever your storage key is an opaque UUID like the one above — without it, the result’s filename field is derived from the last URL segment (a1b2c3d4.pdf), which is useless in an audit trail. Pass the human-readable name and it is stored and returned instead. To use it, extend the client’s submitAnalysis body to JSON.stringify({ url: pdfUrl, original_filename: originalFilename }).

The same pattern works with Google Cloud Storage (getSignedUrl on a File), Cloudflare R2 (S3-compatible — reuse the snippet above with the R2 endpoint), or Vercel Blob (already public, so skip the presigning step).

A Note on Synchronous Analysis and Webhooks

The API runs analysis synchronously. POST /analyze blocks until the verdict is computed, then returns the check ID; the response also carries a Location header pointing at the full result URL. There is no job queue to poll and no webhook callback to register — by the time analyze returns, the result is already retrievable from GET /result/{id}. The verify() method above chains both calls, so a single await gives you the full verdict.

If your own architecture is event-driven, wrap verify() in your job runner (BullMQ, a Lambda, a queue consumer) and emit your own internal webhook once the verdict lands. The detection call itself is a plain request/response — treat it as one step inside your worker, not as an external async service you wait on.

Step 5: Express Middleware

If you are using Express, the cleanest pattern is a middleware that runs before your upload handler and attaches the detection result to the request object:

import { Request, Response, NextFunction } from 'express';
import { HTPBEClient, HTPBEError, HTPBEResult } from './htpbe-client';

// Extend Express Request type
declare global {
  namespace Express {
    interface Request {
      documentVerification?: HTPBEResult;
    }
  }
}

const htpbeClient = new HTPBEClient(process.env.HTPBE_API_KEY!);

export async function verifyDocument(
  req: Request,
  res: Response,
  next: NextFunction,
): Promise<void> {
  const { documentUrl } = req.body as { documentUrl?: string };

  if (!documentUrl) {
    res.status(400).json({ error: 'documentUrl is required' });
    return;
  }

  try {
    const result = await htpbeClient.verify(documentUrl);
    req.documentVerification = result;
    next();
  } catch (err) {
    if (err instanceof HTPBEError) {
      if (err.code === 'UNAUTHORIZED') {
        // Configuration error — do not expose key details to client
        console.error('HTPBE API key is invalid or missing');
        res.status(500).json({ error: 'Document verification service misconfigured' });
        return;
      }
      if (err.code === 'INVALID_PDF') {
        res.status(422).json({ error: 'The provided URL is not a valid PDF' });
        return;
      }
      if (err.code === 'FILE_TOO_LARGE') {
        res.status(413).json({ error: 'PDF must be under 10 MB' });
        return;
      }
    }
    next(err);
  }
}

// Route handler that uses the middleware
export function documentUploadHandler(req: Request, res: Response): void {
  const verification = req.documentVerification!;

  if (verification.status === 'modified') {
    res.status(422).json({
      error: 'Document appears to have been modified after creation',
      modification_markers: verification.modification_markers,
    });
    return;
  }

  if (verification.status === 'inconclusive') {
    // Queue for manual review instead of rejecting outright
    res.status(202).json({
      message: 'Document accepted for manual review',
      reason: verification.modification_markers[0] ?? 'Consumer software origin detected',
    });
    return;
  }

  // status === 'intact' — proceed
  res.status(200).json({ message: 'Document accepted', id: verification.id });
}

Wire these up in your Express app:

import express from 'express';
import { verifyDocument, documentUploadHandler } from './document-middleware';

const app = express();
app.use(express.json());

app.post(
  '/api/documents',
  verifyDocument,
  documentUploadHandler,
);

The middleware runs the HTPBE check and attaches the result to req.documentVerification. The route handler then reads the verdict. This separation keeps fraud detection logic out of your business layer.

Step 6: Test Mode

All HTPBE plans — including free — include a test API key. Test API keys use mock URLs that return predefined responses, similar to Stripe test cards. They are designed for integration testing without consuming production quota or requiring real documents.

Test URL format: https://api.htpbe.tech/v1/test/{filename}.pdf

The available test fixtures and what they return:

URL	`status`	Description
`clean.pdf`	`intact`	Clean document, institutional origin
`clean-no-dates.pdf`	`intact`	Clean, unknown origin, no date metadata
`modified-low.pdf`	`modified`	Single incremental update
`modified-medium.pdf`	`modified`	Consumer software origin, multiple updates
`modified-high.pdf`	`modified`	Different producer, 5-link update chain
`modified-critical.pdf`	`modified`	Signature removed, JavaScript, Excel origin
`signature-removed.pdf`	`modified`	Digital signature stripped
`signature-valid.pdf`	`intact`	Valid digital signature, no modifications
`inconclusive.pdf`	`inconclusive`	Excel origin, no structural modifications
`dates-mismatch.pdf`	`modified`	Modification date 14 days after creation

Use these in your test suite to cover all decision branches:

import { describe, it, expect } from 'vitest';
import { HTPBEClient } from './htpbe-client';

const TEST_BASE = 'https://api.htpbe.tech/v1/test';
const client = new HTPBEClient(process.env.HTPBE_TEST_API_KEY!);

describe('HTPBEClient', () => {
  it('returns intact for a clean document', async () => {
    const result = await client.verify(`${TEST_BASE}/clean.pdf`);
    expect(result.status).toBe('intact');
    expect(result.modification_markers).toHaveLength(0);
  });

  it('returns modified for a high-risk document', async () => {
    const result = await client.verify(`${TEST_BASE}/modified-high.pdf`);
    expect(result.status).toBe('modified');
  });

  it('returns inconclusive with a status_reason', async () => {
    const result = await client.verify(`${TEST_BASE}/inconclusive.pdf`);
    expect(result.status).toBe('inconclusive');
    // status_reason explains WHY: consumer_software_origin, online_editor_origin,
    // scanned_document, or html_renderer_origin. Always branch on it.
    expect(result.status_reason).toBeDefined();
  });

  it('handles signature-removed scenario', async () => {
    const result = await client.verify(`${TEST_BASE}/signature-removed.pdf`);
    expect(result.status).toBe('modified');
    expect(result.signature_removed).toBe(true);
  });
});

Keep your test API key in a .env.test file (separate from production) and never commit either key to version control.

Step 7: Reviewing Past Checks

The GET /api/v1/checks endpoint returns a paginated list of all analysis results for your API key. Use it to audit past checks, filter by verdict, or pull a history for a specific date range.

interface HTPBEChecksResponse {
  data: HTPBECheckSummary[];
  total: number;
  limit: number;
  offset: number;
  has_more: boolean;
}

async function getRecentModified(apiKey: string): Promise<HTPBECheckSummary[]> {
  const params = new URLSearchParams({
    status: 'modified',
    limit: '50',
  });

  const response = await fetch(
    `https://api.htpbe.tech/v1/checks?${params}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch checks: ${response.status}`);
  }

  const body = (await response.json()) as HTPBEChecksResponse;
  return body.data;
}

Monitor your quota consumption via the HTPBE dashboard. 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.

Step 8: Knowing When to Upgrade

The practical signals that a plan upgrade is warranted:

Starter ($15/month, 30 checks): Suitable for low-volume workflows — up to one document per day. If you are hitting quota before mid-month, or if your use case processes more than a handful of documents per week, move to Growth.

Growth ($149/month, 350 checks): The right tier for most production applications — handles roughly 12 documents per day. This is the recommended starting point for any application with real users.

Pro ($499/month, 1,500 checks): For platforms processing 40–50 documents per day consistently. The per-check cost drops to $0.33, a 23% saving over Growth.

Enterprise (custom): For 1,500+ checks per month. Per-check pricing drops to $0.10–$0.20 at high volume.

The clearest indicator to watch is your quota consumption measured at the same point each month — visible in the HTPBE dashboard. If you are consistently below 20% remaining with more than a week left in the billing cycle, you are sized for the next tier.

Complete Client File

For reference, the full htpbe-client.ts module in one place:

// POST /analyze response — just the check ID
export interface HTPBEAnalyzeResponse {
  id: string;
}

// GET /result/{id} response — flat object with all analysis fields
export interface HTPBEResult {
  id: string;
  filename: string;
  check_date: number | null;
  file_size: number;
  page_count: number;

  // Algorithm version tracking
  algorithm_version: string;
  current_algorithm_version: string;
  outdated_warning?: string;

  // Primary verdict
  status: 'intact' | 'modified' | 'inconclusive';
  status_reason?:
    | 'consumer_software_origin'
    | 'online_editor_origin'
    | 'scanned_document'
    | 'html_renderer_origin';
  origin: {
    type: 'consumer_software' | 'institutional' | 'unknown' | 'online_editor' | 'scanned';
    software: string | null;
  };

  // Detection results
  modification_confidence: 'certain' | 'high' | 'none' | null;

  // Metadata
  creator: string | null;
  producer: string | null;
  creation_date: number | null; // Unix timestamp
  modification_date: number | null; // Unix timestamp
  pdf_version: string | null;

  // Metadata analysis
  date_sequence_valid: boolean;
  metadata_completeness_score: number;

  // Structure analysis
  xref_count: number;
  has_incremental_updates: boolean;
  update_chain_length: number;

  // Signature analysis
  has_digital_signature: boolean;
  signature_count: number;
  signature_removed: boolean;
  modifications_after_signature: boolean;

  // Content analysis
  object_count: number;
  has_javascript: boolean;
  has_embedded_files: boolean;

  // Findings
  modification_markers: string[];
}

// GET /checks response item — summary with fewer fields than full result
export interface HTPBECheckSummary {
  id: string;
  filename: string;
  check_date: number | null;
  status: 'intact' | 'modified' | 'inconclusive';
  metadata_completeness_score: number;
  creator: string | null;
  producer: string | null;
  file_size: number;
  page_count: number;
  pdf_version: string | null;
  creation_date: number | null;
  modification_date: number | null;
  has_javascript: boolean;
  has_digital_signature: boolean;
  has_embedded_files: boolean;
  has_incremental_updates: boolean;
  update_chain_length: number;
  object_count: number;
}

export interface HTPBEErrorResponse {
  error: string;
  code: string;
}

export class HTPBEError extends Error {
  constructor(
    message: string,
    public readonly statusCode: number,
    public readonly code: string,
  ) {
    super(message);
    this.name = 'HTPBEError';
  }
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export class HTPBEClient {
  private readonly apiKey: string;
  private readonly baseUrl = 'https://api.htpbe.tech/v1';
  private readonly timeoutMs: number;

  constructor(apiKey: string, options: { timeoutMs?: number } = {}) {
    if (!apiKey) throw new Error('HTPBE API key is required');
    this.apiKey = apiKey;
    this.timeoutMs = options.timeoutMs ?? 30_000;
  }

  async verify(pdfUrl: string, retries = 3): Promise<HTPBEResult> {
    let lastError: HTPBEError | null = null;

    for (let attempt = 0; attempt < retries; attempt++) {
      if (attempt > 0) {
        await sleep(Math.pow(2, attempt - 1) * 1_000);
      }

      try {
        const { id } = await this.submitAnalysis(pdfUrl);
        return await this.getResult(id);
      } catch (err) {
        if (!(err instanceof HTPBEError)) throw err;
        if (err.statusCode < 500 && err.statusCode !== 429) throw err;
        lastError = err;
      }
    }

    throw lastError!;
  }

  private async submitAnalysis(pdfUrl: string): Promise<HTPBEAnalyzeResponse> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeoutMs);

    let response: Response;

    try {
      response = await fetch(`${this.baseUrl}/analyze`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ url: pdfUrl }),
        signal: controller.signal,
      });
    } catch (err) {
      if ((err as Error).name === 'AbortError') {
        throw new HTPBEError(
          `Request timed out after ${this.timeoutMs}ms`,
          408,
          'TIMEOUT',
        );
      }
      throw err;
    } finally {
      clearTimeout(timer);
    }

    if (!response.ok) {
      await this.handleErrorResponse(response);
    }

    return response.json() as Promise<HTPBEAnalyzeResponse>;
  }

  private async getResult(id: string): Promise<HTPBEResult> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeoutMs);

    let response: Response;

    try {
      response = await fetch(`${this.baseUrl}/result/${id}`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
        signal: controller.signal,
      });
    } catch (err) {
      if ((err as Error).name === 'AbortError') {
        throw new HTPBEError(
          `Request timed out after ${this.timeoutMs}ms`,
          408,
          'TIMEOUT',
        );
      }
      throw err;
    } finally {
      clearTimeout(timer);
    }

    if (!response.ok) {
      await this.handleErrorResponse(response);
    }

    return response.json() as Promise<HTPBEResult>;
  }

  private async handleErrorResponse(response: Response): Promise<never> {
    let body: HTPBEErrorResponse = { error: response.statusText, code: 'UNKNOWN' };

    try {
      body = (await response.json()) as HTPBEErrorResponse;
    } catch {
      // non-JSON body
    }

    switch (response.status) {
      case 400:
        throw new HTPBEError(`Bad request: ${body.error}`, 400, 'BAD_REQUEST');
      case 401:
        throw new HTPBEError(
          'Invalid API key. Check your HTPBE_API_KEY environment variable.',
          401,
          'UNAUTHORIZED',
        );
      case 402:
        throw new HTPBEError(
          'Payment required. No credits available for this key. See htpbe.tech/pricing.',
          402,
          'PAYMENT_REQUIRED',
        );
      case 403:
        throw new HTPBEError(
          'Access forbidden. Your API key may not have permission for this resource.',
          403,
          'FORBIDDEN',
        );
      case 404:
        throw new HTPBEError('Check not found.', 404, 'NOT_FOUND');
      case 413:
        throw new HTPBEError('PDF exceeds the 10 MB size limit.', 413, 'FILE_TOO_LARGE');
      case 422:
        throw new HTPBEError('The URL did not return a valid PDF file.', 422, 'INVALID_PDF');
      case 429:
        throw new HTPBEError(
          'Server is at analysis capacity. Retry after the Retry-After interval.',
          429,
          'SERVER_AT_CAPACITY',
        );
      case 500:
        throw new HTPBEError(
          'HTPBE server error. The request will be retried.',
          500,
          'SERVER_ERROR',
        );
      default:
        throw new HTPBEError(
          `Unexpected error ${response.status}: ${body.error}`,
          response.status,
          body.code ?? 'UNKNOWN',
        );
    }
  }
}

Decisions Before You Ship

The integration surface for HTPBE is intentionally small: one POST endpoint, one JSON response, three possible verdicts. The complexity is all on the integration side — retry logic, timeout handling, middleware architecture, test coverage — because those are the pieces that determine whether a third-party API call holds up in production.

Three decisions to make before going live:

inconclusive routing — for documents that claim institutional origin, treat inconclusive the same as modified; for user-generated documents (forms, letters), it may be acceptable
Quota policy — when you reach your monthly quota, further requests return 402 PAYMENT_REQUIRED until it resets; add a one-time credit pack or upgrade to keep going, and handle the 402 so a quota boundary never silently drops a check
Test key separation — keep test and production keys in separate env files; test keys return synthetic data and should never touch production flows

Cloudflare WAF Free Plan: Block Bots Without Paying

Iurii Rogulia — Fri, 12 Jun 2026 10:00:35 +0000

Open your server logs right now. I'll wait.

If your site has been running for more than a week, you almost certainly have hundreds — probably thousands — of requests to paths like /.env, /.git/config, /wp-admin/, /xmlrpc.php, and /phpmyadmin/. Your app is almost certainly not WordPress. The bots don't care. They scan every IP on the internet looking for anything exposed.

These requests don't break your app. But they pollute your logs, burn bandwidth, and add noise that makes real problems harder to spot. On a small VPS, a persistent scanner can also spike CPU enough to matter.

Cloudflare's WAF solves this cleanly — and works on the free plan, with one operator constraint that took me longer than I'd like to admit to figure out.

What the Bots Are Looking For

Each path these scanners request corresponds to something specific they hope to exploit:

Path	Target
`/.env`	Environment file — API keys, database passwords, secrets
`/.git/config`	Git repository — sometimes contains credentials, always reveals codebase structure
`/.aws/credentials`	AWS credentials file — direct cloud access
`/actuator/`	Spring Boot management endpoints — often unauthenticated
`/wp-admin/`	WordPress admin panel — brute-force login target
`/wp-login.php`	WordPress login — credential stuffing
`/xmlrpc.php`	WordPress XML-RPC — amplification attacks, credential testing
`/phpmyadmin/`	Database management UI — direct database access
`/laravel/`	Laravel framework paths — debug mode exposure
`/backend/`	Generic admin paths — admin panel probing
`/config.php`	Configuration files — credentials
`/server-status`	Apache server status — internal metrics exposure

None of this is targeted at you specifically. It's automated, opportunistic, and constant. The scanner tries every IP it finds. Your site being a Next.js app with none of these paths is irrelevant — the bot doesn't know that until it gets a response.

The Cloudflare WAF Rule

slug="fractional-cto"
text="Infrastructure security, deployment pipelines, and production monitoring — if you need an experienced technical lead who owns these layers end-to-end, let's talk."
/>

Cloudflare lets you write custom WAF rules using its Ruleset Language — a boolean expression that evaluates against request properties. When the expression matches, you choose an action: block, challenge, log, etc.

Here's the rule that covers the most common scanner paths:

(http.request.uri.path contains "/.env") or (http.request.uri.path contains "/.git/") or (http.request.uri.path contains "/.aws/") or (http.request.uri.path contains "/actuator/") or (http.request.uri.path contains "/wp-admin/") or (http.request.uri.path contains "/wp-login") or (http.request.uri.path contains "/xmlrpc") or (http.request.uri.path contains "/phpmyadmin/") or (http.request.uri.path contains "/laravel/") or (http.request.uri.path contains "/backend/") or (http.request.uri.path eq "/config.php") or (http.request.uri.path eq "/server-status")

Action: Block.

Notice I'm using contains for most paths and eq for two of them. That's deliberate — and it connects directly to the free plan limitation below.

The Operator Gotcha: Why `starts_with` Breaks on the Free Plan

This is the part nobody documents clearly. When I first wrote this rule, I used starts_with — it's the semantically correct operator for "path begins with /wp-admin/". It immediately threw a parse error in the Cloudflare dashboard.

Here's what's available on each plan tier:

Operator	Free	Pro	Business	Notes
`eq`	Yes	Yes	Yes	Exact match
`contains`	Yes	Yes	Yes	Substring match
`starts_with`	No	No	No	Parse error — not supported in custom rules
`ends_with`	No	No	No	Same
`matches`	No	No	Yes	Regex — requires Business or WAF Advanced

starts_with is not a plan limitation in the sense of "you need to upgrade" — it simply doesn't exist as a supported operator in WAF custom rules. The Cloudflare docs mention it in the context of other products (Transform Rules, Page Rules), but in the custom WAF ruleset, your options are eq, ne, contains, in, lt, le, gt, ge, and a few type-specific ones.

contains works fine as a substitute because scanner bots always use the full path anyway — /.env is always /.env, not /.environment or anything else. The substring match catches everything starts_with would have caught, plus any path that has the string anywhere, which is actually more thorough.

The two exceptions — /config.php and /server-status — use eq because these are exact paths. Using contains for /config.php would block any path that has "config.php" in it, which could catch legitimate admin tools if you have /admin/config.php as an internal path. If your app doesn't have anything like that, contains works equally well.

Deploying via the Dashboard

This is the simpler option. Takes about two minutes.

Log into the Cloudflare dashboard and select your zone
Go to Security → WAF → Custom rules
Click Create rule
Give it a name ("Block scanner bots" works fine)
Switch the expression editor to Edit expression (text mode) and paste the rule above as a single line
Set action to Block
Save and deploy

The rule is active immediately. No propagation delay.

Deploying via API

If you manage infrastructure as code or want to script this, the Cloudflare API works cleanly. You'll need two things:

Zone ID — found on the right sidebar of your zone's Overview page in the dashboard
API Token — create one at dash.cloudflare.com/profile/api-tokens with Zone:Edit permission scoped to your specific zone

curl -X PUT \
  "https://api.cloudflare.com/client/v4/zones/$CF_ZONE_ID/rulesets/phases/http_request_firewall_custom/entrypoint" \
  -H "Authorization: Bearer $CF_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "description": "Block bots",
        "expression": "(http.request.uri.path contains \"/.env\") or (http.request.uri.path contains \"/.git/\") or (http.request.uri.path contains \"/.aws/\") or (http.request.uri.path contains \"/actuator/\") or (http.request.uri.path contains \"/wp-admin/\") or (http.request.uri.path contains \"/wp-login\") or (http.request.uri.path contains \"/xmlrpc\") or (http.request.uri.path contains \"/phpmyadmin/\") or (http.request.uri.path contains \"/laravel/\") or (http.request.uri.path contains \"/backend/\") or (http.request.uri.path eq \"/config.php\") or (http.request.uri.path eq \"/server-status\")",
        "action": "block"
      }
    ]
  }'

This uses the PUT method on the phase entrypoint — which replaces the entire custom ruleset. If you already have other custom WAF rules, add them to the rules array rather than making a separate API call, or you'll overwrite them.

If you want to check what rules are currently set before writing:

curl "https://api.cloudflare.com/client/v4/zones/$CF_ZONE_ID/rulesets/phases/http_request_firewall_custom/entrypoint" \
  -H "Authorization: Bearer $CF_AUTH_TOKEN" | jq '.result.rules'

A successful PUT returns HTTP 200 with the created ruleset. A 400 usually means a malformed expression — double-check the escaping in the JSON string.

Verifying It Works

After deploying, the easiest check is to curl one of the blocked paths from your terminal:

curl -I https://yourdomain.com/.env
# HTTP/2 403

Cloudflare returns 403 for blocked requests. You should also see the blocked request show up in Security → Events in the dashboard, with the custom rule listed as the match reason.

Give it 24 hours and then check Security → Events. On any public-facing site, you'll see the rule firing repeatedly — not because someone is targeting you, but because the scanners are continuous and indiscriminate.

What This Does Not Cover

A few things worth being explicit about:

It doesn't replace proper secrets management. If /.env is actually accessible on your server because you committed it or deployed it to the wrong directory, this rule masks the symptom. Fix the root cause — .env should never be web-accessible regardless of WAF rules.

It doesn't protect against sophisticated attacks. A targeted attacker can easily rotate IPs, use different paths, or probe your application logic directly. This rule is noise reduction, not a security perimeter.

It doesn't cover API abuse or DDoS. For that you need rate limiting at the application layer — sliding window counters in Redis, or Cloudflare's rate limiting rules (also available on the free plan, separately from WAF). I cover the Redis implementation in detail in the Redis rate limiting article.

The /backend/ and /laravel/ paths might be too broad depending on your app. If you have a legitimate /backend/ route in your Next.js app, remove that clause. Review each path against your actual route structure before deploying.

Extending the Rule

The free plan allows up to 5 custom WAF rules, with expressions up to a certain length. The rule above is well within both limits. If you want to add more paths — for example, probes specific to PHP frameworks, Java servlet containers, or cloud metadata endpoints — you can extend the same expression with additional or clauses.

Common additions I consider for projects with more exposure:

or (http.request.uri.path contains "/.ssh/")
or (http.request.uri.path contains "/etc/passwd")
or (http.request.uri.path contains "/proc/self/")
or (http.request.uri.path contains "/.DS_Store")
or (http.request.uri.path contains "/wp-content/")
or (http.request.uri.path eq "/.htaccess")

The .DS_Store one is worth including — macOS creates these files automatically and developers sometimes commit them, leaking directory structure. Scanner bots know this.

This is a 10-minute setup with permanent noise reduction. I add it to every project I deploy behind Cloudflare — it costs nothing on the free plan and makes the Security Events log actually useful instead of 95% bot scanner noise. For the full self-hosting stack with Caddy and Docker, these WAF rules are one layer of a broader infrastructure setup.

If you're building a SaaS or e-commerce platform for the EU market and want the full infrastructure layer handled properly — security, rate limiting, observability, deployment — get in touch. I'm available for freelance projects and long-term engagements.

Further reading:

GitHub Gist — ready-to-use script and expression — copy the expression or run block-bots.sh directly
Cloudflare WAF Custom Rules documentation — official reference for the ruleset language
Cloudflare Ruleset Language field reference — all available fields including http.request.uri.path
Cloudflare Rate Limiting Rules — complementary to WAF, also available on the free plan

Caching VIES Responses Without Breaking Compliance

Iurii Rogulia — Fri, 12 Jun 2026 09:00:36 +0000

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

Caching VIES is easy. Defending the cache during an audit is harder. A single SOAP round-trip to VIES takes 1–3 seconds on a good day and 10+ seconds when a national node is under load, so if your checkout calls VIES synchronously for every B2B customer, you are leaving a lot of latency on the table. Caching is the obvious fix — but VAT validation is not the kind of cache you set to 24 hours and forget about. Get the TTL wrong and your audit trail stops being defensible.

This post walks through what you can safely cache, for how long, and how to keep the consultation number trail intact when you do.

Why caching VIES is different from caching anything else

A normal cache trades freshness for latency. VAT validation has a third axis: evidence. When a tax authority asks "did you check this customer's VAT number at the moment you reverse-charged the invoice?", you need to point at a timestamped record. A response you served from cache is a response you did not actually re-fetch from VIES — which is fine, as long as the cached record still represents what VIES would have said at the time of the transaction.

In practice this means two things:

The cached entry must include the original VIES timestamp and consultation number, not the cache-write time. If you re-serve a 6-hour-old response, the audit log must say it came from a check performed 6 hours ago — not "now".
The TTL must be short enough that you can defend it. There is no statute that says "you must re-check every N hours", but tax authorities will push back on caches measured in days when the underlying status can change overnight.

What VIES actually returns and what changes

A VIES response contains the validity flag, optional name and address, the request timestamp, and — if you pass a requester VAT ID — a consultation number that proves a specific party performed the check on a specific date. The validity flag is the only field that can flip without warning: a company can deregister, a number can be invalidated by the issuing authority, and there is no notification channel.

For SaaS billing, this matters at three moments:

Signup / first invoice — you must check before applying reverse-charge for the first time.
Recurring renewals — a number that was valid in January can be invalid by March.
Audit reconstruction — months or years later, you must show that the check supporting each invoice was real.

The same axes apply outside SaaS — marketplaces, ERP integrations, bulk invoicing, and accounting platforms each have their own invoice-timing expectations, but the underlying "check, evidence, re-check" loop is the same.

A defensible TTL ladder

There is no single right number, but the pattern that holds up across EU tax authorities is a tiered TTL with explicit revalidation on the events that matter:

// Tiered cache strategy
const TTL = {
  // Same request inside one checkout flow / page load
  HOT: 15 * 60, // 15 minutes
  // Same customer interacting with your app the same day
  WARM: 24 * 60 * 60, // 24 hours
  // Hard ceiling — re-check before issuing the next invoice
  INVOICE_REVALIDATE: 30 * 24 * 60 * 60, // 30 days
}

The 15-minute hot tier covers retries and the multi-page checkout pattern (cart → address → payment) without hammering VIES. The 24-hour warm tier covers same-day dashboard interactions. The 30-day ceiling is the one that matters for compliance: there is no single statutory rule here, but many compliance teams treat ~30 days as a practical upper bound between the supporting VIES check and the issued B2B reverse-charge invoice. Re-validate before that horizon, store the new consultation number against the new invoice, and start the TTL again. See the VIES consultation number guide for the audit storage shape.

Negative caching: invalid IDs need a different TTL

The TTL ladder above assumes a valid: true response. Invalid results — VAT_NOT_FOUND, INVALID_INPUT, or a flat valid: false from VIES — should be cached more cautiously, often with a TTL closer to minutes than hours.

It helps to keep the two cache paths conceptually separate: the positive cache is evidence reuse (you are deliberately replaying a known-good check, with its consultation number, to avoid re-asking VIES the same question), while the negative cache is temporary failure suppression (you are throttling repeated client retries against a known-bad input, without committing to that result as audit evidence). Different purposes, different TTL discipline.

Two reasons. First, a freshly-registered taxable person may genuinely become valid within hours of their initial registration appearing in the national database; aggressive negative caching will repeatedly reject a legitimate customer who is trying again after registering. Second, an invalid result is rarely an invoice-critical event in the same way a positive result is — you are not building audit evidence for a transaction that did not happen, so the trade-off is mostly UX, not compliance. A reasonable default is 5–15 minutes for invalid, 24 hours for valid, with the 30-day re-validation ceiling applying only to the positive path.

Redis pattern: cache the response, not the decision

The wrong way to cache: store a boolean isValid: true keyed by VAT ID. The right way: store the full response object, including the original timestamp and consultation number, so that when you re-read it you reconstruct the full audit context.

import { createClient } from 'redis'

const redis = createClient({ url: process.env.REDIS_URL })

type CachedVies = {
  vatId: string
  valid: boolean
  name?: string
  address?: string
  consultationNumber?: string
  checkedAt: string // ISO timestamp of the original VIES call
  source: 'VIES' | 'BZST'
}

async function getValidatedVat(vatId: string): Promise<CachedVies> {
  const key = `vat:${vatId.toUpperCase()}`
  const cached = await redis.get(key)

  if (cached) {
    const entry = JSON.parse(cached) as CachedVies
    // Refuse stale entries for invoice-critical paths
    const ageMs = Date.now() - new Date(entry.checkedAt).getTime()
    if (ageMs < 30 * 24 * 60 * 60 * 1000) {
      return entry
    }
  }

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

  if (!res.ok) {
    throw new Error(`VAT check failed: ${res.status}`)
  }

  const data = await res.json()
  const entry: CachedVies = {
    vatId: data.vatId,
    valid: data.valid,
    name: data.name,
    address: data.address,
    consultationNumber: data.consultationNumber,
    checkedAt: data.checkedAt,
    source: data.source,
  }

  // Positive results: 24-hour Redis TTL with the 30-day ceiling enforced above.
  // Negative results: short TTL, just enough to suppress retry storms.
  const ttl = entry.valid ? 24 * 60 * 60 : 10 * 60
  await redis.set(key, JSON.stringify(entry), { EX: ttl })
  return entry
}

Two details that are easy to miss:

Key on the normalised VAT ID (uppercase, no spaces). de123456789, DE 123 456 789, and DE123456789 are the same number — different cache keys is a memory leak and a correctness bug.
Persist the cached entry to your database too, not just Redis. Redis is for latency; PostgreSQL is for the audit trail. The two have different retention needs — the operational cache exists to make the next request fast and can be flushed at any time, while the evidence snapshot (the row tied to the invoice, with its consultation number and original VIES timestamp) is the artefact you must still be able to produce years later. Treat them as separate systems with separate lifecycles, even if they happen to start out with the same payload.

When to bypass the cache no matter what

Some events should always trigger a fresh VIES call, regardless of how warm the cache is:

Issuing a B2B reverse-charge invoice. The consultation number on that invoice must reflect a check performed close to the invoice date.
Customer-initiated VAT ID change. A new VAT ID always means a new check — never inherit validity from a previous number.
Subscription renewal that crosses a tax year. This is a best-practice heuristic rather than a written rule, but year-end is when most tax authorities reconcile filings — a check that sits cleanly inside the same reporting period as the invoice is easier to defend than one that straddles two.
The cached entry is missing a consultation number. If your previous check did not pass a requester VAT ID and you now need audit-grade evidence, the old entry is not good enough — re-run it.

The cleanest way to express this in code is to make the cache opt-in per call site, not the default:

// Fast paths — cache is fine
const result = await getValidatedVat(vatId)

// Compliance-critical paths — force a fresh check
const fresh = await getValidatedVat(vatId, { bypassCache: true })

Rate limits: a cache is not a license to hammer

Even with a healthy cache hit rate, you will still hit VIES often enough that rate limits matter. There is no published per-IP limit, but national nodes throttle aggressively under load — Germany's BZSt-backed node especially. Two patterns help:

Coalesce concurrent requests for the same VAT ID. If 50 parallel checkout sessions all want to validate DE123456789 and your cache is cold, you want exactly one outbound VIES call, not 50. A simple in-memory promise map per process is enough for a single instance; for horizontally scaled deployments, lift the same idea to a short-lived Redis lock (or any singleflight primitive) so the de-duplication holds across instances.
Queue background revalidations. Renewal checks, scheduled re-validations, and admin-triggered audits should never run on the request path. Use a job queue with concurrency capped at 2–4 to stay polite to VIES.

If you are already hitting VIES_UNAVAILABLE regularly, caching alone will not save you — the VIES downtime guide covers the retry-and-queue pattern that complements this one.

Stale-if-error and partial outages

VIES is not a single service — it is a thin EC gateway in front of national tax-authority nodes. At any given moment one or two country nodes may be unreachable while the rest respond normally. That asymmetry matters for cache design:

Stale-if-error. When VIES (or the relevant national node) is down, a recent cached response is usually preferable to a hard failure on checkout. Allow reads from a slightly-older cache during an outage — but log the stale serve explicitly and never reuse a stale entry as the audit-grade check for a freshly issued invoice. Stale-if-error is a UX safety net for the request path, not a compliance shortcut.
Country-scoped failure modes. If your retry/backoff logic treats every error the same, a single down country will spam your queue while the rest of the EU is healthy. Tracking the failure rate per country prefix lets you cool off only the affected nodes.
Proactive revalidation. For long-running subscriptions, do not wait for the cache to expire on the customer's next invoice — schedule a background re-check a few days before renewal. If the number is still valid, the cache is warm when the invoice runs. If it has gone invalid, you get a quiet email-the-customer window instead of a billing-time failure.

Summary

Cache VIES responses, but cache the full response with its original timestamp and consultation number, not a boolean. Keep the TTL short enough to be defensible (24 hours warm, 30 days hard ceiling), and bypass the cache on the events where evidence actually matters: invoice issuance, VAT ID changes, year boundaries. Coalesce in-flight requests, queue background work, and store the audit trail in your database — Redis is not where compliance lives. The goal is not to avoid VIES calls entirely; it is to minimise unnecessary calls without weakening the evidentiary chain behind the invoices that matter.

vatnode handles the cache layer for you

vatnode caches VIES responses internally with compliance-oriented TTL handling, exposes the consultation number on every response, and returns structured error codes so your app can implement the patterns above without re-implementing the SOAP client. Free plan, 100 requests/month.

Get Free API Key · Error Code Reference

PostNord API and Zoho Desk Automation: Production Gotchas

Iurii Rogulia — Thu, 11 Jun 2026 10:00:35 +0000

I've written before about the overall automation pipeline at pikkuna.fi — the high-level flow from Stripe webhook to customer confirmation in under 2 minutes. This article is the deep cut: specifically PostNord and Zoho Desk, the parts that required the most trial and error to get right in production.

If you're integrating with PostNord's API or building automated Zoho Desk ticket creation, you'll hit the same walls. This is everything I learned.

PostNord: The API That Returns 200 for Errors

slug="automation-workflows"
text="Integrating PostNord, Zoho CRM, and Zoho Desk into a single fulfillment pipeline? I've built and debugged this in production — service codes, EU data centers, token caching, and all."
/>

PostNord's API looks normal on the surface — REST endpoints, JSON, API key authentication. The first surprise comes when you make a successful-looking request and get back this:

{
  "httpStatusCode": 200,
  "CompositeShipmentData": []
}

HTTP 200. Empty shipment array. No error field. No message.

This is PostNord's way of telling you that the service code you requested is unavailable for the destination country. If you're checking response.ok and moving on, you just silently failed to create a shipping label. The order will proceed through your pipeline — Zoho CRM updated, accounting updated, confirmation email sent — with no tracking number and no label.

The correct implementation: always check that CompositeShipmentData is non-empty and treat an empty array as a hard error that should retry:

// lib/shipping/postnord.ts
interface PostNordShipmentResponse {
  httpStatusCode: number;
  CompositeShipmentData: PostNordShipmentData[];
}

interface PostNordShipmentData {
  parcels: Array<{
    parcelNumber: string;
    pdfs: Array<{
      pdf: string; // base64-encoded PDF
      fileName: string;
    }>;
  }>;
}

export async function createPostNordShipment(
  order: Order
): Promise<{ trackingNumber: string; labelPdf: Buffer }> {
  const response = await fetch("https://api2.postnord.com/rest/shipment/v5/shipment", {
    method: "POST",
    headers: {
      "x-api-key": process.env.POSTNORD_API_KEY!,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify(buildShipmentPayload(order)),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`PostNord API error ${response.status}: ${errorText}`);
  }

  const data = (await response.json()) as PostNordShipmentResponse;

  // This is the critical check — HTTP 200 does NOT mean success
  if (!data.CompositeShipmentData || data.CompositeShipmentData.length === 0) {
    throw new Error(
      `PostNord returned 200 but no shipment data. ` +
        `Service code may be unavailable for country: ${order.shippingAddress.country}`
    );
  }

  const shipmentData = data.CompositeShipmentData[0];
  const parcel = shipmentData.parcels[0];

  if (!parcel) {
    throw new Error("PostNord returned shipment data with no parcels");
  }

  const trackingNumber = parcel.parcelNumber;

  // Label is base64-encoded PDF
  const labelPdf = Buffer.from(parcel.pdfs[0].pdf, "base64");

  return { trackingNumber, labelPdf };
}

Building the Shipment Payload

PostNord's payload structure is verbose. Here's the production version with all the fields that matter:

// lib/shipping/postnord.ts
function buildShipmentPayload(order: Order): PostNordShipmentRequest {
  return {
    shipmentServiceCode: getServiceCode(order.shippingAddress.country),
    shipmentDate: new Date().toISOString().split("T")[0], // YYYY-MM-DD
    sender: {
      quickId: process.env.POSTNORD_SENDER_QUICK_ID!, // Your registered sender ID
      name: process.env.POSTNORD_SENDER_NAME!,
      address: {
        street1: process.env.POSTNORD_SENDER_STREET!,
        city: process.env.POSTNORD_SENDER_CITY!,
        stateOrProvinceCode: process.env.POSTNORD_SENDER_STATE!,
        postalCode: process.env.POSTNORD_SENDER_POSTAL!,
        countryCode: "FI",
      },
    },
    receiver: {
      name: order.customerName,
      address: {
        street1: order.shippingAddress.line1,
        street2: order.shippingAddress.line2 || undefined,
        city: order.shippingAddress.city,
        postalCode: order.shippingAddress.postalCode,
        countryCode: order.shippingAddress.country,
      },
      contact: {
        email: order.customerEmail,
        // Mobile required for MyPack Home — PostNord sends delivery notifications
        mobile: order.customerPhone || undefined,
      },
    },
    parcels: [
      {
        weight: calculateTotalWeight(order.lineItems),
        comment: `Order ${order.id}`, // Appears on the label
      },
    ],
    orderReference: order.id, // Your internal reference — returned in webhook callbacks
    printMedia: [
      {
        printMediaType: "PDF",
        mediaSize: "A4",
      },
    ],
  };
}

// Service code selection by destination country
function getServiceCode(countryCode: string): string {
  // Finland domestic
  if (countryCode === "FI") return "19"; // MyPack Home

  // Nordic countries
  if (["SE", "NO", "DK"].includes(countryCode)) return "PD2"; // Parcel Connect

  // EU
  return "PD2"; // Parcel Connect covers most EU destinations

  // If you ship to specific countries that need different services,
  // add them here — this is where 200+empty often originates
}

The service code issue: PostNord has different service codes for different shipping products, and not every product ships to every country. MyPack Home (code 19) is Finland domestic only. Using it for a German delivery returns 200 + empty array. Map your destination countries to the correct service codes explicitly, and add the destination country to your error message so debugging is fast.

Storing the Label PDF

The label PDF needs to be stored somewhere accessible:

The operations team needs to print it
It should be attached to the Zoho Desk ticket (more on that below)
It should survive if the VPS restarts

I upload to Vercel Blob with the tracking number as the filename:

// lib/shipping/store-label.ts
import { put } from "@vercel/blob";

export async function storeShippingLabel(
  labelPdf: Buffer,
  trackingNumber: string
): Promise<string> {
  const blob = await put(`shipping-labels/${trackingNumber}.pdf`, labelPdf, {
    access: "public",
    contentType: "application/pdf",
  });

  return blob.url;
}

The URL is what I pass downstream — to Zoho CRM (stored on the Deal), to Zoho Desk (attached to the ticket), and to the customer email.

Zoho CRM: The EU Data Center Trap

Before the Zoho Desk integration, a quick note about Zoho CRM that trips up many EU developers: Zoho has separate data centers for EU and non-EU customers. If your Zoho account is in the EU data center (which it should be if you're an EU business), your API base URL is zohoapis.eu, not zohoapis.com.

// WRONG — will produce auth errors that look like token problems
const BASE_URL = "https://www.zohoapis.com/crm/v3";

// CORRECT for EU data center accounts
const BASE_URL = "https://www.zohoapis.eu/crm/v3";

The error message you get with the wrong data center is something like INVALID_TOKEN — which leads you to debug your OAuth flow for an hour before you realize it's a URL issue.

Zoho Desk: Auto-Creating Logistics Tickets

After a PostNord shipment is created, I automatically create a Zoho Desk ticket with:

The customer details
The order number
The tracking number
The shipping label PDF attached (as a URL or file)

This gives the operations team a single view: all logistics issues appear as Desk tickets, linked to the CRM deal, with the label ready to print.

// lib/crm/zoho-desk.ts
interface ZohoDeskTicketResult {
  ticketId: string;
  ticketNumber: string;
}

export async function createShipmentTicket(
  order: Order,
  trackingNumber: string,
  labelUrl: string,
  dealId: string
): Promise<ZohoDeskTicketResult> {
  const token = await getZohoAccessToken(); // Shared OAuth token cache with CRM

  // Create the ticket
  const ticketResponse = await fetch("https://desk.zoho.eu/api/v1/tickets", {
    method: "POST",
    headers: {
      Authorization: `Zoho-oauthtoken ${token}`,
      "Content-Type": "application/json",
      orgId: process.env.ZOHO_DESK_ORG_ID!,
    },
    body: JSON.stringify({
      subject: `Shipment — Order ${order.id} — ${order.customerName}`,
      description: buildTicketDescription(order, trackingNumber, labelUrl),
      status: "Open",
      priority: "Medium",
      channel: "Automated",
      contactId: await findOrCreateDeskContact(order, token),
      // CRM Deal ID — links ticket to the deal in CRM
      cf: {
        cf_crm_deal_id: dealId,
        cf_tracking_number: trackingNumber,
        cf_label_url: labelUrl,
      },
      departmentId: process.env.ZOHO_DESK_LOGISTICS_DEPT_ID!,
    }),
  });

  if (!ticketResponse.ok) {
    const error = await ticketResponse.text();
    throw new Error(`Zoho Desk ticket creation failed: ${error}`);
  }

  const ticket = await ticketResponse.json();
  return {
    ticketId: ticket.id,
    ticketNumber: ticket.ticketNumber,
  };
}

function buildTicketDescription(order: Order, trackingNumber: string, labelUrl: string): string {
  return `
<b>Order:</b> ${order.id}<br>
<b>Customer:</b> ${order.customerName}<br>
<b>Email:</b> ${order.customerEmail}<br>
<b>Shipping address:</b> ${order.shippingAddress.line1}, ${order.shippingAddress.city}, ${order.shippingAddress.country}<br>
<br>
<b>Tracking number:</b> ${trackingNumber}<br>
<b>PostNord tracking:</b> <a href="https://tracking.postnord.com/en/?id=${trackingNumber}">Track parcel</a><br>
<b>Shipping label:</b> <a href="${labelUrl}">Download PDF</a><br>
<br>
<b>Items:</b><br>
${order.lineItems.map((i) => `• ${i.name} × ${i.quantity}`).join("<br>")}
  `.trim();
}

Zoho Desk Contact Lookup

Desk contacts are separate from CRM contacts. When creating a ticket, you need a Desk contact ID — not a CRM contact ID. This is a common source of confusion.

// lib/crm/zoho-desk.ts
async function findOrCreateDeskContact(order: Order, token: string): Promise<string> {
  // Search for existing Desk contact by email
  const searchResponse = await fetch(
    `https://desk.zoho.eu/api/v1/contacts/search?email=${encodeURIComponent(order.customerEmail)}`,
    {
      headers: {
        Authorization: `Zoho-oauthtoken ${token}`,
        orgId: process.env.ZOHO_DESK_ORG_ID!,
      },
    }
  );

  const searchData = await searchResponse.json();
  const existingContact = searchData.data?.[0];

  if (existingContact) {
    return existingContact.id;
  }

  // Create new Desk contact
  const createResponse = await fetch("https://desk.zoho.eu/api/v1/contacts", {
    method: "POST",
    headers: {
      Authorization: `Zoho-oauthtoken ${token}`,
      "Content-Type": "application/json",
      orgId: process.env.ZOHO_DESK_ORG_ID!,
    },
    body: JSON.stringify({
      lastName: order.customerName.split(" ").slice(-1)[0] || order.customerName,
      firstName: order.customerName.split(" ").slice(0, -1).join(" ") || "",
      email: order.customerEmail,
      phone: order.customerPhone || undefined,
    }),
  });

  if (!createResponse.ok) {
    throw new Error(`Failed to create Desk contact: ${await createResponse.text()}`);
  }

  const newContact = await createResponse.json();
  return newContact.id;
}

OAuth Token Management

Both Zoho CRM and Zoho Desk use the same OAuth token (if you requested both scopes during initial authorization). Tokens expire after one hour — the most common production failure mode is calling Zoho with an expired token and getting an INVALID_TOKEN error.

The fix: cache the token with an expiry, refresh before expiry:

// lib/crm/zoho-auth.ts
interface CachedToken {
  accessToken: string;
  expiresAt: number; // Unix timestamp in ms
}

let tokenCache: CachedToken | null = null;

export async function getZohoAccessToken(): Promise<string> {
  // Refresh if within 5 minutes of expiry
  if (tokenCache && tokenCache.expiresAt - Date.now() > 5 * 60 * 1000) {
    return tokenCache.accessToken;
  }

  const response = await fetch("https://accounts.zoho.eu/oauth/v2/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      refresh_token: process.env.ZOHO_REFRESH_TOKEN!,
      client_id: process.env.ZOHO_CLIENT_ID!,
      client_secret: process.env.ZOHO_CLIENT_SECRET!,
      grant_type: "refresh_token",
    }),
  });

  if (!response.ok) {
    throw new Error(`Zoho token refresh failed: ${await response.text()}`);
  }

  const data = await response.json();

  // Token is valid for 3600 seconds (1 hour)
  tokenCache = {
    accessToken: data.access_token,
    expiresAt: Date.now() + data.expires_in * 1000,
  };

  return tokenCache.accessToken;
}

Note: accounts.zoho.eu for EU data center accounts, not accounts.zoho.com. Same trap as the API URL.

Zoho's token refresh endpoint is rate-limited at approximately 100 requests per minute. During a flash sale with high order volume, if every order job independently refreshes the token, you'll hit this limit. The module-level tokenCache solves this for a single process. If you run multiple worker processes, you'd want to store the token in Redis instead.

Full Pipeline in the Worker

Putting it together — the complete order fulfillment step in the BullMQ worker:

// workers/fulfillment.worker.ts
import { Worker, Job } from "bullmq";
import { redis } from "@/lib/redis";
import { fetchOrderFromStripe } from "@/lib/payments/stripe";
import { createPostNordShipment } from "@/lib/shipping/postnord";
import { storeShippingLabel } from "@/lib/shipping/store-label";
import { createZohoDeal } from "@/lib/crm/zoho-crm";
import { createShipmentTicket } from "@/lib/crm/zoho-desk";
import { sendOrderConfirmationWithInvoice } from "@/lib/email/send-order-confirmation";
import { notifyTelegram } from "@/lib/monitoring/telegram";

interface FulfillmentJobData {
  paymentIntentId: string;
  eventId: string;
}

const worker = new Worker<FulfillmentJobData>(
  "fulfillment",
  async (job: Job<FulfillmentJobData>) => {
    const order = await fetchOrderFromStripe(job.data.paymentIntentId);

    // 1. CRM — non-blocking, runs first so deal ID is available
    const { dealId } = await createZohoDeal(order);

    // 2. Shipping label — the critical step
    const { trackingNumber, labelPdf } = await createPostNordShipment(order);
    const labelUrl = await storeShippingLabel(labelPdf, trackingNumber);

    // 3. Desk ticket — logistics team visibility
    await createShipmentTicket(order, trackingNumber, labelUrl, dealId);

    // 4. Customer email with invoice and tracking
    await sendOrderConfirmationWithInvoice({
      ...mapOrderToEmailData(order),
      trackingUrl: `https://tracking.postnord.com/en/?id=${trackingNumber}`,
    });

    return { dealId, trackingNumber, labelUrl };
  },
  {
    connection: redis,
    concurrency: 3,
  }
);

worker.on("failed", async (job, err) => {
  if (!job) return;
  const isLastAttempt = job.attemptsMade >= (job.opts.attempts ?? 1);
  if (isLastAttempt) {
    await notifyTelegram(
      `Fulfillment pipeline failed permanently\n` +
        `PaymentIntent: ${job.data.paymentIntentId}\n` +
        `Error: ${err.message}\n` +
        `Attempts: ${job.attemptsMade}`
    );
  }
});

Production Gotchas Summary

Problem	Symptom	Fix
PostNord 200 + empty array	Silently missing tracking numbers	Always check `CompositeShipmentData.length > 0`
Wrong Zoho data center URL	`INVALID_TOKEN` error on valid tokens	Use `zohoapis.eu` and `accounts.zoho.eu` for EU accounts
Token refresh on every request	Rate limit errors during flash sales	Cache token in module scope or Redis, refresh proactively
Desk vs CRM contact IDs	Ticket creation fails with `INVALID_CONTACT`	Desk has separate contact storage — search/create in Desk specifically
No phone in PostNord payload	MyPack Home delivery notifications don't send	Include `receiver.contact.mobile` when available
Service code for wrong country	PostNord 200 + empty array	Map destination countries to correct service codes explicitly

If you're building post-purchase automation for an EU e-commerce platform — shipping labels, CRM updates, logistics tickets — and you're hitting these exact issues, I've been through them in production at Pikkuna. Get in touch for automation workflows and API integration projects.

I'm available for freelance projects and long-term engagements.

Related posts: How I Fully Automated E-commerce Order Processing — the full pipeline overview. Stripe Webhooks Done Right — the webhook architecture that drives this pipeline.

Related project: Pikkuna E-commerce Platform — the system this pipeline runs in production.

Contract Fraud: How Altered PDFs Bypass Legal Review

Iurii Rogulia — Thu, 11 Jun 2026 10:00:34 +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 service agreement arrives by email. Legal reviews it, confirms the terms match the negotiated deal, and routes it for signature. Two weeks later, a dispute reveals that the payment terms in the executed copy differ from the version legal reviewed. The net-30 clause now reads net-60. The liability cap changed from $500,000 to $50,000. The bank account number in the payment instructions section points to a different institution.

The contract was modified between review and execution — or between execution and filing. Nobody noticed because nobody checked the file itself. They checked the words on the page. This is how contract fraud through PDF alteration works: the document looks correct while the file contains a different record.

Why Contracts Are a Prime Target

Contracts are high-value documents processed under time pressure by people who read text, not file structure. This combination makes them one of the most effective targets for PDF-level fraud.

The economics are straightforward. A single altered payment term on a $2 million service agreement can redirect hundreds of thousands of dollars. A changed liability clause can shift millions in exposure during a dispute. Unlike invoice fraud — where amounts are typically in the tens of thousands — contract fraud operates at the scale of the underlying deal.

The detection gap is equally straightforward. Legal teams review contracts by reading them. They compare the current version against the last redline they remember, or against a summary of negotiated terms. What they do not do is inspect the PDF’s binary structure to determine whether the file was modified after the version they approved.

According to the Association of Certified Fraud Examiners’ 2024 Report to the Nations, document alteration and forgery account for a significant share of occupational fraud cases, with a median loss of $150,000 per incident. Contract manipulation specifically — altering terms after agreement — falls into the highest-loss category because the altered document becomes the binding instrument. For a broader view of why PDF authenticity matters across business operations, the problem extends well beyond legal.

Three characteristics make contracts uniquely vulnerable:

Time pressure. Deal closings have deadlines. Legal teams approve final versions under schedule pressure, reducing the likelihood of catching subtle changes between versions.
Version proliferation. A typical contract goes through 5–15 drafts. By the final version, reviewers are fatigued and rely on tracked changes — which only reflect changes the editing party chose to track.
Trust in the signature. Once a contract is signed, the assumption is that the signed version matches the agreed terms. Re-reading a signed contract line by line is rare. Re-checking its file integrity is rarer still.

Three Contract Fraud Scenarios

Changed payment terms after signing

A vendor and a buyer execute a service agreement with net-30 payment terms. The vendor’s accounts receivable team files the signed PDF. Six months later, in a payment dispute, the vendor produces a copy of the “executed agreement” showing net-60 terms — giving them grounds to claim the buyer is in breach for late payment.

The alteration: after the contract was signed and distributed, someone on the vendor side opened the PDF in an editing tool, changed “30” to “60” in the payment terms clause, and re-saved. The visual output is identical to the original in every other respect. If the buyer did not retain their own copy — or if their copy was also sourced from the vendor — the altered version becomes the only version of record.

Altered liability clauses

During M&A due diligence, a target company provides executed contracts with key customers. One contract contains a limitation of liability clause capping exposure at $5 million. The acquirer relies on this cap in their valuation model. Post-acquisition, a dispute arises, and the customer produces the “original” contract showing a $50 million cap — or no cap at all.

The alteration required changing a single number in one clause. The rest of the 40-page agreement is untouched. No one re-reads a 40-page contract in due diligence to check that every figure matches what was represented. The file structure, however, recorded the modification.

Modified bank details in service agreements

This pattern mirrors invoice fraud but at contract scale. An attacker intercepts a signed service agreement in transit — via compromised email or a man-in-the-middle attack on a document sharing platform — and changes the bank account number in the payment instructions section. The counterparty receives what appears to be the executed agreement and begins making payments to the altered account.

Because service agreements often govern payment relationships lasting months or years, the fraud may not surface until a significant sum has been redirected. The mechanics of this attack are identical to how criminals modify invoice PDFs — but the dollar amounts are orders of magnitude larger.

How PDF Alteration Works: What Editing Leaves Behind

Every scenario above involves the same technical action: opening an existing PDF, changing content, and saving. The PDF specification makes this action structurally detectable regardless of how the visual output looks.

Cross-reference tables and incremental updates

When a PDF is created, the generating software writes a cross-reference (xref) table that maps every object in the file to its byte offset. When the file is subsequently edited and saved, the editing software appends a new xref section to the end of the file rather than rewriting the original. This is the PDF incremental update mechanism — designed for efficiency, but forensically significant.

A contract generated once by a document management system has one xref section. The same contract opened in an editor and re-saved has at least two. The original content remains in the file; the appended section contains the modified objects and a new xref pointing to them.

For a detailed breakdown of this structure, see The Anatomy of a Modified PDF.

Metadata divergence

The PDF Info dictionary stores a Creator field (the application that originally produced the document) and a Producer field (the software that last processed it). A contract generated by DocuSign’s signing platform shows a Creator and Producer consistent with DocuSign’s internal PDF generation library. If someone opens that file in iLovePDF or Smallpdf and re-saves it, the Producer field changes to reflect the editing tool.

The CreationDate and ModDate fields show a similar divergence. A contract signed on March 1 with a modification date of March 15 was edited two weeks after signing. The 15-second tolerance built into forensic analysis accounts for normal software behavior during generation — a two-week gap does not fall within that tolerance. For a full breakdown of these fields and what they reveal, see the PDF metadata field reference.

Post-signature modifications

This is the highest-confidence signal in contract forensics. When a PDF is digitally signed, the signature cryptographically binds to a specific byte range of the file. Content appended after the signature — via incremental update — exists outside the signed byte range. The file now contains both signed and unsigned content.

HTPBE detects this pattern with certain confidence. A contract that was signed and then modified is reported with the MODIFICATIONS_AFTER_SIGNATURE marker. This is not a probabilistic assessment — it is a binary structural fact. The signed byte range does not extend to the end of the file.

The Two Highest-Confidence Signals

Not all modification markers carry equal weight. For contract fraud detection, two markers produce certain confidence — the highest level in HTPBE’s 35-check forensic analysis:

Modifications after digital signature

Marker: MODIFICATIONS_AFTER_SIGNATURE
Confidence: certain

The digital signature in a PDF covers a defined byte range. When content is appended after the signature, the new xref section and its objects sit outside that range. The signature itself remains cryptographically valid for the bytes it covers, but the document now contains unsigned content that was added after the signing event.

This is the single most reliable signal in contract fraud detection. It is impossible to produce this pattern through normal document generation. It requires an explicit post-signature edit.

Signature removal

Marker: SIGNATURE_REMOVED
Confidence: certain

A more aggressive approach: the attacker removes the digital signature entirely before making changes, so the modified document does not show a broken or invalidated signature. The absence of a signature that was previously present is itself detectable — the file structure retains traces of the signature dictionary and its associated objects even after removal.

Both signals are structural facts, not heuristic assessments. When either appears in a contract detection result, the appropriate response is immediate escalation — not additional review.

For a deeper understanding of how digital signatures and metadata analysis complement each other, see Digital Signatures vs. Metadata: What Proves PDF Authenticity.

API Integration in Legal Workflows

The practical integration point for contract fraud detection is between document receipt and human review — or between signing and filing. The pattern works with any contract management platform that supports webhooks or post-processing hooks.

DocuSign / contract management webhook pattern

When a signed contract is returned from an e-signature platform, the webhook payload includes a URL to the executed PDF. Before filing the document in your contract management system, send it through HTPBE:

import requests

def verify_signed_contract(document_url: str, contract_id: str) -> dict:
    """
    Verify a signed contract PDF before filing.
    Called from a DocuSign/PandaDoc/Ironclad webhook handler.
    """
    response = requests.post(
        "https://api.htpbe.tech/v1/analyze",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        json={"url": document_url},
    )
    result = response.json()

    if result["status"] == "modified":
        markers = result.get("modification_markers", [])
        certain_signals = [
            "MODIFICATIONS_AFTER_SIGNATURE",
            "SIGNATURE_REMOVED",
        ]
        is_critical = any(m in certain_signals for m in markers)

        return {
            "contract_id": contract_id,
            "action": "escalate" if is_critical else "flag_for_review",
            "check_id": result["id"],
            "markers": markers,
            "confidence": result.get("modification_confidence"),
        }

    if result["status"] == "inconclusive":
        return {
            "contract_id": contract_id,
            "action": "flag_for_review",
            "check_id": result["id"],
            "note": f"Consumer software origin: {result.get('producer')}",
        }

    # intact — file for the record
    return {
        "contract_id": contract_id,
        "action": "file",
        "check_id": result["id"],
    }

The check_id is stored alongside the contract record. If a dispute arises months later, the forensic report is retrievable via GET /api/v1/result/{check_id} — providing a timestamped integrity record that was created at the moment of filing.

Decision matrix for legal ops

Verdict	Confidence	Action
`intact`	—	File as executed. No further action.
`modified`	`certain`	Halt execution. Escalate to legal and counterparty immediately.
`modified`	`high`	Route to legal review queue. Compare against last approved draft.
`inconclusive`	—	Flag for manual review. Consumer software origin on a contract is unusual.

The inconclusive verdict deserves specific attention in the legal context. Contracts are institutional documents — generated by contract management platforms, e-signature tools, or law firm document systems. A contract PDF whose Producer field shows a consumer PDF editor is not necessarily fraudulent, but it is anomalous. Legitimate contracts do not typically pass through Smallpdf or iLovePDF during their lifecycle.

What This Approach Does Not Catch

Binary forensic analysis is not a complete contract fraud prevention system. The following are its boundaries:

Pre-signing alterations made in the same tool. If an attacker modifies contract terms in Microsoft Word before converting to PDF, the resulting PDF is a clean single-revision file. There are no incremental updates, no metadata divergence, no post-signature modifications. The file is structurally indistinguishable from a legitimate contract. This is why version control and redline comparison remain necessary for pre-execution review.

Contracts fabricated from scratch. If someone creates an entirely fake contract in the same software a legitimate party would use, with plausible metadata and consistent timestamps, structural analysis cannot distinguish it from a genuine document. Forensic analysis checks file integrity, not content truthfulness.

Password-protected PDFs. When a PDF is encrypted and the analysis tool cannot access its structure, the result is inconclusive. The file cannot be read, so its integrity cannot be assessed.

Edits made with forensically aware tools. An attacker who understands PDF structure could edit a document, reset metadata, and reconstruct the xref table to remove traces. This requires specialized knowledge beyond what standard PDF editors provide. It is theoretically possible but rare in practice.

Who Should Integrate Contract Fraud Detection

Contract management platforms — Ironclad, Icertis, Agiloft, ContractPodAi — that store and manage executed contracts. Adding a fraud detection step at filing ensures that the stored version is structurally consistent with the version that was signed.

E-signature workflow providers that process signed documents on behalf of clients. Checking document integrity between the signing event and delivery to the requesting party closes a gap in the chain of custody. This is especially relevant because forensic analysis works without the original file — the received document carries its own modification history.

Legal ops teams running due diligence on contract portfolios — M&A, audit, or compliance reviews where the integrity of hundreds or thousands of executed contracts needs fraud detection at scale.

In-house counsel receiving executed agreements from counterparties. A single API call before filing provides a permanent forensic record of the document’s state at the time of receipt.

The API documentation covers the full request/response specification. For a direct comparison of how HTPBE fits alongside KYC platforms and manual review for legal document workflows, see HTPBE vs. iDenfy vs. Manual Review. For a broader view of how PDF tamper detection fits into legal workflows, see the legal industry overview.

Test API keys are available on all plans — including free — and return deterministic responses for integration testing without consuming quota.

PDF Tamper Detection API for Python: Complete Integration Guide

Iurii Rogulia — Wed, 10 Jun 2026 11:00:37 +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 PDF your application accepts is a trust decision. An invoice triggers a payment. A bank statement determines a credit limit. A diploma qualifies a candidate. If the document was modified after creation, the decision it drives is based on false data — and your application made that decision automatically. For the business case, see why PDF tamper detection matters.

This guide walks through integrating the PDF tamper detection API into a Python application: from the first requests call to a production-ready client class with retry logic, typed responses, Django/Flask webhook patterns, and batch processing over cloud storage. All code is complete and working. For Node.js, see the Node.js integration guide. For a language-agnostic overview of what the API detects, see How to Detect PDF Tampering Programmatically.

Prerequisites

Python 3.10+
requests library (pip install requests)
An HTPBE API key (sign up → Dashboard → copy key)

Quick Start: Two API Calls

The HTPBE API uses a two-step flow. First, POST /analyze submits a publicly accessible PDF URL and returns a check ID. Then, GET /result/{id} retrieves the full verdict. Both steps use Bearer token authentication. (For a visual walkthrough of the 35-check forensic analysis that runs behind these endpoints, see the How It Works page.)

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.htpbe.tech/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Step 1: Submit the PDF URL for analysis
response = requests.post(
    f"{BASE_URL}/analyze",
    headers=HEADERS,
    json={"url": "https://api.htpbe.tech/v1/test/clean.pdf"},
)
response.raise_for_status()
check_id = response.json()["id"]

# Step 2: Retrieve the full verdict
result = requests.get(
    f"{BASE_URL}/result/{check_id}",
    headers=HEADERS,
).json()

print(result["status"])              # "intact", "modified", or "inconclusive"
print(result["modification_markers"])  # e.g. ["INCREMENTAL_UPDATES", "PRODUCER_MISMATCH"]
print(result["producer"])             # e.g. "Adobe PDF Library 15.0"
print(result["creator"])              # e.g. "Microsoft Word"

The URL https://api.htpbe.tech/v1/test/clean.pdf is a test mock — it returns a predictable intact response without consuming quota. We cover all test URLs in the testing section below.

Production Client Class

A production integration needs retry logic for transient failures, timeouts to prevent stalled connections, and typed responses so your IDE and type checker can assist you. Here is a complete client using dataclasses and requests.Session:

from dataclasses import dataclass
from typing import Optional
import time
import requests


@dataclass
class HTPBEResult:
    """Typed representation of the GET /result/{id} response."""

    id: str
    filename: str
    status: str  # "intact" | "modified" | "inconclusive"
    modification_confidence: Optional[str]  # "certain" | "high" | "none"
    modification_markers: list[str]

    creator: Optional[str]
    producer: Optional[str]
    creation_date: Optional[int]  # Unix timestamp
    modification_date: Optional[int]  # Unix timestamp

    xref_count: int
    has_incremental_updates: bool
    update_chain_length: int
    has_digital_signature: bool
    signature_removed: bool
    modifications_after_signature: bool

    file_size: int
    page_count: int
    pdf_version: Optional[str]

    @classmethod
    def from_dict(cls, data: dict) -> "HTPBEResult":
        return cls(
            id=data["id"],
            filename=data["filename"],
            status=data["status"],
            modification_confidence=data.get("modification_confidence"),
            modification_markers=data.get("modification_markers", []),
            creator=data.get("creator"),
            producer=data.get("producer"),
            creation_date=data.get("creation_date"),
            modification_date=data.get("modification_date"),
            xref_count=data.get("xref_count", 0),
            has_incremental_updates=data.get("has_incremental_updates", False),
            update_chain_length=data.get("update_chain_length", 0),
            has_digital_signature=data.get("has_digital_signature", False),
            signature_removed=data.get("signature_removed", False),
            modifications_after_signature=data.get(
                "modifications_after_signature", False
            ),
            file_size=data.get("file_size", 0),
            page_count=data.get("page_count", 0),
            pdf_version=data.get("pdf_version"),
        )


class HTPBEError(Exception):
    """Raised when the HTPBE API returns a non-2xx response."""

    def __init__(self, message: str, status_code: int, code: str):
        super().__init__(message)
        self.status_code = status_code
        self.code = code


class HTPBEClient:
    """Production-ready HTPBE API client with retry and timeout."""

    def __init__(
        self,
        api_key: str,
        base_url: str = "https://api.htpbe.tech/v1",
        timeout: float = 30.0,
    ):
        if not api_key:
            raise ValueError("HTPBE API key is required")

        self._session = requests.Session()
        self._session.headers.update(
            {
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json",
            }
        )
        self._base_url = base_url
        self._timeout = timeout

    def verify(self, pdf_url: str, retries: int = 3) -> HTPBEResult:
        """Submit a PDF URL for analysis and return the typed result.

        Retries only on 5xx errors with exponential backoff.
        Client errors (4xx) raise immediately.
        """
        last_error: Optional[HTPBEError] = None

        for attempt in range(retries):
            if attempt > 0:
                time.sleep(2 ** (attempt - 1))  # 1s, 2s, 4s

            try:
                check_id = self._submit(pdf_url)
                return self._get_result(check_id)
            except HTPBEError as exc:
                if exc.status_code < 500:
                    raise  # Client error — do not retry
                last_error = exc

        raise last_error  # type: ignore[misc]

    def _submit(self, pdf_url: str) -> str:
        resp = self._session.post(
            f"{self._base_url}/analyze",
            json={"url": pdf_url},
            timeout=self._timeout,
        )
        self._raise_for_error(resp)
        return resp.json()["id"]

    def _get_result(self, check_id: str) -> HTPBEResult:
        resp = self._session.get(
            f"{self._base_url}/result/{check_id}",
            timeout=self._timeout,
        )
        self._raise_for_error(resp)
        return HTPBEResult.from_dict(resp.json())

    @staticmethod
    def _raise_for_error(resp: requests.Response) -> None:
        if resp.ok:
            return

        try:
            body = resp.json()
        except ValueError:
            body = {"error": resp.text, "code": "UNKNOWN"}

        error_map = {
            400: ("BAD_REQUEST", f"Bad request: {body.get('error', '')}"),
            401: ("UNAUTHORIZED", "Invalid API key. Check your HTPBE_API_KEY."),
            402: ("SUBSCRIPTION_REQUIRED", "Subscription required. See htpbe.tech/pricing."),
            403: ("FORBIDDEN", "Access forbidden."),
            404: ("NOT_FOUND", "Check not found."),
            413: ("FILE_TOO_LARGE", "PDF exceeds the 10 MB size limit."),
            422: ("INVALID_PDF", "The URL did not return a valid PDF file."),
        }

        code, message = error_map.get(
            resp.status_code,
            (body.get("code", "UNKNOWN"), body.get("error", f"HTTP {resp.status_code}")),
        )
        raise HTPBEError(message, resp.status_code, code)

The retry logic only applies to 5xx responses. A 401 means your key is wrong — retrying will not help. A 422 means the URL did not return a valid PDF. Only server-side transient failures warrant a retry.

Handling All Three Verdicts

The API returns exactly one of three statuses. Each maps to a different action in your application:

def handle_document(client: HTPBEClient, pdf_url: str) -> str:
    result = client.verify(pdf_url)

    if result.status == "intact":
        # Document has not been modified since creation.
        # Safe to process automatically.
        return "accept"

    if result.status == "modified":
        # Post-creation changes detected.
        # modification_markers tells you exactly what was found:
        # e.g. ["INCREMENTAL_UPDATES", "PRODUCER_MISMATCH", "DIFFERENT_DATES"]
        print(f"Rejected: {result.modification_markers}")
        print(f"Confidence: {result.modification_confidence}")
        return "reject"

    # status == "inconclusive"
    # The document was created with consumer software (Word, Excel,
    # LibreOffice, Canva) rather than institutional document management
    # software. The API cannot verify its integrity because consumer
    # tools produce metadata patterns that overlap with editing tools.
    # This is NOT a failure — it is a specific, actionable finding.
    print(f"Consumer origin detected: {result.producer}")
    return "manual_review"

The inconclusive verdict requires special attention. It does not mean the check failed or that something went wrong. It means the document was created with consumer software — Microsoft Word, Excel, LibreOffice, Canva — and those tools produce metadata patterns that are indistinguishable from documents that have been opened and re-saved. For documents that claim institutional origin (bank statements, diplomas, contracts from enterprise systems), inconclusive is itself a warning signal: why does a document from a bank look like it was created in Word? Route it to human review. For a deeper explanation, see what “inconclusive” really means.

Django Integration: Document Upload Webhook

A common pattern in Django applications: a user uploads a PDF, your view stores it in S3 or another cloud provider, then checks it asynchronously before processing.

import os
from django.http import JsonResponse
from django.views.decorators.http import require_POST
from django.views.decorators.csrf import csrf_exempt

# Initialize once at module level — reuses the TCP connection
htpbe = HTPBEClient(api_key=os.environ["HTPBE_API_KEY"])


@csrf_exempt
@require_POST
def upload_invoice(request):
    """Handle invoice upload, verify PDF, route by verdict."""
    uploaded_file = request.FILES.get("invoice")
    if not uploaded_file:
        return JsonResponse({"error": "No file provided"}, status=400)

    # 1. Upload to your storage and get a public URL
    #    (replace with your actual storage logic)
    pdf_url = upload_to_s3(uploaded_file)

    # 2. Verify with HTPBE
    try:
        result = htpbe.verify(pdf_url)
    except HTPBEError as exc:
        if exc.code == "INVALID_PDF":
            return JsonResponse({"error": "Not a valid PDF"}, status=422)
        if exc.code == "FILE_TOO_LARGE":
            return JsonResponse({"error": "PDF must be under 10 MB"}, status=413)
        # Log unexpected errors, return a generic message
        import logging
        logging.exception("HTPBE verification failed")
        return JsonResponse(
            {"error": "Verification temporarily unavailable"}, status=503
        )

    # 3. Route based on verdict
    if result.status == "modified":
        flag_for_fraud_review(
            pdf_url=pdf_url,
            markers=result.modification_markers,
            confidence=result.modification_confidence,
        )
        return JsonResponse(
            {"status": "flagged", "reason": result.modification_markers},
            status=422,
        )

    if result.status == "inconclusive":
        queue_for_manual_review(pdf_url=pdf_url, result=result)
        return JsonResponse({"status": "pending_review"}, status=202)

    # intact — proceed with normal processing
    process_invoice(pdf_url=pdf_url, metadata=result)
    return JsonResponse({"status": "accepted", "check_id": result.id})

The same pattern works in Flask — replace the Django decorators with Flask route decorators and request.files instead of request.FILES.

Flask Equivalent

import os
from flask import Flask, request, jsonify

app = Flask(__name__)
htpbe = HTPBEClient(api_key=os.environ["HTPBE_API_KEY"])


@app.route("/api/documents", methods=["POST"])
def upload_document():
    uploaded_file = request.files.get("document")
    if not uploaded_file:
        return jsonify(error="No file provided"), 400

    pdf_url = upload_to_s3(uploaded_file)

    try:
        result = htpbe.verify(pdf_url)
    except HTPBEError as exc:
        if exc.status_code < 500:
            return jsonify(error=str(exc)), exc.status_code
        return jsonify(error="Verification unavailable"), 503

    if result.status == "modified":
        return jsonify(
            status="flagged",
            markers=result.modification_markers,
        ), 422

    if result.status == "inconclusive":
        return jsonify(status="pending_review"), 202

    return jsonify(status="accepted", check_id=result.id)

Batch Processing: S3 or GCS Bucket

For backfill scenarios — checking a bucket of existing documents — iterate over the objects and collect results. This example uses boto3 for AWS S3, but the pattern applies to any storage provider that gives you presigned URLs:

import boto3
import csv
from botocore.config import Config

s3 = boto3.client("s3", config=Config(signature_version="s3v4"))
htpbe = HTPBEClient(api_key=os.environ["HTPBE_API_KEY"])


def batch_verify_bucket(bucket: str, prefix: str = "") -> list[dict]:
    """Verify all PDFs in an S3 bucket prefix. Returns a summary list."""
    paginator = s3.get_paginator("list_objects_v2")
    results = []

    for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
        for obj in page.get("Contents", []):
            key = obj["Key"]
            if not key.lower().endswith(".pdf"):
                continue

            # Generate a presigned URL (valid for 5 minutes)
            presigned_url = s3.generate_presigned_url(
                "get_object",
                Params={"Bucket": bucket, "Key": key},
                ExpiresIn=300,
            )

            try:
                result = htpbe.verify(presigned_url)
                results.append({
                    "key": key,
                    "status": result.status,
                    "confidence": result.modification_confidence,
                    "markers": ", ".join(result.modification_markers),
                    "producer": result.producer,
                    "creator": result.creator,
                })
            except HTPBEError as exc:
                results.append({
                    "key": key,
                    "status": "error",
                    "confidence": None,
                    "markers": f"{exc.code}: {exc}",
                    "producer": None,
                    "creator": None,
                })

    return results


def export_to_csv(results: list[dict], output_path: str) -> None:
    """Write batch results to a CSV file for review."""
    if not results:
        return
    with open(output_path, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=results[0].keys())
        writer.writeheader()
        writer.writerows(results)


# Usage:
# results = batch_verify_bucket("my-documents-bucket", prefix="invoices/2026/")
# export_to_csv(results, "verification_report.csv")

For large buckets, add concurrent.futures.ThreadPoolExecutor to parallelize requests. The API handles concurrent calls — just stay within your plan’s rate limits.

Test Mode: Develop Without Live Documents

All ? plans — including the free tier — include a test API key. Test keys use mock URLs that return deterministic responses without consuming quota. Use them for integration testing and CI pipelines.

Test URL format: https://api.htpbe.tech/v1/test/{filename}.pdf

URL	`status`	What it simulates
`clean.pdf`	`intact`	Clean document, institutional origin
`clean-no-dates.pdf`	`intact`	No date metadata, unknown origin
`modified-low.pdf`	`modified`	Single incremental update
`modified-medium.pdf`	`modified`	Consumer software origin, multiple updates
`modified-high.pdf`	`modified`	Different producer, 5-link update chain
`modified-critical.pdf`	`modified`	Signature removed, JavaScript, Excel origin
`signature-removed.pdf`	`modified`	Digital signature stripped
`signature-valid.pdf`	`intact`	Valid digital signature present
`inconclusive.pdf`	`inconclusive`	Excel origin, no structural modifications
`dates-mismatch.pdf`	`modified`	ModDate 14 days after CreationDate

Use these in your test suite with pytest:

import os
import pytest

TEST_BASE = "https://api.htpbe.tech/v1/test"
client = HTPBEClient(api_key=os.environ["HTPBE_TEST_API_KEY"])


def test_intact_document():
    result = client.verify(f"{TEST_BASE}/clean.pdf")
    assert result.status == "intact"
    assert result.modification_markers == []


def test_modified_document():
    result = client.verify(f"{TEST_BASE}/modified-high.pdf")
    assert result.status == "modified"
    assert result.modification_confidence in ("certain", "high")
    assert len(result.modification_markers) > 0


def test_inconclusive_consumer_origin():
    result = client.verify(f"{TEST_BASE}/inconclusive.pdf")
    assert result.status == "inconclusive"
    # inconclusive is NOT an error — it means consumer software origin


def test_signature_removed():
    result = client.verify(f"{TEST_BASE}/signature-removed.pdf")
    assert result.status == "modified"
    assert result.signature_removed is True

Keep your test API key in a .env.test file and your production key in .env. Never commit either to version control.

What the API Does Not Detect

Understanding the limits is important when building a system that makes automated decisions:

Content-level changes within a single save. If someone creates a PDF in Word, types a fraudulent number, and exports once, the document has never been modified post-creation. It is structurally intact. The fraud happened at authorship, not at the file level.
Documents recreated from scratch. If an attacker recreates a document from scratch in the same software the original used and matches the metadata fields, the structural signals will not distinguish it from the original. This attack requires significant effort and is rare, but it is possible.
Encrypted or password-protected PDFs. The API cannot analyze a PDF it cannot parse. If the file requires a password to open, the analysis will return an error.
Scanned documents with no digital metadata. A photo of a document converted to PDF contains minimal structural metadata. These typically return inconclusive because the originating software is a scanner driver or image converter, not an institutional system. For more on what metadata fields the API reads and why, see the PDF metadata fields reference.

These limits are why HTPBE? works best as one layer in a fraud-detection workflow — not the only layer. Combine structural PDF analysis with domain-specific checks (amount validation, vendor database lookups, sender authentication) for a layered defense. See PDF Fraud Prevention Best Practices.

Choosing a Plan

Plans start at $15/month for 30 checks (Starter). The right tier depends on your document volume:

Starter ($15/mo, 30 checks): Low-volume workflows — a handful of documents per week. Good for initial production deployment.
Growth ($149/mo, 350 checks): The recommended starting point for applications with real users. Handles roughly 12 documents per day.
Pro ($499/mo, 1,500 checks): For platforms processing 40–50 documents per day. Per-check cost drops to $0.33.
Enterprise (custom): Volume pricing for 1,500+ checks per month.

When you reach your monthly quota, further requests return 402 PAYMENT_REQUIRED until the quota resets — add a one-time credit pack or move to a higher tier to keep going. Handle the 402 in your client so a quota boundary never silently drops a check.

Decisions Before You Ship

The integration surface is small: one POST, one GET, three verdicts. The decisions that matter are on your side:

inconclusive routing — for documents that claim institutional origin (bank statements, diplomas), treat inconclusive the same as modified and route to human review. For user-generated documents (cover letters, personal forms), it may be acceptable to proceed.
Where in your pipeline — check at intake, before any data extraction or business logic runs. Checking after processing does not prevent harm.
Test key separation — keep test and production keys in separate environment files. Test keys return synthetic data and must not be used in production flows.

The full API reference covers all response fields, error codes, and rate limits. To get started, sign up for a free account, copy your test key from the dashboard, and run the quick-start example above.

Next.js 16 proxy.ts Migration: From middleware.ts

Iurii Rogulia — Wed, 10 Jun 2026 10:00:35 +0000

Next.js 16 renamed middleware.ts to proxy.ts. The official reason is naming clarity — but unpacking why the name matters reveals a decade of misuse patterns and one memorable security incident that proved the conceptual confusion had real consequences. This is part of a broader architecture question covered in how I build a production SaaS checklist — where auth belongs in the stack.

This is not a cosmetic rename. The official migration docs are explicit about why the old name was wrong: "middleware" implied Express-style capabilities that this layer never had, led developers to treat it as a security boundary it was never designed to be, and accumulated so much misuse that the team felt the name itself was misleading. The rename is a deliberate signal — reach for proxy.ts as a last resort, not as your default request-handling strategy.

Here is the full picture: what changed, why the name mattered more than most people realized, the security incident that made the conceptual confusion concrete, and how to migrate auth correctly.

What Changed in Next.js 16

The API surface change is minimal. NextRequest, NextResponse, the config matcher — all identical. The differences:

The file is named proxy.ts (or proxy.js)
The exported function is named proxy, not middleware
The runtime is Node.js — Edge runtime is explicitly not supported
Several next.config.ts properties were renamed

middleware.ts still works but logs a deprecation warning. You have a migration window.

The Node.js runtime change is the structurally meaningful one. The proxy layer now runs at origin with full access to the Node.js ecosystem. The latency tradeoff is real and worth understanding before you migrate — more on that in the trade-offs section.

The official reasons given for the rename, straight from the docs:

Naming confusion with Express.js middleware — developers expected full Node.js capabilities and got a stripped-down Edge environment instead
Intent signal — the team wants this feature used as a last resort; the name "middleware" implied it was the standard interception point for all request logic
Clarifying the actual role — a proxy sits at a network boundary in front of the app; that is what proxy.ts does
Future direction — the team is actively working on better APIs so that most goals currently achieved in proxy.ts can be accomplished closer to the data, without needing the proxy layer at all

Why "Middleware" Was the Wrong Name All Along

The confusion did not start with a CVE. It started with a word.

Express.js popularized "middleware" as a concept: functions that intercept and process requests in sequence, running in the same Node.js process as your application, with full access to whatever npm packages you need. When Next.js introduced middleware.ts in Next.js 12, it borrowed the term for a structurally different thing: a thin interception layer running on the Edge runtime at CDN nodes, with a 25ms CPU time limit and no native Node.js modules.

Developers familiar with Express naturally expected Express-like behavior. They discovered the mismatch when they tried to import jsonwebtoken — which uses Node.js crypto APIs — and got a runtime error. The correct alternative was jose, a Web Crypto API-based library designed for edge environments. The error message was not helpful. The lesson — that this was not Express middleware — was learned the hard way by a lot of teams.

GitHub discussions #46722 and #71727 tracked years of demand for Node.js runtime access in middleware. The community wanted to use real libraries. The framework could not provide them without abandoning the Edge performance model. The tension was never resolved — it was dissolved by moving the runtime to Node.js and acknowledging in the name that this is not general-purpose middleware.

The second problem was overloading. In practice, middleware.ts became a catch-all: auth redirects, A/B testing, locale routing, logging, rate limiting, canary deployments, bot detection — all in one file with strict runtime limits. The more concerns you pile into a single network interception layer, the harder it is to reason about what any given request will actually do.

CVE-2025-29927: Exhibit A

In March 2025, a vulnerability was disclosed that crystallized the naming problem into something concrete.

Next.js used the x-middleware-subrequest header internally to track recursive middleware invocations and prevent infinite loops. If the header was already set when a request arrived, Next.js assumed the middleware had already run and skipped execution. An external attacker could set that header on any incoming request. Next.js would see it, conclude middleware had already executed, and serve the response without running any middleware code at all.

x-middleware-subrequest: middleware

Every application running Next.js 11.1.4 through 15.2.2 with authentication logic in middleware.ts was potentially vulnerable. Auth checks: skipped. Geo-blocking: skipped. Admin-only redirects: skipped. The UK National Cyber Security Centre issued a public advisory. Proof-of-concept exploits were circulating within days.

The patch was straightforward — validate the header's origin before trusting it. But the vulnerability exposed something that had been structurally true before the patch existed: middleware was never a reliable security boundary. The x-middleware-subrequest header was just the specific mechanism. The deeper issue was architectural. A layer designed for lightweight request interception was being used as the primary enforcement point for access control.

This is exactly the kind of failure mode the naming confusion produces. If you think you have "middleware" in the Express sense — something that runs reliably in your application's trust boundary — you will trust it as a security layer. If you think of it as a network proxy, you will not. The CVE did not change the architecture; it illustrated why the architecture had been misunderstood.

A second vulnerability, CVE-2025-66478, followed in December 2025 — a remote code execution issue that further eroded confidence in the security model of the layer.

The Codemod

The fastest path to migration is the official codemod:

npx @next/codemod@latest upgrade 16

The codemod handles four things:

Renames middleware.ts → proxy.ts
Renames the exported function from middleware to proxy
Renames next.config.ts properties:
- skipMiddlewareUrlNormalize → skipProxyUrlNormalize
- experimental.middlewarePrefetch → experimental.proxyPrefetch
- experimental.middlewareClientMaxBodySize → experimental.proxyClientMaxBodySize
- experimental.externalMiddlewareRewritesResolve → experimental.externalProxyRewritesResolve

One known edge case: GitHub issue #86478 documents a scenario where the codemod skips the file rename when it determines no content changes are needed. If your proxy.ts does not appear after running the codemod, rename the file manually.

Verify the output, run your tests, and proceed to the auth migration below — because the codemod does not touch your auth logic.

Manual Migration

The mechanical part of manual migration is a straightforward rename:

Before (middleware.ts):

import { NextRequest, NextResponse } from "next/server";

export function middleware(request: NextRequest) {
  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"],
};

After (proxy.ts):

import { NextRequest, NextResponse } from "next/server";

export function proxy(request: NextRequest) {
  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"],
};

Two characters changed in the function name. One filename changed. Everything else is identical.

If you have any of the renamed next.config.ts properties, update those as well. The TypeScript types will flag them as errors if you miss any.

The Auth Migration — Where Most Teams Get It Wrong

slug="rescue-projects"
text="Inherited a Next.js codebase with middleware-based auth or security patterns that rely on the proxy layer? I audit, identify the exposure, and migrate to a proper Data Access Layer."
/>

This is the section that actually matters. The mechanical rename is trivial. Getting auth right in the new model requires rethinking where validation belongs.

The old pattern looked something like this:

// middleware.ts — the vulnerable approach
import { NextRequest, NextResponse } from "next/server";
import { jwtVerify } from "jose";

const SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);

export async function middleware(request: NextRequest) {
  const token = request.cookies.get("session")?.value;
  if (!token) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  try {
    await jwtVerify(token, SECRET);
    return NextResponse.next();
  } catch {
    return NextResponse.redirect(new URL("/login", request.url));
  }
}

export const config = {
  matcher: ["/dashboard/:path*"],
};

This code did JWT verification in middleware. It used jose because jsonwebtoken did not work on the Edge runtime. It looked correct. It was the approach recommended in multiple Auth.js tutorials and Next.js blog posts.

The problem: this pattern is exactly what CVE-2025-29927 made irrelevant. An attacker with the right header never reached the jwtVerify call. The middleware was skipped entirely.

The deeper issue: even without the CVE, middleware-as-sole-security-boundary is architecturally wrong. If a bug in your routing logic accidentally serves a protected page without going through the matcher, the auth layer has no coverage there. If you add a new route and forget to update the matcher pattern, that route is unprotected. Security that depends on a routing config staying in sync with your actual routes is security waiting to fail.

The correct pattern in proxy.ts is an optimistic cookie existence check — not validation:

// proxy.ts — correct approach
import { NextRequest, NextResponse } from "next/server";

export function proxy(request: NextRequest) {
  const sessionCookie = request.cookies.get("session");

  if (!sessionCookie) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("from", request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*", "/account/:path*", "/api/private/:path*"],
};

Notice what this does not do: it does not verify the JWT signature. It does not decode the token. It does not check expiry. It checks one thing: does a cookie with the session name exist? If no cookie, redirect to login. If the cookie exists, let the request through and let the actual validation happen downstream.

This is not a security hole. It is a correct division of responsibility. The proxy layer handles the user experience concern — redirecting unauthenticated visitors to the login page before they see a flash of protected content. The actual security enforcement happens in a Data Access Layer that every Server Component and Route Handler calls:

// lib/auth.ts — server-only, the actual security boundary
import "server-only";
import { jwtVerify } from "jose";
import { cookies } from "next/headers";
import { cache } from "react";

const SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);

interface Session {
  userId: string;
  email: string;
  role: "user" | "admin";
  exp: number;
}

// cache() memoizes per request — jwtVerify runs once per request, not once per component
export const getSession = cache(async (): Promise<Session | null> => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (!token) return null;

  try {
    const { payload } = await jwtVerify(token, SECRET);
    return payload as unknown as Session;
  } catch {
    return null;
  }
});

export async function requireSession(): Promise<Session> {
  const session = await getSession();
  if (!session) {
    throw new Error("Unauthorized");
  }
  return session;
}

Every Server Component that renders protected data calls getSession() or requireSession(). Every Route Handler that serves private API endpoints calls it. The validation is colocated with the data access — not centralized in a network-level proxy that can be bypassed or misconfigured.

// app/dashboard/page.tsx
import { requireSession } from '@/lib/auth'
import { getUserData } from '@/lib/data'

export default async function DashboardPage() {
  // Throws if no valid session — caught by the nearest error boundary
  const session = await requireSession()
  const data = await getUserData(session.userId)

  return <Dashboard user={session} data={data} />
}

// app/api/private/orders/route.ts
import { NextResponse } from "next/server";
import { getSession } from "@/lib/auth";
import { getOrders } from "@/lib/data";

export async function GET() {
  const session = await getSession();
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const orders = await getOrders(session.userId);
  return NextResponse.json(orders);
}

The proxy layer handles the redirect. The Data Access Layer handles the enforcement. Neither depends on the other being correctly configured.

What Happens With a Tampered Cookie

A common concern: if proxy.ts only checks cookie existence, what stops an attacker from sending a fake session cookie with arbitrary content?

The answer is: the Data Access Layer. getSession() calls jwtVerify, which verifies the cryptographic signature using your JWT_SECRET. A cookie containing garbage, an expired token, or a token signed with the wrong key will fail jwtVerify and return null. The user gets treated as unauthenticated and receives a 401 or an error boundary response — not access to protected data.

The proxy redirect is a UX optimization. The Data Access Layer is the enforcement mechanism. These roles do not overlap.

What proxy.ts Is Actually For

With auth correctly handled downstream, the proxy layer is free to do what it is actually good at:

Programmatic redirects based on request properties:

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Redirect legacy URLs
  if (pathname.startsWith("/old-dashboard")) {
    return NextResponse.redirect(
      new URL(pathname.replace("/old-dashboard", "/dashboard"), request.url),
      { status: 301 }
    );
  }

  return NextResponse.next();
}

URL rewrites for A/B testing:

export function proxy(request: NextRequest) {
  const bucket = request.cookies.get("ab-bucket")?.value ?? "control";

  if (request.nextUrl.pathname === "/pricing") {
    return NextResponse.rewrite(new URL(`/pricing-${bucket}`, request.url));
  }

  return NextResponse.next();
}

Locale routing (also covered in depth in Next.js i18n at Scale):

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const locale =
    request.cookies.get("locale")?.value ??
    request.headers.get("accept-language")?.split(",")[0]?.split("-")[0] ??
    "en";

  if (!pathname.startsWith(`/${locale}`)) {
    return NextResponse.redirect(new URL(`/${locale}${pathname}`, request.url));
  }

  return NextResponse.next();
}

Modifying headers for downstream use:

export function proxy(request: NextRequest) {
  const response = NextResponse.next();

  // Pass request metadata downstream without re-reading headers
  response.headers.set("x-request-id", crypto.randomUUID());
  response.headers.set("x-pathname", request.nextUrl.pathname);

  return response;
}

These are the proxy layer's strengths: thin request inspection, lightweight branching, header manipulation. Nothing that requires heavy computation, database access, or cryptographic operations. In pikkuna.fi and pi-pi.ee, locale routing is exactly what the proxy layer is used for — detecting the user's preferred language and rewriting the URL before the request reaches the application.

The Trade-offs You Should Know Before Migrating

Edge Performance Loss

The original middleware.ts ran at the CDN edge — geographically close to the user. For a user in Stockholm hitting Cloudflare's edge node in Frankfurt, middleware executed in 1–2ms of round-trip latency. Redirects were fast because they happened before the request ever reached origin.

proxy.ts runs on Node.js at origin. For the same Stockholm user, a redirect now requires a round trip to wherever your origin server sits. If your origin is in us-east-1, that is 80–100ms of added latency for every redirect.

For most applications, this is acceptable. But if you have high-traffic redirect logic — locale routing that fires on every request, aggressive A/B test bucketing — measure the latency impact before migrating. Alternatively, move that logic to Cloudflare Workers or your CDN's edge functions, which are purpose-built for it.

The Cloudflare Compatibility Bug

As of this writing, there is an open issue (#86122) where proxy.ts does not execute when the application is deployed behind Cloudflare Proxy in production. The old middleware.ts works correctly in the same setup.

This affects self-hosted deployments that use Cloudflare for DDoS protection and CDN. If you run your Next.js application on a VPS with Cloudflare in proxy mode — which is common for EU teams trying to avoid Vercel costs — test proxy.ts thoroughly in staging before cutting over. The issue is open and being tracked, but there is no timeline for resolution.

For context: the vatnode.dev setup (Turborepo monorepo, Hono API on VPS, Next.js frontend) uses Coolify for deployment and sits behind Cloudflare. This bug is directly relevant. The current workaround is to keep middleware.ts on affected deployments and wait for the upstream fix, or route proxy logic through Cloudflare Workers instead.

Third-Party Library Churn

Auth.js (formerly NextAuth), Auth0's Next.js SDK, Better Auth, and every internationalization library that hooks into middleware — all had to update their integrations when Next.js 16 landed. If you rely on any of these, check that you are on a version that supports proxy.ts before upgrading Next.js.

next-intl, for example, published a migration guide alongside the Next.js 16 release. The API change is minor, but the update is required.

The Broader Lesson

CVE-2025-29927 was a specific vulnerability with a specific patch. But the rename to proxy.ts is responding to something larger: years of ecosystem confusion about what this layer was supposed to do.

The team's own framing in the migration docs is telling: they are actively working on better APIs so that developers can achieve their goals without the proxy layer. The direction is not "use proxy.ts more confidently" — it is "use proxy.ts less, and understand exactly why you are using it when you do."

When a security boundary is defined by a routing config that can go out of sync, by a runtime that cannot run real crypto libraries, and by a name that implies capabilities it does not have — you get defensive code in the wrong place, false confidence in that defensive code, and eventually a CVE that proves the confidence was misplaced.

The architectural lesson is not specific to Next.js. It applies to any framework with a request interception layer: thin interception should not be your security boundary. The security boundary should be colocated with the data, in code that runs every time the data is accessed, under a runtime that can actually enforce access controls.

proxy.ts makes this division explicit in the name. It will not stop teams from putting auth logic in the proxy layer — the API allows it. But the name makes the intent harder to misread.

Building something on Next.js 16 that needs production-grade auth, multi-region routing, or EU compliance? These are problems I've solved across vatnode.dev, pikkuna.fi, and pi-pi.ee. If your codebase needs security-focused rescue work or technical consultation on the auth architecture specifically, I can step in either way. If you need a senior developer who can own the architecture end-to-end — get in touch.

Related reading:

How to Build a SaaS with Next.js: Production Checklist — auth architecture, billing, and production readiness in one place
Stripe Webhooks Done Right: Production Architecture — another security-sensitive layer where naive implementations fail
Redis Rate Limiting in Production — protecting API endpoints with sliding window counters
Next.js 16 release post — official announcement including the proxy.ts introduction
Official migration reference — nextjs.org/docs/messages/middleware-to-proxy

Business Process Automation Case Study: 40 Hours/Month Saved

Iurii Rogulia — Tue, 09 Jun 2026 10:00:37 +0000

Nobody called it a problem. It was just how things worked.

A mid-size distributor, around 50 employees, processing roughly 80 orders per week. When a customer confirmed an order, a logistics coordinator would sit down and work through the same sequence, every time. Copy the customer information into the shipping software. Update the inventory spreadsheet. Email the warehouse a formatted order summary. Create a PDF invoice in the accounting system. Email the customer with the invoice and an estimated delivery date.

Twenty-five to thirty-five minutes per order. At 80 orders a week, that's somewhere between 40 and 45 hours a month — a full working week, spent on manual data entry.

The coordinator had been doing this for four years. There was a part-time assistant who helped during busy periods. Neither of them was doing anything wrong. They were doing the job as it existed.

What Changed

After mapping the process, it took about two weeks to build the automation. Not because it was complicated — but because we took the time to do it carefully, test it against edge cases, and make sure the exceptions were handled thoughtfully.

After the change: when an order is confirmed, the shipping software updates automatically. Inventory adjusts in real time. The warehouse receives a formatted notification within seconds. The invoice is generated and sent without anyone touching it. The customer gets a confirmation and tracking information within minutes of payment.

Human time per routine order: zero.

slug="automation-workflows"
text="If your team runs repeatable manual processes — copying data, generating reports, sending confirmations — I map and automate them. The savings are usually faster than you'd expect."
/>

The coordinator now handles customer relationships, resolves exceptions, and manages the cases that genuinely need a person — address problems, special requests, complaints. The work that actually requires judgment. The part-time assistant's hours were reallocated to a different project.

The error rate on routine orders went to effectively zero. Previously, occasional data-entry mistakes caused delivery problems — wrong addresses transcribed, quantities miscopied. Not often, but often enough. Those errors disappeared.

The Numbers

Before	After
25–35 min per order (manual)	~0 min per routine order
~40 hours/month in coordinator time	Manual review for exceptions only
Occasional data-entry errors causing delivery issues	Error rate effectively zero
Part-time assistant required for peak periods	Hours reallocated

The cost to build the automation was a fraction of one year's worth of the time it recovered. By month three, it had paid for itself.

The Harder Point

This company didn't have a technology problem. They had an unexamined process.

Nobody had sat down and asked: does this sequence of steps need a human? Each step, individually, felt necessary. Copy this information, send that email, update this sheet. But looked at as a whole, the sequence was almost entirely mechanical — the same inputs producing the same outputs in the same order, every time. That's not a human task. It only became one because nobody had looked at it that way.

Most companies I work with have three to five processes like this. They don't look like automation opportunities. They look like "how things work." There's often one specific person who does them, and they're good at it, and the process runs reliably enough that it doesn't feel like a problem. That combination — competent execution of an inefficient process — is almost always a sign. The 5 signs your IT is costing more than it saves post runs through the broader diagnostic — this case fits sign number one almost exactly.

The question isn't whether your team is working hard. It's whether they're working on things that need them. A similar pattern played out at Pikkuna, where end-to-end order automation — Stripe through PostNord through Mailgun — reduced the per-order manual burden to zero across 35 countries.

If your team has processes like this — repeatable, manual, time-consuming — let's map them out. The savings are usually faster than you'd expect.

PDF Forensics Without the Original File: One-Sided Fraud Detection

Iurii Rogulia — Tue, 09 Jun 2026 10:00:34 +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.

The most common question we get from teams evaluating PDF tamper detection tools: "Do we need to keep a copy of the original?"

The answer is no — and understanding why reveals something important about how PDF files work and why tampering is harder to hide than most people assume.

The comparison trap

The obvious approach to detecting whether a document was modified is comparison: keep the original, compare it to what you received, flag the differences. This is how tools like Draftable, Adobe Compare Documents, and diff utilities work.

The comparison approach has a structural problem: it requires you to have the original. In most fraud scenarios, you do not. You received an invoice, a diploma, a bank statement, or a contract from a counterparty. You have the document they sent you. You do not have what the document looked like before they sent it.

If an attacker modified the bank account number on an invoice before sending it to you, you have no original to compare against. You have one file. Comparison-based tools cannot help you.

Forensic analysis works differently. It does not compare the document against anything external. It reads what the document preserved about its own history.

What a PDF knows about itself

The PDF specification was designed around a model of incremental updates. When a PDF is edited and saved, the editing software does not rewrite the entire file — it appends the changes to the end and adds a new cross-reference table pointing to the updated objects. The original content remains in the file.

This design decision, intended for efficiency, has a forensic consequence: a modified PDF carries a structural record of that modification.

When a document is analyzed without the original, the analysis reads:

The cross-reference (xref) chain. How many edit sessions does the file contain? Each incremental update adds at least one xref section. A document created in one session has one xref. A document created and then edited has at least two. The chain length tells you how many times the file changed hands between creation and analysis.

The metadata record. The PDF Info dictionary stores CreationDate and ModDate as part of the file’s standard metadata. These fields record when the document was created and when it was last modified. When a document submitted as a fresh bank statement shows a modification date six months after the creation date, the document was modified — even without a copy of the bank statement from six months ago to compare against.

The authoring trail. The Creator field identifies the software used to create the document. The Producer field identifies the software that last processed it. When a document claims to be a corporate tax filing but was last processed by a free consumer PDF editor, the authoring trail contradicts the claimed origin.

The signature binding. Digital signatures in PDFs cryptographically bind a checksum to a specific byte range of the file. When content is appended after a signature, the signature remains valid for the content it covers — but the document now contains unsigned content. This pattern is detectable without the original: the signature’s byte range does not extend to the end of the file, and xref entries exist outside the signed range.

The limits of one-sided analysis

Honesty about what this approach cannot detect:

Content changes to unsigned documents. If an attacker edits a text field in an unsigned PDF and the editing software rewrites the file cleanly — removing evidence of prior xref structure, preserving or backdating timestamps — the structural record may not reveal the edit. This requires sophisticated tooling and deliberate counter-forensic effort. It is possible, but it is not what most fraud uses. Most fraud uses off-the-shelf PDF editors that leave clear traces.

Fabricated documents created from scratch. If an attacker builds a document in the same software a legitimate issuer uses, sets plausible timestamps, and produces a structurally consistent file — one-sided analysis cannot distinguish it from a genuine document. Structural forensics alone cannot determine that the content is truthful, only that the file is structurally consistent with its claimed origin.

Encrypted documents. Strong encryption prevents reading the structural content of a PDF. Analysis returns inconclusive when the file cannot be read.

For the fraud patterns that account for the vast majority of real-world document fraud — editing existing documents with consumer software, modifying bank details on legitimate invoices, altering figures on real financial statements — one-sided forensic analysis catches them reliably.

Why most fraud does not evade one-sided analysis

Real-world invoice fraud and document tampering is not performed by people with forensic knowledge of the PDF specification. It is performed by attackers who:

Download a legitimate PDF
Open it in iLovePDF, PDF24, Adobe Acrobat Reader (free), or a similar tool
Change the relevant text
Save and send

Every step of this process leaves marks:

The consumer editor rewrites the Producer field to its own name. It creates a new xref entry. It updates the modification date. It may not preserve the original structure cleanly.

The resulting file shows all the signals that one-sided analysis reads: multiple xref tables, a Producer that contradicts the document’s claimed origin, a modification date inconsistent with the claimed issuance date.

A practical example: bank statement fraud

A lender requests three months of bank statements from a loan applicant. The applicant downloads genuine statements from their bank’s online portal — PDF files generated by the bank’s document system. They then edit the statements to inflate the account balances, using a free online PDF editor.

The lender has no original statements. They cannot compare the submitted documents against bank records. What they have is one PDF per month.

What those PDFs preserve:

Creator: HSBC Document Service (the bank’s original authoring software)
Producer: Smallpdf (the free editor used to modify the file)
CreationDate: 2025-12-01 (when the bank generated the statement)
ModDate: 2026-03-15 (when the applicant modified it before submission)
xref_count: 3 (original creation + two editing sessions)

The forensic verdict: MODIFIED with markers PRODUCER_MISMATCH and INCREMENTAL_UPDATES.

The lender did not need the original bank statements. The modified file told them everything.

The API call

One-sided forensic analysis runs as a single HTTP call against the PDF forensics API — no original document, no comparison corpus, no per-file setup.

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/statement-dec.pdf"}'

The response includes both the verdict and the specific signals:

{
  "status": "modified",
  "modification_confidence": "high",
  "modification_markers": ["PRODUCER_MISMATCH", "INCREMENTAL_UPDATES"],
  "creator": "HSBC Document Service",
  "producer": "Smallpdf",
  "creation_date": 1764547200,
  "modification_date": 1742688000,
  "xref_count": 3
}

No original file required. No comparison. One HTTP call.

When to use one-sided analysis vs. comparison

Use one-sided forensic analysis when:

You receive documents from third parties and do not have originals
You process documents at scale and need automation
You need to audit a backlog of documents you received in the past
You are building this into an API workflow

Use comparison when:

You have both the original and the received version
You want to see exactly what changed (field by field, pixel by pixel)
You are doing manual forensic review of a specific document with known original

These approaches are complementary, not competing. Forensic analysis tells you whether a document was modified. Comparison shows you what changed. In most fraud scenarios, you only have the modified version — comparison is not available to you.

Integrating into document intake

The pattern that works for any document intake workflow:

def process_received_document(doc_url: str, doc_type: str) -> dict:
    """
    Run one-sided forensic analysis on a received document.
    doc_type: "bank_statement" | "invoice" | "contract" | "certificate"
    """
    result = verify_pdf(doc_url)  # see developer guide for full client code

    if result["status"] == "intact":
        return {"action": "accept", "check_id": result["id"]}

    if result["status"] == "modified":
        return {
            "action": "reject",
            "check_id": result["id"],
            "markers": result["modification_markers"],
            "note": "Document shows forensic signs of post-creation modification",
        }

    # inconclusive — consumer software
    # For documents claiming institutional origin, treat as suspicious
    institutional_doc_types = {"bank_statement", "tax_certificate", "official_contract"}
    if doc_type in institutional_doc_types:
        return {
            "action": "review",
            "check_id": result["id"],
            "note": f"Document origin ({result['producer']}) inconsistent with {doc_type}",
        }

    return {"action": "accept", "check_id": result["id"]}

The check_id is stored alongside the document record. If a document is later disputed, the forensic report is retrievable via GET /api/v1/result/{check_id} — a permanent audit trail that does not require storing the original document.

What this means for compliance teams

For compliance workflows that receive third-party documents — KYC onboarding, loan applications, insurance claims, contract execution — one-sided fraud detection changes the math on document fraud detection. The same principle applies in government procurement and benefits programs, where agencies receive permits, contractor credentials, and benefit application support documents from external parties without holding originals to compare against.

Previously: catch fraud only when the original is available for comparison, or rely on manual review that misses structural signals.

With forensic analysis: every received document is automatically checked against its own preserved history. The document does not need to be caught against an original. It just needs to have been modified.

This is not foolproof — sophisticated forgery from scratch evades it. But it reliably catches the category of fraud that accounts for the majority of real-world document manipulation: taking a legitimate document and editing it with available tools.

Freelance Developer vs IT Partner: What's the Difference?

Iurii Rogulia — Mon, 08 Jun 2026 10:00:33 +0000

A developer's job is to build what you describe. An IT partner's job is to figure out what you should actually build — and then build it.

That distinction sounds minor. It isn't.

The Same Budget, Two Different Outcomes

Here's a situation I've seen play out more than once.

A company comes to a developer with a clear request: "We need a website with a product catalog and a contact form." The developer builds exactly that. The project delivers on time, on budget, technically correct. Six months later: no traffic, no leads, the catalog is already out of date because updating it requires technical skills nobody on the team has, and the contact form emails are going to an inbox nobody checks.

The developer didn't do anything wrong. They did their job correctly. The problem is that someone needed to ask the business questions before a line of code was written — and that wasn't the developer's job.

Now take the same company, same budget, same request — but this time they're talking to someone who asks questions first.

Before any design or code, there's a 30-minute conversation. Who are your customers? How do they find you today? What do you want them to do when they arrive at your site? What happens after they submit a form — who sees it, and how fast? After those 30 minutes, the answer might look completely different: you don't need a catalog at all. You need a landing page built around the three services people actually buy, connected to your CRM so leads don't fall through the cracks.

Same budget. Completely different outcome.

The Questions That Should Come Before the Code

When a new client describes a project to me, I spend the first part of the conversation asking about their business, not the technology. What are they selling, and to whom? What does success look like in 12 months? What's the most painful part of how things work today?

The technology is how we solve the problem. Understanding the problem comes first.

This matters especially for companies hiring outside IT help for the first time. If nobody is asking the business questions, you end up with technically correct solutions to the wrong problems. The code works. It just doesn't do what you needed.

This is also where experience shows. After 25 years of development and 12 years as CTO of a logistics company, I've been involved in enough projects to recognize, early in a conversation, when someone is asking for a thing when they actually need a different thing. Sometimes what they've described is exactly right. But at least the idea has been pressure-tested before anyone starts building. When the stakes are higher — a major platform decision or an acquisition — that same discipline is what technical due diligence provides formally.

slug="fractional-cto"
text="If you're not sure whether you need a developer or someone to own the bigger technical picture, that question itself is the answer. I work as an IT partner for growing businesses — asking the hard questions before a line of code is written."
/>

What This Looks Like in Practice

An IT partner relationship doesn't mean your project takes longer or costs more. It means the conversation before the work is different.

Instead of receiving a specification and starting immediately, there's a brief period of asking uncomfortable questions. What problem are we actually solving? Who will maintain this after it's built? What happens when it breaks? Is this the right tool for this job, or is it the tool you happened to think of first?

Those questions take maybe a few hours. They can save months of rebuilding something that technically worked but practically didn't.

The companies I do my best work with are the ones who come in willing to have that conversation — where the brief is a starting point for thinking, not a contract I'm being hired to execute. Those projects tend to be more focused, finish faster, and produce something the client actually uses rather than something that gets quietly shelved. The pi-pi.ee B2B platform — 28 languages, 32 EU markets, six payment methods — started with exactly that kind of conversation, not a specification document. The result was a system the team actually uses across borders, not a deliverable that got filed away. For a broader look at what this ownership model means day-to-day, see what a fractional CTO actually does.

If you have an IT project and you're not sure you're solving the right problem, let's talk before you build anything.

Fake Invoice Detection: What PDF Metadata Reveals

Iurii Rogulia — Mon, 08 Jun 2026 10:00:31 +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.

Invoice fraud costs businesses an estimated $300 billion annually. The majority of fraudulent invoices succeed not because they look convincing, but because the organizations receiving them rely entirely on visual review. The same detection logic that applies to invoices applies equally to contracts: altered contract PDFs change payment terms or bank details after signing, and insurance claims fraud inflates repair estimates and medical bills before submission — using the same consumer editing tools and leaving the same structural traces.

A finance team member opens a PDF, confirms the vendor name, checks the amount against a purchase order, and approves payment. What that review misses is invisible to the eye but readable in milliseconds by forensic analysis: who modified the file, with what software, and when.

This guide covers what metadata signals reveal invoice fraud, how attackers modify invoices, and how to automate detection at scale.

Why visual review fails

Consider the most common invoice fraud pattern: business email compromise with modified bank details. An attacker intercepts a legitimate vendor invoice — either by compromising email or by social engineering — and replaces the bank account number before forwarding it to accounts payable. The invoice looks identical to every previous invoice from that vendor. The amount is correct. The logo is correct. The line items match the purchase order.

The only thing that changed is two lines of text: the account number and the sort code.

A human reviewer has no way to know the document was modified. The PDF looks the same as it always has. But the file is not the same — and the file preserves evidence that the human reviewer never sees.

What happens to a PDF when it is edited

PDF files store changes incrementally. When an editor opens a PDF and makes a change, the original content is preserved and the new content is appended. The file grows. A new cross-reference table (xref) entry is written at the end of the file pointing to the updated content.

This means an invoice modified once has at least two xref tables. Modified three times: at least four. The original creation content is still in the file, alongside every subsequent edit. A forensic analysis reads this structure.

Beyond structure, two other records are left:

The modification timestamp. PDF embeds a ModDate field in its Info dictionary. Many editors update this automatically when saving. An invoice from three months ago showing a modification date of yesterday has been touched recently.

The Producer field. This identifies the software that last processed the file. An invoice generated by an enterprise accounting system showing iLovePDF or PDF24 as producer has been through a consumer PDF editor — something that should not appear on an original vendor invoice.

The four signals that catch most invoice fraud

1. Producer field mismatch

Legitimate invoices from vendors using professional billing systems — SAP, Oracle, QuickBooks, Xero, Sage — have consistent Producer fields reflecting their software stack. An invoice claiming to come from an enterprise vendor but showing a consumer editor as Producer is immediately suspect.

This is the signal that catches the largest category of invoice fraud: attackers who download a legitimate invoice, open it in a free PDF editor to change the bank details, and re-save it. The editor writes its own name into the Producer field.

2. Modification date after receipt

If you record when a document was received and compare it against the document’s embedded modification date, a modification date that post-dates receipt is impossible under normal circumstances. The document was modified after you received it — either before forwarding within your organization, or by someone who intercepted and re-sent it.

3. Multiple xref tables in a single-session document

A document generated once by an accounting system should have one xref table representing a single authoring session. Multiple xref tables in what should be a freshly generated document indicate editing after generation.

This signal requires context: some legitimate documents do have multiple xref tables (signed documents that had a signature field added, for example). Combined with other signals, it becomes highly indicative.

4. Metadata completeness and consistency

Professional invoicing software generates documents with complete, consistent metadata: creator, producer, creation date, modification date all populated and coherent. Fabricated or heavily modified invoices frequently have incomplete metadata — missing dates, empty creator fields, or timestamps that are clearly defaults rather than real values.

A metadata completeness score below a threshold is not proof of fraud, but it raises the probability of a non-institutional document origin.

What attackers do — and what gives them away

Bank detail replacement (most common). Attacker opens the invoice in any PDF editor, modifies the account number, saves. Result: Producer field changes to the editor’s name. Modification date updates. Xref count increases.

Amount modification. Attacker inflates the invoice total. Same signals as bank detail replacement, plus often a date anomaly if the original invoice had been on file for a while before the modification.

Duplicate invoice with modified details. Attacker copies an old invoice and modifies multiple fields. The file retains the original’s creation date but shows a recent modification date — and often a different Producer than the original.

Fabricated invoice from scratch. Attacker builds a new invoice in design software (Canva, Microsoft Word, Google Docs) and exports to PDF. The Creator field reveals the software used. The document lacks the structural characteristics of professionally generated invoices. This is the pattern inconclusive verdicts often catch — the origin is consumer software, which is incompatible with a claimed enterprise vendor.

Automated detection in an AP workflow

The pattern for AP automation:

Vendor submits invoice (email attachment, supplier portal upload, EDI)
Before any human touches it, run forensic analysis via the invoice fraud detection API
Route based on verdict: intact → normal processing, modified → flag for investigation, inconclusive → secondary review if the vendor claims enterprise billing system

import httpx
import os

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


def check_invoice(invoice_url: str, vendor_name: str) -> dict:
    """
    Run forensic analysis on an invoice PDF.
    Returns a dict with action and details for the AP system.
    """
    submit = httpx.post(
        f"{BASE_URL}/analyze",
        headers=HEADERS,
        json={"url": invoice_url},
        timeout=30,
    )
    submit.raise_for_status()
    check_id = submit.json()["id"]

    result = httpx.get(
        f"{BASE_URL}/result/{check_id}",
        headers=HEADERS,
        timeout=30,
    )
    result.raise_for_status()
    data = result.json()

    status = data["status"]
    markers = data.get("modification_markers", [])
    producer = data.get("producer", "unknown")

    if status == "intact":
        return {
            "action": "process",
            "vendor": vendor_name,
            "check_id": check_id,
        }

    if status == "modified":
        return {
            "action": "hold",
            "vendor": vendor_name,
            "check_id": check_id,
            "reason": f"Forensic markers detected: {', '.join(markers)}",
            "producer": producer,
        }

    # inconclusive — consumer software origin
    return {
        "action": "review",
        "vendor": vendor_name,
        "check_id": check_id,
        "reason": f"Invoice generated by consumer software: {producer}",
    }

The check_id returned by the API is a permanent reference — link it to your invoice record so your finance team can view the full forensic report when investigating a flagged payment.

What to do when an invoice is flagged

A modified verdict does not automatically mean fraud. It means the file was edited. Legitimate reasons exist: a vendor corrected a typo, your team redacted sensitive information before filing, a PDF printer regenerated the file during email transmission.

The forensic report tells you which specific signals triggered the verdict. PRODUCER_MISMATCH with iLovePDF as producer and a recent modification date is a strong fraud signal. A single extra xref table with no modification date change and a consistent Producer may warrant calling the vendor to confirm the document is unchanged.

The response workflow:

Put the payment on hold immediately
Retrieve the full forensic report (the check_id links to it in your dashboard)
Contact the vendor through a checked channel — not by replying to the email that carried the invoice
Confirm account details verbally or through your vendor portal
If fraud is confirmed: report to your bank immediately (many jurisdictions have 24-hour windows for payment recall), and to relevant law enforcement

False positive rate

Modern forensic PDF analysis on invoice documents has a low false positive rate for the specific case of bank detail modification — the most common fraud pattern. Producer field analysis is highly specific: a vendor that generates invoices through a professional billing system will have a consistent Producer across all invoices. Deviation is meaningful.

The higher false positive rate appears in edge cases: vendors who genuinely do use consumer PDF tools (small sole traders using Canva invoices), documents that were legitimately converted between formats, or signed documents where the signing software appended its own xref entry.

For these cases, the inconclusive verdict is the appropriate output rather than modified. A sole trader using Google Docs to generate invoices will return inconclusive, not modified — flagged for review rather than automatic rejection.

Scaling the check

For high-volume AP operations, the check runs asynchronously and takes under two seconds per document. At the Growth plan rate, 350 checks per month covers roughly 12 invoice checks per working day — appropriate for a mid-size AP team. The Pro plan (1,500 checks) covers up to 50 checks per day.

The cost per prevented fraudulent payment is essentially zero. The average business email compromise invoice fraud loss is $50,000–$200,000 per incident. A month of Pro API access costs $499.

Reverse-Charge VAT for B2B SaaS: Node.js Implementation Checklist

Iurii Rogulia — Mon, 08 Jun 2026 09:00:37 +0000

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

Most EU B2B SaaS billing systems converge on the same flow: the buyer enters a VAT ID at checkout, the seller validates it, and if the validation passes the invoice is issued without VAT and labelled as a reverse-charge supply. The mechanism itself is well-documented in Council Directive 2006/112/EC — Article 44 (place of supply of services to a taxable person) and Article 196 (the reverse charge for services). What is less well-documented is what your code actually has to do to implement it correctly. This is that checklist.

This post focuses on SaaS — i.e. services, not goods. Article 138 (intra-EU supply of goods) and the related goods-side rules sit on a different code path and are out of scope here. Scope-wise, this post also stops at the invoice-issuance boundary: credit notes, partial refunds, subscription proration, jurisdiction-specific invoice immutability rules, and the e-invoicing / Peppol direction that EU member states are converging on each deserve their own treatment.

The reverse-charge concept guide covers the legal frame. This post is the engineering counterpart: what to validate, when to flag, what to store, and where the real-world edge cases sit.

Preconditions: when reverse-charge applies

Before any code runs, four conditions need to hold for a B2B SaaS supply to qualify for reverse-charge treatment:

You (the seller) are established in one EU member state. If you are outside the EU but selling into it, different rules apply — OSS / IOSS are simplification schemes for distance sales and certain B2C / low-value flows; they sit alongside reverse-charge, not in opposition to it, and a non-EU seller's path to B2B EU customers may still involve a reverse-charge treatment under local rules. They are not the topic of this post.
The buyer is established in a different EU member state from you.
The buyer is a taxable person — i.e. a business registered for VAT — and you can demonstrate it. National tax authorities accept "reasonable evidence" of taxable-person status, but a VIES-confirmed validation with a stored consultation number is the strongest practical standard most SaaS companies can produce and the one auditors are most likely to expect by default.
The service falls under the general B2B rule (Article 44). For most SaaS — software access, hosting, support — it does. Edge cases (telecoms, broadcasting, certain digital services to specific buyers) can land under different place-of-supply rules.

If any of these fails, your invoice is not a reverse-charge invoice. Domestic supplies, B2C supplies, and supplies to buyers in your own member state all charge VAT normally.

The most common bug we see in early-stage B2B SaaS billing is treating "the buyer entered a VAT ID" as sufficient. It isn't. The VAT ID has to be valid in VIES, the buyer's country has to differ from yours, and you have to keep evidence of the check. Skipping any one of those puts you in the position of having issued zero-VAT invoices that an auditor can reclassify as VAT-inclusive, with you on the hook for the missing VAT.

The decision function

The whole thing collapses into a single decision function that runs on every B2B invoice. Everything else in this post is what feeds it.

type ReverseChargeDecision =
  | { applyReverseCharge: true; evidence: VatEvidence }
  | { applyReverseCharge: false; reason: ReverseChargeBlockedReason }

type ReverseChargeBlockedReason =
  | 'BUYER_SAME_COUNTRY_AS_SELLER'
  | 'BUYER_VAT_INVALID'
  | 'BUYER_VAT_NOT_PROVIDED'
  | 'BUYER_OUTSIDE_EU'
  | 'VIES_UNAVAILABLE_NO_FALLBACK'

interface VatEvidence {
  vatId: string
  source: 'VIES' | 'NATIONAL_FALLBACK'
  consultationNumber: string | null
  traderName: string | null
  traderAddress: string | null
  checkedAt: string // ISO timestamp
}

function decideReverseCharge(input: {
  sellerCountry: string
  buyer: { country: string; vatId: string | null }
  vatCheck: VatCheckResult | null
}): ReverseChargeDecision {
  if (!input.buyer.vatId) {
    return { applyReverseCharge: false, reason: 'BUYER_VAT_NOT_PROVIDED' }
  }
  if (!isEUCountry(input.buyer.country)) {
    return { applyReverseCharge: false, reason: 'BUYER_OUTSIDE_EU' }
  }
  if (input.buyer.country === input.sellerCountry) {
    return { applyReverseCharge: false, reason: 'BUYER_SAME_COUNTRY_AS_SELLER' }
  }
  if (!input.vatCheck || !input.vatCheck.valid) {
    return { applyReverseCharge: false, reason: 'BUYER_VAT_INVALID' }
  }
  return {
    applyReverseCharge: true,
    evidence: {
      vatId: input.vatCheck.vatId,
      source: input.vatCheck.source,
      consultationNumber: input.vatCheck.consultationNumber,
      traderName: input.vatCheck.name,
      traderAddress: input.vatCheck.address,
      checkedAt: input.vatCheck.checkedAt,
    },
  }
}

That function should be pure, deterministic, and called from exactly one place in your billing code path. If reverse-charge decisions are scattered across the checkout UI, the invoice renderer, and the Stripe webhook handler, the audit trail will be impossible to reason about later.

Step 1: validate the buyer VAT ID

The validation step is the one place where "reasonable steps to verify" is operationalised in code. A VIES-confirmed validation, with a consultation number and a stored result, is the strongest evidence most SaaS companies can produce.

The full validation pipeline is covered in the Node.js VAT validation guide; the relevant outputs here are:

valid (boolean)
source — VIES or a national-fallback source when VIES was degraded
consultationNumber — the requester-qualified reference described in the VIES consultation number guide
name and address — the trader details VIES returns (when not opted out)
checkedAt — the timestamp of the check

What matters for reverse-charge specifically:

The validation must be requester-qualified. Call checkVatApprox with your own VAT ID as the requester, not the bare checkVat. Only the requester-qualified call produces a consultation number.
A "valid" result from a national-registry fallback is not equivalent to a VIES "valid". A buyer can be active in a national company registry without being VAT-registered for intra-EU operations. If your fallback path returned a non-VIES source, flag the invoice for re-validation once VIES recovers, and record requires_recheck = true.
A MS_UNAVAILABLE from VIES is not "invalid". It is a transport signal. Handle it with retry and fallback patterns as covered in the VIES downtime guide; do not flip the buyer to a VAT-charged invoice just because VIES is having a bad afternoon.

Step 2: the country-comparison rule

Reverse-charge applies only when buyer and seller are in different EU member states. The two ways teams get this wrong:

Using the buyer's billing address country instead of the country of the VAT ID. They should match (and you should require them to match), but if they do not, you cannot resolve the ambiguity yourself. Place of supply is determined by where the buyer is established as a taxable person, not by either the billing address or the VAT ID prefix in isolation — but for an automated checkout, the VAT ID prefix is the strongest signal you have, and a mismatch between it and the billing country is a signal to stop and ask. If a Spanish company with ES-prefixed VAT ID enters a Portuguese billing address, reject the mismatch at checkout rather than guess.
Treating domestic intra-country supplies as reverse-charge. A German seller selling to a German buyer charges 19% German VAT. Reverse-charge does not apply, regardless of how clean the buyer's VAT ID is.

function isReverseChargeEligibleByGeography(
  sellerCountry: string,
  buyerVatId: string,
  buyerBillingCountry: string,
): { ok: boolean; reason?: string } {
  const vatPrefix = buyerVatId.slice(0, 2).toUpperCase()
  if (vatPrefix !== buyerBillingCountry.toUpperCase()) {
    return { ok: false, reason: 'VAT_ID_COUNTRY_DOES_NOT_MATCH_BILLING' }
  }
  if (!isEUCountry(vatPrefix)) {
    return { ok: false, reason: 'BUYER_OUTSIDE_EU' }
  }
  if (vatPrefix === sellerCountry.toUpperCase()) {
    return { ok: false, reason: 'BUYER_SAME_COUNTRY_AS_SELLER' }
  }
  return { ok: true }
}

Note that the EU country list is a moving target on the margins — Brexit removed GB, and XI (Northern Ireland) is special-cased for goods only. Pull the membership check from a maintained source rather than hardcoding it; the eu-vat-rates-data package exposes an isEUMember() helper that tracks this for you.

Step 3: render the invoice correctly

The invoice itself has formal requirements when reverse-charge applies. From Article 226 of Directive 2006/112/EC, invoices for reverse-charge supplies must include:

The buyer's VAT identification number
The seller's VAT identification number
A reference to the reverse-charge mechanism — typically the wording "Reverse charge" (Article 226(11a))
A reference to the legal basis, when local rules require it (e.g., "Article 196 of Directive 2006/112/EC" or the national-law equivalent)
Zero VAT amount and a clear line that VAT is not charged

In practice, the minimum that satisfies tax authorities across member states is the phrase "Reverse charge" plus the buyer VAT ID. Some authorities expect the legal citation; if you serve customers across all 27 member states, include it.

function renderInvoiceTotals(invoice: Invoice, decision: ReverseChargeDecision) {
  if (decision.applyReverseCharge) {
    return {
      subtotal: invoice.subtotal,
      vatRate: 0,
      vatAmount: 0,
      total: invoice.subtotal,
      vatNote:
        'Reverse charge — VAT to be accounted for by the recipient ' +
        '(Article 196 of Council Directive 2006/112/EC).',
      buyerVatId: decision.evidence.vatId,
      sellerVatId: invoice.seller.vatId,
    }
  }

  const vatRate = lookupVatRate(invoice.buyer.country, invoice.lineItems)
  return {
    subtotal: invoice.subtotal,
    vatRate,
    vatAmount: round2(invoice.subtotal * vatRate),
    total: round2(invoice.subtotal * (1 + vatRate)),
    vatNote: null,
    buyerVatId: invoice.buyer.vatId ?? null,
    sellerVatId: invoice.seller.vatId,
  }
}

If you are using Stripe, the tax_behavior and customer_tax_ids fields on Invoice / Subscription objects participate in this — Stripe will mark the line as reverse-charge if you have configured Stripe Tax appropriately, but the legal responsibility for the invoice contents remains yours. Treat Stripe's tax engine as a helper, not as the source of truth for the wording on the document.

Step 4: store audit evidence

The single most useful audit habit is to write the evidence next to the invoice, not in a separate validation log nobody links back. A reverse-charge invoice row should carry, at minimum:

ALTER TABLE invoices ADD COLUMN reverse_charge_applied boolean NOT NULL DEFAULT false;
ALTER TABLE invoices ADD COLUMN buyer_vat_id text;
ALTER TABLE invoices ADD COLUMN buyer_vat_source text; -- 'VIES' | 'NATIONAL_FALLBACK'
ALTER TABLE invoices ADD COLUMN buyer_vat_consultation_no text;
ALTER TABLE invoices ADD COLUMN buyer_vat_checked_at timestamptz;
ALTER TABLE invoices ADD COLUMN buyer_vat_trader_name text;
ALTER TABLE invoices ADD COLUMN buyer_vat_requires_recheck boolean NOT NULL DEFAULT false;

The reason to denormalise this onto the invoice — rather than keep it as a foreign key to a vat_checks table — is that VAT IDs can be deregistered after the fact. The evidence you care about is the state at the moment of the supply. If you only keep a pointer to the latest check, a buyer whose VAT ID expires next year will appear "invalid" against last year's invoices, and you will not be able to reconstruct what your audit posture was when you issued them. The broader VAT audit trail guide covers the cross-table schema.

A background job should reconcile requires_recheck = true rows against VIES when the relevant national node recovers, and update source, consultation_no, and requires_recheck accordingly. The invoice itself does not change — what changes is the evidence row attached to it.

One more thing worth surfacing in the schema: retention. EU member states set their own statutory retention periods for invoices and supporting tax evidence (commonly 5–10 years, jurisdiction-dependent), and the audit evidence attached to a reverse-charge invoice falls under the same regime as the invoice itself. Pick the longest retention horizon among the jurisdictions you serve and use it as the floor; do not let log-rotation or "tidying up old rows" routines silently truncate this table.

Step 5: handle the edge cases

These are the cases most early implementations miss:

VAT ID deregistered after the invoice was issued. Not your problem at the moment of supply, provided the validation was genuine at the time. Keep the original checked_at and consultation_no; the audit position is "valid at time of supply", not "still valid today".
Buyer changes their VAT ID mid-subscription. Treat as a new validation. Re-validate, store fresh evidence on the next invoice, and consider whether your subscription model needs a vat_id_history audit trail.
Buyer downgrades from B2B to B2C (e.g., they remove the VAT ID from their account). Subsequent invoices are no longer reverse-charge. Make sure your subscription renewal path re-evaluates the decision function on every invoice, not just at sign-up.
You change member state. Rare but real for early-stage companies relocating. From the relocation date forwards, the country-comparison rule changes for every existing customer. Re-evaluate.
VIES says invalid for a known-good customer. Surface a clear UX path: keep the customer on a paid plan (do not lock them out), invoice with VAT temporarily (depending on local invoicing rules — in some jurisdictions a later correction via credit note plus reissued invoice is the cleaner path than holding the invoice in limbo), and let them re-submit the VAT ID. Cache the failure for a short window only (5–15 minutes), as discussed in the VIES downtime guide.
MS_UNAVAILABLE at invoice-generation time. This is the most subtle case. You cannot prove the VAT ID is currently valid, but you may have a fresh successful check from an hour ago. The defensible position is: rely on the most recent successful VIES check within a documented cache window (often 24 hours), and queue an async re-check. Do not silently flip the invoice to VAT-inclusive in response to a transient VIES outage.
Buyer in Northern Ireland (XI prefix). Post-Brexit, XI exists under the Windsor Framework specifically for the intra-EU goods regime — Northern Ireland businesses dealing in goods remain inside the EU VAT system for those flows, even though the rest of the UK does not. For SaaS (services), XI is not the right identifier; the relevant prefix for UK-based buyers is GB, which is outside the EU VAT system entirely. Treat GB as BUYER_OUTSIDE_EU for the reverse-charge decision, and if a buyer presents an XI VAT ID for a services supply, treat the prefix as a signal to ask for the underlying GB VAT ID rather than blindly accepting it.

The minimum viable implementation checklist

If you implement nothing else, implement this list:

Validate the buyer VAT ID through VIES with a requester-qualified call.
Store the consultation number, source, trader name, and checked_at next to the invoice.
Re-run the decision function on every invoice, not just at sign-up.
Render "Reverse charge — Article 196 of Directive 2006/112/EC" on the invoice when the decision is true.
Have a background job that flips requires_recheck = false once VIES has confirmed a fallback-sourced validation.
Never silently flip a customer from reverse-charge to VAT-inclusive in response to a transient VIES outage.

Everything else — checkout UX, tax-rate lookup for non-reverse-charge cases, OSS/IOSS for non-EU buyers — sits on top of those six.

Skip the pipeline boilerplate

vatnode runs the full requester-qualified VIES call (with consultation number), national-registry fallback when VIES is degraded, and a stable response shape across all 27 member states. If you want to keep the decision function in your own code but stop maintaining SOAP, fallback clients, and per-country regex, that is what the API is for.

Get a free API key · VIES API alternative · Reverse-charge concept guide

DEV Community: Iurii Rogulia

PDF Tamper Detection API for Node.js: Complete Integration Guide

Prerequisites

Step 1: Test the API with curl

Step 2: Define Types

Step 3: Build the Client Class

Step 4: Production Integration Pattern

Step 4b: Giving the API a Reachable URL

A Note on Synchronous Analysis and Webhooks

Step 5: Express Middleware

Step 6: Test Mode

Step 7: Reviewing Past Checks

Step 8: Knowing When to Upgrade

Complete Client File

Decisions Before You Ship

Cloudflare WAF Free Plan: Block Bots Without Paying

What the Bots Are Looking For

The Cloudflare WAF Rule

The Operator Gotcha: Why starts_with Breaks on the Free Plan

Deploying via the Dashboard

Deploying via API

Verifying It Works

What This Does Not Cover

Extending the Rule

Caching VIES Responses Without Breaking Compliance

Why caching VIES is different from caching anything else

What VIES actually returns and what changes

A defensible TTL ladder

Negative caching: invalid IDs need a different TTL

Redis pattern: cache the response, not the decision

When to bypass the cache no matter what

Rate limits: a cache is not a license to hammer

Stale-if-error and partial outages

Summary

vatnode handles the cache layer for you

PostNord API and Zoho Desk Automation: Production Gotchas

PostNord: The API That Returns 200 for Errors

Building the Shipment Payload

Storing the Label PDF

Zoho CRM: The EU Data Center Trap

Zoho Desk: Auto-Creating Logistics Tickets

Zoho Desk Contact Lookup

OAuth Token Management

Full Pipeline in the Worker

Production Gotchas Summary

Contract Fraud: How Altered PDFs Bypass Legal Review

Why Contracts Are a Prime Target

Three Contract Fraud Scenarios

Changed payment terms after signing

Altered liability clauses

Modified bank details in service agreements

How PDF Alteration Works: What Editing Leaves Behind

Cross-reference tables and incremental updates

Metadata divergence

Post-signature modifications

The Two Highest-Confidence Signals

Modifications after digital signature

Signature removal

API Integration in Legal Workflows

DocuSign / contract management webhook pattern

Decision matrix for legal ops

What This Approach Does Not Catch

Who Should Integrate Contract Fraud Detection

PDF Tamper Detection API for Python: Complete Integration Guide

Prerequisites

Quick Start: Two API Calls

Production Client Class

Handling All Three Verdicts

Django Integration: Document Upload Webhook

Flask Equivalent

Batch Processing: S3 or GCS Bucket

Test Mode: Develop Without Live Documents

What the API Does Not Detect

Choosing a Plan

Decisions Before You Ship

Next.js 16 proxy.ts Migration: From middleware.ts

What Changed in Next.js 16

Why "Middleware" Was the Wrong Name All Along

CVE-2025-29927: Exhibit A

The Codemod

The Operator Gotcha: Why `starts_with` Breaks on the Free Plan