API ViaDireta
Documentación técnica para integración programática con la plataforma ViaDireta.
Nuestra API permite integrar operaciones de transporte directamente en sus aplicaciones. Con ella puede:
- Autenticarse vía OAuth2 y obtener tokens de acceso.
- Crear nuevos envíos con todos los detalles del destinatario y servicio.
- Consultar el estado actual de un envío.
- Acceder al historial completo de seguimiento.
- Generar y descargar documentos PDF (etiquetas y guías de transporte).
Ejemplos de código disponibles en C#, PHP, Python y JavaScript.
1. Autenticación — Obtener Token
Use este endpoint para obtener un token de autenticación proporcionando sus credenciales. El token devuelto debe incluirse como Bearer en el encabezado Authorization en todas las solicitudes siguientes.
Parámetros de la solicitud
Content-Type: application/x-www-form-urlencoded
| Parámetro | Descripción | Ejemplo |
|---|---|---|
username | Su nombre de usuario | your_username |
password | Su contraseña | your_password |
grant_type | Tipo de concesión — usar siempre password | password |
Ejemplos 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. Crear Envío
Crea un nuevo envío. El cuerpo de la solicitud debe estar en formato JSON e incluir todos los parámetros obligatorios.
Authorization: Bearer <access_token> · Content-Type: application/json
Parámetros obligatorios
| Parámetro | Descripción | Tipo |
|---|---|---|
NumConta | Su número de cuenta | Integer |
NumServico | Número de seguimiento — puede generarse automáticamente si está vacío (requiere activación en la cuenta) | String (máx. 25) |
Referencia | Su referencia o ID del envío | String (máx. 30) |
DataServico | Fecha de entrega prevista | Date YYYY-MM-DD |
Nome | Nombre del destinatario | String (máx. 120) |
Morada | Dirección del destinatario | String (máx. 170) |
CodPost | Código postal del destinatario | String (máx. 8) |
LocPost | Localidad del destinatario | String (máx. 50) |
Pais | País del destinatario (ISO 3166-1 alpha-2) | String (máx. 2) |
Contacto | Contacto(s) del destinatario — puede incluir múltiples números | String (máx. 80) |
Telefone | Parámetro heredado — enviar vacío | String (máx. 12) |
EMAIL | Email del destinatario | String (máx. 120) |
NumVolumes | Número de bultos (mínimo 1) | Integer |
Peso | Peso total | Float |
Valor | Valor de reembolso contra entrega (COD) | Float |
TipoServico | "E" — Entrega · "R" — Recogida · "ER" — Entrega + Recogida | String |
SlotHoraria | Franja horaria de entrega preferida | String (máx. 20) |
Material_Recolha | Descripción de la recogida | String (máx. 150) |
Material_Entrega | Descripción del envío | String (máx. 150) |
Parámetros opcionales
| Parámetro | Descripción | Tipo |
|---|---|---|
Referencia2 | Referencia secundaria del envío | String (máx. 30) |
Observacoes | Observaciones del envío | String (máx. 300) |
ObsAgenda | Observaciones adicionales para la agenda | String (máx. 50) |
Parámetros avanzados — utilizar solo con instrucciones específicas de ViaDireta
| Parámetro | Descripción | Tipo |
|---|---|---|
ServicoPreDef | Valor proporcionado por ViaDireta | Integer |
CentroCusto | Valor proporcionado por ViaDireta | Integer |
NomeOR | Nombre del destinatario (alternativo) | String (máx. 120) |
MoradaOR | Dirección alternativa | String (máx. 170) |
CodPostOR | Código postal alternativo | String (máx. 8) |
LocPostOR | Localidad 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 |
Ejemplos 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 del Envío
Devuelve el estado actual de un envío.
Authorization: Bearer <access_token>
Query Parameters
| Parámetro | Descripción | Ejemplo |
|---|---|---|
CodSRV | Número de seguimiento del envío | VD123456789 |
numConta | Número de cuenta | 0000 |
Ejemplos 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. Historial de Seguimiento
Devuelve el historial completo de operaciones de un envío.
Authorization: Bearer <access_token>
Query Parameters
| Parámetro | Descripción | Ejemplo |
|---|---|---|
CodSrv | Número de seguimiento del envío | VD307144207468 |
NumConta | Número de cuenta | 3071 |
Hist | Si True, devuelve el historial completo; de lo contrario devuelve solo el estado actual | True |
Ejemplos 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. Obtener Etiqueta / Guía de Transporte
Devuelve un documento PDF asociado a un envío. Use el parámetro TypeFile para especificar el tipo de documento.
Authorization: Bearer <access_token>
Query Parameters
| Parámetro | Descripción | Ejemplo |
|---|---|---|
CodSRV | Número de seguimiento del envío | VD123456789 |
numConta | Número de cuenta | 0000 |
TypeFile | Label — etiqueta de envío · GuiaTransp — guía de transporte | Label |
Ejemplos 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));