inv.bg MCP by usefulapi

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

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "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"
}

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}.

{
  "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"
}

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

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "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"
}

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.

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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.

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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.

{
  "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"
}

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

{
  "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"
}

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

{
  "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"
}

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.

{
  "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"
}

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.

{
  "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"
}

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).

{
  "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"
}