InvoiceOcean API

This API allows you to easily integrate with other applications. In the examples below we use CURL tool - you can easily change it to any computer language.

Please contact us If you want any additional API function, we will add it as fast as possible.

All examples work with JSON too (you simply need to change xml extension to json)

NOTE: Full documentation can be found on GitHub https://github.com/InvoiceOcean/api

API token

API token can be downloaded from the application's settings (Settings -> Account settings -> Integration -> API authorization code)

Invoices

Select all invoices from a selected time period

select invoice from current month:

XML curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.xml?period=this_month&api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.json?period=this_month&api_token=API_TOKEN" You can pass the same parameters that are passed in the application (on the invoice list)

Select invoice by ID

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

Download invoice as PDF

curl "https://YOUR_DOMAIN.invoiceocean.com/invoices/100.pdf?api_token=API_TOKEN"

Send invoice to client by email

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

Download invoice by OID

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

Add new invoice

JSON (recommended)

JSON (recommended)

curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-08-22", "issue_date": "2017-08-22", "payment_to": "2017-08-29", "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} ] }}' Download code CURL


With default department data : curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-08-22", "issue_date": "2017-08-22", "payment_to": "2017-08-29", "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} ] }}' Download code CURL


XML

curl https://YOUR_DOMAIN.invoiceocean.com/invoices.xml -u 'login:YOUR_PASSWORD' -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '<invoice> <kind>vat</kind> <sell_date>2017-08-22</sell_date> <issue_date>2017-08-22</issue_date> <payment_to>2017-08-29</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>' Download code CURL

Example in Ruby

endpoint = 'https://YOUR_DOMAIN.invoiceocean.com/invoices.json' uri = URI.parse(endpoint) json_params = { "api_token" => "API_TOKEN", "invoice" => { "kind" =>"vat", "number" => nil, "sell_date" => "2017-08-22", "issue_date" => "2017-08-22", "payment_to" => "2017-08-29", "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 Download code Ruby



Javascript / Ajax jQuery

json_params = { "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-08-22", "issue_date": "2017-08-22", "payment_to": "2017-08-29", "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.invoiceocean.com/invoices.json' $.ajax({ type: "POST", url: endpoint, data: json_params, dataType: 'json', success: function(data) { alert('invoice created! ' + data['number'])}, }); Download code JavaScript

Adding invoice with a percentage discount

NOTE: Prior to issuing, please check that in Account Settings, field: 'How to calculate a discount' is set for 'percentage per net unit price' curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-08-22", "issue_date": "2017-08-22", "payment_to": "2017-08-29", "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} ] }}' Download code CURL


Adding invoice with amount discount

NOTE: Before issuing, make sure to check 'Value' in Account Settings -> How to calculate a discount
curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2017-08-22", "issue_date": "2017-08-22", "payment_to": "2017-08-29", "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} ] }}' Download code CURL

Adding invoice to existing client and product

If you have your client's ID (client_id), seller (department_id) or product (product_id) you do not have to enter more data. Invoice will be issued with the current date and 5 day maturity.
curl https://YOUR_DOMAIN.invoiceocean.com/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} ] }}' Download code CURL

Invoice update


curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL


Delete invoice

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



Warehouse Documents


All warehouse documents


JSON curl "https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents.json?api_token=API_TOKEN" You can pass the same parameters that are passed in the application (on the invoice list)


Fetch warehouse document by ID

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents/555.json?api_token=API_TOKEN"


Add new Goods Received Note



JSON

curl https://YOUR_DOMAIN.invoiceocean.com/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-08-22", "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} ] }}' Download code CURL


Add new Goods Issued Note



JSON

curl https://YOUR_DOMAIN.invoiceocean.com/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-08-22", "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} ] }}' Download code CURL


Add new warehouse document for existing client, department and product

To set default department just skip these keys: department_id and department_name

JSON

curl https://YOUR_DOMAIN.invoiceocean.com/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-08-22", "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} ] }}' Download code CURL


Update warehouse document


curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL


Delete warehouse document

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





Products / services

Products

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

Select product using their ID

curl "https://YOUR_DOMAIN.invoiceocean.com/products/100.xml?api_token=API_TOKEN"

Add product


curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL

Product update


curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL

Widget

To download payment widget (in JS format) enter URL:

http://app.invoiceocean.com/a/YOUR_DOMAIN/p/{{token}}.js

where {{token}} is a specific token product value



Clients

Clients

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

Select client using their ID

curl "https://YOUR_DOMAIN.invoiceocean.com/clients/100.xml?api_token=API_TOKEN"

Adding client


curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL

Client update

curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL




Payments

Payments


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

Select payment using their ID


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

Adding new payment

minimal JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL
full JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/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" }}' Download code CURL



System Accounts

Creating new account

JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/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" } }' Download code CURL

More examples: https://github.com/radgost/fakturownia-api


Get user info (with API Access Token)

JSON (recommended) curl https://app.invoiceocean.com/login.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "login": "login_or_email1", "password": "password1" }' Download code CURL


Get account info

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



More examples: https://github.com/radgost/fakturownia-api