API-v2

Application Programming Interface

InvoiceXpress Documentation

Documentation Invoices Estimates Guides Purchase orders Clients Items Sequences Taxes Accounts Saf t Treasury

Create

POST /:document-type.json

Creates a new invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.

Creating new clients or items along with the invoice

This method also allows to create a new client and/or new items in the same request with the following behavior:

  • If the client name does not exist a new one is created.
  • If items do not exist with the given names, new ones will be created.
  • If item name already exists, the item is updated with the new values.

Taxes

Regarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).

Note: Simplified Invoices are only available in Portugal.

Example URL

https://ACCOUNT_NAME.app.invoicexpress.com/invoices.json?api_key=API_KEY

You can find your ACCOUNT_NAME and API_KEY here: https://www.app.invoicexpress.com/users/api

Example Request

curl

curl --request POST \
  --url 'https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"invoice":{"date":"03/12/2017","due_date":"03/12/2017","client":{"name":"Client Name","code":"A1"},"items":[{"name":"Item Name","description":"Item Description","unit_price":"100","quantity":"5"}]}}'

Ruby

require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}"

response = http.request(request)
puts response.read_body

Node

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ invoice:
   { date: '03/12/2017',
     due_date: '03/12/2017',
     client:
      { name: 'Client Name',
        code: 'A1'},
     items:
      [ { name: 'Item Name',
          description: 'Item Description',
          unit_price: '100',
          quantity: '5' } ],
    }}));
req.end();

Python

import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("POST", "/:document-type.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

PHP

<?php

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE"

  payload := strings.NewReader("{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("accept", "application/json")
  req.Header.Add("content-type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

Path Parameters

Name Type Required Description Example
document-type String Required The type of document you want to create. For example: invoices, simplified_invoices, invoice_receipts, credit_notes or debit_notes. invoices

Request Body

Name Type Required Description
invoice Object Required Invoice data to be created
date String Required The invoice date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date.
due_date String Required The invoice due date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date.
reference String The invoice purchase order reference field.
observations String Invoice observations, these will be printed with the invoice.
retention String Withholding tax percentage (%). Must be a number between 0 and 99.99.
tax_exemption String Depends Portuguese IVA exemption code. Required for portuguese accounts on invoices with IVA exempt items (0%). Refer to the Appendix for the complete list of “IVA Exemption Codes”.
sequence_id String Id of the sequence you want to use with this invoice. If missing, the default sequence will be used.
manual_sequence_number String Depends Required for non portuguese accounts with manual sequence numbering.
client Object Required
name String Required The invoice’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.
code String Required The client’s unique code. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.
email String Client email address. Must be a valid email address ex: foo@bar.com
address String Client company address.
city String Client’s city.
postal_code String Client’s postal code for it’s company address.
country String Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the Appendix of this Documentation.
fiscal_id String The client fiscal ID (Número de Contribuinte)
website String The client web address
phone String The client phone number
fax String The client fax number
observations String The client default observations. This is added to the observations field of all the invoices sent to this client.
items Array Required An array of invoice items. If items with the given names do not exist, they are created. If an item already exists, it is updated with the new values. At least one is required.
name String Required Name of the item. Must be unique.
description String Required Item’s description
unit_price Number Required Item’s unit price. Must be a number equal or greater than 0.0.
quantity Number Required Quantity. Must be a number equal or greater than 0.
unit String The item unit of measure
discount Number The item discount percentage(%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.
tax Object The tax applied to the item line. If not present the default tax is applied to the item
name String The tax name to be used on this item line. If not found the default tax is applied to the line item
mb_reference String Generates a Multibanco Reference after you finalize your invoice. This option is only available for Portuguese Accounts. You must have the feature enabled on your account first.
owner_invoice_id Integer The (owner) invoice associated to this document. This option is only available for credit_notes or debit_notes. You can also send the (owner) guide id when creating an invoice to associate an invoice to a guide.
tax_exemption_reason String Used when updating a document and removing all tax exempt items. The code M00 means 'Without tax exemption'.
currency_code String If your plan as multicurrency, you can issue invoices in another currency than your account's default currency. The currency_code should be one of the following ISO 3166 alpha-2 currency codes.
rate String When sending a currency_code you can specify its' rate.
proprietary_uid String When sending your process' UUID you will prevent the creation of duplicate requests.
global_discount Object The discount applied to the document
value_type String Value type can be percentage or absolute
value Number Document's global discount value. Must be a number greater than 0.0
plugin_id String This is used by plugin owners to include in the creation of their user's invoices. Please reach out for our support team at plugins@invoicexpress.com if you are interested in developing a new plugin.

Example Request Body

{
  "invoice": {
    "date": "03/12/2017",
    "due_date": "03/12/2017",
    "reference": "999",
    "observations": "Observations",
    "retention": "0",
    "tax_exemption": "M01",
    "sequence_id": "12345",
    "manual_sequence_number": "1",
    "client": {
      "name": "Client Name",
      "code": "A1",
      "email": "foo@bar.com",
      "address": "Saldanha",
      "city": "Lisbon",
      "postal_code": "1050-555",
      "country": "Portugal",
      "fiscal_id": "508000000",
      "website": "www.website.com",
      "phone": "910000000",
      "fax": "210000000",
      "observations": "Observations"
    },
    "items": [
      {
        "name": "Item Name",
        "description": "Item Description",
        "unit_price": "100",
        "quantity": "5",
        "unit": "service",
        "discount": "50",
        "tax": {
          "name": "IVA23"
        }
      }
    ],
    "mb_reference": "0",
    "owner_invoice_id": "12345",
    "tax_exemption_reason": "M00",
    "currency_code": "USD",
    "rate": "1.23565",
    "global_discount": {
      "value_type": "percentage",
      "value": 50.0
    }
  },
  "proprietary_uid": "UUID41237123189981ddajkls23478y"
}

Responses
201 SUCCESS
Invoice was created successfully.		 Invoices Get
401 ACCESS DENIED
The API Key parameter is missing or is incorrectly entered.		 (Empty Response)
409 CONFLICT
There's an ongoing document creation with the provided UID.		 (Empty Response)
422 UNPROCESSABLE ENTITY
Some parameters were incorrect.		 (Empty Response)

Example Success Body Response

{
  "invoice": {
    "id": 2137287,
    "status": "draft",
    "archived": false,
    "type": "Invoice",
    "sequence_number": "6/G",
    "inverted_sequence_number": "G/6",
    "atcud": "ABCD1234-28",
    "sequence_id": "12345",
    "tax_exemption": "M01",
    "date": "04/08/2016",
    "due_date": "19/08/2016",
    "reference": "foo",
    "observations": "foo",
    "retention": "foo",
    "permalink": "https://www.app.invoicexpress.com/documents/213728738ca780a8de4330cad4a5a556360304bd9c57011",
    "saft_hash": "J4ay",
    "sum": 24.39,
    "discount": 0,
    "before_taxes": 24.39,
    "taxes": 5.61,
    "total": 30,
    "currency": "Euro",
    "client": {
      "id": 628535,
      "name": "John",
      "country": "Portugal"
    },
    "items": [
      {
        "name": "Large",
        "description": "foo",
        "unit_price": "24.3902",
        "unit": "foo",
        "quantity": "1.0",
        "tax": {
          "id": 69166,
          "name": "IVA23",
          "value": 23
        },
        "discount": 0,
        "subtotal": 24.39,
        "tax_amount": 5.61,
        "discount_amount": 0,
        "total": 30
      }
    ],
    "mb_reference": {
      "entity": "10611",
      "value": 30,
      "reference": "952000823"
    },
    "global_discount": {
      "value_type": "percentage",
      "value": 50.0
    }
  }
}