API-V2

Application Programming Interface

InvoiceXpress Documentation

Create

POST /:document-type.json

Creates a new shipping guide, transport guide or devolution guide.

Creating new clients or items along with the guide

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 guide contains exempt items (IVA 0%).

Example URL

https://ACCOUNT_NAME.app.invoicexpress.com/shippings.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 '{"shipping":{"date":"03/12/2017","due_date":"03/12/2017","loaded_at":"02/12/2017 19:00:00","address_from":{"detail":"Rua 5","city":"Lisboa","postal_code":"1000-555","country":"Portugal"},"address_to":{"detail":"Avenida 10","city":"Porto","postal_code":"2000-555","country":"Portugal"},"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 = "{\"shipping\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"02/12/2017 19:00:00\",\"address_from\":{\"detail\":\"Rua 5\",\"city\":\"Lisboa\",\"postal_code\":\"1000-555\",\"country\":\"Portugal\"},\"address_to\":{\"detail\":\"Avenida 10\",\"city\":\"Porto\",\"postal_code\":\"2000-555\",\"country\":\"Portugal\"},\"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({ shipping:
   { date: '03/12/2017',
     due_date: '03/12/2017',
     loaded_at: '02/12/2017 19:00:00',
     address_from:
      { detail: 'Rua 5',
        city: 'Lisboa',
        postal_code: '1000-555',
        country: 'Portugal' },
     address_to:
      { detail: 'Avenida 10',
        city: 'Porto',
        postal_code: '2000-555',
        country: 'Portugal' },
     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 = "{\"shipping\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"02/12/2017 19:00:00\",\"address_from\":{\"detail\":\"Rua 5\",\"city\":\"Lisboa\",\"postal_code\":\"1000-555\",\"country\":\"Portugal\"},\"address_to\":{\"detail\":\"Avenida 10\",\"city\":\"Porto\",\"postal_code\":\"2000-555\",\"country\":\"Portugal\"},\"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 = curl_init();

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 => "{\"shipping\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"02/12/2017 19:00:00\",\"address_from\":{\"detail\":\"Rua 5\",\"city\":\"Lisboa\",\"postal_code\":\"1000-555\",\"country\":\"Portugal\"},\"address_to\":{\"detail\":\"Avenida 10\",\"city\":\"Porto\",\"postal_code\":\"2000-555\",\"country\":\"Portugal\"},\"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("{\"shipping\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"02/12/2017 19:00:00\",\"address_from\":{\"detail\":\"Rua 5\",\"city\":\"Lisboa\",\"postal_code\":\"1000-555\",\"country\":\"Portugal\"},\"address_to\":{\"detail\":\"Avenida 10\",\"city\":\"Porto\",\"postal_code\":\"2000-555\",\"country\":\"Portugal\"},\"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

NameTypeRequiredDescriptionExample
document-typeStringRequiredThe type of document you want to create. For example: shippingstransports or devolutions.shippings

Request Body

NameTypeRequiredDescription
shippingObjectRequiredGuide data to be created
dateStringRequiredThe guide date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date.
due_dateStringRequiredThe guide due date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date.
loaded_atStringRequiredThe date and time that this guide will be used. Must be greater than or equal to the current date and time.
license_plateStringThe license plate of the vehicle using this guide.
address_fromObjectRequiredThe starting point of this guide.
detailStringRequiredThe address of the starting point of this guide.
cityStringRequiredThe city of the starting point of this guide.
postal_codeStringRequiredThe postal code of the starting point of this guide.
countryStringRequiredThe country of the starting point of this guide.
address_toObjectRequiredThe address of the ending point of this guide.
detailStringRequiredThe address of the ending point of this guide.
cityStringRequiredThe city of the ending point of this guide.
postal_codeStringRequiredThe postal code of the ending point of this guide.
countryStringRequiredThe country of the ending point of this guide.
referenceStringThe guide purchase order reference field.
observationsStringguide observations, these will be printed with the invoice.
retentionNumberWithholding tax percentage (%). Must be a number between 0 and 99.99.
tax_exemptionStringDependsPortuguese IVA exemption code. Required for portuguese accounts on transport-guides with IVA exempt items (0%). Refer to the Appendix for the complete list of “IVA Exemption Codes”.
sequence_idStringId of the sequence you want to use with this guide. If missing, the default sequence will be used.
manual_sequence_numberStringDependsRequired for non portuguese accounts with manual sequence numbering.
clientObjectRequiredClient’s information.
nameStringRequiredThe guide’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.
codeStringRequiredThe 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.
emailStringClient email address. Must be a valid email address ex: foo@bar.com
addressStringClient company address.
cityStringClient’s city.
postal_codeStringClient’s postal code for it’s company address.
countryStringCountry, 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_idStringThe client fiscal ID (Número de Contribuinte).
websiteStringThe client web address.
phoneStringThe client phone number.
faxStringThe client fax number.
observationsStringThe client default observations. This is added to the observations field of all the invoices sent to this client.
itemsArrayRequiredAn 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.
nameStringRequiredName of the item. Must be unique.
descriptionStringRequiredItem’s description.
unit_priceNumberRequiredItem’s unit price. Must be a number equal or greater than 0.0.
quantityNumberRequiredQuantity. Must be a number equal or greater than 0.
unitStringThe item unit of measure.
discountNumberThe item discount percentage(%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.
taxObjectThe tax applied to the item line. If not present the default tax is applied to the item.
nameStringThe tax name to be used on this item line. If not found the default tax is applied to the line item.
tax_exemption_reasonStringUsed when updating a document and removing all tax exempt items. The code M00 means ‘Without tax exemption’.
load_siteStringThe starting point of this guide.
delivery_siteStringThe ending point of this guide.

Example Request Body

{
  "shipping": {
    "date": "03/12/2017",
    "due_date": "03/12/2017",
    "loaded_at": "02/12/2017 19:00:00",
    "license_plate": "11-AA-22",
    "address_from": {
      "detail": "Rua 5",
      "city": "Lisboa",
      "postal_code": "1000-555",
      "country": "Portugal"
    },
    "address_to": {
      "detail": "Avenida 10",
      "city": "Porto",
      "postal_code": "2000-555",
      "country": "Portugal"
    },
    "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"
        }
      }
    ],
    "tax_exemption_reason": "M00",
    "load_site": "Lisbon, Portugal",
    "delivery_site": "Madrid, Spain"
  }
}

Responses

201SUCCESS
Guide was created successfully.
Guides Get
401ACCESS DENIED
The API Key parameter is missing or is incorrectly entered.
(Empty Response)
422UNPROCESSABLE ENTITY
Some parameters were incorrect.
(Empty Response)

Example Success Body Response

{
  "shipping": {
    "id": 541797,
    "status": "final",
    "archived": false,
    "type": "Shipping",
    "sequence_number": "1/D",
    "inverted_sequence_number": "D/1",
    "atcud": "ABCD1234-28",
    "date": "13/07/2017",
    "due_date": "foo",
    "reference": "foo",
    "observations": "foo",
    "retention": "foo",
    "permalink": "https://www.app.invoicexpress.com/documents/541797d75bbee48911934cbd4a4294946a324295f52b08",
    "saft_hash": "vaDf",
    "sum": 1,
    "discount": 0,
    "before_taxes": 1,
    "taxes": 0.07,
    "total": 1.07,
    "currency": "Euro",
    "address_from": {
      "country": "Portugal",
      "postal_code": "1050-083",
      "detail": "Avenida Duque D'Avila, 46 - 3ºA",
      "city": "Lisboa"
    },
    "address_to": {
      "country": "Portugal",
      "postal_code": "4000-327",
      "detail": "Avenida dos Aliados",
      "city": "Porto"
    },
    "client": {
      "id": 1310176,
      "name": "John",
      "country": "Portugal"
    },
    "items": [
      {
        "name": "iPhone",
        "description": "foo",
        "unit_price": "1.0",
        "unit": "foo",
        "quantity": "1.0",
        "tax": {
          "id": 31597,
          "name": "IVA7",
          "value": 7
        },
        "discount": 0,
        "subtotal": 1,
        "tax_amount": 0.07,
        "discount_amount": 0,
        "total": 1.07
      }
    ],
    "sequence_id": "12345",
    "tax_exemption": "M01",
    "at_doc_code_id": "999",
    "license_plate": "11-AA-22"
  }
}