HTTPS OAuth 2.0 Bearer Token

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

POST https://www.viadirectanet.pt/WebApiOAuth/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

ParameterDescriptionExample
usernameYour usernameyour_username
passwordYour passwordyour_password
grant_typeGrant type — always use passwordpassword

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

POST https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD

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

ParameterDescriptionType
NumContaYour account numberInteger
NumServicoTracking number — can be auto-generated if empty (requires account activation)String (máx. 25)
ReferenciaYour reference or shipment IDString (máx. 30)
DataServicoExpected delivery dateDate YYYY-MM-DD
NomeRecipient nameString (máx. 120)
MoradaRecipient addressString (máx. 170)
CodPostRecipient postcodeString (máx. 8)
LocPostRecipient cityString (máx. 50)
PaisRecipient country (ISO 3166-1 alpha-2)String (máx. 2)
ContactoRecipient contact(s) — may include multiple numbersString (máx. 80)
TelefoneLegacy parameter — send emptyString (máx. 12)
EMAILRecipient emailString (máx. 120)
NumVolumesNumber of items (minimum 1)Integer
PesoTotal weightFloat
ValorCash on delivery (COD) valueFloat
TipoServico"E" — Delivery  ·  "R" — Pickup  ·  "ER" — Delivery + PickupString
SlotHorariaPreferred delivery time slotString (máx. 20)
Material_RecolhaPickup descriptionString (máx. 150)
Material_EntregaShipment descriptionString (máx. 150)

Optional parameters

ParameterDescriptionType
Referencia2Secondary shipment referenceString (máx. 30)
ObservacoesShipment notesString (máx. 300)
ObsAgendaAdditional scheduling notesString (máx. 50)
Advanced parameters — use only with specific ViaDireta instructions
ParameterDescriptionType
ServicoPreDefValue provided by ViaDiretaInteger
CentroCustoValue provided by ViaDiretaInteger
NomeORRecipient name (alternative)String (máx. 120)
MoradaORAlternative addressString (máx. 170)
CodPostORAlternative postcodeString (máx. 8)
LocPostORAlternative cityString (máx. 50)
CodPaisORAlternative country (ISO 3166-1 alpha-2)String (máx. 2)
ContactoORAlternative contactString (máx. 80)
CodigoPINPinCode — 0 = False, 1 = TrueBoolean

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

GET https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD

Returns the current status of a shipment.

Authorization: Bearer <access_token>

Query Parameters

ParameterDescriptionExample
CodSRVShipment tracking numberVD123456789
numContaAccount number0000

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

GET https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD

Returns the full operation history of a shipment.

Authorization: Bearer <access_token>

Query Parameters

ParameterDescriptionExample
CodSrvShipment tracking numberVD307144207468
NumContaAccount number3071
HistIf True, returns the full history; otherwise returns only the current statusTrue

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

GET https://www.viadirectanet.pt/WebApiOAuth/api/ServiceVD

Returns a PDF document associated with a shipment. Use the TypeFile parameter to specify the document type.

Authorization: Bearer <access_token>

Query Parameters

ParameterDescriptionExample
CodSRVShipment tracking numberVD123456789
numContaAccount number0000
TypeFileLabel — shipping label  ·  GuiaTransp — transport waybillLabel
Note: The response is a binary PDF file. Your application must be prepared to handle binary responses.

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