API Fakturowni

Dzięki API system fakturownia można łatwo zintegrować z innymi aplikacjami. W przykładach podajemy wywołania za pomocą narzędzia CURL, które można łatwo zastąpić wywołaniem dowolnego języka programowania.

Jeśli do Waszej integracji potrzebne będą dodatkowe funkcje wywoływane przez API to prosimy o kontakt - postaramy się szybko je dodać.

Wszystkie przykłady działają z JSON lub XML (wystarczy zmienić rozszerzenie xml na json). Wszystkie wywołania API działają z SSL, warto więc w wersji produkcyjnej zamienić HTTP na HTTPS.

UWAGA: pełna dokumentacja znajduje się na GitHub: https://github.com/fakturownia/api

API token

API token trzeba pobrać z ustawień aplikacji ('Ustawienia -> Ustawienia konta -> Integracja -> Kod autoryzacyjny API')

Faktury

Pobranie wszystkich faktur z danego okresu

pobranie faktur z aktualnego miesiąca:

XML curl "https://YOUR_DOMAIN.fakturownia.pl/invoices.xml?period=this_month&api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/invoices.json?period=this_month&api_token=API_TOKEN" można przekazywać takie same parametry jakie są przekazywane w aplikacji (na stronie listy faktur)

Pobranie wybranej faktury po ID

XML curl "https://YOUR_DOMAIN.fakturownia.pl/invoices/100.xml?api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/invoices/100.json?api_token=API_TOKEN"

Pobieranie faktury w PDF

curl "https://YOUR_DOMAIN.fakturownia.pl/invoices/100.pdf?api_token=API_TOKEN"

Wysłanie faktury do klienta e-mailem

XML curl -X POST "https://YOUR_DOMAIN.fakturownia.pl/invoices/100/send_by_email.xml?api_token=API_TOKEN" JSON curl -X POST "https://YOUR_DOMAIN.fakturownia.pl/invoices/100/send_by_email.json?api_token=API_TOKEN"

Pobranie faktury po Id zamówienia

XML curl "https://YOUR_DOMAIN.fakturownia.pl/invoices.xml?oid=nr_zam&api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/invoices.json?oid=nr_zam&api_token=API_TOKEN"

Dodanie nowej faktury

JSON (zalecany)

JSON (zalecany)

curl https://YOUR_DOMAIN.fakturownia.pl/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-03-28", "issue_date": "2017-03-28", "payment_to": "2017-04-04", "seller_name": "Seller SA", "seller_tax_no": "5252445767", "buyer_name": "Client1 SA", "buyer_tax_no": "5252445767", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2} ] }}' pobierz kod CURL


Z danymi domyślnego działu : curl https://YOUR_DOMAIN.fakturownia.pl/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-03-28", "issue_date": "2017-03-28", "payment_to": "2017-04-04", "buyer_name": "Client1 SA", "buyer_tax_no": "5252445767", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2} ] }}' pobierz kod CURL


XML

curl https://YOUR_DOMAIN.fakturownia.pl/invoices.xml -u 'login:YOUR_PASSWORD' -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '<invoice> <kind>vat</kind> <sell_date>2017-03-28</sell_date> <issue_date>2017-03-28</issue_date> <payment_to>2017-04-04</payment_to> <seller_name>Seller SA</seller_name> <seller_tax_no>5252445767</seller_tax_no> <buyer_name>Client1 SA</buyer_name> <buyer_tax_no>5252445767</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>' pobierz kod CURL

Przykład w Ruby

endpoint = 'https://YOUR_DOMAIN.fakturownia.pl/invoices.json' uri = URI.parse(endpoint) json_params = { "api_token" => "API_TOKEN", "invoice" => { "kind" =>"vat", "number" => nil, "sell_date" => "2017-03-28", "issue_date" => "2017-03-28", "payment_to" => "2017-04-04", "buyer_name" => "Client1 SA", "buyer_tax_no" => "5252445767", "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 pobierz kod Ruby



Javascript / Ajax jQuery

json_params = { "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-03-28", "issue_date": "2017-03-28", "payment_to": "2017-04-04", "buyer_name": "Client1 SA", "buyer_tax_no": "5252445767", "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.fakturownia.pl/invoices.json' $.ajax({ type: "POST", url: endpoint, data: json_params, dataType: 'json', success: function(data) { alert('invoice created! ' + data['number'])}, }); pobierz kod JavaScript

Dodanie faktury z rabatem procentowym

UWAGA: przed wywołaniem należy sprawdzić czy w Ustawieniach Konta pole: 'Jak obliczać rabat' ustawione jest na 'procentowo od ceny jednostkowej netto' curl https://YOUR_DOMAIN.fakturownia.pl/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-03-28", "issue_date": "2017-03-28", "payment_to": "2017-04-04", "seller_name": "Seller SA", "seller_tax_no": "5252445767", "buyer_name": "Client1 SA", "buyer_tax_no": "5252445767", "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} ] }}' pobierz kod CURL


Dodanie faktury z rabatem kwotowym

UWAGA: przed wywołaniem należy sprawdzić czy w Ustawieniach Konta pole: 'Jak obliczać rabat' ustawione jest na 'kwotowo'
curl https://YOUR_DOMAIN.fakturownia.pl/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-03-28", "issue_date": "2017-03-28", "payment_to": "2017-04-04", "seller_name": "Seller SA", "seller_tax_no": "5252445767", "buyer_name": "Client1 SA", "buyer_tax_no": "5252445767", "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} ] }}' pobierz kod CURL

Dodanie faktury dla istniejącego klienta i produktu

Jeśli masz ID danego klienta (client_id), sprzedawcę (department_id) lub produkt (product_id) to nie musisz przekazywać większej ilości danych. Faktura wystawi się z aktualnym dniem i z 5 dniowym terminem płatności.
curl https://YOUR_DOMAIN.fakturownia.pl/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} ] }}' pobierz kod CURL

Aktualizacja faktury


curl https://YOUR_DOMAIN.fakturownia.pl/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" }}' pobierz kod CURL


Usunięcie faktury

XML curl -X DELETE "https://YOUR_DOMAIN.fakturownia.pl/invoices/100.xml?api_token=API_TOKEN" JSON curl -X DELETE "https://YOUR_DOMAIN.fakturownia.pl/invoices/100.json?api_token=API_TOKEN"



Dokumenty magazynowe


Wszystkie dokumenty magazynowe


JSON curl "https://YOUR_DOMAIN.fakturownia.pl/warehouse_documents.json?api_token=API_TOKEN" można przekazywać takie same parametry jakie są przekazywane w aplikacji (na stronie listy faktur)


Pobranie wybranego dokumentu po ID

JSON curl "https://YOUR_DOMAIN.fakturownia.pl/warehouse_documents/555.json?api_token=API_TOKEN"


Dodanie dokumentu magazynowego PZ



JSON

curl https://YOUR_DOMAIN.fakturownia.pl/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": "2017-03-28", "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} ] }}' pobierz kod CURL


Dodanie dokumentu magazynowego WZ



JSON

curl https://YOUR_DOMAIN.fakturownia.pl/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": "2017-03-28", "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} ] }}' pobierz kod CURL


Dodanie dokumentu magazynowego PZ dla istniejącego klienta, działu i produktu

Aby ustawić domyślny dział, pomiń klucz department_id (oraz department_name)

JSON

curl https://YOUR_DOMAIN.fakturownia.pl/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": "2017-03-28", "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} ] }}' pobierz kod CURL


Aktualizacja dokumentu


curl https://YOUR_DOMAIN.fakturownia.pl/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" }}' pobierz kod CURL


Usunięcie dokumentu

JSON curl -X DELETE "https://YOUR_DOMAIN.fakturownia.pl/warehouse_documents/100.json?api_token=API_TOKEN"





Produkty / usługi

Wszystkie produkty

XML curl "https://YOUR_DOMAIN.fakturownia.pl/products.xml?api_token=API_TOKEN&page=1" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/products.json?api_token=API_TOKEN&page=1"

Pobranie wybranego produktu po ID

curl "https://YOUR_DOMAIN.fakturownia.pl/products/100.xml?api_token=API_TOKEN"

Dodanie produktu


curl https://YOUR_DOMAIN.fakturownia.pl/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" }}' pobierz kod CURL

Aktualizacja produktu


curl https://YOUR_DOMAIN.fakturownia.pl/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" }}' pobierz kod CURL

Widget

Aby pobrać formatkę płatności (w postaci JS) należy wywołać URL:

http://app.fakturownia.pl/a/YOUR_DOMAIN/p/{{token}}.js

gdzie {{token}} to wartość pola token z danego produktu



Klienci

Wszyscy klienci

XML curl "https://YOUR_DOMAIN.fakturownia.pl/clients.xml?api_token=API_TOKEN&page=1" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/clients.json?api_token=API_TOKEN&page=1"

Pobranie wybranego klienta po ID

curl "https://YOUR_DOMAIN.fakturownia.pl/clients/100.xml?api_token=API_TOKEN"

Dodanie klienta


curl https://YOUR_DOMAIN.fakturownia.pl/clients.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "client": { "name": "Client1", "tax_no": "5252445767", "bank" : "bank1", "bank_account" : "bank_account1", "city" : "city1", "country" : "", "email" : "bank1", "person" : "person1", "post_code" : "post-code1", "phone" : "phone1", "street" : "street1", "street_no" : "street-no1" }}' pobierz kod CURL

Aktualizacja klienta

curl https://YOUR_DOMAIN.fakturownia.pl/clients/111.json -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "client": { "name": "Klient2", "tax_no": "52524457672", "bank" : "bank2", "bank_account" : "bank_account2", "city" : "city2", "country" : "PL", "email" : "bank2", "person" : "person2", "post_code" : "post-code2", "phone" : "phone2", "street" : "street2", "street_no" : "street-no2" }}' pobierz kod CURL




Płatności

Wszystkie płatności


XML curl "https://YOUR_DOMAIN.fakturownia.pl/payments.xml?api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/payments.json?api_token=API_TOKEN"

Pobranie wybranej płatności po ID


XML curl "https://YOUR_DOMAIN.fakturownia.pl/payments/100.xml?api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.fakturownia.pl/payment/100.json?api_token=API_TOKEN"

Dodawanie nowej płatności

minimal JSON (zalecany) curl https://YOUR_DOMAIN.fakturownia.pl/payments.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "payment": { "name":"Payment 001", "price": 100.05, "invoice_id": null, "paid":true, "kind": "api" }}' pobierz kod CURL
full JSON (zalecany) curl https://YOUR_DOMAIN.fakturownia.pl/payments.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "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":"5252445767", "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" }}' pobierz kod CURL



Konta systemowe

Tworzenie nowego konta

JSON (zalecany) curl https://YOUR_DOMAIN.fakturownia.pl/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" } }' pobierz kod CURL

Inne przykłady: https://github.com/radgost/fakturownia-api


Pobranie informacji o użytkowniku (wraz z kodem dostępu API)

JSON (zalecany) curl https://app.fakturownia.pl/login.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "login": "login_or_email1", "password": "password1" }' pobierz kod CURL


Pobranie informacji o koncie

JSON curl "https://YOUR_DOMAIN.fakturownia.pl/account.json?api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.fakturownia.pl/account.xml?api_token=API_TOKEN"



Inne przykłady: https://github.com/radgost/fakturownia-api