API BitFaktura
Завдяки API систему "BitFaktura" можна легко інтегрувати з іншими програмами. У наведених нижче прикладах ми використовуємо інструмент CURL, який можна легко замінити викликом будь-якої мови
Будь ласка, зв'яжіться з нами, якщо вам потрібна буде будь-яка додаткова функція API, ми додамо її якомога швидше.
Усі приклади працюють з JSON або XML (просто змініть розширення xml на json). Усі виклики API працюють із SSL, тому варто замінити HTTP на HTTPS у виробничій версії.
- Рахунки-фактури
- Продукти / послуги
- Клієнти
- Складські документи
- Платежі
- Categories
- Warehouses
- Інтеграція
- Відділи
ПРИМІТКА: повна документація доступна на GitHub:
https://github.com/bitfaktura-com-ua/api
ПРИМІТКА: повна документація доступна на GitHub: https://github.com/bitfaktura-com-ua/api
API токен ?
API токен потрібно завантажити з налаштувань програми ('Налаштування -> Налаштування акаунта -> Інтеграція -> Код авторизації API')Рахунки-фактури
Завантажити всі рахунки-фактури за обраний період
завантаження рахунків-фактур за поточний місяць:
JSON
Завантажити код CURL
https://YOUR_DOMAIN.com.ua/invoices.json?period=this_month&page=1&per_page=25&api_token=API_TOKEN
XML
Завантажити код CURL
https://YOUR_DOMAIN.com.ua/invoices.xml?period=this_month&page=1&per_page=25&api_token=API_TOKEN
можна передавати ті ж самі параметри, які передаються в програмі (на сторінці списку рахунків-фактур), напр. "income=no" для витрат
Завантажити обраний рахунок-фактуру за ID
JSON
Завантажити код CURL
https://YOUR_DOMAIN.com.ua/invoices/100.json?api_token=API_TOKEN
XML
Завантажити код CURL
https://YOUR_DOMAIN.com.ua/invoices/100.xml?api_token=API_TOKEN
Завантажити рахунок-фактуру в форматі PDF
PDF
Завантажити код CURL
https://YOUR_DOMAIN.com.ua/invoices/100.pdf?api_token=API_TOKEN
Надіслати рахунок-фактуру клієнту по електронній пошті
JSON curl -X POST "https://YOUR_DOMAIN.com.ua/invoices/100/send_by_email.json?api_token=API_TOKEN"
XML curl -X POST "https://YOUR_DOMAIN.com.ua/invoices/100/send_by_email.xml?api_token=API_TOKEN"
Завантаження рахунку-фактури по ID замовлення
JSON curl "https://YOUR_DOMAIN.com.ua/invoices.json?oid=nr_zam&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/invoices.xml?oid=nr_zam&api_token=API_TOKEN"
Завантаження рахунків-фактур, на основі яких був створений документ із наданим ID
JSON curl "https://YOUR_DOMAIN.com.ua/invoices.json?invoice_id=id&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/invoices.xml?invoice_id=id&api_token=API_TOKEN"
Завантаження рахунків-фактур, створених на основі документа із наданим ID
JSON curl "https://YOUR_DOMAIN.com.ua/invoices.json?from_invoice_id=id&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/invoices.xml?from_invoice_id=id&api_token=API_TOKEN"
Додавання нового рахунку-фактури
JSON (рекомендується)JSON (рекомендується)
curl https://YOUR_DOMAIN.com.ua/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-12-15",
"issue_date": "2024-12-15",
"payment_to": "2024-12-22",
"seller_name": "Seller SA",
"seller_tax_no": "6272616681",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2}
]
}}'
Завантажити код CURLЗ даними відділу за замовчуванням :
curl https://YOUR_DOMAIN.com.ua/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-12-15",
"issue_date": "2024-12-15",
"payment_to": "2024-12-22",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2}
]
}}'
Завантажити код CURLXML
curl https://YOUR_DOMAIN.com.ua/invoices.xml \
-u 'login:YOUR_PASSWORD' \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-d '<invoice>
<kind>vat</kind>
<sell_date>2024-12-15</sell_date>
<issue_date>2024-12-15</issue_date>
<payment_to>2024-12-22</payment_to>
<seller_name>Seller SA</seller_name>
<seller_tax_no>6272616681</seller_tax_no>
<buyer_name>Client1 SA</buyer_name>
<buyer_tax_no>6272616681</buyer_tax_no>
<positions>
<position>
<name>Produkt X1</name>
<tax>23</tax>
<total_price_gross>20</total_price_gross>
<quantity>1</quantity>
</position>
<position>
<name>Produkt X2</name>
<tax>0</tax>
<total_price_gross>10</total_price_gross>
<quantity>3</quantity>
</position>
</positions>
</invoice>'
Завантажити код CURLПриклад в Ruby
endpoint = 'https://YOUR_DOMAIN.com.ua/invoices.json'
uri = URI.parse(endpoint)
json_params = {
"api_token" => "API_TOKEN",
"invoice" => {
"kind" =>"vat",
"number" => nil,
"sell_date" => "2024-12-15",
"issue_date" => "2024-12-15",
"payment_to" => "2024-12-22",
"buyer_name" => "Client1 SA",
"buyer_tax_no" => "6272616681",
"positions" =>[
{"name" =>"Produkt A1", "tax" =>23, "total_price_gross" =>10.23, "quantity" =>1},
{"name" =>"Produkt A2", "tax" =>0, "total_price_gross" =>50, "quantity" =>2}
]
}}
request = Net::HTTP::Post.new(uri.path)
request.body = JSON.generate(json_params)
request["Content-Type"] = "application/json"
http = Net::HTTP.new(uri.host, uri.port)
response = http.start {|h| h.request(request)}
if response.code == '201'
ret = JSON.parse(response.body)
else
ret = response.body
end
puts ret.to_json
Javascript / Ajax jQuery
json_params = {
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-12-15",
"issue_date": "2024-12-15",
"payment_to": "2024-12-22",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2}
]
}}
//alert(JSON.stringify(json_params))
endpoint = 'https://YOUR_DOMAIN.com.ua/invoices.json'
$.ajax({
type: "POST",
url: endpoint,
data: json_params,
dataType: 'json',
success: function(data) { alert('invoice created! ' + data['number'])},
});
Додавання рахунку-фактури з відсотковою знижкою
УВАГА: Перш ніж виставляти, переконайтеся, що в Налаштуваннях Акаунта в полі: "Як розрахувати знижку" встановлено значення "відсоток від ціни нетто за одиницю"curl https://YOUR_DOMAIN.com.ua/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-12-15",
"issue_date": "2024-12-15",
"payment_to": "2024-12-22",
"seller_name": "Seller SA",
"seller_tax_no": "6272616681",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"show_discount": true,
"discount_kind": "percent_unit",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1, "discount_percent": 50},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2, "discount_percent": 10}
]
}}'
Завантажити код CURLДодавання рахунку-фактури з фіксованою знижкою
Увага: перед виставленням необхідно перевірити, чи в Налаштуваннях акаунта в полі: 'Як розрахувати знижку' встановлено на 'фіксована сума'curl https://YOUR_DOMAIN.com.ua/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-12-15",
"issue_date": "2024-12-15",
"payment_to": "2024-12-22",
"seller_name": "Seller SA",
"seller_tax_no": "6272616681",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"show_discount": true,
"discount_kind": "amount",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1, "discount": 5},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2, "discount": 25}
]
}}'
Завантажити код CURLДодавання рахунку-фактури для існуючого клієнта та продукта
Якщо у вас є ID даного клієнта (client_id), продавця (department_id) або продукт (product_id), тоді вам не потрібно передавати більше даних. Рахунок-фактура буде виставлений у поточний день та із 5-денним терміном платежу.curl https://YOUR_DOMAIN.com.ua/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"invoice": {
"payment_to_kind": 5,
"department_id": 222,
"client_id": 111,
"positions":[
{"product_id": 333, "quantity":2}
]
}}'
Завантажити код CURLОновлення рахунку-фактури
curl https://YOUR_DOMAIN.com.ua/invoices/444.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"invoice": {
"buyer_name": "New buyer name SA"
}}'
Завантажити код CURLВидалення рахунку-фактури
JSON curl -X DELETE "https://YOUR_DOMAIN.com.ua/invoices/100.json?api_token=API_TOKEN"
XML curl -X DELETE "https://YOUR_DOMAIN.com.ua/invoices/100.xml?api_token=API_TOKEN"
Складські документи
Всі складські документи
JSONcurl "https://YOUR_DOMAIN.com.ua/warehouse_documents.json?page=1&per_page=25&api_token=API_TOKEN"
можна передавати ті ж самі параметри, які передаються в програмі (на сторінці списку рахунків-фактур), напр. "income=no" для витрат
Завантажити вибраний документ по ID
JSON curl "https://YOUR_DOMAIN.com.ua/warehouse_documents/555.json?api_token=API_TOKEN"
Додавання складського документа про приймання матеріалів
JSON
curl https://YOUR_DOMAIN.com.ua/warehouse_documents.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse_document": {
"kind":"pz",
"number": null,
"warehouse_id": "1",
"issue_date": "2024-12-15",
"department_name": "Department1 SA",
"client_name": "Client1 SA",
"warehouse_actions":[
{"product_name":"Produkt A1", "purchase_tax":23, "purchase_price_net":10.23, "quantity":1},
{"product_name":"Produkt A2", "purchase_tax":0, "purchase_price_net":50, "quantity":2}
]
}}'
Завантажити код CURLДодавання видаткової накладної
JSON
curl https://YOUR_DOMAIN.com.ua/warehouse_documents.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse_document": {
"kind":"wz",
"number": null,
"warehouse_id": "1",
"issue_date": "2024-12-15",
"department_name": "Department1 SA",
"client_name": "Client1 SA",
"warehouse_actions":[
{"product_id":"333", "tax":23, "price_net":10.23, "quantity":1},
{"product_id":"333", "tax":0, "price_net":50, "quantity":2}
]
}}'
Завантажити код CURLДодавання складського документа приймання матеріалів (ПМ) для існуючого клієнта, відділу та товару
Щоб встановити відділ за замовчуванням, пропустіть ключ department_id (та department_name)JSON
curl https://YOUR_DOMAIN.com.ua/warehouse_documents.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse_document": {
"kind":"pz",
"number": null,
"warehouse_id": "1",
"issue_date": "2024-12-15",
"department_id": "222",
"client_id": "111",
"warehouse_actions":[
{"product_id":"333", "purchase_tax":23, "price_net":10.23, "quantity":1},
{"product_id":"333", "purchase_tax":0, "price_net":50, "quantity":2}
]
}}'
Завантажити код CURLОновлення документа
curl https://YOUR_DOMAIN.com.ua/warehouse_documents/555.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"warehouse_document": {
"client_name": "New client name SA"
}}'
Завантажити код CURLВидалити документ
JSON curl -X DELETE "https://YOUR_DOMAIN.com.ua/warehouse_documents/100.json?api_token=API_TOKEN"
Продукти / послуги
Всі продукти
JSON curl "https://YOUR_DOMAIN.com.ua/products.json?page=1&per_page=25&api_token=API_TOKEN&page=1"
XML curl "https://YOUR_DOMAIN.com.ua/products.xml?page=1&per_page=25&api_token=API_TOKEN&page=1"
Завантажити вибраний продукт за ID
curl "https://YOUR_DOMAIN.com.ua/products/100.xml?api_token=API_TOKEN"
Додавання продукту
curl https://YOUR_DOMAIN.com.ua/products.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"product": {
"name": "PoroductAA",
"code": "A001",
"price_net": "100",
"tax": "23"
}}'
Завантажити код CURLОновлення продукту
curl https://YOUR_DOMAIN.com.ua/products/333.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"product": {
"name": "PoroductAA2",
"code": "A0012",
"price_gross": "102"
}}'
Завантажити код CURLWidget
Щоб завантажити форму оплати (у форматі JS), введіть URL-адресу:
https://app.bitfaktura.ua/a/YOUR_DOMAIN/p/{{token}}.js
Клієнти
Всі клієнти
JSON curl "https://YOUR_DOMAIN.com.ua/clients.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/clients.xml?page=1&per_page=25&api_token=API_TOKEN"
Завантажити вибраного клієнта за ID
curl "https://YOUR_DOMAIN.com.ua/clients/100.xml?api_token=API_TOKEN"
Виберіть клієнта, використовуючи його зовнішній ID
JSON curl "https://YOUR_DOMAIN.com.ua/clients.json?external_id=100&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/clients.xml?external_id=100&api_token=API_TOKEN"
Додавання клієнта
curl https://YOUR_DOMAIN.com.ua/clients.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"client": {
"name": "Client1",
"tax_no": "6272616681",
"bank" : "bank1",
"bank_account" : "bank_account1",
"city" : "city1",
"country" : "",
"email" : "example@email.com",
"person" : "person1",
"post_code" : "post-code1",
"phone" : "phone1",
"street" : "street1"
}}'
Завантажити код CURLОновлення клієнта
curl https://YOUR_DOMAIN.com.ua/clients/111.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"client": {
"name": "Klient2",
"tax_no": "62726166812",
"bank" : "bank2",
"bank_account" : "bank_account2",
"city" : "city2",
"country" : "PL",
"email" : "example2@email.com",
"person" : "person2",
"post_code" : "post-code2",
"phone" : "phone2",
"street" : "street2"
}}'
Завантажити код CURLПлатежі
Всі платежі
JSON curl "https://YOUR_DOMAIN.com.ua/banking/payments.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/banking/payments.xml?page=1&per_page=25&api_token=API_TOKEN"
Завантаження вибраного платежу за ID
JSON curl "https://YOUR_DOMAIN.com.ua/banking/payment/100.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/banking/payments/100.xml?api_token=API_TOKEN"
Додавання нового платежу
minimal JSON (рекомендується)curl https://YOUR_DOMAIN.com.ua/banking/payments.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"banking_payment": {
"name":"Payment 001",
"price": 100.05,
"invoice_id": null,
"paid":true,
"kind": "api"
}}'
Завантажити код CURLfull JSON (рекомендується)
curl https://YOUR_DOMAIN.com.ua/banking/payments.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"banking_payment": {
"city": null,
"client_id":null,
"comment":null,
"country":null,
"currency":"PLN",
"deleted":false,
"department_id":null,
"description":"abonament roczny",
"email":"email@email.pl",
"first_name":"Jan",
"generate_invoice":true,
"invoice_city":"Warszawa",
"invoice_comment":"",
"invoice_country":null,
"invoice_id":null,
"invoice_name":"Company name",
"invoice_post_code":"00-112",
"invoice_street":"street 52",
"invoice_tax_no":"6272616681",
"last_name":"Kowalski",
"name":"Plantnosc za produkt1",
"oid":"",
"paid":true,
"paid_date":null,
"phone":null,
"post_code":null,
"price":"100.00",
"product_id":1,
"promocode":"",
"provider":"transfer",
"provider_response":null,
"provider_status":null,
"provider_title":null,
"quantity":1,
"street":null,
"kind": "api"
}}'
Завантажити код CURLCategories
Create new category
JSON (рекомендується)curl https://YOUR_DOMAIN.com.ua/categories.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"category": {
"name": "my_category",
"description": null
}
}'
Завантажити код CURLList of categories
XML curl "https://YOUR_DOMAIN.com.ua/categories.xml?api_token=API_TOKEN"
JSON curl "https://YOUR_DOMAIN.com.ua/categories.json?api_token=API_TOKEN"
Obtaining information for a single category by ID
XML curl "https://YOUR_DOMAIN.com.ua/categories/100.xml?api_token=API_TOKEN"
JSON curl "https://YOUR_DOMAIN.com.ua/categories/100.json?api_token=API_TOKEN"
Інші приклади: https://github.com/bitfaktura-com-ua/api
Warehouses
Create new warehouse
JSON (рекомендується)curl https://YOUR_DOMAIN.com.ua/warehouses.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse": {
"name": "my_warehouse",
"kind": null,
"description": null
}
}'
Завантажити код CURLList of Warehouses
JSON curl "https://YOUR_DOMAIN.com.ua/warehouses.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/warehouses.xml?api_token=API_TOKEN"
Obtaining warehouse information based on ID
JSON curl "https://YOUR_DOMAIN.com.ua/warehouses/100.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.com.ua/warehouses/100.xml?api_token=API_TOKEN"
Інтеграція
Додавання нового користувача
JSON method: POST url: https://app.com.ua/users.json
{
"user": {
"email": "email29052@fakturowytmail.pl",
"password": "your_secret_password"
},
"integration_token": "email-us-for-this-token"
}
Завантажити код CURL | Завантажити код Ruby | Завантажити код JavaScript | Завантажити код PHP | Завантажити код JSONОтримати інформацію про користувача (разом з кодом доступу API)
JSON method: POST url: https://app.com.ua/login.json
{
"login": "email29052@fakturowytmail.pl",
"password": "your_secret_password",
"integration_token": "email-us-for-this-token"
}
Завантажити код CURL | Завантажити код Ruby | Завантажити код JavaScript | Завантажити код PHP | Завантажити код JSONСтворення нового акаунта
JSON method: POST url: https://app.com.ua/account.json
{
"api_token": "API_TOKEN",
"account": {
"prefix": "ftprefix"
},
"integration_token": "email-us-for-this-token"
}
Завантажити код CURL | Завантажити код Ruby | Завантажити код JavaScript | Завантажити код PHP | Завантажити код JSONСтворення нового акаунта разом із власником цього акаунта та даними фірми
JSONcurl https://app.com.ua/account.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"account": {
"prefix": "prefix1"
},
"user": {
"login": "login1",
"email": "email1@email.pl",
"password": "password1",
"from_partner": "PARTNER_CODE"
},
"company": {
"name": "Company1",
"tax_no": "5252445700",
"post_code": "00-112",
"city": "Warsaw",
"street": "Street 1/10",
"person": "Jan Nowak",
"bank": "Bank1",
"bank_account": "111222333444555666111"
},
"integration_token": "email-us-for-this-token"
}'
Завантажити код CURLОтримання інформації про акаунт
Завантажити код CURL
https://YOUR_DOMAIN.com.ua/account.json?api_token=API_TOKEN&integration_token=email-us-for-this-token
Відділи
Додати логотип
curl -X PUT https://YOUR_DOMAIN.com.ua/departments/222.json \
-F 'api_token=API_TOKEN' \
-F 'department[logo]=@/file_path/logo.png'
Завантажити код CURL
Інші приклади: https://github.com/bitfaktura-com-ua/api
- Рахунки-фактури
- Продукти / послуги
- Клієнти
- Складські документи
- Платежі
- Categories
- Warehouses
- Інтеграція
- Відділи