PUT /:document-type/:document-id.json
Updates an invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.
Creating new clients or items along with the invoice
This method also allows to create a new client and/or new items in the same request with the following behavior:
- If the client name does not exist a new one is created.
- If items do not exist with the given names, new ones will be created.
- If item name already exists, the item is updated with the new values.
Taxes
Regarding item taxes, if the tax name is not found, 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?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{"invoice":{"date":"03/12/2017","due_date":"03/12/2017","reference":"999","observations":"Observations","retention":"0","tax_exemption":"M01","sequence_id":"12345","manual_sequence_number":"1","client":{"name":"Client Name","code":"A1","email":"foo@bar.com","address":"Saldanha","city":"Lisbon","postal_code":"1050-555","country":"Portugal","fiscal_id":"508000000","website":"www.website.com","phone":"910000000","fax":"210000000","observations":"Observations"},"items":[{"name":"Item Name","description":"Item Description","unit_price":"100","quantity":"5","unit":"service","discount":"50","tax":{"name":"IVA23"}}],"mb_reference":"0","owner_invoice_id":"12345","tax_exemption_reason":"M00"}}'Ruby
require 'uri'
require 'net/http'
url = URI("https://account_name.app.invoicexpress.com/:document-type/:document-id.json?document-type=invoices&document-id=1&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 = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}"
response = http.request(request)
puts response.read_bodyNode
var http = require("https");
var options = {
"method": "PUT",
"hostname": "account_name.app.invoicexpress.com",
"port": null,
"path": "/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE",
"headers": {
"accept": "application/json",
"content-type": "application/json"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ invoice:
{ date: '03/12/2017',
due_date: '03/12/2017',
reference: '999',
observations: 'Observations',
retention: '0',
tax_exemption: 'M01',
sequence_id: '12345',
manual_sequence_number: '1',
client:
{ name: 'Client Name',
code: 'A1',
email: 'foo@bar.com',
address: 'Saldanha',
city: 'Lisbon',
postal_code: '1050-555',
country: 'Portugal',
fiscal_id: '508000000',
website: 'www.website.com',
phone: '910000000',
fax: '210000000',
observations: 'Observations' },
items:
[ { name: 'Item Name',
description: 'Item Description',
unit_price: '100',
quantity: '5',
unit: 'service',
discount: '50',
tax: { name: 'IVA23' } } ],
mb_reference: '0',
owner_invoice_id: '12345',
tax_exemption_reason: 'M00' } }));
req.end();Python
import http.client
conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")
payload = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}"
headers = {
'accept': "application/json",
'content-type': "application/json"
}
conn.request("PUT", "/:document-type/:document-id.json?document-type=invoices&document-id=1&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?document-type=invoices&document-id=1&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 => "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}",
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?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE"
payload := strings.NewReader("{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}")
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 create. For example: invoices, simplified_invoices, invoice_receipts, credit_notes or debit_notes. | invoices |
document-id | Integer | Required | ID of the document to be updated | 1 |
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
invoice | Object | Required | Invoice data to be created |
date | String | Required | The invoice date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date. |
due_date | String | Required | The invoice due date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date. |
reference | String | The invoice purchase order reference field. | |
observations | String | Invoice observations, these will be printed with the invoice. | |
retention | String | Withholding tax percentage (%). Must be a number between 0 and 99.99. | |
tax_exemption | String | Depends | Portuguese IVA exemption code. Required for portuguese accounts on invoices with IVA exempt items (0%). Refer to the Appendix for the complete list of “IVA Exemption Codes”. |
sequence_id | String | Id of the sequence you want to use with this invoice. If missing, the default sequence will be used. | |
manual_sequence_number | String | Depends | Required for non portuguese accounts with manual sequence numbering. |
client | Object | Required | |
name | String | Required | The invoice’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored. |
code | String | Required | The client’s unique code. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored. |
email | String | Client email address. Must be a valid email address ex: foo@bar.com | |
address | String | Client company address. | |
city | String | Client’s city. | |
postal_code | String | Client’s postal code for it’s company address. | |
country | String | Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the Appendix of this Documentation. | |
fiscal_id | String | The client fiscal ID (Número de Contribuinte) | |
website | String | The client web address | |
phone | String | The client phone number | |
fax | String | The client fax number | |
observations | String | The client default observations. This is added to the observations field of all the invoices sent to this client. | |
items | Array | Required | An array of invoice items. If items with the given names do not exist, they are created. If an item already exists, it is updated with the new values. At least one is required. |
name | String | Required | Name of the item. Must be unique. |
description | String | Required | Item’s description |
unit_price | Number | Required | Item’s unit price. Must be a number equal or greater than 0.0. |
quantity | Number | Required | Quantity. Must be a number equal or greater than 0. |
unit | String | The item unit of measure | |
discount | Number | The item discount percentage(%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive. | |
tax | Object | The tax applied to the item line. If not present the default tax is applied to the item | |
name | String | The tax name to be used on this item line. If not found the default tax is applied to the line item | |
mb_reference | String | Generates a Multibanco Reference after you finalize your invoice. This option is only available for Portuguese Accounts. You must have the feature enabled on your account first. | |
owner_invoice_id | Integer | The (owner) invoice associated to this document. This option is only available for credit_notes or debit_notes. You can also send the (owner) guide id when creating an invoice to associate an invoice to a guide. | |
tax_exemption_reason | String | Used when updating a document and removing all tax exempt items. The code M00 means ‘Without tax exemption’. | |
currency_code | String | If your plan as multicurrency, you can issue invoices in another currency than your account’s default currency. The currency_code should be one of the following ISO 4217 currency codes. | |
rate | String | When sending a currency_code you can specify its’ rate. |
Example Request Body
{
"invoice": {
"date": "03/12/2017",
"due_date": "03/12/2017",
"reference": "999",
"observations": "Observations",
"retention": "0",
"tax_exemption": "M01",
"sequence_id": "12345",
"manual_sequence_number": "1",
"client": {
"name": "Client Name",
"code": "A1",
"email": "foo@bar.com",
"address": "Saldanha",
"city": "Lisbon",
"postal_code": "1050-555",
"country": "Portugal",
"fiscal_id": "508000000",
"website": "www.website.com",
"phone": "910000000",
"fax": "210000000",
"observations": "Observations"
},
"items": [
{
"name": "Item Name",
"description": "Item Description",
"unit_price": "100",
"quantity": "5",
"unit": "service",
"discount": "50",
"tax": {
"name": "IVA23"
}
}
],
"mb_reference": "0",
"owner_invoice_id": "12345",
"tax_exemption_reason": "M00",
"currency_code": "USD",
"rate": "1.23565"
}
}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) |
