API-v2

Application Programming Interface

InvoiceXpress Documentation



Change State


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

Changes the state of a shipping guide, transport guide or devolution guide.

Possible state transitions:

From To Event
draft final finalized
draft deleted deleted
final 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 '{"shipping":{"state":"finalized","message":"Wrong shipping 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 = "{\"shipping\":{\"state\":\"finalized\",\"message\":\"Wrong shipping 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({ shipping: { state: 'finalized', message: 'Wrong shipping totals.' } }));
req.end();

Python

import http.client

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

payload = "{\"shipping\":{\"state\":\"finalized\",\"message\":\"Wrong shipping 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 => "{\"shipping\":{\"state\":\"finalized\",\"message\":\"Wrong shipping 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("{\"shipping\":{\"state\":\"finalized\",\"message\":\"Wrong shipping 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: shippings, transports or devolutions. shippings
document-id Integer Required ID of the document to change state.. 42

Request Body

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

Example Request Body

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

Responses

200 SUCCESS
Document changed state successfully.
Guides 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

{
  "shipping": {
    "id": 541797,
    "status": "final",
    "archived": false,
    "type": "Shipping",
    "sequence_number": "1/D",
    "inverted_sequence_number": "D/1",
    "date": "13/07/2017",
    "due_date": "foo",
    "reference": "foo",
    "observations": "foo",
    "retention": "foo",
    "permalink": "https://www.app.invoicexpress.com/documents/541797d75bbee48911934cbd4a4294946a324295f52b08",
    "saft_hash": "vaDf",
    "sum": 1,
    "discount": 0,
    "before_taxes": 1,
    "taxes": 0.07,
    "total": 1.07,
    "currency": "Euro",
    "address_from": {
      "country": "Portugal",
      "postal_code": "1050-083",
      "detail": "Avenida Duque D'Avila, 46 - 3ºA",
      "city": "Lisboa"
    },
    "address_to": {
      "country": "Portugal",
      "postal_code": "4000-327",
      "detail": "Avenida dos Aliados",
      "city": "Porto"
    },
    "client": {
      "id": 1310176,
      "name": "John",
      "country": "Portugal"
    },
    "items": [
      {
        "name": "iPhone",
        "description": "foo",
        "unit_price": "1.0",
        "unit": "foo",
        "quantity": "1.0",
        "tax": {
          "id": 31597,
          "name": "IVA7",
          "value": 7
        },
        "discount": 0,
        "subtotal": 1,
        "tax_amount": 0.07,
        "discount_amount": 0,
        "total": 1.07
      }
    ],
    "sequence_id": "12345",
    "tax_exemption": "M01",
    "at_doc_code_id": "999",
    "license_plate": "11-AA-22"
  }
}
Livro de Reclamação