Тази документация е за стара и неподдържана версия (v2) на API-то на inv.bg. Моля, изполвайте новата версия, информация за която можете да намерите тук. Тя съдържа много подобрения, има повече възможности и е по - лесна за използване.
Линк към последната версия на API-то.
Към този момент поддържаме само JSON заявки към API-то.
В заявките трябва да се използва точка (.) като знак за десетичен разделител.
Оторизацията се извършва посредством метода "http basic authentication" и присъства към всяка заявка. За
username и password се използват данните на съществуващ потребител от списъка с потребители на фирмата, като за
API достъпа може да добави отделен акаунт или да се използва съществуващ. Всички действия през API-то ще се
извършват от името на този потребител.
Допълнение: вече е възможна и оторизация чрез X-JWT HTTP header. Той трябва да съдържа валиден token за
APIv3.
Връща списък с фактури.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
query | type | string | - | тип на документа: dan - фактура, prof - проформа, deb - дебитно, kred - кредитно, custom - къстъм документ |
query | status | string | - | статуса на документа: draft - чернова, anulled - анулирана, paid - платена, partially-paid - частично платена, unpaid = неплатена. Използвайте "!" за да изключите конкретен тип |
query | client_id | integer | - | ID на клиента получател |
query | from_date | string | - | издадени след дата (формат yyyy-mm-dd) |
query | to_date | string | - | издадени преди дата (формат yyyy-mm-dd) |
query | limit | integer | - | лимит на броя върнати записи. По подразбиране 50, максимално 100 |
query | offset | integer | - | отстояние от първия запис |
query | signed | integer | - | търси само подписани/неподпипсани фактури. Възможни стойности 1 и 0 |
Редакция на фактура {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата която се редактира |
formData | type | string | Опционално | Тип на фактурата: dan - фактура, prof - проформа, deb - дебитно, kred - кредитно, custom - къстъм документ |
formData | inv_number | integer | Опционално | Номер на фактурата. Ако липсва ще се генерира |
formData | template | integer | Опционално | Номер на шаблон. Ако липсва ще използва шаблона по подразбиране |
formData | related_invoice | integer | Опционално | Към фактура номер (за дебитно и кредитно известие) |
formData | related_date | integer | Опционално | Към фактура от дата (за дебитно и кредитно известие) (unix timestamp) |
formData | status | string | Опционално | Статуса на фактурата: draft - чернова, paid - платена, partially-paid - частично платена, unpaid = неплатена |
formData | date_create | integer | Опционално | Дата на издаване на фатурата (unix timestamp) |
formData | date_event | integer | Опционално | Дата на данъчното събитие (unix timestamp) |
formData | date_padej | integer | Опционално | Дата на падеж на фактурата (unix timestamp) |
formData | is_to_person | string | Опционално | Получателя е физическо лице |
formData | to_person_name | string | Опционално | Получател име |
formData | to_person_egn | string | Опционално | Получател ЕГН |
formData | to_person_city | string | Опционално | Получател град |
formData | to_person_address | string | Опционално | Получател адрес |
formData | to_firm_name | string | Задължително | Фирма получател име |
formData | to_firm_bulstat | string | Задължително | Фирма получател ЕИК/Булстат |
formData | to_firm_is_reg_vat | boolean | Задължително | Фирма получател регистрация по ДДС |
formData | to_firm_vat_number | string | Задължително | Фирма получател номер по ДДС |
formData | to_firm_mol | string | Задължително | Фирма получател МОЛ |
formData | to_firm_town | string | Задължително | Фирма получател град |
formData | to_firm_addr | string | Задължително | Фирма получател адрес |
formData | to_firm_email | string | Опционално | Фирма получател email |
formData | recipient | string | Опционално | Получател |
formData | vat_percent | number | Опционално | ДДС |
formData | without_vat_reason | string | Опционално | Основание за неначисление на ДДС |
formData | show_objects_with_vat | integer | Опционално | Цените на артикулите са: 0 - без ДДС, 1 - с ДДС |
formData | is_cash_report | integer | Опционално | Дали е касова отчетност |
formData | currency_rate | number | Опционално | Курс |
formData | payment_currency | string | Опционално | Валута |
formData | payment_method | string | Опционално | Начин на плащане: cash, bank, ondlv, card, order, cheque, other |
formData | payment_method_other | string | Опционално | Начин на плащане с думи ако payment_method = other |
formData | bankaccount_bank | string | Опционално | Банка име |
formData | bankaccount_bank_en | string | Опционално | Банка име на английски |
formData | bankaccount_iban | string | Опционално | Банка IBAN |
formData | bankaccount_bic | string | Опционално | Банка BIC/SWIFT |
formData | reduction_type | string | Опционално | Тип на отстъпката: percent - процент, currency - фиксирана сума |
formData | reduction_value | number | Опционално | Отстъпка |
formData | notes | string | Опционално | Бележки |
formData | items | array | Задължително | Артикули array('name', 'quantity', 'quantity_unit', 'price', 'price_for_quantity', 'vat_percent') - име, количество, мярка, цена, за какво количество е цената, Процент ДДС ставка на артикула `(not implemented yet)`. При използване на това поле, то всеки артикул от фактурата трябва да има зададена ДДС ставка и не се взима предвид зададената ставка в самата фактура. |
Създаване на фактура.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | type | string | Опционално | Тип на фактурата: dan - фактура, prof - проформа, deb - дебитно, kred - кредитно, custom - къстъм документ |
formData | inv_number | integer | Опционално | Номер на фактурата. Ако липсва ще се генерира |
formData | template | integer | Опционално | Номер на шаблон. Ако липсва ще използва шаблона по подразбиране |
formData | related_invoice | integer | Опционално | Към фактура номер (за дебитно и кредитно известие) |
formData | related_date | integer | Опционално | Към фактура от дата (за дебитно и кредитно известие) (unix timestamp) |
formData | status | string | Опционално | Статуса на фактурата: draft - чернова, paid - платена, partially-paid - частично платена, unpaid = неплатена |
formData | date_create | integer | Опционално | Дата на издаване на фатурата (unix timestamp) |
formData | date_event | integer | Опционално | Дата на данъчното събитие (unix timestamp) |
formData | date_padej | integer | Опционално | Дата на падеж на фактурата (unix timestamp) |
formData | is_to_person | string | Опционално | Получателя е физическо лице |
formData | to_person_name | string | Опционално | Получател име |
formData | to_person_egn | string | Опционално | Получател ЕГН |
formData | to_person_city | string | Опционално | Получател град |
formData | to_person_address | string | Опционално | Получател адрес |
formData | to_firm_name | string | Задължително | Фирма получател име |
formData | to_firm_bulstat | string | Задължително | Фирма получател ЕИК/Булстат |
formData | to_firm_is_reg_vat | boolean | Задължително | Фирма получател регистрация по ДДС |
formData | to_firm_vat_number | string | Задължително | Фирма получател номер по ДДС |
formData | to_firm_mol | string | Задължително | Фирма получател МОЛ |
formData | to_firm_town | string | Задължително | Фирма получател град |
formData | to_firm_addr | string | Задължително | Фирма получател адрес |
formData | to_firm_email | string | Опционално | Фирма получател email |
formData | recipient | string | Опционално | Получател |
formData | vat_percent | number | Опционално | ДДС |
formData | without_vat_reason | string | Опционално | Основание за неначисление на ДДС |
formData | show_objects_with_vat | integer | Опционално | Цените на артикулите са: 0 - без ДДС, 1 - с ДДС |
formData | is_cash_report | integer | Опционално | Дали е касова отчетност |
formData | currency_rate | number | Опционално | Курс трябва да е число, например "1.953". Това са 1.953лв. за един "payment_currency". |
formData | payment_currency | string | Опционално | Валута като по подразбиране е валутата която е избрана от Настройки -> По фактурите -> Основна валута. Кодовете на валутите могат да се видят от там, за българската валута се приемат и BGN и лв |
formData | payment_method | string | Опционално | Начин на плащане: cash, bank, ondlv, card, order, cheque, other |
formData | payment_method_other | string | Опционално | Начин на плащане с думи ако payment_method = other |
formData | bankaccount_bank | string | Опционално | Име на банка на издателя на фактурата |
formData | bankaccount_bank_en | string | Опционално | Име на английски на банка на издателя на фактурата |
formData | bankaccount_iban | string | Опционално | IBAN на банка на издателя на фактурата |
formData | bankaccount_bic | string | Опционално | BIC/SWIFT на банка на издателя на фактурата |
formData | reduction_type | string | Опционално | Тип на отстъпката: percent - процент, currency - фиксирана сума |
formData | reduction_value | number | Опционално | Отстъпка |
formData | notes | string | Опционално | Бележки |
formData | html_block | string | Опционално | Къстъм HTML към фактурата |
formData | additional_html_page | string | Опционално | Допълнителен HTML код който ще се покаже на допълнителна страница към фактурата |
formData | additional_html_page_header | string | Опционално | HTML хедър за допълнителната страница |
formData | additional_html_page_footer | string | Опционално | HTML футър за допълнителната страница |
formData | additional_html_page_orientation | string | Опционално | Ориентация на допълнителната страница landscape или portrait |
formData | items | array | Задължително | Артикули - JSON масив, съдържащ елементи {name - име, quantity - количество, quantity_unit - мерна единица, price - обща цена, price_for_quantity - за какво количество е цената, vat_percent - Процент ДДС ставка на артикула `(not implemented yet)`. При използване на това поле, то всеки артикул от фактурата трябва да има зададена ДДС ставка и не се взима предвид зададената ставка в самата фактура.}. Пример: [{"name": "Вилица", "quantity": 3, "quantity_unit": "бр.", "price_for_quantity": 2, "price": 6.00, "vat_percent": 20}] |
Изтриване на фактура {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата която се изтрива |
Връщане на цялото инфо за фактура {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
Генериране и връщане на PDF файла на фактурата {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
query | lang_id | integer | - | ID на езика 1 - БГ, 2 - EN |
query | doc_type | string | - | Тип на документа: original, copy, both. За подписана фактура both ще върне само оригинала на фактурата. |
query | direct | integer | - | При стойност "1" ще бъде върнат директно PDF файл вместо base64 кодирана версия в JSON. |
Качване на предварително подписан PDF файл за фактура
Тялото на заявката трябва да е подписаният PDF файл в бинарен формат. Това
означава, че Content-Type на request-a трябва да е "application/octet-stream" или
"application/pdf";
Къде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
query | lang_id | integer | - | ID на езика 1 - БГ, 2 - EN. На какъв език е подписаният файл. Български по подразбиране. |
Качване на информация за извършено подписване
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | os | string | Задължително | Информация за операционната система |
formData | technology | string | Задължително | Версия на използваната технология. Пример: java v1.8 |
formData | version | string | Задължително | Версия на използвания софтуер. Пример: Inv.bg Signer 1.0 |
formData | status | integer | Задължително | Статус на подписването. 0 - успешно, 1 - неуспешно |
formData | log | string | - | Допълнителена информация за извършеното подписване |
Архивиране на фактура {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
Разархивиране на фактура {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
Смяна на статуса на фактура {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
query | status | string | Задължително | статуса на документа: draft - чернова, anulled - анулирана, paid - платена, partially-paid - частично платена, unpaid = неплатена |
Изпращане на фактурата {id} до фирмата получател или email адрес
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на фактурата |
formData | invtype | string | Опционално | Изпрати само: original - оригинала, copy - копието, both - и двете. По подразбиране се праща само оригинала |
formData | send_as | string | Опционално | Изпрати като: link - линк за сваляне, file - като прикачен файл. По подразбиране се изпраща като линк |
formData | string | Задължително | Email на получателя | |
formData | name | string | Задължително | Име на получателя |
formData | subject | string | Опционално | Относно. По подразбиране името на документа |
formData | message | string | Опционално | Текста на писмото |
formData | lang_id | integer | Опционално | ID на езика 1 - БГ, 2 - EN. По подразбиране 1. |
formData | template_id | integer | Опционално | ID на шаблон на имейла. От "Настройки -> Шаблони на мейлите" може да се вземе ID на съответния шаблон който да бъде използван в имейла |
Връща списък с клиенти
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
query | with_deleted | boolean | Опционално | върни и изтритите клиенти |
query | limit | integer | Опционално | лимит на броя върнати записи, по подразбиране 50, максимално 100 |
query | offset | integer | Опционално | отстояние от първия запис |
Връщане информацията за клиента {id}
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на клиента |
Редакция на клиент {id}
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на клиента който се редактира |
formData | firm_name | string | Задължително | Име на фирмата |
formData | firm_name_en | string | Опционално | Име на фирмата на английски |
formData | firm_town | string | Задължително | Град на фирмата |
formData | firm_town_en | string | Опционално | Град на фирмата на английски |
formData | firm_addr | string | Задължително | Адрес на фирмата |
formData | firm_addr_en | string | Опционално | Адрес на фирмата на английски |
formData | firm_bulstat | string | Задължително | ЕИК/Булстат на фирмата |
formData | firm_is_reg_vat | boolean | Задължително | Фирмата регистрирана ли е по ДДС |
formData | firm_vat_number | string | Задължително | ДДС номер ако фирмата е регистрирана по ДДС e задължителен |
formData | firm_mol | string | Задължително | МОЛ на фирмата |
formData | firm_mol_en | string | Опционално | МОЛ на фирмата на английски |
formData | is_person | string | Опционално | Физическо лице true/false. По подразбиране е false |
formData | person_name | string | Опционално | Физическо лице име |
formData | person_name_en | string | Опционално | Физическо лице име на английски |
formData | person_egn | string | Опционално | Физическо лице ЕГН |
formData | person_city | string | Опционално | Физическо лице град |
formData | person_city_en | string | Опционално | Физическо лице град на английски |
formData | person_address | string | Опционално | Физическо лице адрес |
formData | person_address_en | string | Опционално | Физическо лице адрес на английски |
formData | country | string | Опционално | Държава на фирмата или физическото лице |
formData | country_en | string | Опционално | Държава английски на фирмата или физическото лице |
Създаване на клиент
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | firm_name | string | Задължително | Име на фирмата |
formData | firm_name_en | string | Опционално | Име на фирмата на английски |
formData | firm_town | string | Задължително | Град на фирмата |
formData | firm_town_en | string | Опционално | Град на фирмата на английски |
formData | firm_addr | string | Задължително | Адрес на фирмата |
formData | firm_addr_en | string | Опционално | Адрес на фирмата на английски |
formData | firm_bulstat | string | Опционално | ЕИК/Булстат на фирмата |
formData | firm_is_reg_vat | boolean | Задължително | Фирмата регистрирана ли е по ДДС |
formData | firm_vat_number | string | Опционално | ДДС номер ако фирмата е регистрирана по ДДС e задължителен |
formData | firm_mol | string | Задължително | МОЛ на фирмата |
formData | firm_mol_en | string | Опционално | МОЛ на фирмата на английски |
formData | is_person | string | Опционално | Физическо лице true/false. По подразбиране е false |
formData | person_name | string | Опционално | Физическо лице име |
formData | person_name_en | string | Опционално | Физическо лице име на английски |
formData | person_egn | string | Опционално | Физическо лице ЕГН |
formData | person_city | string | Опционално | Физическо лице град |
formData | person_city_en | string | Опционално | Физическо лице град на английски |
formData | person_address | string | Опционално | Физическо лице адрес |
formData | person_address_en | string | Опционално | Физическо лице адрес на английски |
formData | country | string | Опционално | Държава на фирмата или физическото лице |
formData | country_en | string | Опционално | Държава английски на фирмата или физическото лице |
Изтриване на клиента {id}
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на клиента който се изтрива |
Връща списък с артикули
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
query | with_deleted | boolean | Опционално | върни и изтритите артикули |
query | limit | integer | Опционално | лимит на броя върнати записи, по подразбиране 50, максимално 100 |
query | offset | integer | Опционално | отстояние от първия запис |
Връщане информацията за артикула {id}
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на артикула |
Създаване на артикул
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | name | string | Задължително | Име на артикула |
formData | price | number | Опционално | Цена на артикула |
formData | currency | string | Опционално | Валута на цената |
formData | price_for_quantity | integer | Задължително | За какво количество е цената |
formData | quantity_unit | string | Задължително | Мерна единица |
formData | is_limited | boolean | Опционално | Да се следи ли наличността на артикула |
formData | if_limited_count | number | Опционално | Наличност на артикула |
formData | warranty | integer | Опционално | Гаранционен срок (само за модул Гаранции) |
formData | catalog_num | string | Опционално | Каталожен номер (само за модул Склад) |
formData | outside_id | integer | Опционално | ID във външната система |
Редакция на артикул {id}
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на артикула който се редактира |
formData | name | string | Задължително | Име на артикула |
formData | price | number | Опционално | Цена на артикула |
formData | currency | string | Опционално | Валута на цената |
formData | price_for_quantity | integer | Задължително | За какво количество е цената |
formData | quantity_unit | string | Задължително | Мерна единица |
formData | is_limited | boolean | Опционално | Да се следи ли наличността на артикула |
formData | if_limited_count | number | Опционално | Наличност на артикула |
formData | warranty | integer | Опционално | Гаранционен срок (само за модул Гаранции) |
formData | catalog_num | string | Опционално | Каталожен номер (само за модул Склад) |
formData | outside_id | integer | Опционално | ID във външната система |
Изтриване на артикул {id}
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на артикула който се изтрива |
Редакция на данните на фирмата.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | name | string | Задължително | Име на фирмата |
formData | name_en | string | Опционално | Цена на фирмата на английски |
formData | bulstat | string | Задължително | Булстат на фирмата |
formData | vat_registered | boolean | Задължително | Има ли регистрация по ДДС |
formData | vat_number | string | Опционално | ДДС номер на фирмата |
formData | town | string | Задължително | Град на фирмата |
formData | town_en | string | Опционално | Град на фирмата на английски |
formData | address | string | Задължително | Адрес на фирмата |
formData | address_en | string | Опционално | Адрес на фирмата на английски |
formData | mol | string | Задължително | МОЛ на фирмата |
formData | mol_en | string | Опционално | МОЛ на фирмата на английски |
formData | string | Задължително | Email на фирмата |
Редакция на банкова сметка {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на банковата сметка която се редактира |
formData | name | string | Опционално | Име на сметката |
formData | bank_name | string | Задължително | Име на банката |
formData | bank_name_en | string | Опционално | Име на банката на английски |
formData | bank_iban | string | Задължително | IBAN на банката |
formData | bank_bic | string | Задължително | BIC на банката |
formData | currency | string | Опционално | Валута на сметката |
Създаване на банкова сметка.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | name | string | Опционално | Име на сметката |
formData | bank_name | string | Задължително | Име на банката |
formData | bank_name_en | string | Опционално | Име на банката на английски |
formData | bank_iban | string | Задължително | IBAN на банката |
formData | bank_bic | string | Задължително | BIC на банката |
formData | currency | string | Опционално | Валута на сметката |
Изтриване на банкова сметка {id}.
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
path | id | integer | Задължително | ID на банковата сметка която се редактира |
Промяна на шаблон на документи
ПараметриКъде | Име | Тип | Задължително | Описание |
---|---|---|---|---|
formData | id | integer | Задължително | ID на променяният шаблон за документи. |
formData | doc_types | array | Задължително | Типове на документите, на които трябва да бъде сменен шаблона. Позволени типове са 'dan' - фактура, 'prof' - проформа, 'deb' - дебитно известие, 'kred' - кредитно известие. Пример: {"doc_types":["dan","prof","deb","kred"]} |
Това е примерен код с който можете да реализирате REST заявките с помоща на PHP библиотеката HttpFul Разбора се можете да използвате всяка друга библиотека.