Tabscanner for AI agents

[
  {
    "name": "scan_receipt",
    "description": "Extract structured data from a photo of a receipt using the Tabscanner API. Uploads the image, waits for processing (usually a few seconds) and returns the result object: establishment, date, total, subTotal, tax, tip, discount, currency, paymentMethod, address, lineItems, summaryItems and confidence scores (0 to 1). Each call uses one credit. Call it once per receipt image. Pass the receipt's country as region for best accuracy. Trust total when validatedTotal is true; otherwise check totalConfidence and the arithmetic of lineItems.",
    "input_schema": {
      "type": "object",
      "properties": {
        "image_path": {
          "type": "string",
          "description": "Local path to a JPG or PNG photo of the receipt."
        },
        "region": {
          "type": "string",
          "description": "Two-letter lower-case ISO 3166-1 country code of the receipt, for example \"us\" or \"gb\". Optional but recommended."
        },
        "documentType": {
          "type": "string",
          "enum": ["receipt", "invoice", "auto"],
          "description": "Type of document. Default \"receipt\". Use \"auto\" to let the API detect it."
        },
        "defaultDateParsing": {
          "type": "string",
          "enum": ["d/m", "m/d"],
          "description": "How to read an ambiguous numeric date such as 02/03/2026: \"d/m\" is 2 March, \"m/d\" is 3 February."
        }
      },
      "required": ["image_path"]
    }
  },
  {
    "name": "get_credit",
    "description": "Return the number of Tabscanner credits left on the account. Each scan_receipt call uses one credit.",
    "input_schema": {
      "type": "object",
      "properties": {}
    }
  }
]

// Tabscanner as an agent tool. scanReceipt() uploads, polls and returns the result object,
// so the model sees one call instead of a polling loop. getCredit() returns the balance.
// Node 20 or newer, no packages.  Usage as a script: node agent-tool.js receipt.jpg [region]
import { openAsBlob } from 'node:fs';
import path from 'node:path';

const API_URL = process.env.TABSCANNER_API_URL ?? 'https://api.tabscanner.com';
const API_KEY = process.env.TABSCANNER_API_KEY;
const POLL_MS = Number(process.env.TABSCANNER_POLL_MS ?? 1000);

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Every response is HTTP 200; the outcome is the "code" field in the JSON body.
async function api(route, init = {}) {
  const response = await fetch(`${API_URL}${route}`, { ...init, headers: { apikey: API_KEY } });
  return response.json();
}

class TabscannerError extends Error {
  constructor(body) {
    super(`Tabscanner ${body.code}: ${body.message}`);
    this.code = body.code;
    this.retryable = body.code >= 500 && body.code !== 500;
  }
}

/**
 * Tool: scan_receipt. Returns the result object for one receipt image.
 * @param {{ image_path: string, region?: string, documentType?: string, defaultDateParsing?: string }} input
 */
export async function scanReceipt(input, { timeoutMs = 60_000 } = {}) {
  const form = new FormData();
  const mimeType = input.image_path.toLowerCase().endsWith('.png') ? 'image/png' : 'image/jpeg';
  form.append('file', await openAsBlob(input.image_path, { type: mimeType }), path.basename(input.image_path));
  for (const key of ['region', 'documentType', 'defaultDateParsing']) {
    if (input[key]) form.append(key, input[key]);
  }

  const upload = await api('/api/2/process', { method: 'POST', body: form });
  if (upload.code !== 200 && upload.code !== 300) throw new TabscannerError(upload);

  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    await sleep(POLL_MS);
    const body = await api(`/api/result/${upload.token}`);
    if (body.code === 202) return { token: upload.token, duplicate: upload.duplicate, ...body.result };
    if (body.code !== 301) throw new TabscannerError(body);
  }
  throw new Error(`Tabscanner: result for ${upload.token} not ready after ${timeoutMs} ms; poll it later`);
}

/** Tool: get_credit. Returns the number of credits left on the account. */
export async function getCredit() {
  const body = await api('/api/credit');
  if (typeof body !== 'number') throw new TabscannerError(body);
  return body;
}

if (process.argv[1] && path.resolve(process.argv[1]) === new URL(import.meta.url).pathname) {
  const result = await scanReceipt({ image_path: process.argv[2] ?? 'receipt.jpg', region: process.argv[3] });
  console.log(JSON.stringify(result, null, 2));
}

## Tabscanner receipt OCR

Base URL `https://api.tabscanner.com`. Auth: header `apikey: <key>` (read it from `TABSCANNER_API_KEY`, never print it).

Flow: `POST /api/2/process` (multipart, one JPG/PNG in field `file`, optional `region`
two-letter country code) returns `{ token }`. Then `GET /api/result/{token}` once per second
until body `code` is 202; `result` holds the data. `GET /api/credit` returns a bare number.

Rules:
- Every response is HTTP 200. Read the numeric `code` in the JSON body, never the HTTP status.
- 200/300 = upload accepted (300 = image smaller than 720x1280, still processed).
- 301 = not ready, keep polling. 202 = done. Any other code = stop and report `message`.
- 4xx codes are permanent for the same input; do not retry. 5xx: retry with backoff. 500 = unreadable image.
- One credit per accepted upload. Re-uploading identical bytes returns `duplicate: true` and the original token.
- Prefer `validatedTotal`/`validatedEstablishment` = true. Otherwise compare `*Confidence` fields and check
  that `lineItems` sum to `subTotal` and `subTotal + tax + tip + serviceCharges - discount = total`.
- Results and images are deleted after 90 days; store what you need.

Spec: https://docs.tabscanner.com/openapi.yaml · Full docs: https://docs.tabscanner.com/llms-full.txt