Release v4928.1.4.2 stable

2026-06-09 22:55:58 +01:00
commit 6445044ac6
280 changed files with 41775 additions and 0 deletions
--- a/docs/PACKLINK_CLIENTFLOW.md
+++ b/docs/PACKLINK_CLIENTFLOW.md
@@ -0,0 +1,118 @@
+# 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.