API ViaDireta
Documentação técnica para integração programática com a plataforma ViaDireta.
A nossa API permite integrar operações de transporte diretamente nas suas aplicações. Com ela pode:
- Autenticar via OAuth2 e obter tokens de acesso.
- Criar novos envios com todos os detalhes de destinatário e serviço.
- Consultar o estado atual de um envio.
- Aceder ao histórico completo de tracking.
- Gerar e descarregar documentos PDF (etiquetas e guias de transporte).
Exemplos de código disponíveis em C#, PHP, Python e JavaScript.
1. Autenticação — Obter Token
Utilize este endpoint para obter um token de autenticação fornecendo as suas credenciais. O token retornado deve ser incluído como Bearer no cabeçalho Authorization em todos os pedidos seguintes.
Parâmetros do pedido
Content-Type: application/x-www-form-urlencoded
| Parâmetro | Descrição | Exemplo |
|---|---|---|
username | O seu nome de utilizador | your_username |
password | A sua palavra-passe | your_password |
grant_type | Tipo de concessão — usar sempre password | password |
Exemplos de código
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. Criar Envio
Cria um novo envio. O corpo do pedido deve estar em formato JSON e incluir todos os parâmetros obrigatórios.
Authorization: Bearer <access_token> · Content-Type: application/json
Parâmetros obrigatórios
| Parâmetro | Descrição | Tipo |
|---|---|---|
NumConta | O seu número de conta | Integer |
NumServico | Número de tracking — pode ser gerado automaticamente se vazio (requer ativação na conta) | String (máx. 25) |
Referencia | A sua referência ou ID do envio | String (máx. 30) |
DataServico | Data de entrega prevista | Date YYYY-MM-DD |
Nome | Nome do destinatário | String (máx. 120) |
Morada | Morada do destinatário | String (máx. 170) |
CodPost | Código postal do destinatário | String (máx. 8) |
LocPost | Localidade do destinatário | String (máx. 50) |
Pais | País do destinatário (ISO 3166-1 alpha-2) | String (máx. 2) |
Contacto | Contacto(s) do destinatário — pode incluir múltiplos números | String (máx. 80) |
Telefone | Parâmetro legado — enviar vazio | String (máx. 12) |
EMAIL | Email do destinatário | String (máx. 120) |
NumVolumes | Número de volumes (mínimo 1) | Integer |
Peso | Peso total | Float |
Valor | Valor de reembolso contra-entrega (COD) | Float |
TipoServico | "E" — Entrega · "R" — Recolha · "ER" — Entrega + Recolha | String |
SlotHoraria | Período horário de entrega preferido | String (máx. 20) |
Material_Recolha | Descrição da recolha | String (máx. 150) |
Material_Entrega | Descrição do envio | String (máx. 150) |
Parâmetros opcionais
| Parâmetro | Descrição | Tipo |
|---|---|---|
Referencia2 | Referência secundária do envio | String (máx. 30) |
Observacoes | Observações do envio | String (máx. 300) |
ObsAgenda | Observações adicionais para a agenda | String (máx. 50) |
Parâmetros avançados — utilizar apenas com instruções específicas da ViaDireta
| Parâmetro | Descrição | Tipo |
|---|---|---|
ServicoPreDef | Valor fornecido pela ViaDireta | Integer |
CentroCusto | Valor fornecido pela ViaDireta | Integer |
NomeOR | Nome do destinatário (alternativo) | String (máx. 120) |
MoradaOR | Morada alternativa | String (máx. 170) |
CodPostOR | Código postal alternativo | String (máx. 8) |
LocPostOR | Localidade alternativa | String (máx. 50) |
CodPaisOR | País alternativo (ISO 3166-1 alpha-2) | String (máx. 2) |
ContactoOR | Contacto alternativo | String (máx. 80) |
CodigoPIN | PinCode — 0 = False, 1 = True | Boolean |
Exemplos de código
{
"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. Estado do Envio
Retorna o estado atual de um envio.
Authorization: Bearer <access_token>
Query Parameters
| Parâmetro | Descrição | Exemplo |
|---|---|---|
CodSRV | Número de tracking do envio | VD123456789 |
numConta | Número de conta | 0000 |
Exemplos de código
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. Histórico de Tracking
Retorna o histórico completo de operações de um envio.
Authorization: Bearer <access_token>
Query Parameters
| Parâmetro | Descrição | Exemplo |
|---|---|---|
CodSrv | Número de tracking do envio | VD307144207468 |
NumConta | Número de conta | 3071 |
Hist | Se True, retorna o histórico completo; caso contrário retorna apenas o estado atual | True |
Exemplos de código
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. Obter Etiqueta / Guia de Transporte
Retorna um documento PDF associado a um envio. Use o parâmetro TypeFile para especificar o tipo de documento.
Authorization: Bearer <access_token>
Query Parameters
| Parâmetro | Descrição | Exemplo |
|---|---|---|
CodSRV | Número de tracking do envio | VD123456789 |
numConta | Número de conta | 0000 |
TypeFile | Label — etiqueta de envio · GuiaTransp — guia de transporte | Label |
Exemplos de código
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));