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

Updates a quote, proforma or fees_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?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"quote":{"date":"3/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","auto_add_related_document":"0"}}'

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 = "{\"quote\":{\"date\":\"3/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\",\"auto_add_related_document\":\"0\"}}"

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({ quote:
   { date: '3/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',
     auto_add_related_document: '0' } }));
req.end();

Python

import http.client

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

payload = "{\"quote\":{\"date\":\"3/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\",\"auto_add_related_document\":\"0\"}}"

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 => "{\"quote\":{\"date\":\"3/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\",\"auto_add_related_document\":\"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;
}

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("{\"quote\":{\"date\":\"3/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\",\"auto_add_related_document\":\"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))

}

Query Parameters

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

Request Body

Name	Type	Required	Description
quote	Object	Required	Estimate data to be created
date	String	Required	The estimate 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 estimate 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 estimate purchase order reference field.
observations	String		Estimate observations, these will be printed with the estimate.
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 estimate. 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 estimate’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 estimated 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 estimate. This option is only available for Portuguese Accounts. You must have the feature enabled on your account first.
auto_add_related_document	Integer		Send invoice to client after payment. This option is only available for accounts with payment services configurated. Must be a number equal to either 1 or 0.
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

{
  "quote": {
    "date": "3/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",
    "auto_add_related_document": "0",
    "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)