Интеграции с външни системи

REST Api

Тази документация е за стара и неподдържана версия (v2) на API-то на inv.bg. Моля, изполвайте новата версия, информация за която можете да намерите тук. Тя съдържа много подобрения, има повече възможности и е по - лесна за използване.

Линк към последната версия на API-то.

API-то се намира на адрес https://вашия_домейн.inv.bg/RESTapi/ и всички заявки се правят към него. Например ако искате да получите списъка с фактури е достатъчно да направите GET заявка към /RESTapi/invoices/ . Ако желаете да направите live тестове с API-то можете да го направите от тук . Просто въведете домейна на вашата фирма, потребител и парола. Примерен PHP код можете да видите тук

Към този момент поддържаме само JSON заявки към API-то.

В заявките трябва да се използва точка (.) като знак за десетичен разделител.

Оторизацията се извършва посредством метода "http basic authentication" и присъства към всяка заявка. За
username и password се използват данните на съществуващ потребител от списъка с потребители на фирмата, като за
API достъпа може да добави отделен акаунт или да се използва съществуващ. Всички действия през API-то ще се
извършват от името на този потребител.
Допълнение: вече е възможна и оторизация чрез X-JWT HTTP header. Той трябва да съдържа валиден token за
APIv3.

Модул: Invoices GET /invoices

Връща списък с фактури.

Параметри
Къде Име Тип Задължително Описание
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

Модул: Invoices PUT /invoice/{id}

Редакция на фактура {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)`. При използване на това поле, то всеки артикул от фактурата трябва да има зададена ДДС ставка и не се взима предвид зададената ставка в самата фактура.

Модул: Invoices POST /invoice

Създаване на фактура.

Параметри
Къде Име Тип Задължително Описание
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}]

Модул: Invoices DELETE /invoice/{id}

Изтриване на фактура {id}.

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата която се изтрива

Модул: Invoices GET /invoice/{id}

Връщане на цялото инфо за фактура {id}.

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата

Модул: Invoices GET /invoice/pdf/{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.

Модул: Invoices PUT /invoice/signed/{id}

Качване на предварително подписан PDF файл за фактура
Тялото на заявката трябва да е подписаният PDF файл в бинарен формат. Това
означава, че Content-Type на request-a трябва да е "application/octet-stream" или
"application/pdf";

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата
query lang_id integer - ID на езика 1 - БГ, 2 - EN. На какъв език е подписаният файл. Български по подразбиране.

Модул: Invoices POST /invoices/sign/data

Качване на информация за извършено подписване

Параметри
Къде Име Тип Задължително Описание
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 - Допълнителена информация за извършеното подписване

Модул: Invoices PUT /invoice/archive/{id}

Архивиране на фактура {id}.

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата

Модул: Invoices PUT /invoice/unarchive/{id}

Разархивиране на фактура {id}.

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата

Модул: Invoices PUT /invoice/status/{id}

Смяна на статуса на фактура {id}.

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата
query status string Задължително статуса на документа: draft - чернова, anulled - анулирана, paid - платена, partially-paid - частично платена, unpaid = неплатена

Модул: Invoices POST /invoice/send/{id}

Изпращане на фактурата {id} до фирмата получател или email адрес

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на фактурата
formData invtype string Опционално Изпрати само: original - оригинала, copy - копието, both - и двете. По подразбиране се праща само оригинала
formData send_as string Опционално Изпрати като: link - линк за сваляне, file - като прикачен файл. По подразбиране се изпраща като линк
formData email 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 на съответния шаблон който да бъде използван в имейла

Модул: Invoices POST /receipt

Създаване на Електронна касова бележка.

Параметри
Къде Име Тип Задължително Описание
formData related_invoice integer Опционално Към фактура номер (за дебитно и кредитно известие)
formData date_create integer Опционално Дата на издаване на фатурата (unix timestamp)
formData date_event integer Опционално Дата на данъчното събитие (unix timestamp)
formData currency_rate number Опционално Курс трябва да е число, например "1.953". Това са 1.953лв. за един "payment_currency".
formData payment_currency string Опционално Валута като по подразбиране е валутата която е избрана от Настройки -> По фактурите -> Основна валута. Кодовете на валутите могат да се видят от там, за българската валута се приемат и BGN и лв
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}]

Модул: Clients GET /clients

Връща списък с клиенти

Параметри
Къде Име Тип Задължително Описание
query with_deleted boolean Опционално върни и изтритите клиенти
query limit integer Опционално лимит на броя върнати записи, по подразбиране 50, максимално 100
query offset integer Опционално отстояние от първия запис

Модул: Clients GET /client/{id}

Връщане информацията за клиента {id}

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на клиента

Модул: Clients PUT /client/{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 Опционално Държава английски на фирмата или физическото лице

Модул: Clients POST /client

Създаване на клиент

Параметри
Къде Име Тип Задължително Описание
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 Опционално Държава английски на фирмата или физическото лице

Модул: Clients DELETE /client/{id}

Изтриване на клиента {id}

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на клиента който се изтрива

Модул: Items GET /items

Връща списък с артикули

Параметри
Къде Име Тип Задължително Описание
query with_deleted boolean Опционално върни и изтритите артикули
query limit integer Опционално лимит на броя върнати записи, по подразбиране 50, максимално 100
query offset integer Опционално отстояние от първия запис

Модул: Items GET /item/{id}

Връщане информацията за артикула {id}

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на артикула

Модул: Items POST /item

Създаване на артикул

Параметри
Къде Име Тип Задължително Описание
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 във външната система

Модул: Items PUT /item/{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 във външната система

Модул: Items DELETE /item/{id}

Изтриване на артикул {id}

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на артикула който се изтрива

Модул: Settings GET /settings/firm

Данните на фирмата.

Модул: Settings PUT /settings/firm

Редакция на данните на фирмата.

Параметри
Къде Име Тип Задължително Описание
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 email string Задължително Email на фирмата

Модул: Settings GET /settings/bankaccounts

Връща банковите сметки на фирмата.

Модул: Settings PUT /settings/bankaccounts/{id}

Редакция на банкова сметка {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 Опционално Валута на сметката

Модул: Settings POST /settings/bankaccounts

Създаване на банкова сметка.

Параметри
Къде Име Тип Задължително Описание
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 Опционално Валута на сметката

Модул: Settings DELETE /settings/bankaccounts/{id}

Изтриване на банкова сметка {id}.

Параметри
Къде Име Тип Задължително Описание
path id integer Задължително ID на банковата сметка която се редактира

Модул: Settings PUT /settings/templates

Промяна на шаблон на документи

Параметри
Къде Име Тип Задължително Описание
formData id integer Задължително ID на променяният шаблон за документи.
formData doc_types array Задължително Типове на документите, на които трябва да бъде сменен шаблона. Позволени типове са 'dan' - фактура, 'prof' - проформа, 'deb' - дебитно известие, 'kred' - кредитно известие. Пример: {"doc_types":["dan","prof","deb","kred"]}

Модул: Settings GET /settings/templates

Връща информация за всички възможни шаблони на документи

Примерен PHP код

Това е примерен код с който можете да реализирате REST заявките с помоща на PHP библиотеката HttpFul Разбора се можете да използвате всяка друга библиотека.

Инициализиране на библиотеката

require("Httpful/Bootstrap.php"); \Httpful\Bootstrap::init(); use Httpful\Httpful; use Httpful\Request; use Httpful\Mime; use Httpful\Http; use Httpful\Response; $username = "вашия потребител"; $password = "вашата парола"; $baseURL = "https://вашия_домейн.inv.bg/RESTapi/";

Взимане на списъка с фактури

$response = Request::get($baseURL."invoices?limit=5") ->authenticateWith($username, $password) ->sendsJson() ->expectsType("json") ->send(); print_r($response->body);

Създаване на фактура

$response = Request::post($baseURL."invoice") ->authenticateWith($username, $password) ->sendsType(Mime::FORM) ->body(array( "to_firm_name"=>"Картофобер ЕООД", "to_firm_bulstat"=>"123412341234", "to_firm_vat_number"=>"BG123412341234", "to_firm_mol"=>"Картоф Картофков", "to_firm_town"=>"София", "to_firm_addr"=>"ул. картоферна 7", "items"=>array( array( "name"=>"Катофи", "quantity"=>3, "quantity_unit"=>"кг.", "price"=>0.43, "price_for_quantity"=>1, ), ) )) ->sendsJson() ->expectsType("json") ->send(); print_r($response->body);

Взимане на детайлите на фактура

$response = Request::get($baseURL."invoice/ИД_на_фактура") ->authenticateWith($username, $password) ->sendsJson() ->expectsType("json") ->send(); print_r($response->body);

Редакция на фактура

$response = Request::put($baseURL."invoice/ИД_на_фактура") ->authenticateWith($username, $password) ->sendsType(Mime::FORM) ->body($invoice) ->sendsJson() ->expectsType("json") ->send(); print_r($response->body);

Изтриване на фактура

$response = Request::delete($baseURL."invoice/ИД_на_фактура") ->authenticateWith($username, $password) ->sendsJson() ->expectsType("json") ->send(); print_r($response->body);
© inv.bg 2009 - 2021