Fonoa

Batch Validate Tax Ids

Submit a batch of tax identification numbers (VAT IDs, GST numbers, etc.) for validation using Fonoa's Lookup API. Supports multiple countries and TINs per request (up to 10,000 unique TINs). Returns a batch_id immediately — use get_batch_validation_result to poll for results.

Batch Validate Tax Ids Cached

Validate a batch of tax IDs using parallel single-validation calls with prefer_cached_result=true for instant results. Runs up to 10 concurrent requests — suited for small-to-medium sets (under 50 TINs) where immediate results are preferred over async batch submission. Accepts the same input format as batch_validate_tax_ids and returns all results synchronously.

Calculate Tax

Calculate indirect tax (VAT, GST, sales tax) for a transaction using Fonoa's Tax Engine. Provide supplier/customer details and line items to get tax determination with full breakdown.

Generate Validation Report

Generate a validation report from completed batch results. Returns a summary of valid/invalid/unknown TINs plus a detailed list of invalid ones with their original row_numbers for tracing back to the source file. A TIN is classified as invalid only when there is positive evidence (format is invalid OR explicitly not found in official database). Call this after get_batch_validation_result shows status 'completed' for all batches.

Get Batch Validation Result

Retrieve the current status and results of a previously submitted batch validation. Use the batch_id returned by batch_validate_tax_ids or validate_tax_ids_from_file. Returns status ('running', 'completed', or 'canceled'), completion_percentage, and — when completed — the full validation results for all TINs in the batch.

Get Compliance Summary

Get a consolidated compliance overview in a single call: active countries, revenue breakdown, tax breakdown by country, and scenario mix. Use this as the starting point for any broad analysis — threshold reviews, audit preparation, new-country assessment, or executive reporting.

Get Country Codes

List all country codes that have e-invoicing transactions. Use this as a first step to understand which jurisdictions are active before drilling into country-specific breakdowns, error diagnosis, or launch-country assessments.

Get Error Documentation

Look up e-invoicing error codes, their meaning, and remediation steps. Use this when diagnosing transaction failures — filter by country_code to see country-specific errors, or by error_code to look up a specific failure. Returns official error messages and actionable fix guidance.

Get Transaction Details

Get full details of a single e-invoicing transaction by its operation_id. Returns items, tax breakdown, supplier/customer data, error details, and status. Use this after finding transactions via get_transactions or transaction_errors_detail to inspect payloads, understand failures, or prepare corrections.

Get Transactions

List e-invoicing transactions with optional filters. Use this to find failed transactions for error diagnosis, review recent submissions, or collect transactions for an audit pack. Returns up to 500 transactions (paginated internally).

Search Tin

Search for a business by name to find its tax identification number (reverse TIN lookup). Submits a search query for a given country, polls for results, and returns matching entities with their TINs, addresses, and tax registration details. Useful for enriching master data when a TIN is missing or invalid but the business name is known.

Submit Transaction

Submit a compliant e-invoice transaction to a tax authority. WARNING: This action is irreversible in most countries. Always show the full payload to the user and ask for explicit confirmation before calling this tool. Use this as the final step of the invoice workflow after validation and tax calculation.

Transaction Errors Breakdown

Get a count of failed E-Invoicing transactions grouped by error type within a date range. Returns error codes with their occurrence counts and associated country codes.

Transaction Errors Detail

Fetch failed E-Invoicing transactions in a date range and return a detailed aggregation of errors. Groups errors by code and type, includes error messages, affected fields, doc links, total occurrence counts, and sample transaction IDs for each error group.

Validate Tax Id

Validate a tax identification number (VAT ID, GST number, etc.) for a given country using Fonoa's Lookup API. Submits validation, polls for results, and returns the full validation outcome including taxpayer name, address, and registration status.

Validate Tax Ids From File

Submit deduplicated tax IDs for batch validation from a CSV input. Accepts a CSV string with columns: country_code, tax_id, row_numbers (semicolon-separated original row numbers for traceability). Deduplicates entries, submits one or more batches to the Fonoa Lookup API, and returns batch_ids and a file_ref. Use batch_ids with get_batch_validation_result to check status, and file_ref with generate_validation_report once all batches are completed.