Documents

Overview Authentication Versions Requests Responses

Reference

Brands Categories Clients Documents Payments Products Registers Stores Units

List GET

Returns a list of existing documents that may be filtered using store_id, register_id, type and date (using since and until). Please take a look at the Requests page of this documentation to learn how to use pagination parameters.

Example with mandatory parameters

<?php
$url     = 'https://www.vendus.pt/ws/v1.0/documents/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl);
?>

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.pt/ws/v1.0/documents/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'GET';
$params  = array(
    'store_id'    => 123456, 
    'register_id' => 1234567, 
    'type'        => 'FT', 
    'since'       => '2024-01-01', 
    'until'       => '2024-12-31', 
    'mode'        => 'normal', 

);
$url .= '?' . http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
$result = curl_exec($curl);
?>

Request

Name	Type	Example	Description
store_id	int	123456	Store ID
register_id	int	1234567	Register ID
type	string `FT` - Fatura `FS` - Fatura Simplificada `FR` - Fatura Recibo `NC` - Nota de Crédito `DC` - Consulta de Mesa `PF` - Fatura Pró-Forma `OT` - Orçamento `EC` - Encomenda `GA` - Guia de Ativos Próprios `GT` - Guia de Transporte `GR` - Guia de Remessa `GD` - Guia de Devolução `RG` - Recibo		Type
since	date	2024-01-01	Min date
until	date	2024-12-31	Max date
mode	string normal, tests		Working mode

Response

Name	Type	Example	Description
id	int	12345	ID
number	string	FT 01P2016/220	Document number
date	date	2016-01-02	Date
store_id	int	12345	Store ID
register_id	int	12345	Register ID
date_due	date	2016-01-15	Payment date When payment is due
system_time	datetime	2016-01-02 10:01:20	System date and time System time is always defined using UTC timezone
amount_gross	currency	123.00	Total amount
amount_net	currency	100.00	Total amount before taxes

Detail GET

Returns all information about a specific document. To obtain a pdf version, just add .pdf extension to the document's id.

Example with mandatory parameters

<?php
$url     = 'https://www.vendus.pt/ws/v1.0/documents/12345/';
// $url  = 'https://www.vendus.pt/ws/v1.0/documents/12345.pdf';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl);
?>

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.pt/ws/v1.0/documents/12345/';
// $url  = 'https://www.vendus.pt/ws/v1.0/documents/12345.pdf';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'GET';
$params  = array(
    'mode'   => 'normal', 
    'output' => 'html', 

);
$url .= '?' . http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
$result = curl_exec($curl);
?>

Request

Name	Type	Example	Description
mode	string normal, tests	Working mode
output	string pdf, escpos, html	Printable Output

Response

Name Type Example Description

id int 12345 ID

type string FT Official type

number string FT 01P2016/220 Document Number

date date 2016-01-02 Date

system_time datetime 2016-01-02 10:01:20 System date and time
Always using UTC timezone and in sync with the Portuguese Astronomical Observatory

amount_gross currency 123 Total amount after taxes

amount_net currency 100.00 Total amount before taxes

date_due date 2016-01-15 Due date
When payment is due

observations string Versão vermelha Notes

store_id int 12345 Store ID

register_id int 12345 Register ID

user_id int 12345 User ID

taxes collection Taxes list

Name	Type	Example	Description
total	currency	123.00	Amount after taxes
base	currency	100.00	Amount before taxes
amount	currency	23.00	Tax amount
rate	float	23	Tax rate

discounts array

Name	Type	Example	Description
amount	currency	45	Discount amount
percentage	float	5	Discount percentage
total	currency	13.23	Total amount of discounts

payments collection Payment methods

Name	Type	Example	Description
id	int	100.00	Payment method ID
title	string	Dinheiro	Payment title
amount	currency	123.00	Amount

client array

Name	Type	Example	Description
id	int	12345	ID do cliente
name	string	Alberto Lopes	Name
fiscal_id	fiscal_id	123456789	Fiscal ID
address	string	Rua Amadeu Sousa Cardoso, 120, 3E	Address
postalcode	string	4100-251	Postal code
city	string	Porto	City/Locality
country	string	PT	Country

items collection Products

Name Type Example Description

id int 12345 ID

qty float 3.530 Quantity

type_id string P Product type

title string Café ao Kg Name

reference string CAFK001 Reference

text string New Edition Some text about this item

amounts collection

Name	Type	Example	Description
net_unit	currency	100	Unit net amount
net_total	currency	300	Total net amount
gross_unit	currency	123	Unit gross amount
gross_total	currency	266	Total gross amount

discounts collection

Name	Type	Example	Description
amount	currency	13.25	Discount amount
percentage	float	5	Discount percentage

tax array

Name	Type	Example	Description
id	string `NOR` - Taxa Normal `INT` - Taxa Intermédia `RED` - Taxa Reduzida `ISE` - Isento `OUT` - Outros		Tax ID
country	string	PT	Country code
rate	float	23	Tax rate
exemption	string `M01` - M01 - Artigo 16.º, n.º 6 do CIVA ou similar `M02` - M02 - Artigo 6.º do Decreto-Lei n.º 198/90, de 19 de Junho `M03` - M03 - Exigibilidade de caixa (revogado) `M04` - M04 - Artigo 13.º do CIVA ou similar `M05` - M05 - Artigo 14.º do CIVA ou similar `M06` - M06 - Artigo 15.º do CIVA ou similar `M07` - M07 - Artigo 9.º do CIVA ou similar `M08` - M08 - IVA - autoliquidação (revogado) `M09` - M09 - IVA - não confere direito a dedução `M10` - M10 - IVA - Regime de isenção (Artigo 57.º do CIVA) `M11` - M11 - Regime particular do tabaco `M12` - M12 - Regime da margem de lucro - Agências de viagens `M13` - M13 - Regime da margem de lucro - Bens em segunda mão `M14` - M14 - Regime da margem de lucro - Objetos de arte `M15` - M15 - Regime da margem de lucro - Objetos de coleção e antiguidades `M16` - M16 - Artigo 14.º do RITI ou similar `M19` - M19 - Outras isenções `M20` - M20 - IVA - regime forfetário `M21` - M21 - IVA – não confere direito à dedução `M25` - M25 - Mercadorias à consignação `M26` - M26 - Cabaz alimentar `M30` - M30 - IVA - autoliquidação (2.1.i) `M31` - M31 - IVA - autoliquidação (2.1.j) `M32` - M32 - IVA - autoliquidação (2.1.l) `M33` - M33 - IVA - autoliquidação (2.1.m) `M34` - M34 - IVA - autoliquidação (2.1.n) `M40` - M40 - IVA - autoliquidação (6.6.a) `M41` - M41 - IVA - autoliquidação (8.3.R) `M42` - M42 - IVA - autoliquidação (21.2007) `M43` - M43 - IVA - autoliquidação (362.99) `M99` - M99 - Não sujeito; não tributado ou similar		Exemption reason To be used only when tax_id = ISE

category_id int 12345 Category ID

brand_id int 12345 Brand ID

status array Status

Name	Type	Example	Description
id	string `N` - Normal `A` - Anulado		Status ID
date	date	2016-10-10	Last changed date
user_id	int	12345	User ID

debt array Debt amount

Name	Type	Example	Description
total	currency	10.28	Amount to be paid
paid	currency	3.10	Amount already paid
unpaid	currency	7.18	Amount unpaid

movement_of_goods array Transportation info

Name

Type

Example

Description

vehicle_id

string

00-AB-00

Vehicle licence plate

loadpoint

collection

Loadpoint

Name	Type	Example	Description
date	date	2016-10-01	Date
time	time	10:05	Hour
address	string	Rua Amadeu Sousa Cardoso, 13	Address
postalcode	string	4100-423	Postal code
city	string	Porto	City/locality
country	string	PT	País

landpoint

collection

Landpoint

Name	Type	Example	Description
date	date	2016-10-02	Date
time	time	09:15	Hour
address	string	Rua Almada Negreiros, 98	Address
postalcode	string	1100-123	Postal code
city	string	Lisboa	City/locality
country	string	PT	País

at_id

int

12345

ID generated by AT
Only set on documents that have been automatically communicated to AT.

related_docs collection Related documents

Name	Type	Example	Description
id	int	12345	Document ID
type	string `FT` - Fatura `FS` - Fatura Simplificada `FR` - Fatura Recibo `NC` - Nota de Crédito `DC` - Consulta de Mesa `PF` - Fatura Pró-Forma `OT` - Orçamento `EC` - Encomenda `GA` - Guia de Ativos Próprios `GT` - Guia de Transporte `GR` - Guia de Remessa `GD` - Guia de Devolução `RG` - Recibo		Type
number	string	FT 01P2016/220	Document number
amount	currency	123.00	Total amount

hash string Bgah Validation hash

output text Base64 Encoded Printable output

Create POST

Creates a new document. The only mandatory parameter is items. For each item, you must send at least its qty, along with id (or reference). If it is a new product, it will be created.
Likewise, if client does not exist, it will be added. Also regarding client, you don't have to send this parameter if you dont have his fiscal_id, and you should NEVER send fiscal_id as 999999990.

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.pt/ws/v1.0/documents/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'POST';
$params  = array(
    'register_id'         => 12345, 
    'type'                => 'FT', 
    'discount_amount'     => 10.00, 
    'discount_percentage' => 2.50, 
    'notes'               => 'New season', 
    'date'                => '2024-04-27', 
    'mode'                => 'normal', 
    'stock_operation'     => 'out', 
    'output'              => 'html', 
    'client'              => array(
        'id'         => 12345, 
        'fiscal_id'  => '223098091', 
        'name'       => 'Alberto Lopes', 
        'address'    => 'Av. Sousa Magalhães, 126', 
        'postalcode' => '4100-039 Lisboa', 
        'phone'      => '210 192 930', 
        'mobile'     => '918 876 546', 
        'email'      => 'alberto.lopes@dominio.pt', 
        'website'    => 'https://www.dominio.pt', 
        'country'    => 'PT', 
    ), 
    'movement_of_goods'   => array(
        'vehicle_id' => '00-AB-00', 
        'loadpoint'  => array(
            'date'       => '2016-10-01', 
            'time'       => '10:05', 
            'address'    => 'Rua Amadeu Sousa Cardoso, 13', 
            'postalcode' => '4100-423', 
            'city'       => 'Porto', 
            'country'    => 'PT', 
        ), 
        'landpoint'  => array(
            'date'       => '2016-10-02', 
            'time'       => '09:15', 
            'address'    => 'Rua Almada Negreiros, 98', 
            'postalcode' => '1100-123', 
            'city'       => 'Lisboa', 
            'country'    => 'PT', 
        ), 
    ), 
    'payments'            => array(
        array(
            'id'       => 1234, 
            'amount'   => 100.00, 
            'date_due' => '2024-12-31', 
        ),
    ), 
    'items'               => array(
        array(
            'id'                  => 12345, 
            'reference'           => 'CAFK001', 
            'gross_price'         => 12345, 
            'qty'                 => 3.530, 
            'type_id'             => 'N', 
            'title'               => 'Café ao Kg', 
            'unit_id'             => 1872, 
            'category_id'         => 123, 
            'brand_id'            => 124, 
            'discount_amount'     => 124, 
            'discount_percentage' => 5, 
            'stock_control'       => 1, 
            'stock_type'          => 'M', 
            'tax_id'              => 'NOR', 
            'tax_exemption'       => 'M40', 
            'reference_document'  => 'FT 01P2016/220', 
            'reference_row'       => 3, 
            'text'                => 'New Edition', 
        ),
    ), 

);
$content = json_encode($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_HTTPHEADER,
    array(
        "Content-type: application/json",
        "Content-Length: " . strlen($content),
    )
);
$result = curl_exec($curl);
?>

Request

Name Type Example Description

register_id int 12345 POS ID

type

string

FT - Fatura
FS - Fatura Simplificada
FR - Fatura Recibo
NC - Nota de Crédito
DC - Consulta de Mesa
PF - Fatura Pró-Forma
OT - Orçamento
EC - Encomenda
GA - Guia de Ativos Próprios
GT - Guia de Transporte
GR - Guia de Remessa
GD - Guia de Devolução
RG - Recibo

Type of document

discount_amount currency 10.00 Discount in euros

discount_percentage float 2.50 Discount in percentage

payments collection Payment Methods

Name	Type	Example	Description
id	int	1234	Payment Method ID
amount	currency	100.00	Amount in euros
date_due	date	2024-12-31	For `DNP` payments

notes string New season Notes

date date 2024-04-27 If not set, defaults to current date.
Can not be ealier than the one from latest document, nor later than the current date.

mode

string

normal, tests

Working mode

client array Client

Name	Type	Example	Description
id	int	12345	Client ID If client already exists, it is only needed to send this param
fiscal_id	fiscal_id	223098091	Fiscal ID of client If client is portuguese, it must be a valid fiscal id
name	string	Alberto Lopes	Client Name
address	string	Av. Sousa Magalhães, 126	Postal Address
postalcode	string	4100-039 Lisboa	Postal Code
phone	string	210 192 930	Phone
mobile	string	918 876 546	Mobile
email	email	alberto.lopes@dominio.pt	Email
website	url	https://www.dominio.pt	Site url
country	country	PT	Country code using ISO 3166-1 alpha-2

items collection

Name	Type	Example	Description
id	int	12345	ID Mandatory if reference is null
reference	string	CAFK001	Reference Mandatory if ID is null
gross_price	currency	12345	Unit price
qty	float	3.530	Quantity
type_id	string `P` - Produto (default) `S` - Serviço `O` - Outro (portes, adiantamentos, etc.) `I` - Imposto (excepto IVA e IS) ou Encargo Parafiscal `E` - Imposto Especial de Consumo (IABA, ISP e IT)		Type ID
title	string	Café ao Kg	Name
unit_id	int	1872	Unit ID
category_id	int	123	Category ID
brand_id	int	124	Brand ID
discount_amount	currency	124	Discount in euros
discount_percentage	float	5	Discount in percentage
stock_control	int 0, 1		Stock Control
stock_type	string `M` - M - Mercadorias (default) `P` - P - Matérias primas, subsidiárias ou de consumo `A` - A - Produtos acabados ou intermédios `S` - S - Subprodutos, deperdícios ou refugos `T` - T - Produtos e trabalhos em curso		Stock Type
tax_id	string `NOR` - Taxa Normal `INT` - Taxa Intermédia `RED` - Taxa Reduzida `ISE` - Isento `OUT` - Outros		Tax ID
tax_exemption	string `M01` - M01 - Artigo 16.º, n.º 6 do CIVA ou similar `M02` - M02 - Artigo 6.º do Decreto-Lei n.º 198/90, de 19 de Junho `M03` - M03 - Exigibilidade de caixa (revogado) `M04` - M04 - Artigo 13.º do CIVA ou similar `M05` - M05 - Artigo 14.º do CIVA ou similar `M06` - M06 - Artigo 15.º do CIVA ou similar `M07` - M07 - Artigo 9.º do CIVA ou similar `M08` - M08 - IVA - autoliquidação (revogado) `M09` - M09 - IVA - não confere direito a dedução `M10` - M10 - IVA - Regime de isenção (Artigo 57.º do CIVA) `M11` - M11 - Regime particular do tabaco `M12` - M12 - Regime da margem de lucro - Agências de viagens `M13` - M13 - Regime da margem de lucro - Bens em segunda mão `M14` - M14 - Regime da margem de lucro - Objetos de arte `M15` - M15 - Regime da margem de lucro - Objetos de coleção e antiguidades `M16` - M16 - Artigo 14.º do RITI ou similar `M19` - M19 - Outras isenções `M20` - M20 - IVA - regime forfetário `M21` - M21 - IVA – não confere direito à dedução `M25` - M25 - Mercadorias à consignação `M26` - M26 - Cabaz alimentar `M30` - M30 - IVA - autoliquidação (2.1.i) `M31` - M31 - IVA - autoliquidação (2.1.j) `M32` - M32 - IVA - autoliquidação (2.1.l) `M33` - M33 - IVA - autoliquidação (2.1.m) `M34` - M34 - IVA - autoliquidação (2.1.n) `M40` - M40 - IVA - autoliquidação (6.6.a) `M41` - M41 - IVA - autoliquidação (8.3.R) `M42` - M42 - IVA - autoliquidação (21.2007) `M43` - M43 - IVA - autoliquidação (362.99) `M99` - M99 - Não sujeito; não tributado ou similar		Tax Exemption To be used only when tax_id = ISE
reference_document	string	FT 01P2016/220	A document that is related, like when creating a NC
reference_row	int	3	A row number of a document that is related, like when creating a NC
text	string	New Edition	Some text about this item

movement_of_goods array Transportation info

Name

Type

Example

Description

vehicle_id

string

00-AB-00

Vehicle licence plate

loadpoint

array

Loadpoint

Name	Type	Example	Description
date	date	2016-10-01	Date
time	time	10:05	Hour
address	string	Rua Amadeu Sousa Cardoso, 13	Address
postalcode	string	4100-423	Postal code
city	string	Porto	City/locality
country	country	PT	País

landpoint

array

Landpoint

Name	Type	Example	Description
date	date	2016-10-02	Date
time	time	09:15	Hour
address	string	Rua Almada Negreiros, 98	Address
postalcode	string	1100-123	Postal code
city	string	Lisboa	City/locality
country	country	PT	País

stock_operation

string

in - Increment stock
out - Decrement stock

Operation on items with stock_control.
If not sent, system will use the default for the type of document being created

output

string

pdf, escpos, html

Printable Output

Response

Name	Type	Example	Description
id	int	12345	ID
type	string	FT	Official type
number	string	FT 01P2016/220	Document Number
date	date	2016-01-02	Date
system_time	datetime	2016-01-02 10:01:20	System date and time Always using UTC timezone and in sync with the Portuguese Astronomical Observatory
amount_gross	currency	123	Total amount after taxes
amount_net	currency	100.00	Total amount before taxes
hash	string	Bgah	Validation hash
output	text	Base64 Encoded	Printable output

Update PATCH

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.pt/ws/v1.0/documents/12345/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'PATCH';
$params  = array(
    'status' => 'N', 

);
$content = json_encode($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_HTTPHEADER,
    array(
        "Content-type: application/json",
        "Content-Length: " . strlen($content),
    )
);
$result = curl_exec($curl);
?>

Name	Type	Example	Description
id	int	1234	ID
status	string `N` - Normal `A` - Anulado		Estado

API (v1.0)

List GET

Example with mandatory parameters

Example with all allowed parameters

Request

Response

Detail GET

Example with mandatory parameters

Example with all allowed parameters

Request

Response

Create POST

Example with all allowed parameters

Request

Response

Update PATCH

Example with all allowed parameters

Request

Response