API-v2

Application Programming Interface

InvoiceXpress Documentation



Change State


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

Changes the state of a quote, proforma or fees_note.

Possible state transitions:

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

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

Example Request

curl

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

Ruby

require 'uri'
require 'net/http'

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

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/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({ quote: { state: 'finalized', message: 'Wrong quote totals.' } }));
req.end();

Python

import http.client

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

payload = "{\"quote\":{\"state\":\"finalized\",\"message\":\"Wrong quote totals.\"}}"

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

conn.request("PUT", "/:document-type/: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

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type/: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 => "{\"quote\":{\"state\":\"finalized\",\"message\":\"Wrong quote 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;
}

Go

package main

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

func main() {

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

    payload := strings.NewReader("{\"quote\":{\"state\":\"finalized\",\"message\":\"Wrong quote 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-type String Required The type of document you wish to change state: quotes, proformas or fees_notes. quotes
document-id Integer Required ID of the document to change state.. 42

Request Body

Name Type Required Description
quote Object Required Document state transition.
state String Required State which the quote will be changed to. Options are: finalized, deleted, canceled, accepted, refused.
message String Depends Reason for cancelling the quote. Only required when state is “canceled”, otherwise ignored.

Example Request Body

{
  "quote": {
    "state": "finalized",
    "message": "Wrong quote totals."
  }
}

Responses

200 SUCCESS
Document changed state successfully.
Estimates Get
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)

Example Success Body Response

{
  "quote": {
    "id": 541791,
    "status": "final",
    "archived": false,
    "type": "Quote",
    "sequence_number": "1/A",
    "inverted_sequence_number": "A/1",
    "date": "12/06/2017",
    "due_date": "12/06/2017",
    "reference": "foo",
    "observations": "foo",
    "retention": "foo",
    "permalink": "https://www.app.invoicexpress.com/documents/541791f16ae45a73b703c684a221ef198c10020f3d56a1",
    "saft_hash": "NfTN",
    "sum": 10,
    "discount": 0,
    "before_taxes": 10,
    "taxes": 2.3,
    "total": 12.3,
    "currency": "Euro",
    "client": {
      "id": 1310176,
      "name": "John",
      "country": "Portugal"
    },
    "items": [
      {
        "name": "iPhone",
        "description": "foo",
        "unit_price": "10.0",
        "unit": "foo",
        "quantity": "1.0",
        "tax": {
          "id": 31567,
          "name": "IVA23",
          "value": 23
        },
        "discount": 0,
        "subtotal": 10,
        "tax_amount": 2.3,
        "discount_amount": 0,
        "total": 12.3
      }
    ],
    "sequence_id": "12345",
    "tax_exemption": "M01"
  }
}
Livro de Reclamação