API BitFaktury
Vďaka rozhraniu API je možné BitFakturu ľahko integrovať s inými aplikáciami. V nižšie uvedených príkladoch používame nástroj CURL - ľahko ho môžete zmeniť na ľubovoľný programovací jazyk.
Kontaktujte nás pokiaľ chcete ďalšiu funkciu rozhrania API - skúsime ich rýchlo pridať.
Všetky príklady pracujú aj s JSON (jednoducho zmeňte rozšírenie z xml na json)
POZNÁMKA: kompletná dokumentácia je na stránke GitHub:
https://github.com/InvoiceOcean/api
POZNÁMKA: kompletná dokumentácia je na stránke GitHub: https://github.com/InvoiceOcean/api
API token
Token API je nutné stiahnuť z nastavenia aplikácie ("Nastavenia -> Nastavenie účtu -> Integrácia -> Autorizačný kód API")Faktúry
stiahnutie všetkých faktúr za dané obdobie
stiahnutie faktúr z aktuálneho mesiaca:
JSON
stiahnuť kód CURL
https://YOUR_DOMAIN.bitfaktura.sk/invoices.json?period=this_month&page=1&per_page=25&api_token=API_TOKEN
XML
stiahnuť kód CURL
https://YOUR_DOMAIN.bitfaktura.sk/invoices.xml?period=this_month&page=1&per_page=25&api_token=API_TOKEN
Môžete predať rovnaké parametre, ktoré boli predané v aplikácií (na zozname faktúr)
Stiahnutie vybranej faktúry podľa ID
JSON
stiahnuť kód CURL
https://YOUR_DOMAIN.bitfaktura.sk/invoices/100.json?api_token=API_TOKEN
XML
stiahnuť kód CURL
https://YOUR_DOMAIN.bitfaktura.sk/invoices/100.xml?api_token=API_TOKEN
Stiahnuť faktúru vo formáte PDF
PDF
stiahnuť kód CURL
https://YOUR_DOMAIN.bitfaktura.sk/invoices/100.pdf?api_token=API_TOKEN
Zaslať faktúru klientovi e-mailom
JSON curl -X POST "https://YOUR_DOMAIN.bitfaktura.sk/invoices/100/send_by_email.json?api_token=API_TOKEN"
XML curl -X POST "https://YOUR_DOMAIN.bitfaktura.sk/invoices/100/send_by_email.xml?api_token=API_TOKEN"
Stiahnuť faktúru podľa OID
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/invoices.json?oid=nr_zam&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/invoices.xml?oid=nr_zam&api_token=API_TOKEN"
Sťahovanie faktúr podľa ID dokladu, ktorý bol vygenerovaný na ich základe
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/invoices.json?invoice_id=id&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/invoices.xml?invoice_id=id&api_token=API_TOKEN"
Sťahovanie faktúr podľa ID dokladu, na základe ktorého boli vygenerované
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/invoices.json?from_invoice_id=id&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/invoices.xml?from_invoice_id=id&api_token=API_TOKEN"
Pridanie novej faktúry
JSON (odporúčaný)JSON (odporúčaný)
curl https://YOUR_DOMAIN.bitfaktura.sk/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-10-03",
"issue_date": "2024-10-03",
"payment_to": "2024-10-10",
"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}
]
}}'
stiahnuť kód CURLS údajmi východiskového oddelenia :
curl https://YOUR_DOMAIN.bitfaktura.sk/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-10-03",
"issue_date": "2024-10-03",
"payment_to": "2024-10-10",
"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}
]
}}'
stiahnuť kód CURLXML
curl https://YOUR_DOMAIN.bitfaktura.sk/invoices.xml \
-u 'login:YOUR_PASSWORD' \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-d '<invoice>
<kind>vat</kind>
<sell_date>2024-10-03</sell_date>
<issue_date>2024-10-03</issue_date>
<payment_to>2024-10-10</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>'
stiahnuť kód CURLPríklad v Ruby
endpoint = 'https://YOUR_DOMAIN.bitfaktura.sk/invoices.json'
uri = URI.parse(endpoint)
json_params = {
"api_token" => "API_TOKEN",
"invoice" => {
"kind" =>"vat",
"number" => nil,
"sell_date" => "2024-10-03",
"issue_date" => "2024-10-03",
"payment_to" => "2024-10-10",
"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-10-03",
"issue_date": "2024-10-03",
"payment_to": "2024-10-10",
"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.bitfaktura.sk/invoices.json'
$.ajax({
type: "POST",
url: endpoint,
data: json_params,
dataType: 'json',
success: function(data) { alert('invoice created! ' + data['number'])},
});
Pridať faktúru s percentuálnou zľavou
UPOZORNENIE: pred vystavením je potrebné skontrolovať, či v poli Nastavenie účtu: "Ako vypočítať zľavu" je nastavené "percento z ceny bez DPH za jednotku"curl https://YOUR_DOMAIN.bitfaktura.sk/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-10-03",
"issue_date": "2024-10-03",
"payment_to": "2024-10-10",
"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}
]
}}'
stiahnuť kód CURLPridanie faktúry so zľavou
UPOZORNENIE: pred vydaním je potrebné skontrolovať, či v poli Nastavenie účtu "Ako vypočítať zľavu" je nastavené na "sumu"curl https://YOUR_DOMAIN.bitfaktura.sk/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-10-03",
"issue_date": "2024-10-03",
"payment_to": "2024-10-10",
"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}
]
}}'
stiahnuť kód CURLPridanie faktúry pre existujúceho zákazníka a produktu
Ak máte ID zákazníka (client_id), dodávateľa (department_id) alebo produkt (product_id), nemusíte prevádzať viac dát. Faktúra bude vystavená v danom dni s päťdňovou splatnosťou.curl https://YOUR_DOMAIN.bitfaktura.sk/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}
]
}}'
stiahnuť kód CURLAktualizácia faktúry
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLOdstránenie faktúry
JSON curl -X DELETE "https://YOUR_DOMAIN.bitfaktura.sk/invoices/100.json?api_token=API_TOKEN"
XML curl -X DELETE "https://YOUR_DOMAIN.bitfaktura.sk/invoices/100.xml?api_token=API_TOKEN"
Skladové doklady
Všetky skladové doklady
JSONcurl "https://YOUR_DOMAIN.bitfaktura.sk/warehouse_documents.json?page=1&per_page=25&api_token=API_TOKEN"
Môžete predať rovnaké parametre, ktoré boli predané v aplikácií (na zozname faktúr)
Stiahnutie vybraného dokladu podľa ID
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/warehouse_documents/555.json?api_token=API_TOKEN"
Pridať príjmový skladový doklad
JSON
curl https://YOUR_DOMAIN.bitfaktura.sk/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-10-03",
"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}
]
}}'
stiahnuť kód CURLPridať výdavkový skladový doklad
JSON
curl https://YOUR_DOMAIN.bitfaktura.sk/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-10-03",
"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}
]
}}'
stiahnuť kód CURLPridanie skladového dokladu PZ pre existujúceho zákazníka, oddelenie a výrobok
Pre nastavenie východzieho oddelenia vynechajte kľúč: department_id (a department_name)JSON
curl https://YOUR_DOMAIN.bitfaktura.sk/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-10-03",
"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}
]
}}'
stiahnuť kód CURLAktualizácia dokladu
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLOdstránenie dokladu
JSON curl -X DELETE "https://YOUR_DOMAIN.bitfaktura.sk/warehouse_documents/100.json?api_token=API_TOKEN"
Produkty / služby
Všetky produkty
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/products.json?page=1&per_page=25&api_token=API_TOKEN&page=1"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/products.xml?page=1&per_page=25&api_token=API_TOKEN&page=1"
Stiahnutie daného výrobku podľa ID
curl "https://YOUR_DOMAIN.bitfaktura.sk/products/100.xml?api_token=API_TOKEN"
Pridanie výrobku
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLAktualizácia výrobku
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLWidget
Ak chcete stiahnuť formát platby (vo formáte JS), zadajte adresu URL:
https://app.bitfaktura.sk/a/YOUR_DOMAIN/p/{{token}}.js
Klienti
Všetci zákazníci
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/clients.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/clients.xml?page=1&per_page=25&api_token=API_TOKEN"
Vyberte klienta pomocou jeho ID
curl "https://YOUR_DOMAIN.bitfaktura.sk/clients/100.xml?api_token=API_TOKEN"
Stiahnutie vybraného zákazníka podľa externého ID
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/clients.json?external_id=100&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/clients.xml?external_id=100&api_token=API_TOKEN"
Pridanie klienta
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLAktualizácia klienta
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLPlatby
Všetky platby
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/banking/payments.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/banking/payments.xml?page=1&per_page=25&api_token=API_TOKEN"
Stiahnutie danej platby podľa ID
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/banking/payment/100.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/banking/payments/100.xml?api_token=API_TOKEN"
Pridanie novej platby
minimal JSON (odporúčaný)curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLfull JSON (odporúčaný)
curl https://YOUR_DOMAIN.bitfaktura.sk/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"
}}'
stiahnuť kód CURLKategórie
Vytvorenie novej kategórie
JSON (odporúčaný)curl https://YOUR_DOMAIN.bitfaktura.sk/categories.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"category": {
"name": "my_category",
"description": null
}
}'
stiahnuť kód CURLZoznam kategórií
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/categories.xml?api_token=API_TOKEN"
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/categories.json?api_token=API_TOKEN"
Stiahnutie informácií o jednotlivej kategórii pre ID
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/categories/100.xml?api_token=API_TOKEN"
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/categories/100.json?api_token=API_TOKEN"
Viac príkladov: https://github.com/InvoiceOcean/api
Sklady
Vytvorenie nového skladu
JSON (odporúčaný)curl https://YOUR_DOMAIN.bitfaktura.sk/warehouses.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse": {
"name": "my_warehouse",
"kind": null,
"description": null
}
}'
stiahnuť kód CURLStiahnutie zoznamu skladov
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/warehouses.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/warehouses.xml?api_token=API_TOKEN"
Stiahnutie informácií o sklade podľa ID
JSON curl "https://YOUR_DOMAIN.bitfaktura.sk/warehouses/100.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfaktura.sk/warehouses/100.xml?api_token=API_TOKEN"
Integrácie
Pridanie nového užívateľa
JSON method: POST url: https://app.bitfaktura.sk/users.json
{
"user": {
"email": "email5670@fakturowytmail.pl",
"password": "your_secret_password"
},
"integration_token": "email-us-for-this-token"
}
stiahnuť kód CURL | stiahnuť kód Ruby | stiahnuť kód JavaScript | stiahnuť kód PHP | stiahnuť kód JSONZískajte informácie o užívateľovi (spolu s prístupovým kódom API)
JSON method: POST url: https://app.bitfaktura.sk/login.json
{
"login": "email5670@fakturowytmail.pl",
"password": "your_secret_password",
"integration_token": "email-us-for-this-token"
}
stiahnuť kód CURL | stiahnuť kód Ruby | stiahnuť kód JavaScript | stiahnuť kód PHP | stiahnuť kód JSONVytvorenie nového účtu
JSON method: POST url: https://app.bitfaktura.sk/account.json
{
"api_token": "API_TOKEN",
"account": {
"prefix": "ftprefix"
},
"integration_token": "email-us-for-this-token"
}
stiahnuť kód CURL | stiahnuť kód Ruby | stiahnuť kód JavaScript | stiahnuť kód PHP | stiahnuť kód JSONVytvorenie nového účtu spolu s majiteľom tohto účtu a firemnými údajmi
JSONcurl https://app.bitfaktura.sk/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"
}'
stiahnuť kód CURLZískajte informácie o účte
stiahnuť kód CURL
https://YOUR_DOMAIN.bitfaktura.sk/account.json?api_token=API_TOKEN&integration_token=email-us-for-this-token
Oddelenie
Pridanie loga
curl -X PUT https://YOUR_DOMAIN.bitfaktura.sk/departments/222.json \
-F 'api_token=API_TOKEN' \
-F 'department[logo]=@/file_path/logo.png'
stiahnuť kód CURL
Viac príkladov: https://github.com/InvoiceOcean/api