Documents

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.cv/ws/v1.1/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.cv/ws/v1.1/documents/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'GET';
$params  = array(
    'store_id'           => 123456, 
    'register_id'        => 1234567, 
    'client_id'          => 1234567, 
    'client_fiscal_id'   => '123456789', 
    'client_country'     => 'PT', 
    'type'               => 'FT', 
    'subtype'            => 'G', 
    'since'              => '2024-01-01', 
    'until'              => '2024-12-31', 
    'q'                  => '01P2024/133', 
    'external_reference' => 'SSO00092/133', 
    'status'             => 'N', 
    'view'               => 'normal', 
    '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
client_id	int	1234567	Client ID
client_fiscal_id	string	123456789	Client Fiscal ID
client_country	string	PT	Client Country
type	string	FT	Valid Document Type You may send a comma separated string with multiple document types
subtype	string	G	Document Sub Type You may send a comma separated string with multiple document sub types
since	date	2024-01-01	Min date
until	date	2024-12-31	Max date
q	string	01P2024/133	Search string
external_reference	string	SSO00092/133	Search string
status	string `N` - Normal `A` - Canceled `F` - Invoiced		Status
view	string normal, detailed		More details of the documents
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
date_supply	date	2016-01-15	Delivery Date
system_time	datetime	2016-01-02 10:01:20	System date and time System time is always defined using UTC timezone
local_time	datetime	2016-01-02 10:01:20	Local date and time Local time according to your timezone
amount_gross	currency	123.00	Total amount
amount_net	currency	100.00	Total amount before taxes
type	string	FT	Document Type
subtype	string	G	Document Subtype
tax_authority_id	string	10000708560	Tax Authority ID Only for movement of goods
status	string	N	Status
qty_left_to_invoice	float	1	Quantity left to invoice Returned only when document is a "Guia Global"
total_unpaid	float		Unpaid amount
payment_status	string pending, expired, paid		Payment Status
external_reference	string	PT00192-24-21302	External reference

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.cv/ws/v1.1/documents/12345/';
// $url  = 'https://www.vendus.cv/ws/v1.1/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.cv/ws/v1.1/documents/12345/';
// $url  = 'https://www.vendus.cv/ws/v1.1/documents/12345.pdf';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'GET';
$params  = array(
    'mode'               => 'normal', 
    'copies'             => 1, 
    'output'             => 'html', 
    'output_template_id' => 123, 
    'output_version'     => 'ORIGINAL', 
    'return_qrcode'      => 1 or 0, 
    'download'           => 1 or 0, 
    'register_id'        => 12345, 

);
$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
copies	int 1, 2, 3		Number of copies
output	string auto, pdf, html, escpos, tpasibs, json		Printable Output
output_template_id	int	123	Template ID
output_version	string ORIGINAL, SECOND		Version
return_qrcode	int	1 or 0	Return SVG Qrcode
download	int	1 or 0	Download PDF. Only .pdf extension
register_id	int	12345	Register ID. Only used if the output is auto

Response

Name Type Example Description

id int 12345 ID

type string FT Official type

subtype string G Document Subtype

tax_authority_id string 10000708560 Tax Authority ID
Only for movement of goods

number string FT 01P2016/220 Document Number

date date 2016-01-02 Date

date_supply 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

local_time datetime 2016-01-02 10:01:20 Local date and time
Local time according to your timezone

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

external_reference string PT00192-2024-21302 External reference

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	Payment method ID
title	string	Dinheiro	Payment title
amount	currency	100	Amount
change	currency	37.00	Change

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 Code
country_name	string	Portugal	Country Name
email	email	alberto.lopes@dominio.pt	Email
external_reference	string	AB892798/19	External Reference

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

serial string 907298237982393 Serial Number(s)

reference_document string GT 12P2017/22 Reference Document

stock_control int 1 or 0 Control Stock

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	100	Total gross amount

discounts collection

Name	Type	Example	Description
amount	currency	20	Discount amount
percentage	float	5	Discount percentage
calculated_percentage	float	25	Calculated 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 Code To be used only when tax_id = ISE
exemption_law	string	Artigo 13.º do CIVA	Exemption Law To be used only when tax_id = ISE

category_id int 12345 Category ID

brand_id int 12345 Brand ID

qty_left_to_invoice float 1 Quantity left to invoice
Returned only when document is a "Guia Global"

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

irs array IRS data

Name	Type	Example	Description
amount	currency	10.28	Amount
rate	float	0.115	Rate
description	string	Art. 101.º, n.ºs 1 e 9, do CIRS. Art. 101.º, n.º1, do CIRS	Description

movement_of_goods array Transportation info

Name

Type

Example

Description

licence_plate

string

00-AB-00

Vehicle licence plate

at_code

string

1223234

AT Code

show_prices

string

yes

If prices should be printed

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
changestock	string	Yes	Stock Out

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
disclaimer	string		Global disclaimer

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	Type
number	string	FT 01P2016/220	Document number
amount	currency	123.00	Total amount

hash string Bgah Validation hash

atcud string JFAAAAAA-123 ATCUD

output text Printable output

output_data immutable Printable output data

qrcode text Qrcode SVG

qrcode_data text Qrcode Data

multibanco array Your own multibanco data.

Name	Type	Example	Description
entity	string	10022	Multibanco Entity
reference	string	222333444	Multibanco Reference
amount	currency	22.53	Multibanco Amount

venduspay array Vendus Pay Smart Checkout Page

Name	Type	Example	Description
payment_url	string	https://pay.vendus.pt/	Smart checkout URL
payment_qrcode	text		QR CODE

Create POST

Creates a new document like an invoice, a credit note, a receipt for a payment, a transportation document, and all others.

Invoices
The only mandatory parameter when creating an invoice 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. Regarding client, you don't have to send this parameter if you don't have his fiscal_id, and you should NEVER send fiscal_id as 999999990. And if client does not exist, it will be added.

Credit Notes
When creating a NC, you must specify reference_document for each item, passing document_number and document_row which unequivocally identifies an existing line on the original invoice, along with id and qty. You also have to specify notes stating the reason for issuing the credit note.

Payments and Receipts
To register a customer's payment, you create a receipt, that is, a document of type RG. Relevant parameters are payments and invoices, which should contain a list of all invoices being paid, each identified by its document_number. You should NOT send items.

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.cv/ws/v1.1/documents/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'POST';
$params  = array(
    'register_id'            => 12345, 
    'type'                   => 'FT', 
    'discount_code'          => '23-180523-7', 
    'discount_amount'        => 10.00, 
    'discount_percentage'    => '2.50', 
    'date_due'               => '2024-12-31', 
    'mode'                   => 'normal', 
    'date'                   => '2024-04-20', 
    'date_supply'            => '2024-04-20', 
    'notes'                  => 'New season', 
    'ncr_id'                 => 'Specific to CV', 
    'external_reference'     => 'PT00192-2024-21302', 
    'stock_operation'        => 'out', 
    'ifthenpay'              => 'no', 
    'eupago'                 => 'no', 
    'print_discount'         => 'no', 
    'output'                 => 'html', 
    'output_template_id'     => 123, 
    'tx_id'                  => '123', 
    'errors_full'            => 'no', 
    'rest_room'              => 12345, 
    'rest_table'             => 12345, 
    'occupation'             => 2, 
    'stamp_retention_amount' => 100.00, 
    'irc_retention_id'       => 'a', 
    'related_document_id'    => 12345, 
    'return_qrcode'          => 1 or 0, 
    'doc_to_generate'        => 'FT', 
    'multibanco'             => array(
        'entity'    => '10022', 
        'reference' => '222333444', 
        'amount'    => 22.53, 
    ), 
    'client'                 => array(
        'id'                 => 12345, 
        'fiscal_id'          => '223098091', 
        'name'               => 'Alberto Lopes', 
        'address'            => 'Av. Sousa Magalhães, 126', 
        'postalcode'         => '4100-039', 
        'city'               => 'Lisboa', 
        'phone'              => '210 192 930', 
        'mobile'             => '918 876 546', 
        'email'              => 'alberto.lopes@dominio.pt', 
        'website'            => 'https://www.dominio.pt', 
        'notes'              => 'VIP client', 
        'country'            => 'PT', 
        'external_reference' => 'AB892798/19', 
        'send_email'         => 'yes', 
        'billing_email'      => 'alberto.lopes.contabilista@dominio.pt', 
        'irs_retention'      => 'no', 
    ), 
    'supplier'               => array(
        'id'         => 12345, 
        'fiscal_id'  => '223098091', 
        'name'       => 'Alberto Lopes', 
        'address'    => 'Av. Sousa Magalhães, 126', 
        'postalcode' => '4100-039', 
        'city'       => 'Lisboa', 
        'phone'      => '210 192 930', 
        'mobile'     => '918 876 546', 
        'email'      => 'alberto.lopes@dominio.pt', 
        'website'    => 'https://www.dominio.pt', 
        'country'    => 'PT', 
        'obs'        => 'Some info about supplier', 
    ), 
    'movement_of_goods'      => array(
        'vehicle_id'  => '00-AB-00', 
        'show_prices' => 'yes', 
        'loadpoint'   => array(
            'date'        => '2016-10-01', 
            'time'        => '10:05', 
            'address'     => 'Rua Amadeu Sousa Cardoso, 13', 
            'postalcode'  => '4100-423', 
            'city'        => 'Porto', 
            'country'     => 'PT', 
            'store_id'    => 1234, 
            'changestock' => 'out', 
        ), 
        'landpoint'   => array(
            'is_global'    => 'no', 
            'date'         => '2016-10-02', 
            'time'         => '09:15', 
            'address'      => 'Rua Almada Negreiros, 98', 
            'postalcode'   => '1100-123', 
            'city'         => 'Lisboa', 
            'country'      => 'PT', 
            'store_id'     => 1234, 
            'receivestock' => 'yes', 
        ), 
    ), 
    'payments'               => array(
        array(
            'id'           => '1234', 
            'amount'       => 100.00, 
            'date_due'     => '2024-12-31', 
            'venduspay_id' => 'xxxxxxxxxx', 
        ),
    ), 
    'items'                  => array(
        array(
            'id'                  => 12345, 
            'reference'           => 'CAFK001', 
            'gross_price'         => 12345, 
            'supply_price'        => 12345, 
            'qty'                 => 3.530, 
            'type_id'             => 'P', 
            'variant_id'          => 12345, 
            'lot_id'              => 12345, 
            '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', 
            'tax_exemption_law'   => 'Artigo 13.º do CIVA', 
            'text'                => 'New Edition', 
            'serial'              => '87393872983792', 
            'tax_custom'          => array(
                'country' => 'PT, ES, FR, PT-AC', 
                'rate'    => 23, 
                'code'    => 'NOR, INT, RED, NS, ...', 
                'type'    => 'IVA', 
            ), 
            'reference_document'  => array(
                'document_number'    => 'FT 01P2016/220', 
                'document_row'       => 3, 
                'reference_id'       => 1234, 
                'reference_relation' => 'GG', 
            ), 
        ),
    ), 
    'invoices'               => array(
        array(
            'document_number' => 'FT 01P2016/28', 
        ),
    ), 

);
$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 - Talão de Venda
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_code string 23-180523-7 Discount code

discount_amount currency 10.00 Discount in euros

discount_percentage string 2.50 Discount in percentage

date_due date 2024-12-31 Due date

payments collection Payment Methods

Name	Type	Example	Description
id	string	1234	Payment Method ID
amount	currency	100.00	Amount in euros If not set the computed total is used.
date_due	date	2024-12-31	For `DNP` payments
venduspay_id	string	xxxxxxxxxx	Vendus Pay payment ID

mode

string

normal, tests

Working mode
If not provided, it will be assumed register's mode definition

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

date_supply date 2024-04-20 If not set, defaults to current date.
Date when goods/services are made available to customer

notes string New season Notes

ncr_id string Specific to CV NC reason ID

external_reference string PT00192-2024-21302 External reference
For example, to reference a tracking code

stock_operation

string

in - Increment stock
none - Don't change 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

ifthenpay

string

no, yes

Generate ifthenpay reference.
If not set, default is no.

eupago

string

no, yes

Generate euPago reference.
If not set, default is no.

multibanco array Your own multibanco data.

Name	Type	Example	Description
entity	string	10022	Multibanco Entity
reference	string	222333444	Multibanco Reference
amount	currency	22.53	Multibanco Amount

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	Postal Code
city	string	Lisboa	City
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
notes	string	VIP client	Notes
country	country	PT	Country code using ISO 3166-1 alpha-2
external_reference	string	AB892798/19	External Reference
send_email	string `yes` - Sim `no` - Não		Send Invoice
billing_email	email	alberto.lopes.contabilista@dominio.pt	Email to send the invoice. If empty, the email field is used
irs_retention	string `yes` - Sim `no` - Não		Whether client does IRS retention

supplier array Supplier

Name	Type	Example	Description
id	int	12345	Supplier ID If supplier already exists, it is only needed to send this param
fiscal_id	fiscal_id	223098091	Fiscal ID of supplier If supplier is portuguese, it must be a valid fiscal id
name	string	Alberto Lopes	Supplier Name
address	string	Av. Sousa Magalhães, 126	Postal Address
postalcode	string	4100-039	Postal Code
city	string	Lisboa	City
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
obs	string	Some info about supplier	Observations

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

supply_price currency 12345 Supply price

qty float 3.530 Quantity

type_id

string

P - Produto
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

variant_id int 12345 Variant ID

lot_id int 12345 Lot 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 string 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 Code
To be used only when tax_id = ISE

tax_exemption_law string Artigo 13.º do CIVA Tax Exemption Law
To be used only when tax_id = ISE

tax_custom array To be used only when taxation is for another region/country

Name	Type	Example	Description
country	string	PT, ES, FR, PT-AC	Region/Country in ISO 3166-1 alpha-2 format and also PT-AC and PT-MA
rate	float	23	Tax Percentage
code	string	NOR, INT, RED, NS, ...	Tax Code matching [a-zA-Z0-9.]
type	string IVA		Tax Type - currently, only IVA

reference_document array A document that is related, like when creating a NC

Name	Type	Example	Description
document_number	string	FT 01P2016/220	Document number
document_row	int	3	A row number of the document where the product is
reference_id	int	1234	Reference Document ID
reference_relation	string	GG	Valid Document Type

text string New Edition Some text about this item

serial string 87393872983792 Serial number(s) if applicable

movement_of_goods array Transportation info

Name

Type

Example

Description

vehicle_id

string

00-AB-00

Vehicle licence plate

show_prices

string

no, yes

If prices should be printed

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
store_id	int	1234	Store ID Used to set store from where stock is going to be removed
changestock	string	out	Stock

landpoint

array

Landpoint

Name	Type	Example	Description
is_global	string no, yes		Whether it is a global movement
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
store_id	int	1234	Store ID Used to set store to where stock is going to be moved
receivestock	string	yes	Stock

invoices collection When creating a RG

Name	Type	Example	Description
document_number	string	FT 01P2016/28	Document Number

print_discount

string

yes, no

Print Discount Coupons

output

string

auto, pdf, html, escpos, tpasibs

Printable Output

output_template_id int 123 Template ID

tx_id string 123 Transaction unique identifier.
If set, this will ensure that only a document may be created using the same tx_id, even if multiple requests are made by mistake.

errors_full

string

no, yes

Whether to return full error info or just error string

rest_room int 12345 ID Room

rest_table int 12345 ID Table

occupation int 2 Occupation

stamp_retention_amount currency 100.00 Amount in euros

irc_retention_id text a IRC ID

related_document_id int 12345 ID of a document that relates to this one

return_qrcode int 1 or 0 Return SVG Qrcode

doc_to_generate

string

FT, FR

Type of document to generate when RG or OT is paid

Response

Name	Type	Example	Description
id	int	12345	ID
type	string	FT	Official type
subtype	string	G	Document Subtype
tax_authority_id	string	10000708560	Tax Authority ID Only for movement of goods
number	string	FT 01P2016/220	Document Number
date	date	2016-01-02	Date
date_supply	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
local_time	datetime	2016-01-02 10:01:20	Local date and time Local time according to your timezone
amount_gross	currency	123	Total amount after taxes
amount_net	currency	100.00	Total amount before taxes
hash	string	Bgah	Validation hash
atcud	string	JFAAAAAA-123	ATCUD
output	text		Printable output
output_data	immutable		Printable output data
qrcode	text		Qrcode SVG
qrcode_data	text		Qrcode Data

Update PATCH

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.cv/ws/v1.1/documents/12345/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'PATCH';
$params  = array(
    'stock'  => 'true', 
    'status' => 'N', 
    'mode'   => 'normal', 

);
$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);
?>

API (v1.1)

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