# TACITo > TACITo (https://tacito.hu) is a Hungarian invoicing service with automatic NAV Online Számla reporting. Software > integrates it like a payment provider: an API key on the server, then create, issue, download, mark paid, > cancel. This file tells an AI coding agent everything it needs to integrate TACITo correctly, in TypeScript > (with the `tacito-sdk` package) or in any other language (plain HTTP). ## Rules (read first; they prevent real damage) 1. **Server-side only.** The API key (`tacit_...`) can issue legally binding invoices for the whole company. Keep it in a server environment variable named `TACITO_API_KEY`. Never put it in browser code, mobile apps, or `NEXT_PUBLIC_*` / `VITE_*` / `EXPO_PUBLIC_*` variables. A browser calls *your* server route; only that route calls TACITo. 2. **Authorize and compute on the server.** Before invoicing, check that the logged-in user owns the order, and take buyer data and amounts from your own database, never from the request body. A route that invoices whatever a browser sends lets anyone issue invoices in your company's name. 3. **Every write carries a `reference`**: your stable id for the business event (the order id for its invoice, the payment id for a payment, `:refund` for a cancellation). Retries are then safe: the same reference returns the first result instead of a second invoice. Use a new reference only for a new business event. References are shared by everything that uses the same TACITo account, so **prefix them with your app's name** (`myshop:order-42`, not `42`): two systems sending `42` would collide. In the SDK it is the `reference` option; over plain HTTP it is not a body field but the `Idempotency-Key` header (`:`, see the table below). If a call dies halfway (for example after the draft was created but before it was issued), repeat it with the same reference: the finished steps are replayed and the rest completes. 4. **An issued invoice cannot be edited or deleted.** It gets a number and is reported to the tax authority (NAV). To undo one, issue a storno (cancellation). Drafts can be deleted. 5. **Check readiness before going live.** `GET /api/v1/readiness` lists what is missing (issuer details, invoice series, subscription, NAV production credentials), each with a link to fix it. 6. **Do not invent tax logic.** Send the buyer type, the lines and the VAT rate; the server decides the tax treatment and refuses invalid combinations with a clear error. ## Fitting TACITo into your app (do this in order) TACITo works with any database and any payment processor: it never touches either. Your code decides *when* an invoice is due (the processor's "payment succeeded" event) and *what* goes on it (your own database). Work through these steps before writing code. ### 1. Ask the user (do not guess) - Is the company VAT-exempt (alanyi adómentes, AAM)? Then domestic lines use `vatRate: 'AAM'`; otherwise usually `27%`. Sales to EU businesses or buyers outside the EU follow the VAT table in "Lines and VAT" below, not this rule. - Who pays: Hungarian companies, private persons, EU businesses, buyers outside the EU? This decides which billing fields you collect. - Are the stored prices net or gross? Send `unitPriceNet` or `unitPriceGross` accordingly, never both. - Which payment processor, and is it a merchant of record (see the last row of the table below)? - For subscriptions: which performance date (teljesítés dátuma) the accountant wants on each period's invoice. ### 2. Find the trigger: the payment processor Verify the event with the processor's own library or API, then invoice from your database. Put your own order id in the payment's metadata when you create it, so the handler can load the order. | Processor | Invoice when | Reference (`app` = your app's name) | |---|---|---| | Stripe Checkout (one-off) | `checkout.session.completed` with `payment_status: 'paid'`, and `checkout.session.async_payment_succeeded` | `app:order-` | | Stripe Billing (SaaS subscription) | `invoice.paid`: one TACITo invoice per paid Stripe invoice (first payment and every renewal) | `app:stripe-invoice-` | | Barion | the callback gives a `paymentId`; ask Barion for its state and invoice when it is `Succeeded` | `app:barion-` | | SimplePay | the IPN call; verify its signature, invoice when the status is `FINISHED`, then send the confirmation SimplePay expects | `app:order-` | | PayPal Checkout | `PAYMENT.CAPTURE.COMPLETED` (verify the webhook signature) | `app:paypal-` | | PayPal Subscriptions | `PAYMENT.SALE.COMPLETED`: one invoice per completed sale (verify the webhook signature) | `app:paypal-sale-` | | Bank transfer | issue at order time with `paymentMethod: 'BANK_TRANSFER'` and a `dueDate`; call `markPaid` when the money arrives | `app:order-`, payment `app:payment-` | | Paddle, Lemon Squeezy or another merchant of record | **do not invoice the customer**: the platform sells to them and issues its own invoice, and usually also creates a self-billed invoice for your payout. Build nothing for this without asking the user, who should check with their accountant | - | - **Save first, invoice after.** In the webhook handler, verify the event, save a payment row (the buyer and line snapshot, invoice pending) and acknowledge quickly: Barion expects an answer within about 15 seconds, and every processor stops redelivering after a while. Then issue the invoice from that row, right away and again from a scheduled job (every few minutes) for rows still pending, always with the same reference, so a TACITo or network outage longer than the processor's retries still ends in exactly one invoice. - **Which failures to retry later:** network errors, 429, 5xx, a 409 whose message says "Please retry" (the invoice changed while it was being issued), and `errors.exchange_rate = ["EXCHANGE_RATE_UNAVAILABLE"]` (the MNB exchange rate is temporarily unavailable; foreign-currency invoices only). Any other 4xx will not fix itself, including a 409 conflict (the same reference with a different payload is a bug in your code): save it in `tacito_error` and show it to an admin. - **After an admin fixes the data:** only successful steps are stored under a reference, but `createAndIssue` may already have created the draft before the issue step failed. Find that draft (`GET /api/v1/invoices/search` by buyer and date, or the id in your logs), delete it (`DELETE /api/v1/invoices/`, drafts only), then retry with the corrected snapshot under a new reference (append `:2`). Never reuse a reference with a different payload. - **Subscriptions:** invoice what the customer was actually charged. Save each paid Stripe invoice's lines and amounts as Stripe finalized them (prorations, discounts and quantities included), from the verified event or the Stripe API, into the payment row, and take the VAT rate and the product name from your own plan row (mapped by price id). Stripe amounts are in the currency's smallest unit (see Stripe's currency list; HUF is a two-decimal currency in its API). Skip zero-amount Stripe invoices (free trials). A Stripe invoice is not a Hungarian invoice: tell the user to turn off Stripe's customer invoice emails (or treat them as receipts) so the customer gets one invoice, from TACITo. - **Refunds:** a full refund event (Stripe: `charge.refunded` with `refunded: true`; match it to your payment row by the charge or payment-intent id you stored) → `storno` with the reference `:refund`, and store the returned storno invoice's id and number. If the refund arrives before the invoice was issued, mark the row and storno right after issuing. A partial refund needs a modifying invoice (`POST /api/v1/invoices//modify`, via the SDK's `request()`); ask the user before building it. ### 3. Your database Use the project's existing database, ORM and migration tool (Postgres, MySQL, SQLite, MongoDB, Prisma, Drizzle, Supabase all work). Add: - **On the paid thing** (the order, or one payment row per paid subscription period): `tacito_invoice_id`, `tacito_invoice_number`, `tacito_nav_outcome`, `tacito_error`, all nullable text, plus the buyer and line snapshot the invoice is built from. Save the first two right after `createAndIssue` returns; a row with no `tacito_invoice_id` is still pending. - **Billing details on the customer or account**, because SaaS signups usually have only an email: buyer type (company or private person), name, country, postal code, city, street address, and the Hungarian tax number for companies or the EU VAT number for EU businesses. Ask for them in a short form before the first payment, and copy them onto the order when it is paid, so the invoice shows the details valid at purchase. - **On each product or plan:** its price (net or gross, as the user answered) and its VAT rate. - **For the change feed:** one row that stores the last `next_cursor`. ```sql -- Postgres example; adapt to the project's ORM and migration tool ALTER TABLE orders ADD COLUMN tacito_invoice_id text, ADD COLUMN tacito_invoice_number text, ADD COLUMN tacito_nav_outcome text, ADD COLUMN tacito_error text; ``` ## TypeScript / JavaScript: `tacito-sdk` Zero dependencies; Node 18+, Deno (`npm:tacito-sdk`, e.g. Supabase Edge Functions), Bun, Vercel/Cloudflare edge. ```bash npm install tacito-sdk ``` ```ts import { TacitoSDK, TacitoError } from 'tacito-sdk' const tacito = new TacitoSDK({ apiKey: process.env.TACITO_API_KEY! }) const invoice = await tacito.invoices.createAndIssue({ reference: `myshop:order-${order.id}`, // required; app-prefixed; makes retries safe buyer: { type: 'company', name: 'Vevő Kft.', taxNumber: '12345678-2-41', address: { postalCode: '1111', city: 'Budapest', street: 'Fő utca 1.' } }, lines: [{ description: 'Pro csomag', quantity: '1', unitPriceNet: '10000', vatRate: '27%' }], paymentMethod: 'CARD', // BANK_TRANSFER | CASH | CARD }) const pdf = await tacito.invoices.pdf(invoice.id) // ArrayBuffer; `new Response(pdf)` works as-is // invoice is the API's invoice object (snake_case): id, invoice_number, state, gross_total, currency, // payment_status, nav_outcome. Store invoice.id and invoice.invoice_number on your order. await tacito.invoices.markPaid(invoice.id, { reference: `myshop:payment-${payment.id}`, amount: '12700' }) // storno creates AND issues the cancelling invoice; it returns that new (storno) invoice: store its id and number too const cancel = await tacito.invoices.storno(invoice.id, { reference: `myshop:order-${order.id}:refund` }) await tacito.invoices.send(invoice.id) // email it now; never retried; see auto_send_invoice_email const status = await tacito.readiness() // { ready, livemode, missing: [{ step, url }], nav: { configured, environment, production_allowed }, // subscription: { state, mutation_allowed }, auto_send_invoice_email } for await (const event of tacito.events.iterate({ after: savedSeq })) { // event: { id, seq, type, invoice_id, created_at, data }; match your row by event.invoice_id, // then save event.seq as the new cursor (in the same transaction as your update) } // Anything else: tacito.request(method, '/api/v1/...', { query, body, idempotencyKey }), full path, same auth, // retries and errors. E.g. a partial refund: request('POST', `/api/v1/invoices/${id}/modify`, { body, idempotencyKey }) ``` **Buyers in the SDK** (the server maps them to the API fields; the address is `{ postalCode, city, street }`, `email` is optional on all of them): | `type` | Fields | |---|---| | `company` | Hungarian company or sole trader: `name`, `taxNumber` (`12345678-2-41` format), `address` | | `private` | private person: `name`, `address` (add `countryCode` inside it for a foreign private buyer; default `HU`) | | `eu_business` | `name`, `euVatNumber` (e.g. `DE123456789`), `countryCode`, `address` | | `foreign` | outside the EU: `name`, `countryCode`, `address`, optional `thirdCountryTaxId`, `isBusiness` | **Dates:** `issueDate`, `performanceDate` (teljesítés dátuma) and `dueDate`, all `YYYY-MM-DD`; the server fills in today and the series' due-date rule when omitted. Hungarian VAT has special rules for the performance date of periodic services such as subscriptions: do not choose one yourself, ask the user (and their accountant) which date to send, and store it in the payment snapshot. Other optional fields: `currency` (default HUF), `language` (`hu`, `en`, `de`, `cs`, `pl`), `note`, `paymentReference` (e.g. the processor's payment id). **Foreign currency (EUR etc.):** send the prices in that currency and **no exchange rate**. TACITo decides the tax exchange rate when the invoice is issued: the official MNB rate for the invoice's issue date (or the last published day before it). The amounts in the invoice currency never change; only the HUF tax amounts use the rate. On a draft, `exchange_rate_status` is `PENDING_AT_ISSUE` and `exchange_rate` is a placeholder. After issuing, it is `RESOLVED`, and `exchange_rate`, `exchange_rate_source` (`MNB`) and `exchange_rate_date` hold what was applied. A rate sent anyway is replaced, and the response carries the warning `EXCHANGE_RATE_REPLACED_AT_ISSUE`. To show the rate in advance, call `exchangeRate('EUR', 'YYYY-MM-DD')` (`GET /api/v1/exchange-rates`). It is a preview only; a `503` there, or `EXCHANGE_RATE_UNAVAILABLE` on issue, means MNB is unreachable: retry later. **Emailing the invoice:** if `readiness().auto_send_invoice_email` is true, TACITo emails every issued invoice to the buyer's `email` itself; otherwise call `invoices.send(id)` once after issuing (it is never retried automatically). Every failure is a `TacitoError`: `status`, `code`, `message`, `fieldErrors`, `requestId`, `retryable`, `retryAfterSeconds`. The SDK already retries safe calls (reads, and writes with a reference) on 429/5xx; do not wrap it in your own retry loop. Each attempt times out after 30 seconds (option `timeoutMs`) and a call makes at most 3 attempts, so do not run `createAndIssue` inside a webhook that must answer fast: save first, invoice after (see "Fitting TACITo into your app"). Two simultaneous calls with the same reference do not both run: the second waits for the first and returns the same result. Option `baseUrl` points the SDK at another server (default `https://tacito.hu`). ## Any other language: plain HTTP Base URL `https://tacito.hu/api/v1`. Auth header `Authorization: Bearer $TACITO_API_KEY`. JSON in and out; amounts and quantities as decimal strings. ```bash # 1. Create a draft (Idempotency-Key = your reference + ":create") curl -sS https://tacito.hu/api/v1/invoices \ -H "Authorization: Bearer $TACITO_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: myshop:order-42:create" \ -d '{"buyer":{"name":"Vevő Kft.","country_code":"HU","postal_code":"1111","city":"Budapest", "address":"Fő utca 1.","tax_number":"12345678-2-41","is_taxable_person":true}, "lines":[{"description":"Pro csomag","quantity":"1","unit_price_net":"10000","vat_rate":"27%"}], "payment_method":"CARD"}' # -> 201 {"id": "", "state": "DRAFT", ...} # 2. Issue it (no body; Idempotency-Key = reference + ":issue") curl -sS -X POST https://tacito.hu/api/v1/invoices//issue \ -H "Authorization: Bearer $TACITO_API_KEY" -H "Idempotency-Key: myshop:order-42:issue" # -> 200 {"id": ..., "state": "ISSUED", "invoice_number": "A-000123", ...} # 3. PDF curl -sS https://tacito.hu/api/v1/invoices//pdf -H "Authorization: Bearer $TACITO_API_KEY" -o invoice.pdf ``` | Purpose | Call | Idempotency-Key | |---|---|---| | Readiness | `GET /readiness` | - | | Create draft | `POST /invoices` | `:create` | | Issue | `POST /invoices//issue` | `:issue` | | Invoice detail | `GET /invoices//detail` | - | | PDF | `GET /invoices//pdf` | - | | Record payment | `POST /invoices//payments` `{"amount":"12700"}` | `:pay` | | Cancel (storno) | `POST /invoices//storno`, then issue the returned draft | `:storno`, `:storno-issue` | | Email to buyer | `POST /invoices//send` | none: never retry it | | Changes | `GET /events?after=` | - | | Company lookup | `GET /cegadatapi/lookup?tax_number=12345678-2-41` (the whole tax number) | - | **One reference, one payload.** Every entry point that can invoice the same order (checkout route, payment webhook, admin button) must build the identical request for its reference, from one shared function. A different body under the same key is a 409, not a resume. **Retries.** Retry only reads and requests that carry an `Idempotency-Key`, on 429, 5xx or a network error, at most 3 times. Wait `Retry-After` seconds (header) or `errors.rate_limit.retry_after_seconds`; if that is more than a minute, give up and report it. The same key with a different body returns 409: that is a bug in your code, not a reason to change the key. Only successful responses are stored under a key, so after a 4xx you may fix the body and send it again with the same key. Every response has an `X-Request-Id`; log it. **Errors** are JSON `{"code": 400, "status": "...", "message": "...", "errors": {...}}`. Read `message` first; `errors` names the offending fields, e.g. `errors.json.` for schema errors, `errors.lines.0.unit_price_net` for a line, `errors.query.` for query parameters. A read-only (unpaid) account answers 403 with `errors.subscription = ["subscription_read_only"]`. ## Buyers | Buyer | Fields | |---|---| | Hungarian company or sole trader | `tax_number` (`12345678-2-41` format), `is_taxable_person: true`, `country_code: "HU"` | | Private person | `is_taxable_person: false`, no tax number, `country_code` (default `HU`) | | EU business | `eu_vat_number` (e.g. `DE123456789`), `country_code`, `is_taxable_person: true` | | Outside the EU | `country_code`, optional `third_country_tax_id`, `is_taxable_person` | All buyers need `name`, `postal_code`, `city`, `address`; `email` is optional (used for sending the invoice). ## Lines and VAT Each line: `description`, `quantity`, `unit_price_net` **or** `unit_price_gross`, `vat_rate`, optional `unit`. `vat_rate`: `27%`, `18%`, `5%` for domestic sales; `AAM` if the seller is VAT-exempt (alanyi adómentes); `ÁKK` (out of scope) and `TAM` (exempt, optional `vat_exemption_case`) with an optional `vat_reason`; `0%` for EU business or non-EU buyers (the server derives the reason), or on a domestic invoice only with a legal reason in `tax_profile.zero_rate_reason_code` (e.g. `HU_NEWSPAPER_VTSZ_4902`, daily newspapers). Anything else is refused with a field error. ## Changes (instead of webhooks) `GET /api/v1/events?after=` returns `{events, has_more, next_cursor}`, ordered. Types: `invoice.issued`, `invoice.payment_status_changed`, `invoice.nav_status_changed`; `data` holds the invoice's current summary (`invoice_number`, `state`, `payment_status`, `nav_status`, `gross_total`, `currency`). Poll it from a scheduled job (every minute is plenty), store `next_cursor` (a string) after each page, and dedupe by event `id`. **NAV state.** Invoice objects carry `nav_outcome`: `ACCEPTED` (NAV accepted it), `IN_PROGRESS` (queued or waiting), `ERROR` (needs action; see `GET /invoices//detail` → `nav_job.messages`, NAV's own messages, and `nav_job.last_error`), `NOT_CONFIGURED` (issued before NAV credentials were set, so not reported), `NOT_REPORTABLE` (no report required), `VOIDED` (voided by the operator because NAV holds its number from another document; NAV never accepted it, it is kept for the archive and left out of search unless `nav=VOIDED`). Events carry the raw `nav_status`; map it like this, or read `nav_outcome` from `invoices.get(id)`: `DONE`, `DONE_WITH_WARNINGS` → `ACCEPTED`; `REJECTED`, `FAILED`, `XML_INVALID`, `NAV_CONFIG_ERROR`, `CHAIN_HOLD`, `DUPLICATE_HOLD`, `PDF_HOLD` → `ERROR`; `NOT_CONFIGURED`, `NOT_REPORTABLE`, `VOIDED` as is; any other value (for example `PENDING`, `RETRY`) → `IN_PROGRESS`. ## MCP server (an AI assistant working in a TACITo account) Everything above is for software that integrates TACITo. To let an AI assistant (Claude Desktop, Claude Code, Cursor, Codex or any other MCP client) work in a person's own TACITo account, use the MCP server `tacito-mcp` (npm, MIT, Node 18+). It runs on the user's computer over stdio and calls this API with the user's API key. ```json { "mcpServers": { "tacito": { "command": "npx", "args": ["-y", "tacito-mcp"], "env": { "TACITO_API_KEY": "tacit_...", "TACITO_MCP_MODE": "draft" } } } } ``` Claude Code: `claude mcp add tacito --env TACITO_API_KEY=tacit_... -- npx -y tacito-mcp`. Codex: the same with `codex mcp add`. In every form on this page the user puts the key in: an assistant does not ask for the key in the chat, does not write it into a command or a settings file for the user, and does not run the setup for them. A key given in the chat stays in the conversation, and on a command line it lands in the shell history. One-line setup on macOS and Linux: `curl -fsSL https://tacito.hu/mcp-szerver/install.sh | sh`. It asks for the key and the mode in the terminal, installs the package into `~/.tacito-mcp` and adds that copy to every client it finds (Claude Code, Codex, Claude Desktop, Cursor); the key is kept in one private file there. The user runs it and types the key there. With the `npx` form above, npx takes a package named `tacito-mcp` from the client's current folder first: in a project folder that is not trusted, use the one-line setup or a global install (`npm install -g tacito-mcp`, command `tacito-mcp`). `TACITO_MCP_MODE` decides which tools exist; each mode includes the ones before it: | Mode | Tools | |---|---| | `read` | `get_readiness`, `search_invoices`, `get_invoice`, `lookup_company`, `get_exchange_rate` | | `draft` (default) | `create_invoice_draft`, `create_storno_draft`, `delete_invoice_draft` | | `full` | `issue_invoice` | In the default mode nothing legally binding can happen: a draft has no number, is not reported to NAV and can be deleted. Only `issue_invoice` (mode `full`, switched on by the user) issues: show the user the draft and get an explicit yes first. `issue_invoice` takes the draft's id and the gross total the user approved, and issues nothing if the draft's total differs. If the account e-mails invoices automatically (`auto_send_invoice_email` in `get_readiness`), issuing e-mails the invoice to the buyer. Repeating `issue_invoice` for the same draft returns the first result. To cancel an issued invoice, call `create_storno_draft` and issue that draft. Not in this server: modifying invoices, pro forma and advance invoices, payments, e-mail, PDF download. ## Going live 1. Create the API key: Beállítások → API kulcsok (https://tacito.hu/beallitasok/api-kulcsok). Choose read+write. 2. Run `GET /api/v1/readiness` and fix every `missing` step: issuer details, invoice series, subscription, NAV production credentials. If the user needs help creating the NAV technical user and connecting NAV, hand them https://tacito.hu/nav-beallitas (a guide written for AI assistants that coach the user; they never touch the secrets). 3. Issue one real invoice to yourself, check the PDF and that `nav_outcome` becomes `ACCEPTED`, then storno it. ## More - SDK source and recipes (Next.js route handler, Supabase Edge Function, Stripe webhook, event polling): https://www.npmjs.com/package/tacito-sdk - MCP server for AI assistants (`tacito-mcp`; page in Hungarian): https://tacito.hu/mcp-szerver, https://www.npmjs.com/package/tacito-mcp - Full API reference: https://tacito.hu/api/docs (OpenAPI: https://tacito.hu/api/openapi.json) - Facts about the service (operator, price, features, limits; Hungarian): https://tacito.hu/ai-info - Support: info@tacitproject.hu (include the `X-Request-Id`)