|
|
Overview
Before starting to use our API, please refer to the following help topic on how to configure WISEDAT API Server and how to get an API Key.
The implementation of the public API is not included in the BASIC Plan. The support focuses on providing technical assistance for bug fixing and suggestion analysis only. Does not include software development services for implementing it.
- Names, Methods and URLs
- Notes
All requests are preceded by http://{server-ip}:{port} or https://{server-ip}:{port}, depending on the HTTPS configuration of the service.
The content is exchanged in JSON, so all requests must contain the header “Accept: application/json”. If the method of the request is POST or PUT, the header “Content-Type: application/json” is mandatory.
Status
Get
The API status of a given company
Usage
GET/status
Header
Authorization: WDAPI [api-key]
Returned Values
- Success
- Error 400
400 Bad Request – No Authorization property on the request header
Authentication ^
Login
Login on the Wisedat server
Usage
POST/authentication/login
Header
Authorization: WDAPI [ApiKey;User;Password] (encrypted with server’s public RSA key which is received on the status request, and its result converted to a Base64 string)
Returned Values
- Success
- Error 400
400 Bad Request – No Authorization property on the request header
- Error 401
401 Unauthorized – Login failed
Company ^
Get
Information about a given company
Usage
GET/company
Header
Authorization: Bearer {JWT} (The JWT contains the ApiKey that identifies the company)
Returned Values
- Success
200 OK
{
id: string,
name: string,
tax_id: string,
address:{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string,
name: string
}
},
currency:{
id: string,
description: string,
symbol: string,
decimal_cases: int,
}
alt_currency:{
id: string,
description: string,
symbol: string,
decimal_cases: int
}
}
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
Products ^
Get
Get one or a list of products
Usage
GET/products {id,limit,page,modified_since,query,name,description,barcode,brand,model,show_inactive,stock_modified_since}
Parameters
| id (int): |
ID of a product. If this parameter is declared, all others are ignored. |
| limit(int): |
Limit of products per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get products modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get products whose name, description or barcode contain this parameter. |
| name (string): |
Get products whose unique name contains this parameter. |
| description (string): |
Get products whose description contains this parameter. |
| barcode (string): |
Get products whose barcode contains this parameter. |
| brand (string): |
Get products whose brand ID matches this parameter. |
| model (string): |
Get products whose model ID matches this parameter. |
| show_inactive (boolean): |
Show or hide inactive products. The default value is false. |
| stock_modified_since (date): |
Get products with stock modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int, page: int,
number_pages: int,
number_items: int
},
products:
[
{
id: int,
name:string,
description: string,
barcode: string,
image: string,
price: float,
current_stock: float,
type: int,
active: boolean,
tax: {
id: string,
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
},
unit: {
id: string,
description: string
},
model: {
id: string,
description: string
brand: {
id: string,
description: string
}
},
stocks:
[
{
id_warehouse: int,
id_location: int,
id_lot: int,
current_stock: float,
reserved_stock: float
},
(…)
],
categories:
[
{
id: int,
id_parent:int,
name: string,
short_name: string
},
(…)
]
},
(…)
]
}
- Success with ID
200 OK
{
id: int,
name: string,
description: string,
barcode: string,
brief_description: string,
commercial_description: string,
notes: string,
images:
[
string,
(…)
]
price: float,
current_stock: float,
type: int,
net_weight: float,
gross_weight: float,
volume: float,
delivery_time: int,
active: boolean,
tax: {
id: string,
value: float,
description: string.
type: int,
exemption_reason: {
id: string,
description: string
}
},
unit: {
id: string,
description: string
},
model: {
id: string,
description: string
brand: {
id: string,
description: string
}
},
categories:
[
{
id: int,
id_parent: int,
name: string,
short_name: string
},
(…)
],
stocks:
[
{
id_warehouse: int,
id_location: int,
id_lot: int,
current_stock: float,
reserved_stock: float
},
(…)
],
suppliers:
[
{
id: int,
cost_price: float,
unit: {
id: string,
description: string
}
},
(…)
],
main_supplier: {
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
}
}
Images are Base64 encoded strings.
Type can assume two values: 1 (merchandise) and 2 (service).
An inactive product is always returned when searched by ID.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Product from parameter id doesn’t exist
Post
Insert a new product
Usage
POST/products
Header
Authorization: Bearer {JWT}
Body
{
name: string,
description: string,
barcode: string,
price: float,
type: int,
tax: string,
unit: string,
brand: string,
model: string,
warehouse: int,
brief_description: string,
commercial_description: string,
notes: string,
categories: [
(…)
]
}
- Note
– Name, description, price and type are mandatory;
– Name must be unique and contain only alpha-numeric characters;
– Price must be equal or higher than 0;
– Type can only assume 1 (merchandise) or 2 (service);
– Barcode must be unique;
– If tax, unit, or warehouse are not defined, their respective suggested values are used;
– The first category in the list, is considered the main one;
– To associate the product to a brand or model, both fields must be filled with the correct ID’s.
Returned Values
Put
Update an existing product
PUT/product
Header
Authorization: Bearer {JWT}
Body
{
id: int,
description:string,
barcode: string,
price: float,
type: int,
tax: string,
brand: string,
model: string,
warehouse: int,
brief_description: string,
commercial_description: string,
notes: string,
categories: [
suppliers:
[
{
id: int,
cost_price: float,
unit: string
},
(…)
],
main_supplier: int
}
- Note
– Id is mandatory;
– Price and supplier’s cost_price must be equal or higher than 0;
– Type can only assume 1 (merchandise) or 2 (service);
– Barcode must be unique;
– When a list of categories or suppliers is declared, they replace all the current ones. The first category in the list, is considered the main one;
– The main_supplier must be included on suppliers if it’s declared. Otherwise, it must be present on the current list of suppliers;
– If the suppliers’ unit is not indicated, the product’s unit is used. Otherwise, it must be related to the later;
– To update the brand or model, both fields must be filled with the correct ID’s.
Returned Values
- Success
- Error 400
400 Bad Request – A list of errors concerning the validation of
the request is returned
{
errors:
[
string,
(…)
]
}
- Error 404
404 Not Found – The product indicated by the id does not exist
Delete
Delete a product
Usage
DELETE/product?id={id}
Header
Authorization Bearer {JWT}
Returned Values
- Success
- Error 400
- Error 404
404 Not Found – The product indicated by the id does not exist
Categories ^
Get
Get one or a list of categories
Usage
GET/categories{?id,limit,page,modified_since,query,name,parent}
Parameters
| id (int): |
ID of a category. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of categories per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get categories modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get categories whose name, or parent name contain this parameter. |
| name (string): |
Get categories whose name contains this parameter. |
| parent (int/string): |
Get categories whose parent name or ID contains this parameter. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
categories: [
{
id: int, id_parent: int,
name: string,
short_name: string,
image: string
},
(…)
]
}
- Success with ID
Image is a Base64 encoded string.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Category from parameter id doesn’t exist
Post
Insert a new category
Usage
POST/category
Header
Authorization: Bearer {JWT}
Body
{
name: string,
short_name: string,
id_parent: int
}
Name is mandatory.
Returned Values
Put
Update an existing category
Usage
PUT/category
Header
Authorization: Bearer {JWT}
Body
{
id: int,
name: string,
short_name: string
}
Id is mandatory.
Returned Values
Delete
Delete a category
Usage
DELETE/category?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Brands ^
Get
Get one or a list of brands
Usage
GET/brands{id,description}
Parameters
| id (string): |
ID of a brand. |
| description (string): |
Get brands whose description contains this parameter. |
Header
Authorization: Bearer {JWT}.
Returned Values
Post
Insert a new brand
Usage
POST/brands
Header
Authorization: Bearer {JWT}
Body
{
id: string,
description: string
}
Returned Values
Put
Update an existing brand
Usage
PUT/brands
Header
Authorization: Bearer {JWT}
Body
{
id: string,
description: string
}
Returned Values
Delete
Delete a brand
Usage
DELETE/brands?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Models ^
Get
Get one or a list of models
Usage
GET/models{id,description,brand}
Parameters
| id (string): |
ID of a model. |
| description (string): |
Get models whose description contains this parameter. |
| brand (string): |
Get models whose brand ID matches this parameter. |
Header
Authorization: Bearer {JWT}.
Returned Values
- Success without ID
- Success without ID
- Error 400
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Model from parameter id doesn’t exist
Post
Insert a new model
Usage
POST/models
Header
Authorization: Bearer {JWT}
Body
{
id: string,
description: string
brand: string
}
Returned Values
Put
Update an existing model
Usage
PUT/models
Header
Authorization: Bearer {JWT}
Body
{
id: string,
brand: string,
description: string
}
Returned Values
Delete
Delete a model
Usage
DELETE/models?id={id}&brand={brand}
Header
Authorization: Bearer {JWT}
Returned Values
Customers ^
Get
Get one or a list of customers
Usage
GET/customers{?id,limit,page,modified_since,query,name,code,tax_id,show_inactive}
Parameters
| id (int): |
ID of a customer. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of customers per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get customers modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get customers whose name, code, or tax ID contain this parameter. |
| name (string): |
Get customers whose name contains this parameter. |
| name (string): |
Get customers whose code contains this parameter. |
| tax_id (string): |
Get customers whose tax ID contains this parameter. |
| show_inactive (boolean): |
Show or hide inactive customers. The default value is false. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
customers: [
{
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
},
(…)
]
}
- Success with ID
200 OK
{
id: int,
code: string,
name: string,
tax_id: string,
website: string,
email: string,
phone: string,
notes: string,
entity_type: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
birthday: date,
payment_method: {
string,
},
payment_condition: {
id: string,
description: string
},
delivery_method:{
id: string,
description: string
},
currency: {
id: string,
description:string.
symbol: string.
decimal_cases: int
},
salesman: {
id: int,
code:string,
name: string,
commission: float.
tax_id: string,
active: boolean
},
billing_address: {
street:string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
shipping_address: {
street: string,
city: string,
postal_code: string,
postal_code_location:
string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
other_addresses: [
{
street: string,
city: string,
type: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
(…)
]
}
An inactive customer is always returned when searched by ID.
Birthday is a UTC date.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Customer from parameter id doesn’t exist
Post
Insert a new customer
Usage
POST/customers
Header
Authorization: Bearer {JWT}
Body
{
code: string,
name: string,
tax_id: string,
website: string,
email: string,
phone: string,
notes: string,
currency: string,
birthday: string,
salesman: int,
country: string,
billing_address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
},
shipping_address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
}
- Note
Code, name, country and one of the addresses are mandatory.
Code must be unique and contain only alpha-numeric characters.
Country is an ISO 3166-1 code.
In both addresses, the street and city are mandatory. If the country is not defined, the customer’s country is assumed. If the country is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
If the country is Portugal, the tax_id must be a valid NIF.
Email must be a valid e-mail.
Birthday must be sent in UTC.
If currency is not defined, the base currency is assumed.
Returned Values
Put
Update an existing customer
Usage
PUT/customer
Header
Authorization: Bearer {JWT}
Body
{
id: int,
name: string,
tax_id: string,
website: string,
email: string,
phone: string,
notes: string,
currency: string,
birthday: string,
salesman: int,
country: string,
billing_address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
},
shipping_address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
}
- Note
Id is mandatory.
Tax_id is ignored if the customer already has a tax ID.
Country is an ISO 3166-1 code.
The customer’s name can only be changed if it has a
tax ID or no sale associated to it exist.
In both addresses, the street and city are mandatory.
If the country is not defined, the customer’s
country is assumed.
If the country is Portugal, postal_code must be a
valid Portuguese postal code: four digits,
‘-‘, three digits (‘000’ if not present).
If the country is Portugal, the tax_id must be a valid NIF.
Email must be a valid e-mail address.
Birthday must be sent in UTC according to ISO 8601(YYYY-MM-DD).
If currency is not defined, the base currency is assumed.
Returned Values
Delete
Delete a customer
Usage
DELETE/customers?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Customer Addresses ^
Get
Get one or a list
Usage
GET/customeraddresses?customer={id}
Parameters
| id (int): |
Customer ID. Numeric and mandatory. |
| type (string): |
Address type. |
Header
Authorization: Bearer {JWT}
Returned Values
Post
Insert a new customer address
Usage
POST/customeraddresses
Header
Authorization: Bearer {JWT}
Body
{
customer: int,
street: string,
city: string,
type: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
- Note
Customer, type, street, city and country are mandatory.
Type must be unique.
If the country is Portugal, postal_code must be a
valid Portuguese postal code: four digits, ‘-‘,
three digits (‘000’ if not present).
Returned Values
Put
Update an existing customer addresss
Usage
PUT/customeraddresses
Header
Authorization: Bearer {JWT}
Body
{
customer: int,
street: string,
city: string,
type: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
- Note
Customer, and type are mandatory.
If the country is Portugal, postal_code
(or the current one if postal_code isn’t in the request)
must be a valid Portuguese postal code: four digits, ‘-‘,
three digits (‘000’ if not present).
Returned Values
Delete
Delete a customer address
Usage
DELETE/customeraddresses?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Salesmen ^
Get
Get one or a list of salesmen
Usage
GET/salesmen{?id,limit,page,modified_since,query,name,code,tax_id,show_inactive}
Parameters
| id (int): |
ID of a salesman. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of salesmen per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get salesmen modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get salesmen whose name, code, or tax ID contain this parameter. |
| name (string): |
Get salesmen whose name contains this parameter. |
| name (string): |
Get salesmen whose code contains this parameter. |
| tax_id (string): |
Get salemen whose tax ID contains this parameter. |
| show_inactive (boolean): |
Show or hide inactive salesmen. The default value is false. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
salesmen:
[
{
id: int,
code: string,
name: string,
commission: float,
tax_id: string,
active: boolean
},
(…)
]
}
- Sucess with ID
200 OK
{
id: int,
code:string,
name:string,
commission: float,
tax_id: string,
email: string,
phone: string,
notes: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
address: {
street: string,
city:string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
}
}
An inactive salesman is always returned when searched by ID.
Commission is a percentage value.
- Error 400
400 Bad Request – Parameter id must be numeric 401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Salesman from parameter id doesn’t exist
Post
Insert a new salesman
Usage
POST/salesmen
Header
Authorization: Bearer {JWT}
Body
{
code: string,
name: string,
tax_id: string,
commission: float,
email: string,
phone: string,
notes: string,
country: string,
address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
}
- Note
Code, name, country are mandatory.
Code must be unique and contain only alpha-numeric characters.
Country is an ISO 3166-1 code.
If address is declared, the street and city are mandatory.
If the country is not defined, the salesman’s country is assumed.
If the country is Portugal, postal_code must be a valid
Portuguese postal code: four digits,
‘-‘, three digits (‘000’ if not present).
If the country is Portugal, the tax_id must be a valid NIF.
Email must be a valid e-mail address.
Commission must be a number between 0 and 100.
Returned Values
Put
Update an existing salesman
Usage
PUT/salesmen
Header
Authorization: Bearer {JWT}
Body
{
id: int,
name: string,
tax_id: string,
commission: float,
email: string,
phone: string,
notes: string,
country: string,
address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
}
- Note
Id is mandatory.
Tax_id is ignored if the salesman already has a tax ID.
Country is an ISO 3166-1 code.
If address is declared and the salesman doesn’t have an address, the street and city are mandatory. If the country is not defined, the salesman’s country is assumed. If the country is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
If the country is Portugal, the tax_id must be a valid NIF.
Email must be a valid e-mail address.
Commission must be a number between 0 and 100.
Returned Values
Delete
Delete a salesman
Usage
DELETE/salesmen?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Suppliers ^
Get
Get one or a list of suppliers
Usage
GET/suppliers{?id,limit,page,modified_since,query,name,code,tax_id,show_inactive}
Parameters
| id (int): |
ID of a supplier. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of suppliers per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get suppliers modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get suppliers whose name, code, or tax ID contain this parameter. |
| name (string): |
Get suppliers whose name contains this parameter. |
| name (string): |
Get suppliers whose code contains this parameter. |
| tax_id (string): |
Get suppliers whose tax ID contains this parameter. |
| show_inactive (boolean): |
Show or hide inactive suppliers. The default value is false. |
Header
Authorization:Bearer {JWT}
Returned Values
- Success Without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
salesmen:
[
{
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
},
(…)
]
}
- Success with ID
200 OK
{
id: int,
code: string,
name: string,
tax_id: string,
email: string,
phone: string,
notes: string,
entity_type: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
}
}
An inactive supplier is always returned when searched by ID.
- Error 400
400 Bad Request – Parameter id must be numeric – Invalid/Inexistent/Expired token
- Error 404
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 409
404 Not Found – Supplier from parameter id doesn’t exist
Post
Insert a new supplier
Usage
POST/suppliers
Header
Authorization: Bearer{JWT}
Body
{
code: string,
name: string,
tax_id: string,
email: string,
phone: string,
notes: string,
country: string,
address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:
{
iso_3166_1: string
}
}
}
- Note
Code, name, country are mandatory.
Code must be unique and contain only alpha-numeric characters.
Country is an ISO 3166-1 code.
If address is declared, the street and city are mandatory. If the country is not defined, the supplier’s country is assumed. If the country is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
If the country is Portugal, the tax_id must be a valid NIF.
Email must be a valid e-mail address.
Returned Values
Put
Update an existing supplier
Usage
PUT/suppliers
Header
Authorization:Bearer{JWT}
Body
{
id:int,
name: string,
tax_id: string,
email: string,
phone: string,
notes: string,
country: string,
address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country:{
iso_3166_1: string
}
}
}
- Note
Id is mandatory.
Tax_id is ignored if the supplier already has a tax ID.
Country is an ISO 3166-1 code.
If address is declared and the supplier doesn’t have an address, the street and city are mandatory. If the country is not defined, the supplier’s country is assumed. If the country is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
If the country is Portugal, the tax_id must be a valid NIF.
Email must be a valid e-mail address.
Returned Values
Delete
Delete a supplier
Usage
DELETE/suppliers?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
- Success
200 OK
- Error 400
- Error 404
404 Not Found – The supplier indicated by the id does not exist
Orders ^
Get
Get one or a list of orders
Usage
GET/orders{?id,limit,page,modified_since,query,closed,customer,salesman,series,
date,expiration_date,your_reference }
Parameters
| id (string): |
ID of an order. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of orders per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get orders modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get orders whose customer (code/name), salesman (code/name), series or your reference contain this parameter. |
| closed (boolean): |
Get closed or open orders. |
| customer (int/string): |
Get orders whose customer’s ID, code or name contain this parameter. |
| salesman (string): |
Get orders whose salesman’s ID, code or name contain this parameter. |
| series (string): |
Get orders whose series ID contains this parameter. |
| date (date): |
Get orders from the given date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| expiration_date (date): |
Get orders from the given expiration date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| your_reference (string): |
Get orders whose reference contains this parameter. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
orders:
[
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float
},
(…)
]
}
- Success with ID
200 OK
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
email: string,
phone: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
billing_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
shipping_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
}
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
salesman: {
id: int,
code: string,
name: string,
commission: float,
tax_id: string,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
items:
[
{
product: {
id: int,
name: int,
barcode: string,
type: int,
unit: {
id: string,
description: string
}
},
tax: {
id: string,
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
},
price: float,
quantity: float,
discount: float,
type: int,
description: string,
warehouse: int
},
(…)
],
your_reference: string,
notes: string,
vehicle_plate: string,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
hash: string,
hash_control: string,
atcud: string,
loading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
}
}
The field type of items can assume these values:
1. Merchandise/Service
2. Postage
3. Adjustment
4. Value discount on merchandise/service
5. Other value discount
6. Notes
Date and expiration_date are sent in UTC.
Merchandise is the total value of items with type 1. Postage is the total value of items with type 2. Adjusctment is the total value of items with type 3. Discounts is the total value of items with type 4 and 5.
Subtotal is equal to Merchandise plus Postage minus Discounts. Total adds Taxes and subtracts Adjustment to the Subtotal.
Taxes is the total value of item taxes, which exist in every item type, except 3 and 6.
Entity_discount and financial_discount is a percentage value.
Alternate_billing_address and alternate_shipping_address are address types.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Order from parameter id doesn’t exist
- Error 409
409 Conflict – The order was edited by another application, in a way that makes it invalid for API purposes
Post
Insert a new order
Usage
POST/orders
Header
Authorization: Bearer {JWT}
Body
{
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
}
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
Customer, date, expiration_date and series are mandatory.
The customer must have a billing address. The address of type “Empresa” is used as billing address and the one of type “Entrega” is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared.
If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, the customer’s respective values are used. If they don’t exist, the suggested or default values are used instead.
If sales_document is defined, its document type must be 2 (orders). If not, the suggested orders sales document is used.
When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Entity_discount and financial_discount accept numbers between 0 and 100.
If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
The fields id, discount and warehouse of items are only considered if type is 1. Discount accepts numbers between 0 and 100.
If item’s description is not declared a default value is used, except for type 6, the item is simply ignored in that case.
The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types.
Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared.
All the order’s totals must be positive.
Returned Values
Put
Update an existing order
Usage
PUT/orders
Header
Authorization: Bearer {JWT}
Body
{
id: string,
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
Id is mandatory.
Closed orders can’t be modified.
The customer must have a billing address. The address of type “Empresa” is used as billing address and the one of type “Entrega” is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared.
If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, but customer is, the values are replaced by the customer ones, if they exist.
If sales_document is defined, its document type must be 2 (orders).
When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Entity_discount and financial_discount accept numbers between 0 and 100.
If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
The fields id, discount and warehouse of items are only considered if type is 1. Discount accepts numbers between 0 and 100.
If items is declared, all previous items of the order are deleted and replaced by the new ones.
If item’s description is not declared a default value is used, except for type 6, the item is simply ignored in that case.
The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types.
Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared.
All the order’s totals must be positive.
Returned Values
Delete
Delete/cancel an order
Note:If the order is not closed, it’s deleted. If not, it’s canceled.
Usage
DELETE/orders?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Estimates ^
Get
Get one or a list of estimates
Usage
GET/estimates{?id,limit,page,modified_since,query,closed,customer,salesman,series,date,expiration_date,your_reference}
Parameters
| id (string): |
ID of an estimate. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of estimates per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get estimates modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get estimates whose customer (code/name), salesman (code/name), series or your reference contain this parameter. |
| closed (boolean): |
Get closed or open estimates. |
| customer (int/string): |
Get estimates whose customer’s ID, code or name contain this parameter. |
| salesman (string): |
Get estimates whose salesman’s ID, code or name contain this parameter. |
| series (string): |
Get estimates whose series ID contains this parameter. |
| date (date): |
Get estimates from the given date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| expiration_date (date): |
Get estimates from the given expiration date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| your_reference (string): |
Get estimates whose reference contains this parameter. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
estimates:
[
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float
},
(…)
]
}
- Success with ID
200 OK
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
email: string,
phone: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
billing_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
shipping_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
}
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
salesman: {
id: int,
code: string,
name: string,
commission: float,
tax_id: string,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
items:
[
{
product: {
id: int,
name: int,
barcode: string,
type: int,
unit: {
id: string,
description: string
}
},
tax: {
id: string,
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
},
price: float,
quantity: float,
discount: float,
type: int,
description: string,
warehouse: int
},
(…)
],
your_reference: string,
notes: string,
vehicle_plate: string,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
hash: string,
hash_control: string,
atcud: string,
loading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
}
}
The field type of items can assume these values:
1. Merchandise/Service
2. Postage
3. Adjustment
4. Value discount on merchandise/service
5. Other value discount
6. Notes
Date and expiration_date are sent in UTC.
Merchandise is the total value of items with type 1. Postage is the total value of items with type 2. Adjusctment is the total value of items with type 3. Discounts is the total value of items with type 4 and 5.
Subtotal is equal to Merchandise plus Postage minus Discounts. Total adds Taxes and subtracts Adjustment to the Subtotal.
Taxes is the total value of item taxes, which exist in every item type, except 3 and 6.
Entity_discount and financial_discount is a percentage value.
Alternate_billing_address and alternate_shipping_address are address types.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Estimate from parameter id doesn’t exist
- Error 409
409 Conflict – The estimate was edited by another application, in a way that makes it invalid for API purposes
Post
Insert a new estimate
Usage
POST/estimates
Header
Authorization: Bearer {JWT}
Body
{
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
}
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
Customer, date, expiration_date and series are mandatory.
The customer must have a billing address. The address of type “Empresa” is used as billing address and the one of type “Entrega” is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared.
If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, the customer’s respective values are used. If they don’t exist, the suggested or default values are used instead.
If sales_document is defined, its document type must be 2 (estimates). If not, the suggested estimates sales document is used.
When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Entity_discount and financial_discount accept numbers between 0 and 100.
If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
The fields id, discount and warehouse of items are only considered if type is 1. Discount accepts numbers between 0 and 100.
If item’s description is not declared a default value is used, except for type 6, the item is simply ignored in that case.
The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types.
Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared.
All the estimate’s totals must be positive.
Returned Values
Put
Update an existing estimate
Usage
PUT/estimates
Header
Authorization: Bearer {JWT}
Body
{
id: string,
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
Id is mandatory.
Closed estimates can’t be modified.
The customer must have a billing address. The address of type “Empresa” is used as billing address and the one of type “Entrega” is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared.
If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, but customer is, the values are replaced by the customer ones, if they exist.
If sales_document is defined, its document type must be 2 (estimates).
When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Entity_discount and financial_discount accept numbers between 0 and 100.
If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
The fields id, discount and warehouse of items are only considered if type is 1. Discount accepts numbers between 0 and 100.
If items is declared, all previous items of the estimate are deleted and replaced by the new ones.
If item’s description is not declared a default value is used, except for type 6, the item is simply ignored in that case.
The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types.
Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared.
All the estimate’s totals must be positive.
Returned Values
Delete
Delete/cancel an estimate
Note:If the estimate is not closed, it’s deleted. If not, it’s canceled.
Usage
DELETE/estimates?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Movement Of Goods ^
Get
Get one or a list of movements of goods
Usage
GET/movementsofgoods{?id,limit,page,modified_since,query,closed,customer,salesman,series,date,expiration_date,your_reference}
Parameters
| id (string): |
ID of a movement of goods. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of movements of goods per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get movements of goods modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get movements of goods whose customer (code/name), salesman (code/name), series or your reference contain this parameter. |
| closed (boolean): |
Get closed or open movements of goods. |
| customer (int/string): |
Get movements of goods whose customer’s ID, code or name contain this parameter. |
| salesman (string): |
Get movements of goods whose salesman’s ID, code or name contain this parameter. |
| series (string): |
Get movements of goods whose series ID contains this parameter. |
| date (date): |
Get movements of goods from the given date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| expiration_date (date): |
Get movements of goods from the given expiration date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| your_reference (string): |
Get movements of goods whose reference contains this parameter. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
movements_of_goods:
[
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float
},
(…)
]
}
- Success with ID
200 OK
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
email: string,
phone: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
billing_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
shipping_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
}
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
salesman: {
id: int,
code: string,
name: string,
commission: float,
tax_id: string,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
items:
[
{
product: {
id: int,
name: int,
barcode: string,
type: int,
unit: {
id: string,
description: string
}
},
tax: {
id: string,
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
},
price: float,
quantity: float,
discount: float,
type: int,
description: string,
warehouse: int
},
(…)
],
your_reference: string,
notes: string,
vehicle_plate: string,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
hash: string,
hash_control: string,
atcud: string,
loading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
}
}
The field type of items can assume these values:
1. Merchandise/Service
2. Postage
3. Adjustment
4. Value discount on merchandise/service
5. Other value discount
6. Notes
Date and expiration_date are sent in UTC.
Merchandise is the total value of items with type 1. Postage is the total value of items with type 2. Adjusctment is the total value of items with type 3. Discounts is the total value of items with type 4 and 5.
Subtotal is equal to Merchandise plus Postage minus Discounts. Total adds Taxes and subtracts Adjustment to the Subtotal.
Taxes is the total value of item taxes, which exist in every item type, except 3 and 6.
Entity_discount and financial_discount is a percentage value.
Alternate_billing_address and alternate_shipping_address are address types.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Movement of goods from parameter id doesn’t exist
- Error 409
409 Conflict – The movement of goods was edited by another application, in a way that makes it invalid for API purposes
Post
Insert a new movement of goods
Usage
POST/movementsofgoods
Header
Authorization: Bearer {JWT}
Body
{
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
}
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
Customer, date, expiration_date and series are mandatory.
The customer must have a billing address. The address of type “Empresa” is used as billing address and the one of type “Entrega” is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared.
If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, the customer’s respective values are used. If they don’t exist, the suggested or default values are used instead.
If sales_document is defined, its document type must be 2 (movement of goods). If not, the suggested movement of goods sales document is used.
When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Entity_discount and financial_discount accept numbers between 0 and 100.
If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
The fields id, discount and warehouse of items are only considered if type is 1. Discount accepts numbers between 0 and 100.
If item’s description is not declared a default value is used, except for type 6, the item is simply ignored in that case.
The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types.
Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared.
All the movements of goods’s totals must be positive.
Returned Values
Put
Update an existing movement of goods
Usage
PUT/movementsofgoods
Header
Authorization: Bearer {JWT}
Body
{
id: string,
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
Id is mandatory.
Closed movements of goods can’t be modified.
The customer must have a billing address. The address of type “Empresa” is used as billing address and the one of type “Entrega” is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared.
If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, but customer is, the values are replaced by the customer ones, if they exist.
If sales_document is defined, its document type must be 2 (movement of goods).
When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Entity_discount and financial_discount accept numbers between 0 and 100.
If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
The fields id, discount and warehouse of items are only considered if type is 1. Discount accepts numbers between 0 and 100.
If items is declared, all previous items of the movement of goods are deleted and replaced by the new ones.
If item’s description is not declared a default value is used, except for type 6, the item is simply ignored in that case.
The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types.
Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared.
All the movements of goods totals must be positive.
Returned Values
Delete
Delete/cancel a movement of goods
Note:If the movement of goods is not closed, it’s deleted. If not, it’s canceled.
Usage
DELETE/movementsofgoods?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Sales Invoices ^
Get
Get one or a list of sales invoices
Usage
GET/salesinvoices{?id,limit,page,modified_since,query,closed,customer,salesman,series,date,expiration_date,your_reference}
Parameters
| id (string): |
ID of a sale invoice. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of sales invoices per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get sales invoices modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get sales invoices whose customer (code/name), salesman (code/name), series or your reference contain this parameter. |
| closed (boolean): |
Get closed or open sales invoices. |
| customer (int/string): |
Get sales invoices whose customer’s ID, code or name contain this parameter. |
| salesman (string): |
Get sales invoices whose salesman’s ID, code or name contain this parameter. |
| series (string): |
Get sales invoices whose series ID contains this parameter. |
| date (date): |
Get sales invoices from the given date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| expiration_date (date): |
Get sales invoices from the given expiration date. Date must be sent in UTC according to ISO 8601 (YYYY-MM-DD). |
| your_reference (string): |
Get sales invoices whose reference contains this parameter. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
sales_invoice:
[
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
active: boolean
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float
},
(…)
]
}
- Success with ID
200 OK
{
id: string,
document_number: int,
customer: {
id: int,
code: string,
name: string,
tax_id: string,
email: string,
phone: string,
active: boolean,
country: {
iso_3166_1: string,
name: string
},
billing_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
},
shipping_address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
region: string,
country: {
iso_3166_1: string,
name: string
}
}
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
salesman: {
id: int,
code: string,
name: string,
commission: float,
tax_id: string,
active: boolean
},
delivery_method: {
id: string,
description: string
},
payment_condition: {
id: string,
description: string
},
payment_method: {
id: string,
description: string
},
sales_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
items:
[
{
product: {
id: int,
name: int,
barcode: string,
type: int,
unit: {
id: string,
description: string
}
},
tax: {
id: string,
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
},
price: float,
quantity: float,
discount: float,
type: int,
description: string,
warehouse: int
},
(…)
],
your_reference: string,
notes: string,
vehicle_plate: string,
date: date,
expiration_date: date,
canceled: boolean,
closed: boolean,
merchandise: float,
postage: float,
discounts: float,
subtotal: float,
taxes: float,
adjustment: float,
total: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
hash: string,
hash_control: string,
atcud: string,
loading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string,
name: Portugal
}
}
}
The field type of items can assume these values:
1. Merchandise/Service
2. Postage
3. Adjustment
4. Value discount on merchandise/service
5. Other value discount
6. Notes
Date and expiration_date are sent in UTC.
Merchandise is the total value of items with type 1. Postage is the total value of items with type 2. Adjusctment is the total value of items with type 3. Discounts is the total value of items with type 4 and 5.
Subtotal is equal to Merchandise plus Postage minus Discounts. Total adds Taxes and subtracts Adjustment to the Subtotal.
Taxes is the total value of item taxes, which exist in every item type, except 3 and 6.
Entity_discount and financial_discount is a percentage value.
Alternate_billing_address and alternate_shipping_address are address types.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Sale invoice from parameter id doesn’t exist
- Error 409
409 Conflict – The sale invoice was edited by another application, in a way that makes it invalid for API purposes
Post
Insert a new sale invoice
Usage
POST/salesinvoices
Header
Authorization: Bearer {JWT}
Body
{
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
}
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
- customer, date, expiration_date and series are mandatory;
- The customer must have a billing address. The address of type Empresa is used as billing address and the one of type Entrega is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared;
- If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, the customer’s respective values are used. If they don’t exist, the suggested or default values are used instead;
- If sales_document is defined, its document type must be 4 (sale invoice). If not, the suggested sales invoice sales document is used;
- When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero;
- Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it;
- entity_discount and financial_discount accept numbers between 0 and 100:
- If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present);
- The fields id, discount and warehouse of items are only considered if type is 1;
- discount accepts numbers between 0 and 100;
- If item’s description is not declared a default value is used, except for type 6 (notes), the item is simply ignored in that case;
- The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types;
- Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared;
- All the sales invoices totals must be positive;
- The field type of items can assume these values:
1. Merchandise/Service
2. Postage
3. Adjustment
4. Value discount on merchandise/service
5. Other value discount
6. Notes
Returned Values
Put
Update an existing sale invoice
Usage
PUT/salesinvoices
Header
Authorization: Bearer {JWT}
Body
{
id: string,
customer: int,
salesman: int,
series: string,
your_reference: string,
notes: string,
vehicle_plate: string,
delivery_method: string,
sales_document: string,
payment_condition: string,
payment_method: string,
date: date,
expiration_date: date,
closed: boolean,
currency: string,
exchange_rate: float,
entity_discount: float,
financial_discount: float,
alternate_billing_address: string,
alternate_shipping_address: string,
loading_location: {
street: string,
city: string,
postal_code_location: string,
country: {
iso_3166_1: string
}
},
unloading_location: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
country: {
items:
[
{
id: int,
description: string,
tax: string,
price: float,
quantity: float,
discount: float,
type: int,
warehouse: int
},
(…)
]
}
- Note
- Id is mandatory;
- Closed sales invoices can’t be modified;
- customer, date, expiration_date and series are mandatory;
- The customer must have a billing address. The address of type Empresa is used as billing address and the one of type Entrega is used as shipping_address, unless alternate_billing_address or alternate_shipping_address are declared;
- If salesman, delivery_method, payment_condition, payment_method, currency or entity_discount are not defined, the customer’s respective values are used. If they don’t exist, the suggested or default values are used instead;
- If sales_document is defined, its document type must be 4 (sale invoice). If not, the suggested sales invoice sales document is used;
- When currency (either from the request or from customer) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero;
- Series must be active for the sales_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it;
- entity_discount and financial_discount accept numbers between 0 and 100:
- If the country of loading_location and unloading_location is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present);
- The fields id, discount and warehouse of items are only considered if type is 1;
- discount accepts numbers between 0 and 100;
- If item’s description is not declared a default value is used, except for type 6 (notes), the item is simply ignored in that case;
- The tax of an item is mandatory if type is 4 or 5. If type is 1 and tax is not declared, the product’s tax is used. Tax is ignored with other types;
- Item’s price and quantity must be higher than 0. Price is mandatory if type is 2, 3, 4 or 5. Quantity is mandatory if type is 1, otherwise its value is 1 if not declared;
- All the sales invoices totals must be positive;
- The field type of items can assume these values:
1. Merchandise/Service
2. Postage
3. Adjustment
4. Value discount on merchandise/service
5. Other value discount
6. Notes
Returned Values
Delete
Delete/cancel a sale invoice
Note:If the sale invoice is not closed, it’s deleted. If not, it’s canceled.
Usage
DELETE/salesinvoices?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Invoice
Get a PDF invoice
Usage
GET/salesinvoices/invoice?idinvoice={id}
Header
Authorization: Bearer {JWT}
Returned Values
Payments ^
Get
Get one or a list of payments
Usage
GET/payments{?id,limit,page,modified_since,query,entity,entity_type,salesman,series,date}
Parameters
| id (string): |
ID of a payment. If this parameter is declared, all others are ignored. |
| limit (int): |
Limit of payments per page. If not declared, the limit is 50. |
| page (int): |
Page number. If not declared, the default value is 1. |
| modified_since (date): |
Get payments modified/created since the declared date. Date and time must be sent in UTC according to ISO 8601. |
| query (string): |
Get payments whose customer (code/name), salesman (code/name), series or your reference contain this parameter. |
| entity (string): |
Get payments whose customer’s ID, code or name contain this parameter. |
| entity_type (int): |
Get payments from customers (0) or suppliers (1) |
| salesman (string): |
Get payments whose salesman’s ID, code or name contain this parameter. |
| series (string): |
Get payments whose series ID contains this parameter. |
| date (date): |
Get payments from the given date. Date and time must be sent in UTC according to ISO 8601 (yyyy-MM-ddThh:mm:ss). |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
{
pagination: {
limit: int,
page: int,
number_pages: int,
number_items: int
},
payments:
[
{
id: string,
entity: {
id: int,
code: string,
name: string,
tax_id: string,
entity_type: int,
active: boolean,
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
payment_methods:
[
{
id: string,
description: string,
value: float,
date: date
},
(…)
]
payment_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
date: date,
canceled: boolean,
received_value: float,
discount_value: float,
withholding_amount: float,
},
(…)
]
}
- Success with ID
200 OK
{
id: string,
entity: {
id: int,
code: string,
name: string,
tax_id: string,
entity_type: int,
active: boolean,
},
series: {
id: string,
description: string,
vat_cash_system: boolean,
active: boolean
},
salesman: {
id: int,
code: string,
name: string,
commission: float,
tax_id: string,
active: boolean
},
payment_methods:
[
{
id: string,
description: string,
value: float,
date: date
},
(…)
],
payment_document: {
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
},
currency: {
id: string,
description: string,
symbol: string,
decimal_cases: int
},
exchange_rate: float,
associated_documents:
[
{
id: string,
received_value: float,
discount_value: float
},
(…)
],
notes: string,
date: date,
canceled: boolean,
received_value: float,
discount_value: float,
withholding_amount: float,
hash: string,
hash_control: string,
atcud: string
}
Date is sent in UTC.
- Error 400
400 Bad Request – Parameter id must be numeric
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Payment from parameter id doesn’t exist
- Error 409
409 Conflict – The payment was edited by another application, in a way that makes it invalid for API purposes
Post
Insert a new payment
Usage
POST/payments
Header
Authorization: Bearer {JWT}
Body
{
entity: int,
entity_type: int,
salesman: int,
series: string,
notes: string,
payment_document: string,
payment_methods:
[
{
id: string,
value: float,
date: date
},
(…)
],
date: date,
currency: string,
exchange_rate: float,
discount_value: float,
discount_percentage: float,
associated_documents:
[
{
id: int,
received_value: float,
discount_value: float
},
(…)
]
}
- Note
Entity_type only accepts 0 (clients) for now.
Entity, entity_type, date and series are mandatory.
If salesman or currency are not defined, the customer’s respective values are used. If they don’t exist, the suggested or default values are used instead.
If payment_document is not defined, the suggested payments document is used.
When currency (either from the request or from entity) is not the company’s base currency, exchange_rate is mandatory and must be higher than zero.
Series must be active for the payment_document, and the number of documents of that type can’t exceed the series’ limit. Date must be in its date interval. A series with vat_cash_system must be used if the company or the customer uses it. A series without vat_cash_system can only be used if neither use it.
Discount_percentage accepts numbers between 0 and 100.
If discount_percentage or discount_value have value, the discount_value of associated¬_documents is ignored.
All associated_documents must be from the same entity.
All document totals must be positive. The total of received_value’s from associated_documents must match the total of value’s from payment¬_methods.
Returned Values
Delete
Delete/cancel a payment
Note:If the payment is not closed, it’s deleted. If not, it’s canceled.
Usage
DELETE/payments?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Taxes ^
Get
Get one or a list of taxes
Usage
GET/taxes?id={id}
Parameters
| id (string): |
ID of a tax. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
[
{
id: string,
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
},
(…)
]
- Success with ID
200 OK
{
id: string,
description: string
value: float,
description: string,
type: int,
exemption_reason: {
id: string,
description: string
}
}
Type can assume these values:
0. Exempt
1. Reduced
2. Intermediate
3. Normal
4. No deduction
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Tax from parameter id doesn’t exist
Post
Insert a new tax
Usage
POST/taxes
Header
Authorization: Bearer {JWT}
Body
{
id: string,
value: float,
description:string,
type: int,
exemption_reason:string
description: string
}
- Note
Id, value, description and type are mandatory.
Id is a 2 character string, it must be unique and contain only alpha-numeric characters.
Value must be a number between 0 and 100.
If type is 0 or 4, exemption_reason is mandatory. In that case, the value must be 0, otherwise it can’t be 0.
Returned Values
Put
Update an existing tax
Usage
PUT/taxes
Header
Authorization: Bearer {JWT}
Body
{
id: string,
value: float,
description: string,
type: int,
exemption_reason: string
}
- Note
Id is mandatory.
Value must be a number between 0 and 100.
If type is 0 or 4, exemption_reason is mandatory. In that case, the value must be 0, otherwise it can’t be 0.
Returned Values
Delete
Delete a tax
Usage
DELETE/taxes?id={id}
Header
Authorization:Bearer {JWT}
Returned Values
Units ^
Get
Get one or a list of units
Usage
GET/units?id={id}
Parameters
| id (string): |
ID of a unit. |
Header
Authorization: Bearer {JWT}.
Returned Values
Post
Insert a new unit
Usage
POST/units
Header
Authorization: Bearer {JWT}
Body
{
id: string,
description: string
}
Returned Values
Put
Update an existing unit
Usage
PUT/units
Header
Authorization: Bearer {JWT}
Body
{
id: string,
description: string
}
Returned Values
Delete
Delete a unit
Usage
DELETE/units?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Series ^
Get
Get one or a list of series
Usage
GET/series?id={id}
Parameters
| id (string): |
ID of a series. |
Header
Authorization: Bearer {JWT}
Returned Values
Post
Insert a new series
Usage
POST/series
Header
Authorization: Bearer {JWT}
Body
{
id: string,
description: string,
vat_cash_system: boolean
}
Returned Values
Put
Update an existing series
Usage
PUT/series
Header
Authorization:Bearer {JWT}
Body
{
id: string,
description: string,
vat_cash_system: boolean
}
Returned Values
Delete
Delete a series
Usage
DELETE/series?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Warehouses ^
Get
Get one or a list of warehouses
Usage
GET/warehouses?id={id}
Parameters
| id (int): |
ID of a warehouse. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
200 OK
[
{
id: int,
code: string,
description: string,
address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
country: {
iso_3166_1: string,
name: string
}
}
},
(…)
]
- Success with ID
200 OK
{
id: int,
code: string,
description: string,
address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
country: {
iso_3166_1: string,
name: string
}
}
}
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Warehouse from parameter id doesn’t exist
Post
Insert a new warehouse
Usage
POST/warehouses
Header
Authorization: Bearer {JWT}
Body
{
code: string,
description: string,
address:
{
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
country: {
iso_3166_1: string
}
}
}
- Note
Code and description are mandatory.
Code is a 8 character string, it must be unique and contain only alpha-numeric characters.
If the country of address is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present). If country is not defined, the company’s country is used.
Returned Values
Put
Update an existing warehouse
Usage
PUT/warehouses
Header
Authorization: Bearer {JWT}
Body
{
id: int,
description: string,
address: {
street: string,
city: string,
postal_code: string,
postal_code_location: string,
phone: string,
fax: string,
country: {
iso_3166_1: string
}
}
}
- Note
Id is mandatory.
If the country of address is Portugal, postal_code must be a valid Portuguese postal code: four digits, ‘-‘, three digits (‘000’ if not present).
Returned Values
Delete
Delete a warehouse
Usage
DELETE/warehouses?id={id}
Header
Authorization: Bearer {JWT}
Returned Values
Currencies ^
Get
Get one or a list of currencies
Usage
GET/currencies?id={id}
Parameters
| id (string): |
ID of a currency. |
Header
Authorization: Bearer {JWT}
Returned Values
Countries ^
Get
Get one or a list of countries
Usage
GET/countries?id={id}
Parameters
| id (string): |
Code ISO 3166-1 of a country. |
Header
Authorization: Bearer {JWT}
Returned Values
Delivery Methods ^
Get
Get one or a list of delivery methods
Usage
GET/deliverymethods?id={id}
Parameters
| id (string): |
ID of a delivery method. |
Header
Authorization: Bearer {JWT}
Returned Values
Exemption Reasons ^
Get
Get one or a list of exemption reasons
Usage
GET/exemptionreasons?id={id}
Parameters
| id (string): |
ID of an exemption reason. |
Header
Authorization: Bearer {JWT}
Returned Values
Payment Conditions ^
Get
Get one or a list of payment conditions
Usage
GET/paymentconditions?id={id}
Parameters
| id (string):</b< |
ID of a payment condition. |
Header
Authorization: Bearer {JWT}
Returned Values
Payment Methods ^
Get
Get one or a list of payment methods
Usage
GET/paymentmethods?id={id}
Parameters
| id (string): |
ID of a payment method. |
Header
Authorization: Bearer {JWT}
Returned Values
Sales Documents ^
Get
Get one or a list of sales documents
Usage
GET/salesdocuments?id={id}
Parameters
| id (string): |
ID of a sales document. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
- Success with ID
200 OK
{
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
}
Document_type can assume these values:
0. Quotation request (work)
1. Quotation
2. Order
3. Stock/Transfer (mov)
4. Financial (inv)
Saft_type can assume different values, depending on the document_type.
If document_type is 0 or 1, its value can be -1 (no SAFT) or 0 (conference document).
With type 2, it can only be -1 (no SAFT).
If type is 3, it can be -1 (no SAFT), 0 (GR – Goods delivery), 1 (GT – Transport document), 2 (GA – Transport document for own fixed assets), 3 (GC – Consignation guide) and 4 (GD – Return note from customer).
If type is 4, it can be -1 (no SAFT), 0 (FT – Invoice), 1 (ND – Debit note), 2 (NC – Credit note), 3 (VD – Sale for cash), 4 (TV – Sales ticket), 5 (TD – Devolution ticket), 6 (FS – Simplified invoice) and 7 (FR – Invoice-receipt).
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Sales document from parameter id doesn’t exist
Payment Documents ^
Get
Get one or a list of payment documents
Usage
GET/paymentdocuments?id={id}
Parameters
| id (string): |
ID of a payment document. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
- Success with ID
200 OK
{
id: string,
description: string,
default_series: string,
document_type: int,
saft_type: int,
active: boolean
}
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Payment document from parameter id doesn’t exist
Entity Types ^
Get
Get one or a list of entity types
Usage
GET/entitytypes?id={id}
Parameters
| id (string): |
ID of an entity type. |
Header
Authorization: Bearer {JWT}
Returned Values
Promotions ^
Get
Get one or a list of promotions
Usage
GET/promotions?id={id}
Parameters
| id (int): |
ID of a promotion. |
Header
Authorization: Bearer {JWT}
Returned Values
- Success without ID
- Success with ID
200 OK
{
id: int,
description: string
category: int,
entity_type: string,
offered_product: int,
brand: string,
start_date: date,
end_date: date,
happy_hour_start: date,
happy_hour_end: date,
sold_quantity: float,
offered_quantity: float,
price_reduction: float,
fixed_price: float,
discount_percentage: float,
price_type: int,
all_products: boolean,
active: boolean,
products: [
{
id: int
}
(…)
]
}
- Error 401
401 Unauthorized – Invalid/Inexistent/Expired token
- Error 404
404 Not Found – Promotion from parameter id doesn’t exist
Changelog ^
Version 1
Date: 20/03/2017
Notes: First version.
Version 1.1
Date: 04/04/2017
Notes: Added supplier management and product suppliers. New fields on products.
Version 1.2
Date: 17/05/2017
Notes: New fields when getting a single order (hash, hash_control).
Version 1.3
Date: 24/11/2017
Notes: Creation of hash code when creating a new order.
Version 1.4
Date: 16/06/2020
Notes: Added brand and model management. Brand and model fields on products.
Version 1.5
Date: 04/03/2021
Notes: Prices 2 to 5 added to products;
Management of estimates, movement of goods, sales invoices, payments, payment documents, dimensions, dimensions measures and reasons;
Added ATCUD, loading_date and unloading_date fields to orders.
Version 1.6
Date: 21/12/2021
Notes: Added entity types and promotions;
Added entity_type field to customers and suppliers.
Version 1.7
Date: 25/09/2023
Notes: The URL of the request GET salesinvoices/invoice was modified.
|
