inv.bg MCP by usefulapi

The company (id, name, subdomain) and the user the API token belongs to. GET /account.

Takes no parameters.

The issuing company's details: name, Bulstat, VAT registration and VAT number, address, MOL, contact email, custom properties. GET /firm.

Takes no parameters.

List documents (tax invoices, proformas, debit and credit notes) with filters: type, number, issue-date range, amount ranges, payment status, client, draft/annulled, sent status, currency. Each row has number, client, totals, balance_paid, balance_due and dates. GET /invoices.

One document by id: number, type, issuer and recipient, line items, VAT, totals, balance_paid and balance_due, dates, bank accounts, sent/confirmation status. Optionally with its comments. GET /invoices/{id}.

All document types of this company (tax invoice, proforma, debit/credit note and any custom types) with their codes. GET /invoices/types.

Takes no parameters.

The next free document number of the default number set for a document type. Read-only: it does not reserve the number. GET /invoices/free-number.

The company's invoice number sets (separate numbering series) with ids; pass an id as number_set to invbg_create_invoice. GET /invoices/number-sets.

The payment method codes a document accepts (cash, bank, card, ...) with their names. GET /invoices/payment-methods.

The legal reasons for issuing a document without VAT (use one as vat_exemption_reason in invbg_create_invoice). GET /invoices/without-vat-reasons.

List or search clients (customers): name, Bulstat, VAT number, address, MOL, whether it is a person. GET /clients.

One client by id with all stored details (names in both languages, Bulstat, VAT, address, MOL, code, custom properties). GET /clients/{id}.

Contact people of a client (or of all clients) with their names and roles. GET /client-contacts.

The product/service catalogue: name, price, currency, unit, tags. GET /items.

One catalogue item by id. GET /items/{id}.

Units of measure accepted as quantity_unit on items and invoice lines. GET /items/units.

Recorded payments (income and expense) with amount, method, date, counterparty, how much is allocated to invoices (amount_used) and what is left (amount_left). GET /payments.

One payment by id with its allocations to invoices (invoice_payments). GET /payments/{id}.

The company's bank accounts (alias, bank, IBAN, BIC, currency). GET /bank/accounts.

Imported bank transactions with amount, date, counterparty, and whether they are linked to a document. Useful for reconciliation (linked=false = unmatched). GET /bank/transactions.

The company's cash registers (cashboxes) with names and balances. GET /cashboxes.

The exchange rate of a currency to BGN on a date (default: today), as inv.bg uses it for documents. GET /currency/rates/{currency}.

WRITE: add a company client (name, Bulstat, VAT, address, MOL). Check invbg_list_clients first to avoid a duplicate. For an individual (EGN) issue the document with invbg_create_invoice and is_to_person instead. POST /clients.

WRITE: change fields of an existing client (only the fields you pass are changed). PATCH /clients/{id}.

WRITE: add a product or service to the catalogue (name, price, unit). POST /items.

WRITE: create a document (tax invoice by default; proforma, debit/credit note via type). It is saved as a DRAFT unless draft is false: an issued document takes the next legal number and cannot be undone through this tool. Address it to an existing client_id, or give to_name + to_address (+ to_mol and to_bulstat for a company, to_egn for a person) and inv.bg matches or creates the client from those details (an existing client matched by Bulstat or VAT number is UPDATED with the address, MOL and other details you pass). VAT: set vat_percent on the document, or on every item. POST /invoices.

WRITE: email a document to a recipient (as a download link or an attached file). The email goes out immediately and cannot be recalled. POST /invoices/{id}/emails.

WRITE: record a payment received for a document and allocate it, which updates the document's balance_paid/balance_due and payment status. Two calls: POST /payments, then POST /payments/{id}/invoices. If the allocation fails the payment stays recorded: the error names its id (see invbg_get_payment).