inv.bg MCP by usefulapi
Read inv.bg invoices, clients, items, payments and banking; create clients, items, invoices.
¿Debería usar esto?
Calidad y seguridad
A
Hallazgos (1)
- LOWTool 'invbg_list_vat_exemption_reasons' name length outside 3-30 rangeen invbg_list_vat_exemption_reasons
Basado en el análisis automatizado de las definiciones de herramientas y el cumplimiento del protocolo.
Costo de contexto
~7,813Tokens (definiciones de herramientas)
~2.5 KBTamaño de respuesta típico
Impacto significativo en la atención (6.10% del contexto de 128k)
Este es el número aproximado de tokens que se consumen cada vez que las herramientas del servidor se cargan en el contexto de un modelo. Los recuentos más altos reducen la atención disponible para otras tareas.
Instalar
Instalación con un clic
Agrega esto a tu archivo `claude_desktop_config.json`:
{
"mcpServers": {
"inv-bg": {
"url": "https://inv-bg.usefulapi.io/mcp"
}
}
}Puntos de conexión remotos
https://inv-bg.usefulapi.io/mcpstreamable-httpQué puede hacer
Inventario de herramientas
Herramientas (27)
🟢 Solo lectura🟡 Escritura🔴 Eliminación⚪ Desconocido
🟢invbg_get_account
The company (id, name, subdomain) and the user the API token belongs to. GET /account.
Esquema de entrada
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_firm
The issuing company's details: name, Bulstat, VAT registration and VAT number, address, MOL, contact email, custom properties. GET /firm.
Esquema de entrada
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_invoices(type, number, date_from, date_to, amount_gt, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"type": {
"description": "Document types: dan = tax invoice, prof = proforma, deb = debit note, cred = credit note.",
"maxItems": 6,
"type": "array",
"items": {
"type": "string",
"enum": [
"dan",
"prof",
"deb",
"cred",
"protocol",
"custom"
]
}
},
"number": {
"description": "Document number (as printed, e.g. 0000000024).",
"type": "string",
"minLength": 1,
"maxLength": 50
},
"date_from": {
"description": "Only documents dated on or after this date, yyyy-mm-dd.",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
},
"date_to": {
"description": "Only documents dated on or before this date, yyyy-mm-dd.",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
},
"amount_gt": {
"description": "Only documents with a total of at least this amount.",
"type": "number"
},
"amount_lt": {
"description": "Only documents with a total of at most this amount.",
"type": "number"
},
"amount_due_gt": {
"description": "Only documents with an outstanding balance of at least this amount.",
"type": "number"
},
"amount_due_lt": {
"description": "Only documents with an outstanding balance of at most this amount.",
"type": "number"
},
"status": {
"description": "Payment statuses to include. Use [\"unpaid\", \"partially-paid\"] to find open receivables.",
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"enum": [
"paid",
"unpaid",
"partially-paid"
]
}
},
"client_id": {
"description": "Only documents issued to this client (invbg_list_clients).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"client_name": {
"description": "Client name filter; % matches any run of characters, _ one character.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"is_draft": {
"description": "true = only drafts, false = no drafts.",
"type": "boolean"
},
"is_annulled": {
"description": "true = only annulled documents, false = none.",
"type": "boolean"
},
"send_status": {
"description": "Email status(es) to include.",
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"enum": [
"unsent",
"sent",
"resent"
]
}
},
"currency": {
"description": "Only documents in this currency.",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"order_by": {
"description": "Field to sort by (for example id, date or name; see the vendor reference).",
"type": "string",
"minLength": 1,
"maxLength": 50,
"pattern": "^[A-Za-z0-9_.]+$"
},
"order": {
"description": "Sort direction (default desc).",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_invoice(invoice_id, include_comments, language)
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}.
Esquema de entrada
{
"type": "object",
"properties": {
"invoice_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg document id (the id field of invbg_list_invoices, not the printed number)."
},
"include_comments": {
"description": "Also return the document's comments.",
"type": "boolean"
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"required": [
"invoice_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_invoice_types
All document types of this company (tax invoice, proforma, debit/credit note and any custom types) with their codes. GET /invoices/types.
Esquema de entrada
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_next_invoice_number(type)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"type": {
"description": "Document type (default: tax invoice).",
"type": "string",
"enum": [
"dan",
"prof",
"deb",
"cred",
"custom"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_number_sets(page, per_page)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_payment_methods(language)
The payment method codes a document accepts (cash, bank, card, ...) with their names. GET /invoices/payment-methods.
Esquema de entrada
{
"type": "object",
"properties": {
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_vat_exemption_reasons(language)
The legal reasons for issuing a document without VAT (use one as vat_exemption_reason in invbg_create_invoice). GET /invoices/without-vat-reasons.
Esquema de entrada
{
"type": "object",
"properties": {
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_clients(name, bulstat, vat_number, code, is_person, ...)
List or search clients (customers): name, Bulstat, VAT number, address, MOL, whether it is a person. GET /clients.
Esquema de entrada
{
"type": "object",
"properties": {
"name": {
"description": "Filter by client name.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"bulstat": {
"description": "Filter by EIK/Bulstat.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"vat_number": {
"description": "Filter by VAT number.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"code": {
"description": "Filter by the client code.",
"type": "string",
"minLength": 1,
"maxLength": 50
},
"is_person": {
"description": "true = individuals only, false = companies only.",
"type": "boolean"
},
"is_reg_vat": {
"description": "true = VAT-registered clients only.",
"type": "boolean"
},
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"order_by": {
"description": "Field to sort by (for example id, date or name; see the vendor reference).",
"type": "string",
"minLength": 1,
"maxLength": 50,
"pattern": "^[A-Za-z0-9_.]+$"
},
"order": {
"description": "Sort direction (default desc).",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_client(client_id, language)
One client by id with all stored details (names in both languages, Bulstat, VAT, address, MOL, code, custom properties). GET /clients/{id}.
Esquema de entrada
{
"type": "object",
"properties": {
"client_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg client id (invbg_list_clients)."
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"required": [
"client_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_client_contacts(client_id, search, page, per_page)
Contact people of a client (or of all clients) with their names and roles. GET /client-contacts.
Esquema de entrada
{
"type": "object",
"properties": {
"client_id": {
"description": "Only the contacts of this client.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_items(search, tag_name, order_by, order, language, ...)
The product/service catalogue: name, price, currency, unit, tags. GET /items.
Esquema de entrada
{
"type": "object",
"properties": {
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"tag_name": {
"description": "Only items with this tag.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"order_by": {
"description": "Field to sort by (for example id, date or name; see the vendor reference).",
"type": "string",
"minLength": 1,
"maxLength": 50,
"pattern": "^[A-Za-z0-9_.]+$"
},
"order": {
"description": "Sort direction (default desc).",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_item(item_id, language)
One catalogue item by id. GET /items/{id}.
Esquema de entrada
{
"type": "object",
"properties": {
"item_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg item id (invbg_list_items)."
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"required": [
"item_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_item_units(language)
Units of measure accepted as quantity_unit on items and invoice lines. GET /items/units.
Esquema de entrada
{
"type": "object",
"properties": {
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_payments(payment_processor, paid_from, paid_to, amount_gt, amount_lt, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"payment_processor": {
"description": "How the payment was received.",
"maxItems": 6,
"type": "array",
"items": {
"type": "string",
"enum": [
"bank",
"cash",
"epay",
"paypal",
"stripe",
"revolut"
]
}
},
"paid_from": {
"description": "Paid on or after this date.",
"type": "string"
},
"paid_to": {
"description": "Paid on or before this date.",
"type": "string"
},
"amount_gt": {
"description": "Amount of at least this value.",
"type": "number"
},
"amount_lt": {
"description": "Amount of at most this value.",
"type": "number"
},
"contragent": {
"description": "Counterparty name; % matches any run of characters.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contragent_id": {
"description": "Counterparty (client) id.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"is_expense": {
"description": "true = expenses only, false = income only.",
"type": "boolean"
},
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"order_by": {
"description": "Field to sort by (for example id, date or name; see the vendor reference).",
"type": "string",
"minLength": 1,
"maxLength": 50,
"pattern": "^[A-Za-z0-9_.]+$"
},
"order": {
"description": "Sort direction (default desc).",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_payment(payment_id)
One payment by id with its allocations to invoices (invoice_payments). GET /payments/{id}.
Esquema de entrada
{
"type": "object",
"properties": {
"payment_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg payment id (invbg_list_payments)."
}
},
"required": [
"payment_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_bank_accounts(language, page, per_page)
The company's bank accounts (alias, bank, IBAN, BIC, currency). GET /bank/accounts.
Esquema de entrada
{
"type": "object",
"properties": {
"language": {
"description": "Language of names in the reply: bg (default) or en, where the record has both.",
"type": "string",
"enum": [
"bg",
"en"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_bank_transactions(bank_account_id, type, date_from, date_to, amount_gt, ...)
Imported bank transactions with amount, date, counterparty, and whether they are linked to a document. Useful for reconciliation (linked=false = unmatched). GET /bank/transactions.
Esquema de entrada
{
"type": "object",
"properties": {
"bank_account_id": {
"description": "Only these bank accounts (invbg_list_bank_accounts).",
"maxItems": 50,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"type": {
"description": "deb = debit (money out), cred = credit (money in).",
"type": "string",
"enum": [
"deb",
"cred"
]
},
"date_from": {
"description": "On or after this date, yyyy-mm-dd.",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
},
"date_to": {
"description": "On or before this date, yyyy-mm-dd.",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
},
"amount_gt": {
"description": "Amount of at least this value.",
"type": "number"
},
"amount_lt": {
"description": "Amount of at most this value.",
"type": "number"
},
"linked": {
"description": "true = only transactions linked to documents, false = only unlinked ones.",
"type": "boolean"
},
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"order_by": {
"description": "Field to sort by (for example id, date or name; see the vendor reference).",
"type": "string",
"minLength": 1,
"maxLength": 50,
"pattern": "^[A-Za-z0-9_.]+$"
},
"order": {
"description": "Sort direction (default desc).",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_list_cashboxes(search, page, per_page)
The company's cash registers (cashboxes) with names and balances. GET /cashboxes.
Esquema de entrada
{
"type": "object",
"properties": {
"search": {
"description": "Free-text search over the results.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"page": {
"description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
},
"per_page": {
"description": "Results per page, 1-100 (default 25).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢invbg_get_exchange_rate(currency, date)
The exchange rate of a currency to BGN on a date (default: today), as inv.bg uses it for documents. GET /currency/rates/{currency}.
Esquema de entrada
{
"type": "object",
"properties": {
"currency": {
"description": "Currency, ISO 4217 code such as BGN or EUR.",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"date": {
"description": "Rate date, yyyy-mm-dd (default today).",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
}
},
"required": [
"currency"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟡invbg_create_client(name, bulstat, is_reg_vat, vat_number, town, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "Company name."
},
"bulstat": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"description": "EIK/Bulstat of the company."
},
"is_reg_vat": {
"description": "Whether the company is VAT-registered (default false).",
"type": "boolean"
},
"vat_number": {
"description": "VAT number; required when is_reg_vat is true.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"town": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"address": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"country": {
"description": "Country name or code as inv.bg stores it, e.g. BG.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"mol": {
"description": "Accountable person (MOL).",
"type": "string",
"minLength": 1,
"maxLength": 150
},
"code": {
"description": "Your own unique client code.",
"type": "string",
"minLength": 1,
"maxLength": 50
},
"delivery_address": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"name",
"bulstat"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴invbg_update_client(client_id, name, bulstat, is_reg_vat, vat_number, ...)
WRITE: change fields of an existing client (only the fields you pass are changed). PATCH /clients/{id}.
Esquema de entrada
{
"type": "object",
"properties": {
"client_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg client id."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"bulstat": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"is_reg_vat": {
"type": "boolean"
},
"vat_number": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"town": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"address": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"country": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"mol": {
"type": "string",
"minLength": 1,
"maxLength": 150
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"delivery_address": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"client_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟡invbg_create_item(name, price, quantity_unit, currency, name_en, ...)
WRITE: add a product or service to the catalogue (name, price, unit). POST /items.
Esquema de entrada
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Item name."
},
"price": {
"type": "number",
"description": "Price per unit."
},
"quantity_unit": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"description": "Unit of measure (invbg_list_item_units)."
},
"currency": {
"description": "Price currency (default BGN).",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"name_en": {
"description": "Item name in English.",
"type": "string",
"minLength": 1,
"maxLength": 500
},
"tags": {
"description": "Tags to attach.",
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
},
"required": [
"name",
"price",
"quantity_unit"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴invbg_create_invoice(type, draft, client_id, to_name, is_to_person, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"type": {
"description": "dan = tax invoice (default), prof = proforma, deb = debit note, cred = credit note.",
"type": "string",
"enum": [
"dan",
"prof",
"deb",
"cred"
]
},
"draft": {
"description": "Save as a draft (default true). Pass false to issue the document and consume its number.",
"type": "boolean"
},
"client_id": {
"description": "Existing client id (invbg_list_clients). Then the to_* fields are ignored.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"to_name": {
"description": "Recipient name (when no client_id).",
"type": "string",
"minLength": 1,
"maxLength": 300
},
"is_to_person": {
"description": "true when the recipient is an individual (then to_egn is needed).",
"type": "boolean"
},
"to_bulstat": {
"description": "Recipient EIK/Bulstat (companies).",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"to_egn": {
"description": "Recipient EGN, 10 digits (individuals), as text so leading zeros survive.",
"type": "string",
"pattern": "^\\d{10}$"
},
"to_is_reg_vat": {
"description": "Whether the recipient company is VAT-registered.",
"type": "boolean"
},
"to_vat_number": {
"description": "Recipient VAT number (needed when to_is_reg_vat is true).",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"to_mol": {
"description": "Recipient accountable person (MOL); required for companies when no client_id.",
"type": "string",
"minLength": 1,
"maxLength": 150
},
"to_town": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"to_address": {
"description": "Recipient address (required when no client_id).",
"type": "string",
"minLength": 1,
"maxLength": 300
},
"to_country": {
"description": "Recipient country, ISO 3166-1 alpha-2.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"items": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Item name as printed on the invoice."
},
"price": {
"type": "number",
"description": "Price per unit (without VAT unless items_with_vat is true)."
},
"quantity": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Quantity."
},
"quantity_unit": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"description": "Unit of measure, e.g. pcs, hours (see invbg_list_item_units)."
},
"vat_percent": {
"description": "VAT rate for this item in percent (20 is the standard Bulgarian rate). Needed on every item unless the invoice sets vat_percent.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"reduction_percent": {
"description": "Discount on this item in percent.",
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"name",
"price",
"quantity",
"quantity_unit"
]
},
"description": "Line items."
},
"vat_percent": {
"description": "VAT rate for the whole document in percent; ignored where items carry their own vat_percent.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"vat_exemption_reason": {
"description": "Why no VAT is charged (when VAT is 0); see invbg_list_vat_exemption_reasons.",
"type": "string",
"minLength": 1,
"maxLength": 500
},
"items_with_vat": {
"description": "true if item prices already include VAT (default false).",
"type": "boolean"
},
"currency": {
"description": "Document currency (default BGN).",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"currency_rate": {
"description": "Exchange rate to BGN (BGN/XXX). Required when currency is not BGN: take it from invbg_get_exchange_rate.",
"type": "number",
"exclusiveMinimum": 0
},
"payment_method": {
"description": "How the client pays.",
"type": "string",
"enum": [
"cash",
"bank",
"ondlv",
"card",
"order",
"cheque",
"barter",
"moneytransfer",
"epay",
"paypal",
"stripe",
"revolut",
"easypay",
"other"
]
},
"date_create": {
"description": "Issue date (default now).",
"type": "string"
},
"date_event": {
"description": "Tax event date (default: issue date).",
"type": "string"
},
"date_mature": {
"description": "Due date.",
"type": "string"
},
"notes": {
"description": "Notes printed on the document.",
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"po_number": {
"description": "The buyer's purchase order number.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"number_set": {
"description": "Number set id to take the number from (invbg_list_number_sets); omit unless you use several series.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"reduction_percent": {
"description": "Discount on the whole document in percent.",
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"items"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟡invbg_send_invoice_email(invoice_id, email, name, subject, message, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"invoice_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg document id."
},
"email": {
"type": "string",
"maxLength": 254,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"description": "Recipient email address."
},
"name": {
"description": "Recipient name used in the text.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"subject": {
"description": "Email subject (default: the document number).",
"type": "string",
"minLength": 1,
"maxLength": 300
},
"message": {
"description": "Message text placed in the email.",
"type": "string",
"minLength": 1,
"maxLength": 5000
},
"delivery": {
"description": "link = a download link (default), file = attached PDF.",
"type": "string",
"enum": [
"link",
"file"
]
},
"language": {
"description": "Language of the document (default: the document's own).",
"type": "string",
"enum": [
"bg",
"en"
]
}
},
"required": [
"invoice_id",
"email"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟡invbg_record_invoice_payment(invoice_id, amount, payment_processor, currency, currency_rate, ...)
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).
Esquema de entrada
{
"type": "object",
"properties": {
"invoice_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "inv.bg document id the payment is for."
},
"amount": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Amount received and allocated to this document."
},
"payment_processor": {
"type": "string",
"enum": [
"bank",
"cash",
"epay",
"paypal",
"stripe",
"revolut"
],
"description": "How the money was received."
},
"currency": {
"description": "Currency of the payment (required by inv.bg), e.g. BGN or EUR.",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"currency_rate": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Exchange rate to BGN (required by inv.bg): 1 for BGN; otherwise the rate from invbg_get_exchange_rate."
},
"paid_at": {
"description": "When it was paid (default now).",
"type": "string"
},
"contragent_id": {
"description": "The paying client's id.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"note": {
"description": "Note stored on the payment.",
"type": "string",
"minLength": 1,
"maxLength": 500
}
},
"required": [
"invoice_id",
"amount",
"payment_processor",
"currency",
"currency_rate"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Comunidad
Evidencia
Observaciones recientes
verificadoversión no registrada27 herramientas