Skip to Content
Open Books for developers

Test a document integration

Verify release and refusal paths, use bundled fixtures for multiple layouts, and check retries and evidence before scheduling imports.

A document integration needs to handle released files, files that fail verification, and jobs that stop before making a decision. Use known fixtures first so you can tell a plumbing problem from a source-data problem.

1. Establish a bank CSV baseline

Install the Python CLI and download the two-row sample. Run each command individually from the directory with the sample. The last two commands return nonzero exit codes by design.

python -m openbooks run statement.csv --currency INR --date-order dmy --opening 1000.00 --out checks/release
python -m openbooks run statement.csv --currency INR --date-order dmy --out checks/missing-opening
python -m openbooks run statement.csv --currency INR --date-order dmy --opening 1200.00 --out checks/wrong-opening
CaseExpected decisionCheck in your application
Verified openingExit 0, status: "ok", closing amount "950.00"Exactly two transactions reach the import path. The full decision, including assertions and evidence, remains available.
Missing openingExit 1, PARSE_ERROR, data: nullThe file goes to review with the message explaining which parameter it needs.
Wrong openingExit 1, BALANCE_MISMATCH, data: nullThe file goes to review with the failed assertion in the message.

Each output directory contains the decision under the same input hash. This makes it easy to check whether your job history ties all three attempts to the same source while preserving their different settings and outcomes.

2. Exercise the layouts you plan to use

Open the workspace sample picker or read the sample catalog from GET /v1/samples. For HTTP tests, use the catalog's params for each sample. Download the fixture bytes from GET /v1/samples/{id} and submit them through your integration.

SampleCatalog IDExpected check
Bank CSV with a tampered balancebad_bank_balance_breakBALANCE_MISMATCH identifies the running-balance check.
MT940 statementok_mt940The opening plus signed movements equals the source closing balance.
Bank statement PDFok_pdf_textThe stated closing balance equals the last running balance.
Razorpay settlementok_razorpayRow arithmetic ties out and the net amounts match the payout.
Stripe export, payout off by 0.01bad_stripe_payoutBALANCE_MISMATCH identifies the payout total.
Form 26AS (TDS)ok_tdsDeducted and deposited tax totals agree with the source.
Trial balance workbookok_tb_xlsxDebits and credits balance and each side matches its printed total.

The bundled documents are synthetic. Once these checks pass, test representative exports in an environment approved for those files. Include variations you expect to see, such as different date formats, statement periods, and PDF text or scan quality.

3. Test a stopped job and retry

  1. In a test environment, stop or interrupt a batch after at least one file completes. For HTTP, test a stream that delivers file.done for one index and closes before run.done.
  2. Verify that your job records the finished decision and marks only files still waiting for a decision as incomplete.
  3. Retry an incomplete file with its original settings. If the first attempt did finish on the server, your application should still write each set of released records at most once.
  4. For a completed refusal, change the run only after obtaining verified context or a corrected source. Keep both decisions in the job history.

Use the refusal guide to route document and execution outcomes. For HTTP streaming behavior, see the engine API.

4. Check what a reviewer can trace

Pick a released amount and ask someone to find it from the saved JSON. They should be able to identify the input by hash, locate the relevant assertion, and trace the amount back to a row, page, or bounding box where the engine supplies one. Also check that the application preserves exact decimal strings and keeps each amount with its currency. See the output contract for the full field definitions.

View this page as Markdown