Integração Packlink PRO no ClientFlow

Estado validado

Foram validados estes pontos da API Packlink PRO:

GET /clients com Authorization: <PACKLINK_API_KEY> funciona.
GET /locations/postalcodes/PT/3650-219 funciona.
GET /services funciona para Portugal quando os códigos postais são normalizados para 4 dígitos na cotação, por exemplo 3650 → 4000.
Serviço default validado:
- service_id=20571
- carrier=Correos Express
- service=Paq 24
- departure_type=pick-up
- destination_type=home

Configuração `.env`

PACKLINK_ENABLED=true
PACKLINK_OUTBOX_ENABLED=true
PACKLINK_BASE_URL=https://api.packlink.com/v1
PACKLINK_PUBLIC_URL=https://pro.packlink.pt
PACKLINK_API_KEY=...

PACKLINK_DEFAULT_SERVICE_ID=20571
PACKLINK_DEFAULT_SERVICE=Paq 24
PACKLINK_DEFAULT_CARRIER=Correos Express
PACKLINK_SOURCE=PRO
PACKLINK_PLATFORM=PRO
PACKLINK_PLATFORM_COUNTRY=UN

PACKLINK_COLLECTION_TIME=09:00-14:00
PACKLINK_COLLECTION_DAYS_AHEAD=1

PACKLINK_DEFAULT_PACKAGE_HEIGHT=10
PACKLINK_DEFAULT_PACKAGE_WIDTH=20
PACKLINK_DEFAULT_PACKAGE_LENGTH=30
PACKLINK_DEFAULT_PACKAGE_WEIGHT=2

PACKLINK_SENDER_NAME=...
PACKLINK_SENDER_SURNAME=.
PACKLINK_SENDER_COMPANY=...
PACKLINK_SENDER_STREET1=...
PACKLINK_SENDER_STREET2=
PACKLINK_SENDER_ZIP=3650-219
PACKLINK_SENDER_CITY=Vila Nova de Paiva
PACKLINK_SENDER_COUNTRY=PT
PACKLINK_SENDER_PHONE=...
PACKLINK_SENDER_EMAIL=...

PACKLINK_FALLBACK_PHONE=...
PACKLINK_FALLBACK_EMAIL=...

Teste de ligação

python scripts/test_packlink_connection.py

Processamento da outbox

Por segurança, o process_outbox.py corre em dry-run por defeito.

Teste sem criar envio real:

OUTBOX_TARGET_SYSTEM=packlink \
PACKLINK_OUTBOX_ENABLED=true \
OUTBOX_DRY_RUN=true \
python scripts/process_outbox.py

Criação real de envio:

OUTBOX_TARGET_SYSTEM=packlink \
PACKLINK_OUTBOX_ENABLED=true \
OUTBOX_DRY_RUN=false \
python scripts/process_outbox.py

Dados necessários antes de criar envio

A oportunidade precisa de ter dados de entrega em metadata.shipment, metadata.packlink ou numa preparação de tarefa prep_type=shipment.

Campos aceites:

{
  "shipment": {
    "recipient_name": "Nome Cliente",
    "recipient_phone": "+351...",
    "recipient_email": "cliente@example.com",
    "delivery_address": "Rua Exemplo 1, 4000-001 Porto",
    "country": "PT"
  }
}

Se a morada tiver código postal PT completo, o ClientFlow guarda a morada completa, mas normaliza para 4 dígitos apenas na cotação Packlink.

Fluxo implementado

Operador clica em Criar envio Packlink na oportunidade.
Se PACKLINK_ENABLED=true e não foi escrita referência manual, o ClientFlow cria um item integration_outbox:
- target_system=packlink
- action_type=create_shipment
scripts/process_outbox.py processa o item.
O Packlink devolve uma reference.
O ClientFlow regista operation_links com system=packlink, external_type=shipment, status=created.

Notas de segurança

A API key não deve ser colocada no repositório.
O processamento real só deve correr com OUTBOX_DRY_RUN=false depois de confirmares o comportamento de pagamento/rascunho da tua conta Packlink PRO.
A criação de envio pode gerar custos na conta Packlink, dependendo da configuração de pagamento.

3.3 KiB Raw Blame History