Report whether TOCOnline credentials are configured and their expiry.

Fast, no side effects. Call this to decide whether to prompt the user through login before attempting other tools.

Open a browser and complete OAuth login against TOCOnline.

The user must have registered http://127.0.0.1:<redirect_port>/callback as a redirect URI in their TOCOnline integration. Credentials are stored at ~/.config/toconline-mcp/credentials.json (mode 0600) and picked up by subsequent tool calls without restarting the server.

This tool blocks for up to 3 minutes while waiting for the browser callback; ask the user to complete the consent promptly.

Delete the stored TOCOnline credentials and drop in-memory tokens.

Return the authenticated company's own profile.

Includes tax_registration_number (NIPC for Portuguese companies), business_name, tax_country_region, contact fields, currency_id, accountant_tax_registration_number, and the linked address_id.

Use this when you need the reporting entity's own identity — for example when producing tax-authority reports (Modelo 30, SAFT-PT), where you need the company's NIPC as the reporter, not the customer's.

List customers. All filters are exact match.

Fetch a single customer by id.

Create a customer. Returns the created record.

Update a customer. Only non-null fields are sent.

Delete a customer. Requires confirm=true.

List suppliers. All filters are exact match.

Fetch a single supplier by id.

Create a supplier. Returns the created record.

Contacts (email/phone) and addresses are separate resources — use create_contact / create_address with this supplier's id afterwards.

Update a supplier. Only non-null fields are sent.

Delete a supplier. Requires confirm=true.

List products. All filters are exact match.

Fetch a single product by id.

Create a product. Returns the created record.

Update a product. Only non-null fields are sent.

Delete a product. Requires confirm=true.

List services. All filters are exact match.

Services live at /api/services, separate from /api/products. Sales/ purchase document lines distinguish them via item_type (Service vs Product).

Fetch a single service by id.

Create a service. Returns the created record.

Update a service. Only non-null fields are sent.

Delete a service. Requires confirm=true.

List countries (ISO codes, names).

List item families — used to categorize products/services (item_family_id).

List units of measure (unidades) for document lines.

List tax descriptors — VAT rates and their codes (NOR, INT, RED, ISE).

List cash accounts (caixas) used for receipts/payments.

List commercial sales documents, newest first by default.

Use page_number + page_size to paginate, and fields to limit the response to just the columns you need.

Fetch a sales document, optionally with its line items merged.

Create a sales document with line items.

Two code paths depending on finalize:

• finalize=True — uses the v1 endpoint (POST /api/v1/commercial_sales_documents), which takes a flat body, embeds lines inline, and issues the document immediately (fiscally binding, irreversible). Customer identity fields are denormalized by fetching /api/customers/{customer_id} first.

• finalize=False (default) — uses the legacy JSON:API endpoint multi-step: POST the header to /api/commercial_sales_documents, then POST each line to /api/commercial_sales_document_lines with document_id linking. The document stays as a draft (status 0) — editable, not yet fiscally valid. To issue later, call finalize_sales_document(id).

v1 ignores finalize=0 (the documented field), so the legacy path is the only way to actually leave a doc in draft state via this API.

Customer identity (name, tax number, address) is denormalized onto the header by TOCOnline server-side, on both paths — but only from the customer's main address. If the header comes back with an empty customer_address_detail, the customer has no main_address_id set; fix the customer's address rather than passing address fields here.

Date: on a certified series the date cannot precede the series' last issued document. The API enforces this; we don't pre-check it (a type can have multiple series, so a client-side guess would risk blocking valid emissions).

Delete a draft sales document.

Use this for cleaning up unfinalised drafts (e.g. orphans left behind by a failed create_sales_document call, or experimental drafts you no longer want). Will fail if the document has been finalised (status != 0) — finalised documents must be voided via a credit note, not deleted.

List sales receipts (customer payments), newest first by default.

Fetch a single sales receipt by id.

Create a sales receipt (customer payment) record.

Note: this creates the receipt itself. To settle specific sales documents against it, add create_sales_receipt_line calls referencing this receipt's id.

Settle a sales document against a receipt (settlement line).

Links an existing receipt to a receivable so the document is marked paid. Field values (how much settles what) are the caller's responsibility — this tool only builds the documented payload.

List commercial purchase documents, newest first by default.

Fetch a purchase document, optionally with its line items merged.

Create a purchase document with lines in a single v1 call.

Supplier identity fields (tax number, business name) are denormalized from the supplier record.

List purchase payments, newest first by default.

Fetch a single purchase payment by id.

Create a purchase payment record.

Note: this creates the payment itself. To settle specific purchase document lines against it, add create_purchase_payment_line calls referencing this payment's id.

Settle a purchase document line against a payment (settlement line).

Links an existing payment to a payable so the document line is marked paid. Note the payable is a document line (payable_id), unlike sales receipts which settle whole documents. Field values are the caller's responsibility — this tool only builds the documented payload.

List addresses. Normally scope to a customer_id or supplier_id.

Scoping uses the nested route (/api/customers/{id}/addresses); the flat /api/addresses?filter[customer_id]= query raises JA011.

Fetch a single address by id.

Create an address attached to a customer or supplier.

TOCOnline uses a polymorphic association — the parent is identified via the addressable_type ("Customer" | "Supplier") and addressable_id attributes, not a JSON:API relationship.

Returns the created (or, on a duplicate, the existing) address re-fetched by id, so the parent link and all fields are populated — the raw POST echo omits them, which makes the address look empty/unlinked.

TOCOnline enforces a uniqueness constraint on address_detail + postcode per parent and raises [400] já existe na tabela on a duplicate; this tool catches that and returns the existing address (idempotent).

Update an address. Only non-null fields are sent.

Delete an address. Requires confirm=true.

List contacts. Normally scope to a customer_id or supplier_id.

Fetch a single contact by id.

Create a contact attached to a customer or supplier.

Polymorphic association via contactable_type ("Customer" | "Supplier") and contactable_id attributes.

Update a contact. Only non-null fields are sent.

Delete a contact. Requires confirm=true.

List company bank accounts (name, IBAN, SWIFT, type).

Each item is enriched with two derived fields:

• pais_conta — ISO country code, from iban[:2] (e.g. PT, GB).

• id_banco — bank identifier:

  • PT accounts: first 4 digits of nib (e.g. 0007 Novo Banco, 0035 Caixa Geral de Depósitos) — matches AT Tabelas_apoio.

  • Foreign accounts: swift when present, else iban[4:8].

Both are None when the underlying iban/nib/swift is empty — a TOCOnline data-completeness issue to fix in the web UI or via PATCH.

These derived fields are what Portuguese reports like Modelo 30 (foreign payments declaration) and IES bank annexes ask for.

Fetch a single bank account by id, enriched with derived id_banco and pais_conta fields (see list_bank_accounts for the rules).

List bank transactions (movements) imported into TOCOnline.

All filters are exact match. To get a date range, make one call per day or page through without a date filter. value is signed (negative for debits, positive for credits).

Fetch a single bank transaction by id.

Get a signed, shareable URL to a PDF render of a document or receipt.

Returns a short-lived URL on app14.toconline.pt (or equivalent for your tenant) that serves the rendered PDF. The URL is signed and does not require authentication to open — give it to a user and they can download the PDF in their browser. It typically expires after a few hours.

Only finalized documents have a PDF. A draft (status 0) returns a "not ready for print" error — finalize it first.

Send a sales document or receipt to a recipient by email.

Uses TOCOnline's built-in email delivery — the message arrives from TOCOnline's mail servers with your document attached / linked.

Finalize (issue) a draft sales document.

Once finalized, the document becomes fiscally valid and immutable. Requires confirm=true because the operation cannot be reversed.

Finalize a draft purchase document.

Communicate a finalized sales document to the AT (Portuguese tax authority).

Triggers TOCOnline's send_document_at_webservice action. The document must already be finalized. Requires confirm=true because the report is a binding fiscal submission. The response carries the AT communication status/code returned by the webservice.

Communicate a finalized purchase document to the AT (Portuguese tax authority).

Void (anular) a sales receipt.

Void (anular) a purchase document.

Escape hatch for endpoints not covered by typed tools.

Path must match /api/<resource>[/<sub>...]. Destructive methods require confirm=true. Prefer the typed tools (list_customers, create_sales_document, etc.) when they fit.