API-v2

Application Programming Interface

InvoiceXpress Documentation



Update


PUT /:document-type/:document-id.json

Updates a 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, no tax will be applied to that item. Be careful when updating the document items, any missing items from the original document will be deleted.

Example Request

curl

curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/:document-type/:document-id.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","license_plate":"99-AA-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"},"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"}}]}}'

Ruby

require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type/:document-id.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::Put.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\",\"license_plate\":\"99-AA-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\"},\"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\"}}]}}"

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

Node

var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type/:document-id.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',
     license_plate: '99-AA-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' },
     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' } } ] } }));
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\",\"license_plate\":\"99-AA-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\"},\"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\"}}]}}"

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

conn.request("PUT", "/:document-type/:document-id.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/:document-id.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 => "PUT",
  CURLOPT_POSTFIELDS => "{\"shipping\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"02/12/2017 19:00:00\",\"license_plate\":\"99-AA-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\"},\"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\"}}]}}",
  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/:document-id.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\",\"license_plate\":\"99-AA-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\"},\"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\"}}]}}")

    req, _ := http.NewRequest("PUT", 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))

}

Query Parameters

Name Type Required Description Example
document-type String Required The type of document you want to update. For example: shippings, transports or devolutions. shippings
document-id Integer Required ID of the document to be updated 1

Request Body

Name Type Required Description
shipping Object Required Guide data to be created
date String Required The 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_date String Required The 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_at String Required The date and time that this guide will be used. Must be greater than or equal to the current date and time.
license_plate String The license plate of the vehicle using this guide.
address_from Object Required The starting point of this guide.
detail String Required The address of the starting point of this guide.
city String Required The city of the starting point of this guide.
postal_code String Required The postal code of the starting point of this guide.
country String Required The country of the starting point of this guide.
address_to Object Required The address of the ending point of this guide.
detail String Required The address of the ending point of this guide.
city String Required The city of the ending point of this guide.
postal_code String Required The postal code of the ending point of this guide.
country String Required The country of the ending point of this guide.
reference String The guide purchase order reference field.
observations String guide observations, these will be printed with the invoice.
retention Number 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 transport-guides 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 guide. 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 Client’s information.
name String Required The guide’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.
tax_exemption_reason String Used when updating a document and removing all tax exempt items. The code M00 means ‘Without tax exemption’.
load_site String The starting point of this guide.
delivery_site String The 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

200 SUCCESS
Document was updated successfully.
(Empty Response)
401 ACCESS DENIED
The API Key parameter is missing or is incorrectly entered.
(Empty Response)
404 NOT FOUND
The supplied :document-id doesn’t match any existing document.
(Empty Response)
422 UNPROCESSABLE ENTITY
Some parameters were incorrect.
(Empty Response)
Livro de Reclamação