# Envios CTT e DPD por API

Liga a CTT Expresso e a DPD para criares o envio a partir da encomenda, imprimires a etiqueta oficial, pedires a recolha, seguires o tracking sozinho e ofereceres entrega em pontos.

Com a CTT Expresso ou a DPD ligadas à Feitora, deixas de copiar moradas para o portal da transportadora. Na encomenda carregas em **Criar envio CTT/DPD**, imprimes a **etiqueta oficial** e a Feitora trata do resto: guarda o tracking, acompanha a entrega e avisa o cliente quando a encomenda é enviada, quando sai para entrega e quando é entregue.

> **Em testes — Ligação por validar com conta real**
> A ligação segue a documentação pública da CTT (webservice CTT Expresso e API e-commerce) e da DPD (DPD Shipping API e lista de pontos DPD Pickup), mas **ainda não foi validada com contas reais**. Sem credenciais, tudo funciona em **modo de testes** (tracking falso, etiqueta de teste, eventos que avançam sozinhos). Antes de enviar a sério, valida as credenciais no ambiente de testes da transportadora e faz um envio real.

## Antes de começar

- Precisas de um **contrato** com a CTT Expresso e/ou a DPD e de pedir o acesso à API.
- **CTT:** Authentication ID, Código de cliente (ClientId), N.º de contrato (ContractId) e, para tracking automático e pontos, as chaves da API e-commerce (App ID, Token e Hash de segurança).
- **DPD:** Token (JWT), Código da unidade (buCode), Código de cliente (customerId) e os códigos de serviço do teu contrato.
- Só o proprietário altera as definições das transportadoras.

## Ligar a transportadora

1. Abre **Definições → Transportadoras**.
2. Liga o interruptor da **CTT Expresso** ou da **DPD Portugal**.
3. Deixa o **Modo de testes** ligado por agora. Liga também o ambiente de testes da própria transportadora (**Servidores de qualidade da CTT** ou **Pré-produção da DPD**).
4. Cola as credenciais em **Credenciais do webservice de envios** (e, na CTT, em **API e-commerce da CTT**; na DPD, os **Códigos de serviço do contrato**).
5. Escolhe o **Serviço por omissão** e o **Formato da etiqueta**: **PDF (10×15 cm)** ou **ZPL (impressora térmica)** para impressoras Zebra.
6. Carrega em **Guardar** e depois em **Testar ligação**.
7. Quando os testes correrem bem, desliga o ambiente de testes e o **Modo de testes**, e guarda.

*(Captura do painel: Definições → Transportadoras: CTT Expresso e DPD Portugal)*

## Remetente, tracking e avisos

Mais abaixo, na mesma página:

- **Tracking e avisos ao cliente** — a **Transportadora por omissão**, de quanto em quanto tempo consultar o tracking (**Consultar o tracking a cada**), **Atualizar o tracking automaticamente**, **Marcar a encomenda como enviada ao criar o envio** e **Avisar o cliente por email** (enviada, em distribuição e entregue).
- **Remetente e local de recolha** — nome, contacto, telefone, email e morada de recolha, por localização. Vazio, usa os dados da localização ou da loja.

*(Captura do painel: Tracking automático e remetente)*

## Criar um envio a partir da encomenda

1. Abre a encomenda (paga e por enviar) e carrega em **Criar envio CTT/DPD**.
2. Escolhe a transportadora e o **Serviço**.
3. Confirma os **Volumes** e o **Peso total** (calculado pelos artigos; vazio usa o peso por defeito).
4. Se o cliente paga na entrega, liga **À cobrança** e confirma o valor. Para mercadoria de valor, liga **Seguro / valor declarado**.
5. Carrega em **Criar envio**. O tracking fica na encomenda e, se assim o definiste, ela passa a **Enviada** e o cliente recebe o email com o tracking.
6. Carrega em **Imprimir etiqueta** e cola-a no volume.

> **Dica — Muitas encomendas de uma vez**
> Em **Encomendas**, seleciona várias e carrega em **Criar envios CTT/DPD**. No fim podes imprimir as etiquetas em lote e pedir uma recolha para todas. Levantamentos na loja, vendas ao balcão, canceladas e encomendas que já têm envio ficam de fora.

## Recolha, anulação e tracking

- **Pedir recolha** — no envio da encomenda (ícone do calendário) escolhe a data, o intervalo de horas, o local de recolha e uma nota para o estafeta.
- **Anular envio** — se te enganaste, anula o envio antes de o volume ser entregue à transportadora.
- **Tracking** — os estados (registado, em trânsito, em distribuição, entregue, entrega falhou, devolvido) entram na cronologia da encomenda e na página de estado que o cliente vê. Os textos dos emails "em distribuição" e "entregue" editam-se em **Definições → Modelos de email**.

## Entrega em pontos CTT e DPD Pickup

Na mesma página da transportadora liga **Entrega num ponto CTT no checkout** (ou **DPD Pickup**). Indica o **Nome no checkout**, o **Preço**, o **Grátis a partir de**, o **Prazo** e o **Peso máximo**. No checkout o cliente escreve o código postal e escolhe a loja ou o cacifo mais perto (só em Portugal). Na encomenda aparece "Entrega no ponto…" e o envio usa o serviço de pontos da transportadora.

## Sem API: etiquetas próprias e CSV

Se ainda não tens acesso à API, podes imprimir etiquetas da loja e exportar as encomendas em CSV para o portal da CTT ou da DPD. Vê [Etiquetas de envio](https://feitora.pt/ajuda/encomendas/etiquetas-de-envio).

## Problemas frequentes

| Problema | O que fazer |
|---|---|
| "Testar ligação" está cinzento | Guarda primeiro as alterações. |
| O teste dá erro de autenticação | Confirma as credenciais e se o ambiente de testes corresponde às chaves que a transportadora te deu. |
| O tracking não atualiza | Liga **Atualizar o tracking automaticamente**. Na CTT, o tracking automático precisa das chaves da API e-commerce. |
| O botão "Criar envio CTT/DPD" não aparece | Nenhuma transportadora está ligada, ou a encomenda é um levantamento na loja. |