API-v2

Application Programming Interface

InvoiceXpress Documentation



Update


PUT /purchase_orders/:document-id.json

Updates a purchase order.

Creating new clients or items along with the purchase order

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/purchase_orders/:document-id.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"purchase_order":{"date":"03/12/2017","due_date":"03/12/2017","loaded_at":"03/12/2017","delivery_site":"Lisboa","observations":"Observations","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/purchase_orders/: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 = "{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"03/12/2017\",\"delivery_site\":\"Lisboa\",\"observations\":\"Observations\",\"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": "/purchase_orders/: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({ purchase_order:
   { date: '03/12/2017',
     due_date: '03/12/2017',
     loaded_at: '03/12/2017',
     delivery_site: 'Lisboa',
     observations: 'Observations',
     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 = "{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"03/12/2017\",\"delivery_site\":\"Lisboa\",\"observations\":\"Observations\",\"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", "/purchase_orders/: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/purchase_orders/: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 => "{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"03/12/2017\",\"delivery_site\":\"Lisboa\",\"observations\":\"Observations\",\"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/purchase_orders/:document-id.json?api_key=YOUR%20API%20KEY%20HERE"

    payload := strings.NewReader("{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\":\"03/12/2017\",\"delivery_site\":\"Lisboa\",\"observations\":\"Observations\",\"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-id Integer Required ID of the document to be updated 1

Request Body

Name Type Required Description
purchase_order Object Required Purchase order data to be created
date String Required Purchase Order date. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.
due_date String Required Purchase Order due date. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.
loaded_at String Required Purchase Order loaded at date. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.
delivery_site String Purchase Order observations, these will be printed with the document.
observations String Purchase Order observations, these will be printed with the document.
client Object Required Client data.
name String Required Supplier name. If the supplier doesn’t exist a new one is created. If it exists the remaining supplier fields will be ignored.
code String Supplier code.
email String Supplier email.
address String Supplier address, normally used for a company address.
city String Supplier city.
postal_code String Supplier postal code, normally used for a company postal code.
country String Supplier country.
fiscal_id String Supplier fiscal id.
website String Supplier website.
phone String Supplier phone number.
fax String Supplier fax number.
observations String Supplier observations.
items Array Required An array of purchase order 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.
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’.

Example Request Body

{
  "purchase_order": {
    "date": "03/12/2017",
    "due_date": "03/12/2017",
    "loaded_at": "03/12/2017",
    "delivery_site": "Lisboa",
    "observations": "Observations",
    "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"
  }
}

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