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",
    "atcud": "ABCD1234-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"
  }
}

Possible values for field atcud:

ABCD1234-1 or similar: Unique document identifier to the Tax Authority, when the sequence is registered.
N/D: The document’s sequence is relevant for ATCUD but is not registered in the Tax Authority.
N/A: The document’s sequence is not relevant for ATCUD and is not registered in the Tax Authority.

API-V2

Application Programming Interface