InvoiceOcean API
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md

README.md

InvoiceOcean API

Description on how to integrate own apllication or service with http://invoiceocean.com/ system

Thanks to API you can issue invoices/bills/receipts from other systems and manage these documents, as well as clients and products

Table of contents

API token

API_TOKEN token has to be downloaded from application settings ("Settings -> Account settings -> Integration -> API Authorization Code")

Examples of calling

Downloading a list of invoices from current month

curl https://yourdomain.invoiceocean.com/invoices.json?period=this_month&api_token=API_TOKEN

NOTE: additional parameters can be forwarded to calls, e.g. page=, period= etc.

Specific client's invoices

curl https://yourdomain.invoiceocean.com/invoices.json?client_id=ID_KLIENTA&api_token=API_TOKEN

Downloading invoices by ID

curl https://yourdomain.invoiceocean.com/invoices/100.json?api_token=API_TOKEN

Downloading as PDF

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

Sending invoices by email to a client

curl -X POST https://yourdomain.invoiceocean.com/invoices/100/send_by_email.json?api_token=API_TOKEN

Other PDF options:

  • print_option=original - Original
  • print_option=copy - Copy
  • print_option=original_and_copy - Original and copy
  • print_option=duplicate Duplicate

Adding a new invoice

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": "2013-01-16", 
            "issue_date": "2013-01-16", 
            "payment_to": "2013-01-23",
            "seller_name": "Wystawca Sp. z o.o.", 
            "seller_tax_no": "5252445767", 
            "buyer_name": "Klient1 Sp. z o.o.",
            "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":3}
            ]       
        }
    }'

Adding a new invoice - the minimal version (only fields required), when we have product, buyer and seller ID we do not need to provide full details. VAT Invoice with current date and 5 day due date will be issued.

curl http://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": 1, 
            "client_id": 1,
            "positions":[
                {"product_id": 1, "quantity":2}
            ]
        }}'

Adding a new correction invoice

curl http://YOUR_DOMAIN.invoiceocean.com/invoices.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"api_token": "API_TOKEN",
        "invoice": {
            "kind": "correction",
            "from_invoice_id": "2432393,
            "client_id": 1,
            "positions":[
                {"name": "Product A1",
                "quantity":-1,
                "total_price_gross":"-10",
                "tax":"23",
                "correction_before_attributes": {
                    "name":"Product A1",
                    "quantity":"2",
                    "total_price_gross":"20",
                    "tax":"23",
                    "kind":"correction_before"
                },
                "correction_after_attributes": {
                    "name":"Product A1",
                    "quantity":"1",
                    "total_price_gross":"10",
                    "tax":"23",
                    "kind":"correction_after"
                }
            }]
        }}'

Invoice update

curl https://YOUR_DOMAIN.invoiceocean.com/invoices/111.json \
    -X PUT \
    -H 'Accept: application/json'  \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "invoice": {
            "buyer_name": "New client name Ltd."
        }
    }'

Changing invoice status

curl "https://YOUR_DOMAIN.invoiceocean.com/invoices/111/change_status.json?api_token=API_TOKEN&status=STATUS" -X POST

Link to invoice preview and PDF download

After downloading invoice data, e.g. by:

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

API gives us token field, on which basis we may receive invoice preview links Such links allow you to refer to the selected invoice without having to log in - you can, for instance, send these links to the customer, who will have access to invoices and PDF.

Links are in the form:

preview: http://yourdomain.invoiceocean.com/invoice/{{token}} pdf: http://yourdomain.invoiceocean.com/invoice/{{token}}.pdf

E.g. for token equal: HBO3Npx2OzSW79RQL7XV2 public PDF will be at http://yourdomain.invoiceocean.com/invoice/HBO3Npx2OzSW79RQL7XV2.pdf

Examples of using PHP - purchase of training

TODO

Flow Portal Example which generates a proforma invoice for the client, sends it to the client and after receiving payment, sends the training ticket to the client

  • Client fills in details in the Portal
  • The Portal calls API from invoiceocean.com and generates an invoice
  • The Portal sends a Proforma PDF invoice to the Client along with a payment link
  • Client makes a payment for the Proforma invoice (e.g. using PayPal)
  • InvoiceOcean.com receives information that the payment has been made, generates VAT invoice and sends it to the client and calls Portal API
  • After receiving information regarding payment (by API) Portal sends the training ticket to the Client

Invoices

  • GET /invoices/1.json downloading invoice
  • POST /invoices.json adding a new invoice
  • PUT /invoices/1.json updating invoice
  • DELETE /invoices/1.json deleting invoice

Example - adding a new invoice - the minimal version (only fields required), when we have product, buyer and seller ID we do not need to provide full details. Field department_id determines the company (or department) which issues the invoice (it can be obtained by clicking on the company in Settings> Data Company)

curl http://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": 1, 
            "client_id": 1,
            "positions":[
                {"product_id": 1, "quantity":2}
            ]
        }}'

Invoice fields

"number" : "13/2012" - invoice number (if not entered, it will be automatically generated)
"kind" : "vat" - invoice kind (vat, proforma, bill, receipt, advance, correction, vat_mp, invoice_other, vat_margin, kp, kw, final, estimate)
"income" : "1" - income invoice (1) or cost invoice (0)
"issue_date" : "2013-01-16" - date of issue 
"place" : "Warszawa" - place of issue
"sell_date" : "2013-01-16" - date of sale (it can be date or month in the YYYY-MM format)
"category_id" : "" - category id
"department_id" : "1" - department id (in Settings > Company / department, click on company / department and department ID will be shown in the URL)
"seller_name" : "Radgost Sp. z o.o." - seller
"seller_tax_no" : "525-244-57-67" - seller tax id
"seller_bank_account" : "24 1140 1977 0000 5921 7200 1001" - seller bank account
"seller_bank" : "BRE Bank", 
"seller_post_code" : "02-548", 
"seller_city" : "Warsaw", 
"seller_street" : "21 Olesińska St.", 
"seller_country" : "", 
"seller_email" : "platnosci@radgost123.com", 
"seller_www" : "", 
"seller_fax" : "", 
"seller_phone" : "", 
"client_id" : "-1" - buyer id (if -1 then client will be created in the system)
"buyer_name" : "Client name - buyer
"buyer_tax_no" : "525-244-57-67", 
"disable_tax_no_validation" : "", 
"buyer_post_code" : "30-314", 
"buyer_city" : "Warsaw", 
"buyer_street" : "Nowa 44", 
"buyer_country" : "", 
"buyer_note" : "", 
"buyer_email" : "", 
"additional_info" : "0" - whether to display additional field in invoice position
"additional_info_desc" : "PKWiU" - name of the additional column in invoice positions
"show_discount" : "0" - whether show discount or not
"payment_type" : "transfer", 
"payment_to_kind" : due date. if it is "other_date", then you may define a specific date in "payment_to" field, if it is, for example, numer 5 then you have a 5 day payment period
"payment_to" : "2013-01-16", 
"status" : "issued", 
"paid" : "0,00", 
"oid" : "zamowienie10021", - order number (e.g. from external ordering system)
"warehouse_id" : "1090", 
"seller_person" : "Forename Surname", 
"buyer_first_name" : "Forename", 
"buyer_last_name" : "Surname", 
"description" : "", 
"paid_date" : "", 
"currency" : "GBP", 
"lang" : "en", 
"exchange_currency" : "", - converted currency (conversion of the sum and tax into another currency at current exchange rates)
"internal_note" : "", 
"invoice_template_id" : "1", 
"description_footer" : "", 
"description_long" : "", 
"from_invoice_id" : "" - invoice id, on which basis the invoice was generated (useful when generating a VAT invoice from Proforma invoice)
"positions":
        "product_id" : "1", 
        "name" : "InvoiceOcean Basic", 
        "additional_info" : "", - additional information on invoice position 
        "discount_percent" : "", - percentage discount (note: in order for the discount to be calculated, you need to set field 'show_discount' to 1 and before issuing check if in Account Settings, field: "How to calculate discount" is set to 'percentage from unit gross price')
        "discount" : "", - amount discount (note: in order for the discount to be calculated, you need to set field 'show_discount' to 1 and before issuing check if in Account Settings, field: "How to calculate discount" is set to "amount")
        "quantity" : "1", 
        "quantity_unit" : "unit", 
        "price_net" : "59,00", - if not entered it will be calculated
        "tax" : "23", 
        "price_gross" : "72,57", - if not entered it will be calculated
        "total_price_net" : "59,00", - if not entered it will be calculated
        "total_price_gross" : "72,57"

Field entries

Field: kind

    "vat" - VAT invoice
    "proforma" -  Proforma invoice
    "bill" - bill
    "receipt" - receipt
    "advance" - advance invoice
    "final" - final invoice
    "correction" - Credit Note
    "vat_mp" - MP invoice 
    "invoice_other" - other invoice 
    "vat_margin" - margin invoice
    "kp" - cash received
    "kw" - cash disbursed
    "estimate" - Estimate

Field: lang

    "pl" - Polish
    "en" - English
    "de" - German
    "fr" - French
    "cz" - Czech
    "ru" - Russian
    "es" - Spanish
    "it" - Italian
    "nl" - Dutch
    "hr" - Croatian

Field: income

    "1" - income invoice
    "0" - cost invoice

Field: payment_type

    "transfer" - transfer
    "card" - card
    "cash" -  cash
    "any_other_text_entry" 

Field: status

    "issued" - issued
    "sent" - sent
    "paid" - paid
    "partial" - partially paid

Field: discount_kind - discount kind

    "percent_unit" - calculated from the unit price
    "percent_total" - calculated from the total price
    "amount" - amount

Clients

Clients list

curl "http://YOUR_DOMAIN.invoiceocean.com/clients.json?api_token=API_TOKEN&page=1"

Get selected client by ID

curl "http://YOUR_DOMAIN.invoiceocean.com/clients/100.json?api_token=API_TOKEN"

Adding clients

curl http://YOUR_DOMAIN.invoiceocean.com/clients.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"api_token": "API_TOKEN",
        "client": {
            "name": "Klient1",
            "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"
        }}'

Client update

curl http://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"
        }}'

Products

Products

Products list

curl "http://YOUR_DOMAIN.invoiceocean.com/products.json?api_token=API_TOKEN&page=1"

Get selected product by ID

curl "http://YOUR_DOMAIN.invoiceocean.com/products/100.json?api_token=API_TOKEN"

Adding products

curl http://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"
        }}'

Product update

curl http://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_net": "102"
        }}'

Payments

Fields description

  • city - City from the sender's address
  • client_id - ID of the client who makes the payment
  • comment - Comment for the client
  • country - Country from the sender's address
  • currency - Currency of the payment
  • department_id - ID of the department that the client belongs to
  • description - Payment description
  • email - Email of the sender
  • first_name - First name of the sender
  • generate_invoice - If generate an invoice that would match the payment
  • invoice_city - City of the generated invoice's address
  • invoice_comment - Comment for the generated invoice
  • invoice_country - Country of the generated invoice's address
  • invoice_id - ID of the invoice being paid for
  • invoice_name - Name of the client on the generated invoice
  • invoice_post_code - Post code of the generated invoice's address
  • nvoice_street - Street of the generated invoice's address
  • invoice_tax_no - Tax no. on the generated invoice
  • last_name - Last name of the sender
  • name - Name of the sender
  • oid - ID of the order that is paid for
  • paid - If the payment is already paid
  • paid_date - Date when the payment was made
  • phone - Phone of the sender
  • post_code - Post code from the sender's address
  • price - Price of the product that was paid for
  • product_id - ID of the product that was paid for
  • promocode - Promocode that was used with the payment
  • provider - Name of the payment provider (for online payments)
  • provider_response - Response of the payment provider
  • provider_status - Status of the payment according to the provider
  • provider_title - Title of the payment provider
  • quantity - Quantity of the item that was paid for
  • street - Street from the sender's address
  • kind - payment kind (where it comes from). In case of API it should be set to "api".

Listing all payments

XML

curl "http://YOUR_DOMAIN.invoiceocean.com/payments.xml?api_token=API_TOKEN"

JSON

curl "http://YOUR_DOMAIN.invoiceocean.com/payments.json?api_token=API_TOKEN"

Select payment using ID

XML

curl "http://YOUR_DOMAIN.invoiceocean.com/payments/100.xml?api_token=API_TOKEN"

JSON

curl "http://YOUR_DOMAIN.invoiceocean.com/payment/100.json?api_token=API_TOKEN"

Adding new payment

Minimal JSON (recommended)

curl #{domain}/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"
            }
         }'

Full JSON (recommended)

curl #{domain}/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",
            "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"
        }
         }'

Examples in PHP and Ruby

https://github.com/radgost/fakturownia-api/blob/master/example1.php/

https://github.com/radgost/fakturownia-api/blob/master/example1.rb/

Ruby Gem for InvoiceOcean.com integration: https://github.com/kkempin/fakturownia/