Compliance

JP-Verify Invoice Facts — one invoice's register, statutory-item, arithmetic and schedule facts (JSON)

Check ONE invoice from its facts (see InvoiceCheckRequest). What is checked: the issuer's 登録番号 against the NTA register — well-formed (REG-01), present (REG-02) and registered on the transaction date / period (REG-03, evaluated against every registration episode the NTA publishes for the number once the mirror's history table is complete — status_on_date.episode_scope says which); the statutory items of 消費税法57条の4 as presence checks (ITEM-01..06); the printed rates (RATE-01..03); arithmetic on the document's own figures (ARITH-01..05 — per-rate tax within one-yen rounding, sums, totals); plus the published transitional-deduction schedule tier for the evaluation date with its source URLs, and the register/document-name comparison (name_match, never a verdict). Every rule carries a status (pass / fail / unknown / not_applicable), a detail and a source id; rule_set_version names the rule set (catalog: GET /v1/invoice/rules).

NOT tax advice: register facts, document checks and the published schedule only; no determination of any deduction, credit or entitlement — the buyer's consumption-tax treatment is for the taxpayer and their 税理士. No buyer-side input is accepted.

Free refusal (400, nothing charged) for request-level defects only: not an object, missing or malformed issue_date, both transaction_date and transaction_period, a bad document_type / category / amount_basis / currency, more than 10 tax_lines, a non-numeric amount (negative amounts are accepted on every document type and reported as document.amount_sign), return_date on a document type other than return_invoice (適格返還請求書 — declared by the caller, never inferred), an over-long name, a supplier_t_number that is not number-shaped (longer than 32 characters) or a string that cannot be UTF-8 encoded. A missing or malformed 登録番号 is a document finding and is metered — reported as a finding WITHOUT its text (document.supplier_t_number is null, document.supplier_t_number_state says malformed). Metered 1 unit per document on every tier. "sign": true returns an Ed25519-signed record with a sibling compact jws (Growth / Reseller keys; other tiers get signed_record: null and a note). Opt-in Idempotency-Key request header: a retry with the same key + body replays the first response (Idempotent-Replayed: true) instead of being re-metered. Names and amounts are consumed in memory only — never stored, logged or echoed; the digest carries no name.

post/v1/invoice/check

Request

  • Base URL: https://jp-verify.obolpay.xyz
  • URL: https://jp-verify.obolpay.xyz/v1/invoice/check
  • Auth: one of:
    • none
    • API key in header X-API-Key

Headers

X-API-Keystring

Request body

document_typestring nullable

qualified_invoice (適格請求書, default) | simplified_qualified_invoice (適格簡易請求書) | return_invoice (適格返還請求書 — 'credit note' in Peppol/UBL vocabulary; JP PINT models it as a negative Invoice (380)) — as claimed by the caller, never inferred from the sign of the amounts; industry eligibility is not checked

supplier_t_numberstring nullable

the 登録番号 AS PRINTED (NFKC-folded, whitespace removed); absent = the document shows no number; a malformed value is a metered finding reported WITHOUT its text; longer than 32 characters (not number-shaped) or not UTF-8 encodable = free 400

seller_namestring nullable

issuer name as printed (<= 200 chars after NFKC/strip); compared with the register name, never echoed

buyer_namestring nullable

recipient name as printed; only its presence is used, never echoed

buyer_name_presentboolean nullable

alternative to buyer_name: whether the recipient's name is printed

issue_datestring required

REQUIRED — the date printed on the document ('YYYY-MM-DD', ibt-002)

transaction_datestring nullable

課税資産の譲渡等を行った年月日 (goods: delivery; services: completion) — the evaluation date; mutually exclusive with transaction_period. On a return_invoice: the ORIGINAL supply (57条の4③二's second date), which is the register date of record (基通1-8-18/1-8-19)

return_datestring nullable

return_invoice only — 売上げに係る対価の返還等を行う年月日 (57条の4③二's first date), 'YYYY-MM-DD'; optional (ITEM-02 reports unknown without it); informational for the register status (基通1-8-19); a free 400 on any other document_type

preceding_invoice_reference_presentboolean nullable

return_invoice — a reference to the original invoice is printed (presence only; the reference itself is never sent)

currencystring nullable

ISO 4217 (default JPY)

description_presentboolean nullable

資産又は役務の内容 is stated (null = not supplied)

reduced_rate_markedboolean nullable

軽減対象である旨 is marked, in any form per 基通1-8-4 (null = not supplied)

rate_only_statedboolean nullable

適格簡易請求書 printing 適用税率 but no 消費税額等

signboolean nullable

return an Ed25519-signed record (Growth/Reseller keys only; otherwise the response says so and signs nothing)

Response

One document's register facts, document checks, published schedule tier and limitations — every rule with a status and a source; never a verdict. Two real responses on the sample register: a registered issuer, and a malformed 登録番号 reported as a finding whose register record is invalid with every key present (null) and the printed text never echoed.

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.