# 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.