119 lines
3.3 KiB
Markdown
119 lines
3.3 KiB
Markdown
# 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`
|
|
|
|
```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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
OUTBOX_TARGET_SYSTEM=packlink \
|
|
PACKLINK_OUTBOX_ENABLED=true \
|
|
OUTBOX_DRY_RUN=true \
|
|
python scripts/process_outbox.py
|
|
```
|
|
|
|
Criação real de envio:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
1. Operador clica em `Criar envio Packlink` na oportunidade.
|
|
2. 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`
|
|
3. `scripts/process_outbox.py` processa o item.
|
|
4. O Packlink devolve uma `reference`.
|
|
5. 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.
|