Returns Manager — Apresentação de Arquitetura
SonAE MC · Reverse Engineering · Março 2026
SLIDE 1 — Capa
Returns Manager Análise de Arquitetura e Fluxos Funcionais
SonAE MC · Plataforma OutSystems 11 Março 2026
SLIDE 2 — Agenda
- Visão Geral da Aplicação
- Arquitectura de Módulos
- Landscape de Integrações
- Fluxo 1 — Submissão de Devolução Online
- Fluxo 2 — Devolução Presencial em Loja
- Fluxo 3 — Validação e Aprovação Back-Office
- Fluxo 4 — Processamento de Reembolso
- Fluxo 5 — Recolha e Receção do Artigo
- Fluxo 6 — API REST para Canais Externos
- Dependências e Próximos Passos
SLIDE 3 — O que é o Returns Manager
Objetivo: Gestão end-to-end do processo de devoluções de artigos SonAE MC
Utilizadores:
| Perfil | Canal | Ação |
|---|---|---|
| Cliente final | Portal web / App mobile | Submeter e acompanhar devoluções |
| Colaborador de loja | Backoffice instore | Registar devoluções presenciais |
| Operador back-office | Backoffice web | Validar, aprovar e monitorizar |
| Sistema externo | REST API | App mobile, parceiros, canal omnicanal |
Método de reembolso suportado:
- Crédito em cartão bancário
- Pontos Cartão Continente
- Vale de troca em loja
SLIDE 4 — Arquitectura de Módulos (OutSystems 4-Layer Canvas)
┌─────────────────────────────────────────────────────────────┐
│ END-USER LAYER │
│ CW — ReturnsManager_CW BO — ReturnsManagerBackoffice │
│ Ecrãs reactivos / WebBlocks Gestão back-office │
└──────────────────────────┬──────────────────────────────────┘
│
┌───────────── ─────────────▼──────────────────────────────────┐
│ ORCHESTRATION LAYER │
│ BL — ReturnsManager_BL API — ReturnsManager_API │
│ Regras de negócio REST Expose (canal externo) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ CORE BUSINESS LAYER │
│ CS — ReturnsManager_CS │
│ CRUD + entidades de domínio + políticas de devolução │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ FOUNDATION LAYER │
│ IS — ReturnsManager_IS Pat — ReturnsManager_Pat │
│ Integration Services Padrões UI e temas │
│ LIB — Structures_LIB │
│ Estruturas de dados reutilizáveis │
└─────────────────────────────────────────────────────────────┘
Princípio: camadas superiores dependem sempre de camadas inferiores — nunca o inverso.
SLIDE 5 — Landscape de Integrações
Sistemas Externos Integrados
| Sistema | Protocolo | Direção | Finalidade |
|---|---|---|---|
| OMS (Order Management) | REST | Consume | Validação de encomendas e linhas elegíveis |
| SAP / ERP | SOAP | Consume | Criação de nota de devolução e nota de crédito |
| Gateway de Pagamento | REST | Consume | Emissão de reembolso bancário |
| Transportadora / WMS | REST + SOAP | Biderecional | Agendamento de recolha + webhooks de estado |
| Serviço de Notificações | REST | Consume | Envio de email e SMS ao cliente |
| Programa de Fidelização | REST | Consume | Crédito de pontos Cartão Continente |
| Identity Provider | SSO / OAuth | Consume | Autenticação de utilizadores |
| Canais Externos | REST | Expose | App mobile, parceiros, omnicanal |
Volume de Integrações (por OML)
| Tipo | Quantidade | Camada responsável |
|---|---|---|
| REST Expose (endpoints publicados) | 11 | API, IS |
| Consume REST (serviços externos) | 15 | IS (via CustomClients) |
| Consume SOAP (SAP / ERP legacy) | 20 | IS (via CustomClients) |
| Total | 46 |
Nota: Toda a comunicação com sistemas externos passa exclusivamente pelo módulo IS. Os módulos BL, CS, CW e API nunca chamam sistemas externos diretamente.
SLIDE 6 — Fluxo 1: Submissão de Devolução Online
Perfil: Cliente final · Canal: Portal web / App mobile
Passos principais
| # | Passo | Camada | Integração |
|---|---|---|---|
| 1 | Cliente acede ao portal e seleciona "Devolver artigo" | CW | — |
| 2 | Sistema recupera encomendas elegíveis do cliente | BL → IS | OMS REST |
| 3 | Cliente seleciona artigo(s) e motivo | CW | — |
| 4 | Validação de elegibilidade (prazo, política, estado) | BL → CS | DB (política) |
| 5 | Cliente confirma submissão | CW | — |
| 6 | Criação do pedido de devolução no sistema | BL → CS | DB |
| 7 | Estado definido como Pendente | CS | DB |
| 8 | Confirmação apresentada ao cliente (nº de devolução) | CW | — |
Sistemas envolvidos
Cliente → CW → BL → IS → OMS (verificar elegibilidade)
BL → CS → DB (criar e persistir pedido)
Resultado
- Pedido de devolução criado com estado Pendente
- Número de referência gerado e apresentado ao cliente
SLIDE 7 — Fluxo 2: Devolução Presencial em Loja
Perfil: Colaborador de loja · Canal: Backoffice instore
Passos principais
| # | Passo | Camada | Integração |
|---|---|---|---|
| 1 | Colaborador pesquisa encomenda (nº / NIF do cliente) | CW | — |
| 2 | Sistema recupera encomenda do cliente | BL → IS | OMS REST |
| 3 | Colaborador seleciona artigo(s) + inspeciona estado físico | CW | — |
| 4 | Validação de elegibilidade para canal loja | BL → CS | DB (política) |
| 5 | Colaborador confirma receção física do artigo | CW | — |
| 6 | Pedido criado com estado Recebido em Loja | BL → CS | DB |
| 7 | Criação de ordem de devolução no ERP | BL → IS | SAP SOAP |
| 8 | Referência SAP associada ao pedido | CS | DB |
| 9 | Comprovativo impresso / enviado para o colaborador | CW | — |
Sistemas envolvidos
Colaborador → CW → BL → IS → OMS (verificar encomenda)
BL → CS → DB (criar pedido)
BL → IS → SAP (criar ordem de devolução ERP)
Resultado
- Pedido criado com estado Recebido em Loja
- Referência SAP registada → devolução visível no ERP
Diferenças face ao canal online
| Aspeto | Online | Loja |
|---|---|---|
| Quem inicia | Cliente | Colaborador |
| Estado inicial | Pendente | Recebido em Loja |
| Integração SAP | Após aprovação | Imediata (no momento da receção) |
| Recolha agendada | Sim | Não (artigo já entregue) |
SLIDE 8 — Fluxo 3: Validação e Aprovação Back-Office
Perfil: Operador back-office · Canal: Backoffice web
Passos principais
| # | Passo | Camada | Integração |
|---|---|---|---|
| 1 | Operador acede à lista de devoluções pendentes | BO → BL | — |
| 2 | Sistema lista devoluções com estado Pendente | BL → CS | DB |
| 3 | Operador abre detalhe de uma devolução | BO → BL | — |
| 4 | Sistema apresenta devolução + linhas + histórico de estados | BL → CS | DB |
| 5a | Aprovação: operador aprova com notas | BL → CS | DB |
| 5b | Rejeição: operador rejeita com motivo | BL → CS | DB |
| 6 | Log de auditoria criado com operador e decisão | CS | DB |
| 7 | Estado atualizado e visível ao cliente | CS | DB |
Critérios de decisão típicos
- Photographs / evidência de dano
- Prazo de devolução (política por categoria de produto)
- Histórico de devoluções do cliente
- Estado físico reportado (loja) ou declarado (online)
Resultado — Aprovação
- Estado → Aprovado
- Fluxo de reembolso (Fluxo 4) ativado automaticamente
- Fluxo de recolha (Fluxo 5) ativado se canal online
Resultado — Rejeição
- Estado → Rejeitado
- Motivo registado e comunicado ao cliente (Notificações)
- Audit log com operador e timestamp
SLIDE 9 — Fluxo 4: Processamento de Reembolso
Trigger: Automático após aprovação da devolução (evento ou timer BL)
Passos principais
| # | Passo | Camada | Integração |
|---|---|---|---|
| 1 | BL recupera devoluções aprovadas sem reembolso | BL → CS | DB |
| 2 | Emissão de nota de crédito no ERP | BL → IS | SAP SOAP |
| 3a | Cartão bancário: emissão de reembolso | BL → IS | Gateway REST |
| 3b | Pontos Fidelização: crédito de pontos | BL → IS | Fidelização REST |
| 3c | Vale de troca: criação de voucher | BL → CS | DB |
| 4 | Estado de reembolso atualizado | CS | DB |
| 5 | Notificação de confirmação enviada ao cliente | BL → IS | Notificações REST |
Métodos de Reembolso Suportados
| Método | Sistema | Protocolo | SLA típico |
|---|---|---|---|
| Crédito cartão bancário | Gateway Pagamento | REST | 3–5 dias úteis |
| Pontos Cartão Continente | Programa Fidelização | REST | Imediato |
| Vale de troca em loja | Interno (DB) | — | Imediato |
Sistemas envolvidos
BL (timer/evento)
└─→ IS → SAP (nota de crédito — sempre)
└─→ IS → Gateway Pagamento (se reembolso bancário)
└─→ IS → Fidelização (se pontos)
└─→ CS → DB (se vale de troca)
└─→ IS → Notificações (confirmação ao cliente)
SLIDE 10 — Fluxo 5: Recolha e Receção do Artigo (Canal Online)
Trigger: Automático após aprovação de devolução online
Passos principais
| # | Passo | Camada | Integração |
|---|---|---|---|
| 1 | Agendamento de recolha na transportadora | BL → IS | Transportadora REST/SOAP |
| 2 | Referência de recolha e data estimada guardadas | CS | DB |
| 3 | Cliente notificado com data e código de recolha | BL → IS | Notificações REST |
| 4 | Transportadora confirma recolha (webhook) | IS → BL | Callback REST |
| 5 | Estado atualizado para Em Trânsito | CS | DB |
| 6 | Artigo chega ao armazém — confirmação (webhook) | IS → BL | Callback REST |
| 7 | Estado atualizado para Recebido em Armazém | CS | DB |
| 8 | Cliente notificado da receção | BL → IS | Notificações REST |
| 9 | Cliente pode consultar timeline de estado | CW → BL → CS | DB |
Timeline de estados da devolução online
Submetido → Pendente → Aprovado → AguardaRecolha
→ EmTrânsito → RecebidoArmazém → Reembolsado / Rejeitado
Nota sobre Webhooks
A transportadora contacta diretamente o módulo IS via callbacks REST. O IS traduz e encaminha para o BL — padrão anti-corruption layer.
SLIDE 11 — Fluxo 6: API REST para Canais Externos
Perfil: Sistemas externos (app mobile, parceiros, omnicanal)
Endpoints expostos (módulo API)
| Endpoint | Método | Descrição |
|---|---|---|
/returns | POST | Criar pedido de devolução |
/returns/{id} | GET | Consultar detalhe e estado |
/returns/{id}/cancel | PATCH | Cancelar pedido |
/returns | GET | Listar devoluções do cliente |
| (+ outros conforme IS) | — | — |
Fluxo de chamada
Sistema Externo
→ API Module (validação token + mapeamento)
→ BL (regras de negócio — idêntico ao canal web)
→ CS → DB
Características de segurança
- Autenticação por Bearer Token / API Key
- Validação no módulo API antes de qualquer chamada ao BL
- Respostas normalizadas (HTTP status codes standard)
Princípio chave
O módulo API não contém lógica de negócio — é apenas uma camada de tradução e segurança. Toda a lógica está no BL, garantindo comportamento consistente entre todos os canais.
SLIDE 12 — Mapa de Responsabilidades por Módulo
| Módulo | Camada | Responsabilidade | Acede a |
|---|---|---|---|
CW | End-User | Ecrãs reactive (cliente + loja) | BL |
Backoffice | End-User | Ecrãs back-office (aprovação) | BL, CS |
API | Orchestration | REST Expose — canal externo/mobile | BL |
BL | Orchestration | Regras de negócio, orquestração de fluxos | CS, IS |
CS | Core | CRUD entidades, políticas, audit log | DB |
IS | Foundation | Wrappers de sistemas externos | OMS, SAP, Gateway, etc. |
Pat | Foundation | Componentes UI reutilizáveis (temas, padrões) | — |
LIB | Foundation | Estruturas de dados partilhadas | — |
SLIDE 13 — Entidades de Domínio (modelo de dados inferido)
| Entidade | Descrição | Atributos chave |
|---|---|---|
Return | Cabeçalho do pedido de devolução | ReturnId, CustomerId, OrderRef, Status, Channel, CreatedOn |
ReturnLine | Linhas de artigo a devolver | ReturnLineId, ReturnId, ProductId, Qty, Reason, Condition |
ReturnStatus | Histórico de estados | StatusId, ReturnId, Status, ChangedOn, OperatorId |
ReturnReason | Catálogo de motivos de devolução | ReasonId, Code, Description, IsActive |
ReturnPolicy | Políticas por categoria/prazo | PolicyId, Category, MaxDays, AllowedChannels, RefundMethods |
AuditLog | Registo de decisões back-office | LogId, ReturnId, Action, OperatorId, Notes, Timestamp |
Voucher | Vales de troca gerados | VoucherId, ReturnId, CustomerId, Amount, ExpiryDate, IsUsed |
SLIDE 14 — Resumo de Integrações por Fluxo
| Fluxo | OMS | SAP | Pagamento | Transportadora | Notificações | Fidelização |
|---|---|---|---|---|---|---|
| F1 — Submissão Online | ✓ | — | — | — | — | — |
| F2 — Devolução em Loja | ✓ | ✓ | — | — | — | — |
| F3 — Aprovação Back-Office | — | — | — | — | ✓ | — |
| F4 — Reembolso | — | ✓ | ✓ | — | ✓ | ✓ |
| F5 — Recolha/Receção | — | — | — | ✓ | ✓ | — |
| F6 — API Externa | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
SLIDE 15 — Pontos a Confirmar / Próximos Passos
O que falta confirmar (requer acesso ao Service Center / Service Studio)
| Item | Como obter |
|---|---|
| Nomes dos 35 módulos de integração referenciados | SQL em ossys_Espace ou Service Center |
| Endpoints reais das integrações externas (URLs base) | Abrir ReturnsManager_IS no Service Studio → CustomClients |
| Operações SOAP específicas por módulo SAP | Service Studio → Integration → Consume SOAP |
| Regras de elegibilidade detalhadas | Service Studio → BL → Server Actions |
| Timers e eventos automáticos (BPT) | Service Studio → Processes |
| Permissões e roles definidos | Service Studio → Users & Roles |
SQL de lookup dos 35 módulos de integração
-- Colar no SQL Server da plataforma OutSystems
SELECT LOWER(CAST(e.[Guid] AS VARCHAR(36))) AS GUID, e.Name, e.Description, e.Kind
FROM ossys_Espace e
WHERE LOWER(CAST(e.[Guid] AS VARCHAR(36))) IN (
'0ab06d19-d645-444d-a0fb-fae8dbc67e7b', -- SOAP #1
'0ce7ac57-75f1-467b-96f4-352a6b42f8cc', -- SOAP #2
'17e33556-ccf4-4cbf-818d-e117c090e305', -- REST #1
-- ... ver tabela completa em integrations-table.md
)
ORDER BY e.Kind, e.Name
SLIDE 16 — Conclusão
Arquitetura bem estruturada
- Separação clara entre UI, lógica, dados e integrações
- Anti-corruption layer no IS — sistemas externos isolados
- API module garante consistência omnicanal
Cobertura funcional completa
- 3 canais (online, loja, API externa)
- 3 métodos de reembolso
- Pipeline de estados rastreável com audit log
Complexidade de integração
- 46 integrações (20 SOAP + 15 REST + 11 Expose)
- SAP como sistema crítico (SOAP — síncrono, sem retry nativo fácil)
- Webhooks da transportadora — dependência assíncrona crítica
Recomendações
- Mapear nomes reais dos 35 módulos via SQL / Service Center
- Documentar contratos de API dos sistemas externos (WSDL / OpenAPI)
- Validar gestão de erros nas integrações SAP SOAP
- Confirmar estratégia de retry/idempotência no fluxo de reembolso
Documento gerado por análise de reverse engineering dos OML — Returns Manager v11 · SonAE MC