ViaDireta API
Technical documentation for programmatic integration with the ViaDireta platform.
Our API allows you to integrate transport operations directly into your applications. With it you can:
- Authenticate via OAuth2 and obtain access tokens.
- Create new shipments with all recipient and service details.
- Query the current status of a shipment.
- Access the full tracking history.
- Generate and download PDF documents (labels and transport waybills).
Code examples available in C#, PHP, Python and JavaScript.
1. Authentication — Get Token
Use this endpoint to obtain an authentication token by providing your credentials. The returned token must be included as Bearer in the Authorization header of all subsequent requests.
Request parameters
Content-Type: application/x-www-form-urlencoded
| Parameter | Description | Example |
|---|---|---|
username | Your username | your_username |
password | Your password | your_password |
grant_type | Grant type — always use password | password |
Code examples
using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var url = "https://www.viadirectanet.pt/WebApiOAuth/Token";
using (var client = new HttpClient())
{
var parameters = new List<KeyValuePair<string, string>>
{
new KeyValuePair<string, string>("username", "your_username"),
new KeyValuePair<string, string>("password", "your_password"),
new KeyValuePair<string, string>("grant_type", "password")
};
var content = new FormUrlEncodedContent(parameters);
var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
}<?php
$url = "https://www.viadirectanet.pt/WebApiOAuth/Token";
$data = [
"username" => "your_username",
"password" => "your_password",
"grant_type" => "password"
];
$options = [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Content-Type: application/x-www-form-urlencoded"]
];
$ch = curl_init();
curl_setopt_array($ch, $options);
$response = curl_exec($ch);
curl_close($ch);
echo $response;import requests
url = "https://www.viadirectanet.pt/WebApiOAuth/Token"
data = {
"username": "your_username",
"password": "your_password",
"grant_type": "password"
}
response = requests.post(url, data=data)
print(response.text)fetch("https://www.viadirectanet.pt/WebApiOAuth/Token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
username: "your_username",
password: "your_password",
grant_type: "password"
})
})
.then(response => response.json())
.then(data => console.log("Access token:", data.access_token))
.catch(error => console.error("Error:", error));2. Create Shipment
Creates a new shipment. The request body must be in JSON format and include all required parameters.
Authorization: Bearer <access_token> · Content-Type: application/json
Required parameters
| Parameter | Description | Type |
|---|---|---|
NumConta | Your account number | Integer |
NumServico | Tracking number — can be auto-generated if empty (requires account activation) | String (máx. 25) |
Referencia | Your reference or shipment ID | String (máx. 30) |
DataServico | Expected delivery date | Date YYYY-MM-DD |
Nome | Recipient name | String (máx. 120) |
Morada | Recipient address | String (máx. 170) |
CodPost | Recipient postcode | String (máx. 8) |
LocPost | Recipient city | String (máx. 50) |
Pais | Recipient country (ISO 3166-1 alpha-2) | String (máx. 2) |
Contacto | Recipient contact(s) — may include multiple numbers | String (máx. 80) |
Telefone | Legacy parameter — send empty | String (máx. 12) |
EMAIL | Recipient email | String (máx. 120) |
NumVolumes | Number of items (minimum 1) | Integer |
Peso | Total weight | Float |
Valor | Cash on delivery (COD) value | Float |
TipoServico | "E" — Delivery · "R" — Pickup · "ER" — Delivery + Pickup | String |
SlotHoraria | Preferred delivery time slot | String (máx. 20) |
Material_Recolha | Pickup description | String (máx. 150) |
Material_Entrega | Shipment description | String (máx. 150) |
Optional parameters
| Parameter | Description | Type |
|---|---|---|
Referencia2 | Secondary shipment reference | String (máx. 30) |
Observacoes | Shipment notes | String (máx. 300) |
ObsAgenda | Additional scheduling notes | String (máx. 50) |
Advanced parameters — use only with specific ViaDireta instructions
| Parameter | Description | Type |
|---|---|---|
ServicoPreDef | Value provided by ViaDireta | Integer |
CentroCusto | Value provided by ViaDireta | Integer |
NomeOR | Recipient name (alternative) | String (máx. 120) |
MoradaOR | Alternative address | String (máx. 170) |
CodPostOR | Alternative postcode | String (máx. 8) |
LocPostOR | Alternative city | String (máx. 50) |
CodPaisOR | Alternative country (ISO 3166-1 alpha-2) | String (máx. 2) |
ContactoOR | Alternative contact | String (máx. 80) |
CodigoPIN | PinCode — 0 = False, 1 = True | Boolean |
Code examples
{
"NumConta": 0000,
"NumServico": "",
"DataServico": "2021-11-28",
"Nome": "ViaDirecta Lda",
"Morada": "Rua da Escola Primaria Lt 41",
"CodPost": "2660-032",
"LocPost": "Frielas",
"EMAIL": "email@email.com",
"Contacto": "218112800",
"Telefone": "912345678",
"Pais": "PT",
"NumVolumes": 1,
"Peso": 1.2,
"Valor": 16.0,
"SlotHoraria": "09H-13H",
"TipoServico": "E",
"Material_Recolha": "Material Recolha",
"Material_Entrega": "Material Entrega",
"Observacoes": "Observations",
"Referencia": "ref123"
}using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
class Program
{
static async Task Main()
{
var url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD";
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "your_access_token");
var payload = new
{
NumConta = 0000,
NumServico = "",
DataServico = "2021-11-28",
Nome = "ViaDirecta Lda",
Morada = "Rua da Escola Primaria Lt 41",
CodPost = "2660-032",
LocPost = "Frielas",
EMAIL = "email@email.com",
Contacto = "218112800",
Telefone = "912345678",
Pais = "PT",
NumVolumes = 1,
Peso = 1.2,
Valor = 16.0,
SlotHoraria = "09H-13H",
TipoServico = "E",
Material_Recolha = "Material Recolha",
Material_Entrega = "Material Entrega",
Observacoes = "Observations",
Referencia = "ref123"
};
var json = JsonConvert.SerializeObject(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(url, content);
Console.WriteLine(await response.Content.ReadAsStringAsync());
}
}
}<?php
$url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD";
$data = [
"NumConta" => 0000,
"NumServico" => "",
"DataServico" => "2021-11-28",
"Nome" => "ViaDirecta Lda",
"Morada" => "Rua da Escola Primaria Lt 41",
"CodPost" => "2660-032",
"LocPost" => "Frielas",
"EMAIL" => "email@email.com",
"Contacto" => "218112800",
"Telefone" => "912345678",
"Pais" => "PT",
"NumVolumes" => 1,
"Peso" => 1.2,
"Valor" => 16.0,
"SlotHoraria" => "09H-13H",
"TipoServico" => "E",
"Material_Recolha" => "Material Recolha",
"Material_Entrega" => "Material Entrega",
"Observacoes" => "Observations",
"Referencia" => "ref123"
];
$payload = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer your_access_token",
"Content-Length: " . strlen($payload)
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;import requests
url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
headers = {
"Authorization": "Bearer your_access_token",
"Content-Type": "application/json"
}
payload = {
"NumConta": 0000,
"NumServico": "",
"DataServico": "2021-11-28",
"Nome": "ViaDirecta Lda",
"Morada": "Rua da Escola Primaria Lt 41",
"CodPost": "2660-032",
"LocPost": "Frielas",
"EMAIL": "email@email.com",
"Contacto": "218112800",
"Telefone": "912345678",
"Pais": "PT",
"NumVolumes": 1,
"Peso": 1.2,
"Valor": 16.0,
"SlotHoraria": "09H-13H",
"TipoServico": "E",
"Material_Recolha": "Material Recolha",
"Material_Entrega": "Material Entrega",
"Observacoes": "Observations",
"Referencia": "ref123"
}
response = requests.post(url, headers=headers, json=payload)
print(response.text)fetch("https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer your_access_token"
},
body: JSON.stringify({
NumConta: 0000,
NumServico: "",
DataServico: "2021-11-28",
Nome: "ViaDirecta Lda",
Morada: "Rua da Escola Primaria Lt 41",
CodPost: "2660-032",
LocPost: "Frielas",
EMAIL: "email@email.com",
Contacto: "218112800",
Telefone: "912345678",
Pais: "PT",
NumVolumes: 1,
Peso: 1.2,
Valor: 16.0,
SlotHoraria: "09H-13H",
TipoServico: "E",
Material_Recolha: "Material Recolha",
Material_Entrega: "Material Entrega",
Observacoes: "Observations",
Referencia: "ref123"
})
})
.then(response => response.json())
.then(data => console.log("Envio criado:", data))
.catch(error => console.error("Error:", error));3. Shipment Status
Returns the current status of a shipment.
Authorization: Bearer <access_token>
Query Parameters
| Parameter | Description | Example |
|---|---|---|
CodSRV | Shipment tracking number | VD123456789 |
numConta | Account number | 0000 |
Code examples
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
+ "?CodSRV=VD123456789&numConta=0000";
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "your_access_token");
var response = await client.GetAsync(url);
Console.WriteLine(await response.Content.ReadAsStringAsync());
}
}
}<?php
$url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
. "?CodSRV=VD123456789&numConta=0000";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer your_access_token"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;import requests
url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
params = {"CodSRV": "VD123456789", "numConta": "0000"}
headers = {"Authorization": "Bearer your_access_token"}
response = requests.get(url, headers=headers, params=params)
print(response.text)fetch("https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
+ "?CodSRV=VD123456789&numConta=0000", {
method: "GET",
headers: { "Authorization": "Bearer your_access_token" }
})
.then(response => response.json())
.then(data => console.log("Estado do envio:", data))
.catch(error => console.error("Error:", error));4. Tracking History
Returns the full operation history of a shipment.
Authorization: Bearer <access_token>
Query Parameters
| Parameter | Description | Example |
|---|---|---|
CodSrv | Shipment tracking number | VD307144207468 |
NumConta | Account number | 3071 |
Hist | If True, returns the full history; otherwise returns only the current status | True |
Code examples
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
+ "?CodSrv=VD307144207468&NumConta=3071&Hist=True";
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "your_access_token");
var response = await client.GetAsync(url);
Console.WriteLine(await response.Content.ReadAsStringAsync());
}
}
}<?php
$url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
. "?CodSrv=VD307144207468&NumConta=3071&Hist=True";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer your_access_token"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;import requests
url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
params = {"CodSrv": "VD307144207468", "NumConta": "3071", "Hist": "True"}
headers = {"Authorization": "Bearer your_access_token"}
response = requests.get(url, headers=headers, params=params)
print(response.text)fetch("https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
+ "?CodSrv=VD307144207468&NumConta=3071&Hist=True", {
method: "GET",
headers: { "Authorization": "Bearer your_access_token" }
})
.then(response => response.json())
.then(data => console.log("Histórico de tracking:", data))
.catch(error => console.error("Error:", error));5. Get Label / Waybill
Returns a PDF document associated with a shipment. Use the TypeFile parameter to specify the document type.
Authorization: Bearer <access_token>
Query Parameters
| Parameter | Description | Example |
|---|---|---|
CodSRV | Shipment tracking number | VD123456789 |
numConta | Account number | 0000 |
TypeFile | Label — shipping label · GuiaTransp — transport waybill | Label |
Code examples
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.IO;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
+ "?CodSRV=VD123456789&numConta=0000&TypeFile=Label";
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "your_access_token");
var response = await client.GetAsync(url);
response.EnsureSuccessStatusCode();
var bytes = await response.Content.ReadAsByteArrayAsync();
File.WriteAllBytes("VD123456789.pdf", bytes);
Console.WriteLine("PDF guardado como VD123456789.pdf");
}
}
}<?php
$url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
. "?CodSRV=VD123456789&numConta=0000&TypeFile=Label";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer your_access_token"
]);
$response = curl_exec($ch);
curl_close($ch);
// Guardar o PDF
file_put_contents("VD123456789.pdf", $response);
echo "PDF guardado como VD123456789.pdf";import requests
url = "https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
params = {"CodSRV": "VD123456789", "numConta": "0000", "TypeFile": "Label"}
headers = {"Authorization": "Bearer your_access_token"}
response = requests.get(url, headers=headers, params=params)
with open("VD123456789.pdf", "wb") as f:
f.write(response.content)
print("PDF guardado como VD123456789.pdf")fetch("https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD"
+ "?CodSRV=VD123456789&numConta=0000&TypeFile=Label", {
method: "GET",
headers: { "Authorization": "Bearer your_access_token" }
})
.then(response => response.blob())
.then(blob => {
const url = window.URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "VD123456789.pdf";
document.body.appendChild(a);
a.click();
a.remove();
})
.catch(error => console.error("Error:", error));