HTTPS OAuth 2.0 Bearer Token

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

POST https://www.viadirectanet.pt/WebApiOAuth/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âmetroDescriçãoExemplo
usernameO seu nome de utilizadoryour_username
passwordA sua palavra-passeyour_password
grant_typeTipo de concessão — usar sempre passwordpassword

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

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

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âmetroDescriçãoTipo
NumContaO seu número de contaInteger
NumServicoNúmero de tracking — pode ser gerado automaticamente se vazio (requer ativação na conta)String (máx. 25)
ReferenciaA sua referência ou ID do envioString (máx. 30)
DataServicoData de entrega previstaDate YYYY-MM-DD
NomeNome do destinatárioString (máx. 120)
MoradaMorada do destinatárioString (máx. 170)
CodPostCódigo postal do destinatárioString (máx. 8)
LocPostLocalidade do destinatárioString (máx. 50)
PaisPaís do destinatário (ISO 3166-1 alpha-2)String (máx. 2)
ContactoContacto(s) do destinatário — pode incluir múltiplos númerosString (máx. 80)
TelefoneParâmetro legado — enviar vazioString (máx. 12)
EMAILEmail do destinatárioString (máx. 120)
NumVolumesNúmero de volumes (mínimo 1)Integer
PesoPeso totalFloat
ValorValor de reembolso contra-entrega (COD)Float
TipoServico"E" — Entrega  ·  "R" — Recolha  ·  "ER" — Entrega + RecolhaString
SlotHorariaPeríodo horário de entrega preferidoString (máx. 20)
Material_RecolhaDescrição da recolhaString (máx. 150)
Material_EntregaDescrição do envioString (máx. 150)

Parâmetros opcionais

ParâmetroDescriçãoTipo
Referencia2Referência secundária do envioString (máx. 30)
ObservacoesObservações do envioString (máx. 300)
ObsAgendaObservações adicionais para a agendaString (máx. 50)
Parâmetros avançados — utilizar apenas com instruções específicas da ViaDireta
ParâmetroDescriçãoTipo
ServicoPreDefValor fornecido pela ViaDiretaInteger
CentroCustoValor fornecido pela ViaDiretaInteger
NomeORNome do destinatário (alternativo)String (máx. 120)
MoradaORMorada alternativaString (máx. 170)
CodPostORCódigo postal alternativoString (máx. 8)
LocPostORLocalidade alternativaString (máx. 50)
CodPaisORPaís alternativo (ISO 3166-1 alpha-2)String (máx. 2)
ContactoORContacto alternativoString (máx. 80)
CodigoPINPinCode — 0 = False, 1 = TrueBoolean

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

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

Retorna o estado atual de um envio.

Authorization: Bearer <access_token>

Query Parameters

ParâmetroDescriçãoExemplo
CodSRVNúmero de tracking do envioVD123456789
numContaNúmero de conta0000

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

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

Retorna o histórico completo de operações de um envio.

Authorization: Bearer <access_token>

Query Parameters

ParâmetroDescriçãoExemplo
CodSrvNúmero de tracking do envioVD307144207468
NumContaNúmero de conta3071
HistSe True, retorna o histórico completo; caso contrário retorna apenas o estado atualTrue

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

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

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âmetroDescriçãoExemplo
CodSRVNúmero de tracking do envioVD123456789
numContaNúmero de conta0000
TypeFileLabel — etiqueta de envio  ·  GuiaTransp — guia de transporteLabel
Nota: A resposta é um ficheiro PDF binário. A sua aplicação deve estar preparada para lidar com respostas binárias.

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