Covenants

List GET

Example with mandatory parameters

<?php
$url     = 'https://www.vendus.cv/ws/v1.1/covenants/';
$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/covenants/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'GET';
$params  = array(
    'search'   => 'VAT, Client id', 
    'status'   => 'VAT, Client id', 
    'end_from' => '2024-04-27', 
    'end_to'   => '2024-04-27', 
    'type'     => 'Monday, Tuesday, etc...', 

);
$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
search	string	VAT, Client id	Search
status	string all, active, expired, disabled		Search
end_from	date	2024-04-27	End Date From
end_to	date	2024-04-27	End Date To
type	string monday, tuesday, wednesday, thursday, friday, saturday, sunday, every_fifteen_days, every_month, every_two_months, every_three_months, every_four_months, every_six_months, every_year		Recurrency

Response

Name	Type	Example	Description
records	array
pages	array

Create POST

Creates a covenant that is scheduled to generate a document on specific days for a client.

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.cv/ws/v1.1/covenants/';
$apiKey  = 'c433ff57a5ba6cdf301a48c97d9432594e35e73ce545945639bc4fb5798f1e8a';
$method  = 'POST';
$params  = array(
    'recurrency_type'        => 'Monday, Tuesday, etc...', 
    'recurrency_start_date'  => '2024-04-27', 
    'register_id'            => 12345, 
    'date_execution_end'     => '2024-04-27', 
    'draft_data'             => '...', 
    'type'                   => 'FT', 
    'covenant_id'            => 12345, 
    'status'                 => 1 or 0, 
    'execute_times'          => 1, 
    'discount_code'          => '23-180523-7', 
    'discount_amount'        => 10.00, 
    'discount_percentage'    => '2.50', 
    'date_due'               => '2024-12-31', 
    'mode'                   => 'normal', 
    'date'                   => '2024-04-27', 
    'date_supply'            => '2024-04-27', 
    '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, 
    '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', 
        ),
    ), 
    'items'                  => array(
        array(
            'id'                  => 12345, 
            'reference'           => 'CAFK001', 
            'gross_price'         => 12345, 
            'supply_price'        => 12345, 
            'qty'                 => 3.530, 
            'type_id'             => 'P', 
            'variant_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

recurrency_type

string

monday, tuesday, wednesday, thursday, friday, saturday, sunday, every_fifteen_days, every_month, every_two_months, every_three_months, every_four_months, every_six_months, every_year

Recurrency

recurrency_start_date string 2024-04-27 Start date

register_id int 12345 POS ID

date_execution_end string 2024-04-27 Start date

draft_data string ... String

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

covenant_id int 12345 Covenant ID

status int 1 or 0 Status

execute_times int 1 Execute times

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	int	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

mode

string

normal, tests

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

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.

date_supply date 2024-04-27 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

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

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

Response

Name	Type	Example	Description
is_update	boolean

Delete DELETE

Example with all allowed parameters

<?php
$url     = 'https://www.vendus.cv/ws/v1.1/covenants/';
$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);
?>

API (v1.1)

List GET

Example with mandatory parameters

Example with all allowed parameters

Request

Response

Create POST

Example with all allowed parameters

Request

Response

Delete DELETE

Example with all allowed parameters

Request

Response