# Czech VAT Checker & Supplier Bank Account Monitor (`automa-flow/czech-vat-supplier-change-monitor`) Actor Check up to 10,000 Czech VAT IDs against the official ADIS register. Monitor unreliable-payer status and published supplier bank accounts, compare invoice accounts, and export typed changes between runs. Failed checks preserve the last verified baseline. - **URL**: https://apify.com/automa-flow/czech-vat-supplier-change-monitor.md - **Developed by:** [Vadim Bezrukov](https://apify.com/automa-flow) (community) - **Categories:** Business, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 observed suppliers This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Czech VAT Checker & Supplier Bank Account Monitor Watch up to 10,000 Czech suppliers in the official ADIS VAT register and get back **only what changed**: a supplier that became an unreliable VAT payer (nespolehlivý plátce DPH), a published bank account that appeared or disappeared, or the account on your invoice no longer being one the tax authority publishes. The first run stores a baseline. In `changesOnly` mode, later runs return changed suppliers and diagnostic rows. The Console example uses `snapshotAndChanges` so you can inspect the current status on every test run. A failed check is reported as a failed check - it never becomes a false "account removed" alert. ### Why supplier VAT and bank-account status has to be rechecked Czech VAT rules can create supplier-related tax liability in defined circumstances. [The Financial Administration explains unreliable-payer status and liability](https://financnisprava.gov.cz/assets/en/attachments/t-taxes/Information_on_an_unreliable_VAT_payer.pdf). Neither fact is stable: a supplier is declared unreliable on a date you are not told about, and bank accounts are added and withdrawn continuously. [SAP's Czech localization documentation](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/38cd6f4a86f348a0adf5e9e36385c722/aa39e12e81034c17999f6656b6fbb37d.html) recommends a **daily mass validation** of supplier VAT reliability and registered bank accounts for large supplier populations, precisely because a check is only true on the day it was made. A one-off lookup returns the current register record. This Actor answers the question an accounts-payable team actually has: **"which of my 4,000 suppliers changed since yesterday?"** ### What it monitors Per supplier, from the official register: - unreliable VAT payer status, and the date it was published; - subject type - VAT payer, identified person, VAT group, unreliable person; - every officially published bank account, with its publication date and, where present, its **withdrawal date**; - optionally, whether the specific account on your invoice is currently among them. And between runs, these typed change events: | Change type | Meaning | | --- | --- | | `BECAME_UNRELIABLE` | The register now marks this supplier as an unreliable VAT payer | | `BECAME_RELIABLE` | That marking was lifted | | `UNRELIABLE_SINCE_CHANGED` | The publication date of the unreliability changed | | `SUBJECT_TYPE_CHANGED` | e.g. VAT payer became a VAT group | | `BANK_ACCOUNT_ADDED` | A new account is published - with its exact normalized key | | `BANK_ACCOUNT_REMOVED` | A published account is gone or was withdrawn | | `EXPECTED_ACCOUNT_BECAME_PUBLISHED` | The account you pay is now published | | `EXPECTED_ACCOUNT_BECAME_UNPUBLISHED` | The account you pay is no longer published | | `BECAME_NOT_FOUND` | The DIČ no longer resolves in the VAT register | | `BECAME_FOUND` | It resolves again | ### Quickstart ```json { "monitorKey": "accounts-payable-prod", "suppliers": [ { "vatId": "CZ27082440", "reference": "supplier-001", "expectedBankAccount": "2171532/0800" }, { "vatId": "CZ26168685", "reference": "supplier-002" } ], "mode": "changesOnly", "firstRunBehavior": "emitCurrent" } ``` Run it once to get every supplier's current status and store the baseline. Put it on a schedule with the same `monitorKey` and later runs return only changes. - `vatId` - Czech DIČ. `CZ`, spaces and dashes are normalized away. An 8-digit DIČ is checksum-validated locally, so a typo is rejected before it costs a request. - `reference` - your AP/ERP/invoice key, echoed back unchanged on that exact row. - `expectedBankAccount` - optional; see below. - `monitorKey` - names the stored baseline. One key per watchlist. - `mode` - `changesOnly` (default) or `snapshotAndChanges` to also get unchanged rows. - `firstRunBehavior` - `emitCurrent` (default) or `baselineOnly` to store the baseline silently so your first alert is a real change. ### Sample change record ```json { "record_type": "CHANGE", "status": "SUCCESS", "reference": "supplier-001", "vat_id": "27082440", "found": true, "subject_type": "PLATCE_DPH", "unreliable_payer": false, "unreliable_since": null, "change_types": ["BANK_ACCOUNT_REMOVED", "EXPECTED_ACCOUNT_BECAME_UNPUBLISHED"], "changes": { "published_accounts": { "added": [], "removed": ["999888777/0300"] }, "expected_account_published": { "previous": true, "current": false } }, "expected_bank_account": "999888777/0300", "expected_account_published": false, "source": "czech_fs_adis_vat_register", "source_generated_at": "2026-09-06", "scraped_at": "2026-09-06T04:15:00Z", "fingerprint": "9f2c…" } ``` Every row is an append-only observation with a stable `source_id`, a `scraped_at` and a semantic `fingerprint`, so it is usable as an alert payload as-is and joins to its own history later. ### Supplier watchlist example Batch your whole vendor master. 10,000 unique suppliers require 100 requests to the official service before retries. Runtime depends on source responsiveness: ```json { "monitorKey": "vendor-master", "suppliers": [ { "vatId": "CZ27082440", "reference": "V-000117" }, { "vatId": "26168685", "reference": "V-000118" }, { "vatId": "CZ 45-274-649", "reference": "V-000119" } ], "mode": "changesOnly", "firstRunBehavior": "baselineOnly" } ``` Suppliers you drop from the list keep their baseline for 90 days, so splitting one watchlist across several runs does not reset anything. Suppliers included in a run keep their last successful baseline even when their check fails or is skipped for budget reasons, regardless of the baseline's age. Only one run may use a given `monitorKey` at a time. An overlapping run fails before reading the baseline or querying ADIS; retry it after the active run ends. Different monitor keys can run concurrently. ### Invoice / payment bank-account example ```json { "monitorKey": "pre-payment-check", "suppliers": [ { "vatId": "CZ27082440", "reference": "INV-2026-0042", "expectedBankAccount": "2171532/0800" }, { "vatId": "CZ26168685", "reference": "INV-2026-0043", "expectedBankAccount": "CZ4026000000002531920518" } ], "mode": "snapshotAndChanges" } ``` Accepted formats are the Czech domestic form `[prefix-]number/bankCode` and IBAN. A **Czech IBAN and its domestic form are treated as the same account** - the register publishes both shapes, and comparing them as raw strings would report a correct account as unpublished. Anything that cannot be normalized deterministically is rejected with an explicit error rather than guessed at. `expected_account_published` is `true`, `false`, or `null` when the comparison cannot be performed safely (no account supplied, supplier absent, check unverified). > `false` means: **the supplied account is not among the accounts returned as > published by the Czech tax authority for this VAT ID at the observation time.** > That is a fact about the register. It is not a fraud finding, and this Actor > draws no legal conclusion from it. If you edit `expectedBankAccount` between runs, the comparison for that field restarts from the new value and reports `expected_account_rebaselined` - your own edit is never reported as a change in the official register. For duplicate DIČ rows, each invoice's expected account is compared independently against the previous and current published account sets. Only the first row owns the saved expected-account setting; later rows never inherit its account event. ### Scheduling, webhooks and MCP Save the input as a task, then schedule it - daily before the payment run is the usual pattern. Add a webhook on `ACTOR.RUN.SUCCEEDED` pointing at your own endpoint and read the change view: ```text {{resource.defaultDatasetId}}/items?view=changes&clean=true ``` Or poll the same view over the API: ```bash curl "https://api.apify.com/v2/datasets//items?view=changes&clean=true" \ -H "Authorization: Bearer $APIFY_TOKEN" ``` With `mode=changesOnly`, unchanged verified observations are suppressed. Diagnostic rows and first-run baselines may still be present. Dataset views project and unwind fields; they do not provide a status filter. Unwinding empty `change_types` or `published_accounts` omits those rows, including diagnostics. Use `monitoring` or `invoiceAccounts` to preserve emitted supplier-level rows. Select `record_type=CHANGE` client-side for change alerts, and separately handle failed, partial and skipped checks using the full results and `RUN_SUMMARY`. #### MCP Connect using Streamable HTTP and your own Apify OAuth session (recommended) or bearer token. Execution requires authentication; anonymous Store discovery is separate and becomes available after publication. Expose the Actor as a typed tool: ```text https://mcp.apify.com?tools=automa-flow/czech-vat-supplier-change-monitor ``` Example prompt: ```text Run automa-flow/czech-vat-supplier-change-monitor for monitorKey accounts-payable-prod with suppliers CZ27082440 and CZ26168685. Tell me which of them changed since the last run, and for any BANK_ACCOUNT_REMOVED say exactly which account key was removed. If any supplier could not be verified, say so instead of treating it as unchanged. ``` The typed `change_types` are designed to be read by an agent without further parsing, and the distinct `SOURCE_FAILED` / `PARTIAL` statuses exist so an agent cannot mistake an unreachable register for a clean bill of health. ### Pricing Pay per event, with **no start fee and no monitor-run fee**. Apify runtime usage is included. Post-run storage retention and exports can incur your account's normal platform charges; the live Pricing tab is authoritative. | Plan discount tier | Per verified supplier | 100 suppliers / run | 1,000 suppliers / run | | --- | ---: | ---: | ---: | | Free / Bronze | $0.004 | $0.40 | $4.00 | | Silver | $0.0035 | $0.35 | $3.50 | | Gold / Platinum / Diamond | $0.003 | $0.30 | $3.00 | At Free/Bronze prices, 100 suppliers checked daily cost $12 for 30 runs; 1,000 suppliers checked weekly cost $16 for four runs. One supplier costs $0.004 and the maximum 10,000 unique suppliers cost at most $40 per run. These are worst-case event bills when every supplier is successfully observed. **Never charged:** invalid input, authoritative `NOT_FOUND` results, internal retries, planned source maintenance, source failures, unresolved suppliers, discarded watchlist anomalies, or a DIČ listed twice (charged once). A supplier that `changesOnly` mode reports as unchanged **is** charged: the verified check is what you are buying, and suppressing the row is what keeps your dataset a changelog rather than a dump. Set Apify's **maximum total charge** to bound a run. The platform may lower this limit to your available account credit. The Actor selects an affordable prefix of unique suppliers before querying ADIS, using the current event prices and remaining budget. This is a conservative worst-case allocation: unused capacity from failures or `NOT_FOUND` does not expand the selected prefix during that run. Remaining rows have `status=SKIPPED`, `error.code=BUDGET_LIMIT`, and no business observation; their previous state is preserved. If the SDK declines a charge, that supplier is also reported as skipped, without advancing its baseline. `RUN_SUMMARY` includes `skipped`, `budget_limit_reached` and `charged_observations`. `charged_monitor_runs` is retained for compatibility and is zero with current pricing. ### Failure semantics Every supplier has an explicit outcome: | `status` | Meaning | | --- | --- | | `SUCCESS` | The register returned a complete current record | | `NOT_FOUND` | The register explicitly answered `NENALEZEN` - an authoritative absence, **not** a failure | | `PARTIAL` | The request succeeded but this supplier was not conclusively answered | | `SOURCE_FAILED` | Timeout, HTTP error, malformed or unrecognised response after the retry budget | | `SOURCE_MAINTENANCE` | The service reported planned maintenance | | `INVALID_INPUT` | Rejected before any request was sent | | `SKIPPED` | The budget could not fund this check; no observation was delivered and the previous baseline was preserved | Guarantees: - **A source failure never becomes an observation.** No `found`, no accounts, no change events, and the stored baseline is left exactly as it was. - **A failed batch does not touch a successful one.** Every input is classified; `snapshotAndChanges` emits all rows, while `changesOnly` suppresses unchanged successes. - **Reconciliation is by DIČ**, never by position in the response. - Malformed subjects with an identifiable DIČ fail independently. Unknown account structures and invalid calendar dates are errors, never empty account lists. - **No false mass removals.** If most of the suppliers this monitor last saw suddenly return absent, or most of them simultaneously lose every published account, that is treated as a source incident: the observations are discarded, no change event is emitted, every baseline is preserved, and the run says so. - If the register cannot be reached for a single supplier, the run **fails** loudly and charges nothing. For large lists, allow a longer run timeout: cloud validation processed 100 suppliers in 13 seconds and 476 checked suppliers in about 50 seconds. These are individual measurements, not latency guarantees. The default timeout is 30 minutes to accommodate the supported 10,000-row ceiling. ### Source limits and maintenance window The Actor talks directly to the official service over plain HTTPS - no browser, no proxy, no credentials. It batches at the documented 100 DIČ per request, holds at most 2 requests in flight against a documented allowance of 4, and never retries its way around a rate limit. Concurrency is deliberately not a user input. The service documents a maintenance window of **00:00-00:10 Europe/Prague**. Schedule outside it. If a run does hit it, the result is an explicit `SOURCE_MAINTENANCE` status and untouched state, not an empty success. ### Legal and data limitations - Public data from the Czech Financial Administration's ADIS VAT register, a service the tax authority explicitly publishes for third-party software. - **This Actor is not an official government service, not legal advice, not a fraud detector, and not a guarantee that any payment is safe.** It reports what the register said, when it said it. Verify against the official record before acting on anything with financial consequences. - Data minimization: the extended operation also returns a structured postal address. The Actor **discards it** - supplier VAT reliability and published accounts are answerable without it. No directors, owners, dates of birth or personal contact data are collected. - Note that a 9- or 10-digit Czech DIČ is a natural person's identifier. The Actor only ever echoes back identifiers you supplied, and `reference` is never written to logs. ### API usage ```bash curl -X POST "https://api.apify.com/v2/acts/automa-flow~czech-vat-supplier-change-monitor/runs?maxTotalChargeUsd=0.01" \ -H "Authorization: Bearer $APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "monitorKey": "accounts-payable-prod", "suppliers": [{ "vatId": "CZ27082440", "reference": "supplier-001" }], "mode": "changesOnly" }' ``` Start with `RUN_SUMMARY`: inspect failed/partial/skipped counts before treating an empty change view as no changes. Retrieve rows whose `record_type=CHANGE` for review; handle diagnostics separately. Never automate a payment decision from this register check alone. Outputs: the default dataset (`overview`, plus the `changes`, `accounts` and `diagnostics`, `monitoring` and `invoiceAccounts` views) and a `RUN_SUMMARY` record in the key-value store with per-run counts, source request/retry totals and the watchlist-safety verdict. ### Technical source details | | | | --- | --- | | Source | Czech Financial Administration, ADIS VAT register (Registr plátců DPH) | | Endpoint | `https://adisrws.mfcr.cz/dpr/axis2/services/rozhraniCRPDPH.rozhraniCRPDPHSOAP` | | Operation | `getStatusNespolehlivySubjektRozsirenyV2` | | Documentation | `https://adisspr.mfcr.cz/pmd/dokumentace/webove-sluzby-spolehlivost-platcu` | | Batch size | 100 DIČ per request | | Authentication | none | | Browser / proxy | none | State is a single compact key-value record per `monitorKey` (`CZECH_VAT_MONITOR_V1_`) holding the last **successful** observation per supplier - a comparison baseline, not a history database. Full observations accumulate naturally in the dataset of each run. #### Recovering an interrupted monitor The read/compare/write cycle uses a non-expiring mutex marker in the named Apify Request Queue `czech-vat-supplier-monitor-locks`. Atomic unique-key insertion prevents competing runs from reading the same baseline. The queue is used only for coordination; its placeholder URL is never fetched. This uses the documented [request insertion contract](https://docs.apify.com/api/v2/request-queue-requests-post). Normal completion, including a handled ADIS failure, releases the marker. An interrupted run or an unexpected storage error keeps it in place because a remote write may still be in flight. There is no automatic expiry or takeover. To recover, stop all runs and pause schedules using the affected `monitorKey`; wait for their termination. In that queue, delete only the request whose `uniqueKey` matches the `CZECH_VAT_MONITOR_V1_` shown in the lock error. Keep the KVS record with the same key. Resume with a new run after confirming the old runs cannot resume. For local execution the equivalent marker is a file under `/czech-vat-supplier-monitor-locks/`. # Actor input Schema ## `suppliers` (type: `array`): One row per supplier. vatId accepts CZ, spaces and dashes; 8-digit DIC are checksum-validated before any request is sent. reference is echoed back unchanged so results join to your ERP. expectedBankAccount is optional and is compared only against the accounts the tax authority currently publishes. ## `monitorKey` (type: `string`): Names the stored baseline this run compares against. Use one key per watchlist (for example accounts-payable-prod). Changing it starts a fresh baseline. ## `mode` (type: `string`): changesOnly returns the first-run baseline and, after that, only suppliers whose official record changed. snapshotAndChanges also returns every unchanged supplier's current status. ## `firstRunBehavior` (type: `string`): emitCurrent returns every supplier's current status on the first run under a monitor key. baselineOnly stores the baseline silently so the first scheduled alert is a real change. ## Actor input object example ```json { "suppliers": [ { "vatId": "CZ27082440", "reference": "supplier-001", "expectedBankAccount": "2171532/0800" }, { "vatId": "26168685", "reference": "invoice-2026-0042", "expectedBankAccount": "CZ4026000000002531920518" }, { "vatId": "CZ 45-274-649", "reference": "vendor-00417" } ], "monitorKey": "demo-czech-vat", "mode": "snapshotAndChanges", "firstRunBehavior": "emitCurrent" } ``` # Actor output Schema ## `changes` (type: `string`): One row per change type; unwinding omits rows with no change types, including baselines and diagnostics. Inspect RUN\_SUMMARY and full results separately. ## `results` (type: `string`): In snapshotAndChanges, one row per input supplier. changesOnly suppresses unchanged observations; baselineOnly can suppress the initial baseline. Diagnostic rows remain visible. ## `accounts` (type: `string`): One row per officially published account, with its publication and withdrawal dates. ## `diagnostics` (type: `string`): Failure-focused columns for all rows; filter the status field client-side. ## `runSummary` (type: `string`): No description ## `monitoring` (type: `string`): Emitted baselines, changes and diagnostic rows without unwinding. Unchanged observations may be suppressed by the selected mode. ## `invoiceAccounts` (type: `string`): Supplier-level invoice comparison and nested published accounts, preserving diagnostic rows. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "suppliers": [ { "vatId": "CZ27082440", "reference": "supplier-001", "expectedBankAccount": "2171532/0800" }, { "vatId": "CZ26168685", "reference": "supplier-002" } ], "monitorKey": "demo-czech-vat", "mode": "snapshotAndChanges" }; // Run the Actor and wait for it to finish const run = await client.actor("automa-flow/czech-vat-supplier-change-monitor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "suppliers": [ { "vatId": "CZ27082440", "reference": "supplier-001", "expectedBankAccount": "2171532/0800", }, { "vatId": "CZ26168685", "reference": "supplier-002", }, ], "monitorKey": "demo-czech-vat", "mode": "snapshotAndChanges", } # Run the Actor and wait for it to finish run = client.actor("automa-flow/czech-vat-supplier-change-monitor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "suppliers": [ { "vatId": "CZ27082440", "reference": "supplier-001", "expectedBankAccount": "2171532/0800" }, { "vatId": "CZ26168685", "reference": "supplier-002" } ], "monitorKey": "demo-czech-vat", "mode": "snapshotAndChanges" }' | apify call automa-flow/czech-vat-supplier-change-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,automa-flow/czech-vat-supplier-change-monitor" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/h3fvSIyKvJNCTaSTT/builds/9vg3KNSNMv2mIilBP/openapi.json