InvoiceXpress API

Purchase Orders

Send by Email

PUT /purchase_orders/:document-id/email-document.json

Sends a purchase order by email.

Example Body

{
  "message": {
    "client": {
      "email": "someone@example.com",
      "save": "0"
    },
    "subject": "Invoice from company",
    "body": "This is where the email body goes",
    "cc": "cc.client@company.com",
    "bcc": "bcc.client@company.com"
  }
}

Example Request

Format:
curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/purchase_orders/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"message":{"client":{"email":"someone@example.com","save":"0"},"subject":"Invoice from company","body":"This is where the email body goes","cc":"cc.client@company.com","bcc":"bcc.client@company.com","logo":"0"}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/purchase_orders/:document-id/email-document.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 = "{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/purchase_orders/:document-id/email-document.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({ message: 
   { client: { email: 'someone@example.com', save: '0' },
     subject: 'Invoice from company',
     body: 'This is where the email body goes',
     cc: 'cc.client@company.com',
     bcc: 'bcc.client@company.com',
     logo: '0' } }));
req.end();
import http.client

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

payload = "{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}"

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

conn.request("PUT", "/purchase_orders/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

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

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/purchase_orders/:document-id/email-document.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 => "{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}",
  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;
}
package main

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

func main() {

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

	payload := strings.NewReader("{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}")

	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))

}

Path Parameters

Name Type Required Description Example
document-id Integer Required

ID of the purchase order to send by email.

42

Request Body

Name Type Required Description Example
message Object Required

Email data.

{
  "message": {
  "message": { ... }
Object

Email data.

    "client": {
    "client": { ... }
Object

Client email and save options.

      "email": "someone@example.com",
String

[Required] Document will be sent to this email address. Must be a valid email address ex: foo@bar.com

      "save": "0"
String

[Required] Saves this email as your client email address. (0 – Does not save the client’s email. 1 – Saves / Updates the client’s email).

    },
    "subject": "Invoice from company",
String

[Optional] The subject of the email.

    "body": "This is where the email body goes",
String

[Optional] The body of the email.

    "cc": "cc.client@company.com",
String

[Optional] Email CC field. Must be a valid email address ex: foo@bar.com

    "bcc": "bcc.client@company.com",
String

[Optional] Email BCC field. Must be a valid email address ex: foo@bar.com

    "logo": "0"
String

[Optional] Send email with logo. Defaults to 0. Only available in some plans. It’s ignored if the account doesn’t have the logo configured. Not available for trial accounts. (0 - Send email without logo. 1 - Send email with logo )

  }
}

Responses

200 Success

The email was sent 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 sent were incorrect.

(Empty Response)

Generate PDF

GET /api/pdf/:document-id.json

Returns the url of the PDF for the specified document. This is an asynchronous operation, which means the PDF file may not be ready immediately.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&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::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "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.end();
import http.client

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

headers = { 'accept': "application/json" }

conn.request("GET", "/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE", headers=headers)

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

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&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 => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

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

curl_close($curl);

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

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

func main() {

	url := "https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "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-id Integer Required

The document to convert to PDF.

42

Query Parameters

Name Type Required Description Example
second_copy Boolean Optional

Set value to true to generate copy of original document.

false

Responses

200 Success

The request has been successfully processed.

Purchase Orders Generate pdf
{
  "output": {
  "output": { ... }
Object
    "pdfUrl": "https://sum.url"
String
  }
}
202 Accepted

The request will be processed. You need to keep requesting until you get a response with HTTP status code 200.

(Empty Response)
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

No document matches the supplied :document-id.

(Empty Response)
406 Not Acceptable

The :document-id provided is in an invalid state.

(Empty Response)

Get

GET /purchase_orders/:document-id.json

Returns a specific purchase order.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/purchase_orders/:document-id.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
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::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/purchase_orders/:document-id.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "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.end();
import http.client

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

headers = { 'accept': "application/json" }

conn.request("GET", "/purchase_orders/:document-id.json?api_key=YOUR%20API%20KEY%20HERE", headers=headers)

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

print(data.decode("utf-8"))
<?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 => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

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

curl_close($curl);

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

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "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-id Integer Required

The requested purchase order id.

42

Responses

200 Success

The purchase order was returned successfully.

Purchase Orders Get
{
  "purchase_order": {
  "purchase_order": { ... }
Object
    "id": 541790,
Integer
    "status": "completed",
String
    "archived": false,
Boolean
    "type": "PurchaseOrder",
String
    "sequence_number": "1/A",
String
    "inverted_sequence_number": "A/1",
String
    "date": "12/06/2017",
String
    "due_date": "12/06/2017",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/5417901530e3995dac359aacc1a821976099c2c7b3c9b6",
String
    "saft_hash": "TO4M",
String
    "sum": 10,
Integer
    "discount": 0,
Integer
    "before_taxes": 10,
Integer
    "taxes": 2.3,
Number
    "total": 12.3,
Number
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 1310176,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": "iPhone",
String
        "description": "foo",
String
        "unit_price": "10.0",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 31567,
Integer
          "name": "IVA23",
String
          "value": 23
Integer
        },
        "discount": 0,
Integer
        "subtotal": 10,
Integer
        "tax_amount": 2.3,
Number
        "discount_amount": 0,
Integer
        "total": 12.3
Number
      }
    ]
    "sequence_id": "12345",
String
    "tax_exemption": "M01"
String
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

No purchase order matches the supplied :document-id.

(Empty Response)

List All

GET /purchase_orders.json

Returns all your purchase orders. You can filter your purchase orders by passing parameters in the query string.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/purchase_orders.json?text=foo&type=PurchaseOrder&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/purchase_orders.json?text=foo&type=PurchaseOrder&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&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::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/purchase_orders.json?text=foo&type=PurchaseOrder&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "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.end();
import http.client

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

headers = { 'accept': "application/json" }

conn.request("GET", "/purchase_orders.json?text=foo&type=PurchaseOrder&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE", headers=headers)

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

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/purchase_orders.json?text=foo&type=PurchaseOrder&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&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 => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

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

curl_close($curl);

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

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

func main() {

	url := "https://account_name.app.invoicexpress.com/purchase_orders.json?text=foo&type=PurchaseOrder&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "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
text String Optional

Search for purchase order, client or item details.

foo
type String Required

Possible value: PurchaseOrder.

PurchaseOrder
status[] String Required

Possible values: draft, sent, accepted, completed, refused, canceled or second_copy.

sent
date[from] String Optional

Date in format dd/mm/yyyy. Ex: 30/09/2017

30%2F09%2F2017
date[to] String Optional

Date in format dd/mm/yyyy. Ex: 31/10/2017

31%2F10%2F2017
due_date[from] String Optional

Date in format dd/mm/yyyy. Ex: 30/09/2017

30%2F09%2F2017
due_date[to] String Optional

Date in format dd/mm/yyyy. Ex: 31/10/2017

31%2F10%2F2017
total_before_taxes[from] Number Optional

Minimum document amount. Ex: 100.00

100.00
total_before_taxes[to] Number Optional

Maximum document amount. Ex: 500.00

500.00
non_archived Boolean Required

Possible values: true or false.

true
archived Boolean Optional

Possible values: true or false.

false
page Integer Optional

You can ask for a specific page of invoices. Defaults to 1.

1
per_page Integer Optional

You can specify how many results you want to fetch. Defaults to 10 or value defined in account settings (10, 20 or 30).

30

Responses

200 Success

Purchase orders were returned successfully.

Purchase Orders List all
{
  purchase_orders: [
Array

List of purchase orders.

    {
    { ... }
Object

Purchase Order Object

      "id": 541790,
Integer
      "status": "completed",
String
      "archived": false,
Boolean
      "type": "PurchaseOrder",
String
      "sequence_number": "1/A",
String
      "inverted_sequence_number": "A/1",
String
      "date": "12/06/2017",
String
      "due_date": "12/06/2017",
String
      "reference": "foo",
String
      "observations": "foo",
String
      "retention": "foo",
String
      "permalink": "https://www.app.invoicexpress.com/documents/5417901530e3995dac359aacc1a821976099c2c7b3c9b6",
String
      "saft_hash": "TO4M",
String
      "sum": 10,
Integer
      "discount": 0,
Integer
      "before_taxes": 10,
Integer
      "taxes": 2.3,
Number
      "total": 12.3,
Number
      "currency": "Euro",
String
      "client": {
      "client": { ... }
Object
        "id": 1310176,
Integer
        "name": "John",
String
        "country": "Portugal"
String
      },
      items: [
Array
        {
        { ... }
Object

Items

          "name": "iPhone",
String
          "description": "foo",
String
          "unit_price": "10.0",
String
          "unit": "foo",
String
          "quantity": "1.0",
String
          "tax": {
          "tax": { ... }
Object
            "id": 31567,
Integer
            "name": "IVA23",
String
            "value": 23
Integer
          },
          "discount": 0,
Integer
          "subtotal": 10,
Integer
          "tax_amount": 2.3,
Number
          "discount_amount": 0,
Integer
          "total": 12.3
Number
        }
      ]
      "sequence_id": "12345",
String
      "tax_exemption": "M01"
String
    }
  ]
  "pagination": {
  "pagination": { ... }
Object

Pagination info.

    "total_entries": 6,
Integer
    "current_page": 1,
Integer
    "total_pages": 1,
Integer
    "per_page": 10
Integer
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)

Create

POST /purchase_orders.json

Creates a new 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, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the purchase order contains exempt items (IVA 0%).

Example URL

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

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

Example Body

{
  "purchase_order": {
    "date": "07/05/2017",
    "due_date": "08/05/2017",
    "loaded_at": "07/05/2017",
    "delivery_site": "Lisboa",
    "client": {
      "name": "John",
      "code": "100"
    },
    "items": [
        {
          "name": "Product A",
          "description": "Cleaning product",
          "unit_price": "10.0",
          "quantity": "1.0"
        }
      ]
   }
}

Example Request

Format:
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 '{"purchase_order":{"date":"03/12/2017","due_date":"03/12/2017","loaded_at": "07/05/2017","delivery_site": "Lisboa","client":{"name":"Client Name","code":"A1"},"items":[{"name":"Item Name","description":"Item Description","unit_price":"100","quantity":"5"}]}}'
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 = "{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\": \"07/05/2017\",\"delivery_site\": \"Lisboa\",\"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
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({ purchase_order: 
   { date: '03/12/2017',
     due_date: '03/12/2017',
     loaded_at: '07/05/2017',
     delivery_site: 'Lisboa',
     client: 
      { name: 'Client Name',
        code: 'A1'},
     items: 
      [ { name: 'Item Name',
          description: 'Item Description',
          unit_price: '100',
          quantity: '5' } ],
    }}));
req.end();
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\": \"07/05/2017\",\"delivery_site\": \"Lisboa\",\"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

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 => "{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\": \"07/05/2017\",\"delivery_site\": \"Lisboa\",\"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;
}
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("{\"purchase_order\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"loaded_at\": \"07/05/2017\",\"delivery_site\": \"Lisboa\",\"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))
}

Request Body

Name Type Required Description Example
purchase_order Object Required

Purchase order data to be created.

{
  "purchase_order": {
  "purchase_order": { ... }
Object

The purchase order data.

    "date": "03/12/2017",
String

[Required] The document date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "due_date": "03/12/2017",
String

[Required] The document due date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "loaded_at": "03/12/2017",
String

[Required] The delivery date of the purchase order. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "delivery_site": "Lisboa",
String

[Optional] The delivery address of the purchase order.

    "observations": "Observations",
String

[Optional] Document observations, these will be printed with the invoice.

    "client": {
    "client": { ... }
Object

[Required] Client details.

      "name": "Client Name",
String

[Required] The document’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.

      "code": "A1",
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": "foo@bar.com",
String

[Optional] Client email address. Must be a valid email address ex: foo@bar.com

      "address": "Saldanha",
String

[Optional] Client company address.

      "city": "Lisbon",
String

[Optional] Client’s city.

      "postal_code": "1050-555",
String

[Optional] Client’s postal code for it’s company address.

      "country": "Portugal",
String

[Optional] 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": "508000000",
String

[Optional] Client's fiscal ID (Número de Contribuinte).

      "website": "www.website.com",
String

[Optional] Client' website.

      "phone": "910000000",
String

[Optional] Client's phone number.

      "fax": "210000000",
String

[Optional] Client's fax number.

      "observations": "Observations"
String

[Optional] Client's default observations. This is added to the observations field of all the invoices sent to this client.

    },
    items: [
Array

[Required] An array of line 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.

      {
      { ... }
Object

Item Object

        "name": "Item Name",
String

[Required] Name of the item. Must be unique.

        "description": "Item Description",
String

[Required] Item’s description.

        "unit_price": "100",
String

[Required] Item’s unit price. Must be a number equal or greater than 0.0.

        "quantity": "5",
String

[Required] Quantity. Must be a number equal or greater than 0.

        "unit": "service",
String

[Optional] The unit of measure. Ex: hour, day, month, unit , service or other.

        "discount": "50",
String

[Optional] The item discount percentage (%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.

        "tax": {
        "tax": { ... }
Object

[Optional] The tax applied to the line item. If not present the default tax is applied to the line item.

          "name": "IVA23"
String

[Optional] The tax name to be used on this line item. If not found the default tax is applied to the line item.

        }
      }
    ]
    "tax_exemption_reason": "M00"
String

[Optional] Used when updating a document and removing all tax exempt items. The code M00 means 'Without tax exemption'.

  }
}

Responses

201 Success

Purchase order was created successfully.

Purchase Orders Get
{
  "purchase_order": {
  "purchase_order": { ... }
Object
    "id": 541790,
Integer
    "status": "completed",
String
    "archived": false,
Boolean
    "type": "PurchaseOrder",
String
    "sequence_number": "1/A",
String
    "inverted_sequence_number": "A/1",
String
    "date": "12/06/2017",
String
    "due_date": "12/06/2017",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/5417901530e3995dac359aacc1a821976099c2c7b3c9b6",
String
    "saft_hash": "TO4M",
String
    "sum": 10,
Integer
    "discount": 0,
Integer
    "before_taxes": 10,
Integer
    "taxes": 2.3,
Number
    "total": 12.3,
Number
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 1310176,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": "iPhone",
String
        "description": "foo",
String
        "unit_price": "10.0",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 31567,
Integer
          "name": "IVA23",
String
          "value": 23
Integer
        },
        "discount": 0,
Integer
        "subtotal": 10,
Integer
        "tax_amount": 2.3,
Number
        "discount_amount": 0,
Integer
        "total": 12.3
Number
      }
    ]
    "sequence_id": "12345",
String
    "tax_exemption": "M01"
String
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
422 Unprocessable Entity

Some parameters were incorrect.

(Empty Response)

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 Body

{
  "purchase_order": {
    "date": "07/05/2017",
    "due_date": "08/05/2017",
    "loaded_at": "07/05/2017",
    "delivery_site": "Lisboa",
    "client": {
      "name": "John",
      "code": "100"
    },
    "items": [
        {
          "name": "Product A",
          "description": "Cleaning product",
          "unit_price": "10.0",
          "quantity": "1.0"
        }
      ]
   }
}

Example Request

Format:
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"}}]}}'
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
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();
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

$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;
}
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))

}

Path Parameters

Name Type Required Description Example
document-id Integer Required

ID of the document to update.

1

Request Body

Name Type Required Description Example
purchase_order Object Required

Purchase order data to be updated.

{
  "purchase_order": {
  "purchase_order": { ... }
Object

The purchase order data.

    "date": "03/12/2017",
String

[Required] The document date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "due_date": "03/12/2017",
String

[Required] The document due date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "loaded_at": "03/12/2017",
String

[Required] The delivery date of the purchase order. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "delivery_site": "Lisboa",
String

[Optional] The delivery address of the purchase order.

    "observations": "Observations",
String

[Optional] Document observations, these will be printed with the invoice.

    "client": {
    "client": { ... }
Object

[Required] Client details.

      "name": "Client Name",
String

[Required] The document’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.

      "code": "A1",
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": "foo@bar.com",
String

[Optional] Client email address. Must be a valid email address ex: foo@bar.com

      "address": "Saldanha",
String

[Optional] Client company address.

      "city": "Lisbon",
String

[Optional] Client’s city.

      "postal_code": "1050-555",
String

[Optional] Client’s postal code for it’s company address.

      "country": "Portugal",
String

[Optional] 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": "508000000",
String

[Optional] Client's fiscal ID (Número de Contribuinte).

      "website": "www.website.com",
String

[Optional] Client' website.

      "phone": "910000000",
String

[Optional] Client's phone number.

      "fax": "210000000",
String

[Optional] Client's fax number.

      "observations": "Observations"
String

[Optional] Client's default observations. This is added to the observations field of all the invoices sent to this client.

    },
    items: [
Array

[Required] An array of line 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.

      {
      { ... }
Object

Item Object

        "name": "Item Name",
String

[Required] Name of the item. Must be unique.

        "description": "Item Description",
String

[Required] Item’s description.

        "unit_price": "100",
String

[Required] Item’s unit price. Must be a number equal or greater than 0.0.

        "quantity": "5",
String

[Required] Quantity. Must be a number equal or greater than 0.

        "unit": "service",
String

[Optional] The unit of measure. Ex: hour, day, month, unit , service or other.

        "discount": "50",
String

[Optional] The item discount percentage (%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.

        "tax": {
        "tax": { ... }
Object

[Optional] The tax applied to the line item. If not present the default tax is applied to the line item.

          "name": "IVA23"
String

[Optional] The tax name to be used on this line item. If not found the default tax is applied to the line item.

        }
      }
    ]
    "tax_exemption_reason": "M00"
String

[Optional] Used when updating a document and removing all tax exempt items. The code M00 means 'Without tax exemption'.

  }
}

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 sent were incorrect.

(Empty Response)

Change State

PUT /purchase_orders/:document-id/change-state.json

Changes the state of a purchase order.

Possible state transitions:

From To Event
draft final finalized
draft deleted deleted
final accepted accept
final refused refuse
final canceled canceled
accepted refused refuse
accepted completed complete
refused accepted accept
accepted canceled canceled
refused canceled canceled

Any other transitions will fail.
When cancelling a document you must specify a reason.

Example Body

{
  "purchase_order": {
    "state": "finalized"
  }
}

Example Request

Format:
curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/purchase_orders/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"purchase_order":{"state":"finalized","message":"Wrong purchase order totals."}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/purchase_orders/:document-id/change-state.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\":{\"state\":\"finalized\",\"message\":\"Wrong purchase order totals.\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/purchase_orders/:document-id/change-state.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: { state: 'finalized', message: 'Wrong purchase order totals.' } }));
req.end();
import http.client

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

payload = "{\"purchase_order\":{\"state\":\"finalized\",\"message\":\"Wrong purchase order totals.\"}}"

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

conn.request("PUT", "/purchase_orders/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

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

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/purchase_orders/:document-id/change-state.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\":{\"state\":\"finalized\",\"message\":\"Wrong purchase order totals.\"}}",
  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;
}
package main

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

func main() {

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

	payload := strings.NewReader("{\"purchase_order\":{\"state\":\"finalized\",\"message\":\"Wrong purchase order totals.\"}}")

	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))

}

Path Parameters

Name Type Required Description Example
document-id Integer Required

ID of the document to change state.

42

Request Body

Name Type Required Description Example
purchase_order Object Required

Document state transition.

{
  "purchase_order": {
  "purchase_order": { ... }
Object

Purchase order state transition.

    "state": "finalized",
String

[Required] The state the document will be in after the call to this endpoint. Options: finalized, deleted, canceled, accept, refuse or complete.

    "message": "Wrong purchase order totals."
String

[Required/Optional] Reason for cancelling the document. Only required when state is canceled.

  }
}

Responses

200 Success

Document changed state successfully.

Purchase Orders Get
{
  "purchase_order": {
  "purchase_order": { ... }
Object
    "id": 541790,
Integer
    "status": "completed",
String
    "archived": false,
Boolean
    "type": "PurchaseOrder",
String
    "sequence_number": "1/A",
String
    "inverted_sequence_number": "A/1",
String
    "date": "12/06/2017",
String
    "due_date": "12/06/2017",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/5417901530e3995dac359aacc1a821976099c2c7b3c9b6",
String
    "saft_hash": "TO4M",
String
    "sum": 10,
Integer
    "discount": 0,
Integer
    "before_taxes": 10,
Integer
    "taxes": 2.3,
Number
    "total": 12.3,
Number
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 1310176,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": "iPhone",
String
        "description": "foo",
String
        "unit_price": "10.0",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 31567,
Integer
          "name": "IVA23",
String
          "value": 23
Integer
        },
        "discount": 0,
Integer
        "subtotal": 10,
Integer
        "tax_amount": 2.3,
Number
        "discount_amount": 0,
Integer
        "total": 12.3
Number
      }
    ]
    "sequence_id": "12345",
String
    "tax_exemption": "M01"
String
  }
}
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 sent were incorrect.

(Empty Response)