myTeam

MSS 5.1 - Extensibility - myTeam - Guia de Integração

O myTeam disponibiliza dois mecanismos de extensibilidade que permitem integrar conteúdos externos diretamente na aplicação:

• Extensibilidade de Tabs — Adiciona separadores personalizados dentro de ecrãs existentes (ex.: ficha de entidade, monitor de vendas).

• Extensibilidade de Menu — Adiciona entradas de menu na barra lateral que abrem páginas externas dentro da aplicação.

Ambos os mecanismos partilham o mesmo modelo de comunicação: o myTeam faz um pedido HTTP POST ao URL externo configurado, enviando dados de autenticação e contexto. O serviço externo valida a autenticação, processa o pedido e devolve uma página HTML completa que é apresentada num iframe dentro do myTeam.

O serviço externo pode ser implementado em qualquer linguagem ou framework web (ASP.NET, Node.js, PHP, Python, Java, etc.), desde que consiga receber pedidos HTTP POST e devolver HTML.

Exemplos Práticos

Para exemplos práticos de payloads para cada cenário, consulte:

• Entities Tab - Payloads para a ficha de entidade (ENTD)

• Monitors Tab - Payloads para monitores de vendas (MVND) e encomendas (MENC)

• Menu Extensibility - Payloads para extensibilidade de menu

Arquitetura Geral

O fluxo de comunicação entre o myTeam e o serviço externo:

1. O utilizador interage com o myTeam (clica num tab ou entrada de menu).

2. O browser envia um HTTP POST (via JavaScript) ao URL externo configurado.

3. O serviço externo recebe o pedido, valida a autenticação e processa os dados.

4. O serviço externo devolve uma página HTML completa (status 200).

5. O myTeam apresenta o HTML devolvido dentro de um iframe.

┌──────────────────────────────────────────────────┐
│               myTeam (Browser)                   │
│                                                  │
│   Utilizador clica num tab / menu                │
│         │                                        │
│         ▼                                        │
│   JavaScript envia HTTP POST                     │
│         │                                        │
│   ┌─────────────────────────────────────────┐    │
│   │              iframe                     │    │
│   │  HTML devolvido pelo serviço externo    │    │
│   └─────────────────────────────────────────┘    │
└──────────────────────────────────────────────────┘
              │ HTTP POST (payload)
              ▼
┌──────────────────────────────────────────────────┐
│          Serviço Externo (Parceiro)              │
│                                                  │
│   1. Recebe payload (autenticação + filtros)     │
│   2. Valida credenciais                          │
│   3. Processa dados de negócio                   │
│   4. Devolve página HTML (status 200)            │
└──────────────────────────────────────────────────┘

Protocolo de Comunicação

Pedido (POST)

Estrutura do Payload

{
  "authentication": {
    "user": "admin",
    "hash": "a1b2c3d4..."
  },
  "filter": {
    "chave1": "valor1",
    "chave2": "valor2"
  }
}

Campo authentication

Campo	Tipo	Descrição
user	string	Código do utilizador com sessão ativa no myTeam (campo USRUSR)
hash	string	Hash da password do utilizador (campo USRPWD da tabela MSUSR)

Campo filter

Contém pares chave-valor com informação de contexto. Os filtros variam consoante o tipo de extensibilidade e a configuração. Consulte as secções específicas para detalhes:

Extensibilidade de Tabs:

Módulo	Código	Filtros disponíveis
Ficha de Entidade	ENTD	entityId
Monitor de Vendas	MVND	currentStartDate, currentEndDate, previousStartDate, previousEndDate, relativeData
Monitor de Encomendas	MENC	Iguais ao Monitor de Vendas

Extensibilidade de Menu:

A extensibilidade de menu não envia filtros adicionais — o campo filter é sempre um objeto vazio {}. A identificação do utilizador é feita através do campo authentication, e o serviço externo pode consultar a tabela MSUSR para obter qualquer informação adicional sobre o utilizador (nome, código de vendedor, etc.).

Resposta

O serviço externo deve devolver:

Elemento	Requisito
Status code	200 OK para sucesso
Content-Type	text/html
Body	Página HTML completa (com <html>, <head>, <body>)

O HTML devolvido deve ser autocontido — com os seus próprios estilos CSS, scripts e referências a recursos.

O myTeam injeta automaticamente uma tag <base> no HTML devolvido, apontando para o diretório do URL externo. Isto permite que referências relativas a CSS, imagens e scripts sejam resolvidas corretamente.

Tratamento de Erros

O myTeam trata automaticamente os seguintes cenários:

Cenário	Comportamento
Status 401 / 403	Mensagem de erro de autenticação
Status 4xx / 5xx	Mensagem de erro genérica do serviço
Resposta vazia (200)	Mensagem de "sem resposta"
Timeout (> 30 segundos)	Mensagem de timeout
Serviço indisponível	Mensagem de erro de ligação

---

Autenticação

O serviço externo é responsável por validar a autenticação em cada pedido (modelo stateless):

1. Extrair user e hash do campo authentication do payload.

2. Consultar a tabela MSUSR da base de dados do myTeam.

3. Verificar que existe um registo com USRUSR = user e USRPWD = hash.

Se a validação falhar, o serviço deve devolver um status HTTP 401.

Acesso à Base de Dados

O serviço externo necessita de acesso de leitura à base de dados do myTeam para:

• Validar credenciais (tabela MSUSR).

• Consultar dados de negócio conforme necessário (tabelas STMSCLI, STMSDCC, etc.).

A connection string deve ser configurada no serviço externo e apontar para a mesma base de dados utilizada pelo myTeam.

---

Extensibilidade de Tabs

Permite adicionar separadores personalizados dentro de ecrãs existentes. Cada tab carrega conteúdo externo via iframe quando o utilizador o seleciona.

Módulos Disponíveis

Módulo	Código	Filtros enviados
Ficha de Entidade	ENTD	entityId — Código da entidade aberta
Monitor de Vendas	MVND	currentStartDate, currentEndDate, previousStartDate, previousEndDate, relativeData
Monitor de Encomendas	MENC	Iguais ao Monitor de Vendas

Configuração

Ecrã de administração "Extensibilidade de tabs" (Módulo 161):

1. Criar um novo tab, selecionando o módulo destino (ENTD, MVND ou MENC).

2. Definir o URL do serviço externo.

3. Definir o nome do tab (com traduções para os idiomas: PT, EN, ES, FR).

4. Definir a ordem de apresentação.

5. Ativar ou desativar o tab conforme necessário.

Comportamento

• O tab aparece como separador adicional dentro do ecrã configurado.

• Ao clicar no tab, o myTeam faz POST ao URL externo com autenticação e filtros de contexto da página.

• O conteúdo devolvido é carregado no iframe do tab.

• O tab é carregado apenas quando selecionado (lazy loading).

---

Extensibilidade de Menu

Permite adicionar entradas na barra lateral de navegação do myTeam. Ao clicar, o utilizador navega para uma página dedicada dentro da aplicação que apresenta o conteúdo externo em iframe.

Configuração

Ecrã de administração "Menu de extensibilidade" (Módulo 89):

1. Criar uma nova entrada de menu com nome, URL, posição e ícone (opcional).

2. Atribuir utilizadores com acesso à entrada, ou definir como disponível para todos.

Payload

Na extensibilidade de menu, o campo filter é sempre um objeto vazio {}. A identificação do utilizador é feita exclusivamente pelo campo authentication. O serviço externo pode consultar a tabela MSUSR para obter dados adicionais do utilizador (nome, código de vendedor, etc.).

Comportamento

• A entrada aparece na barra lateral de navegação, com ícone e nome configurados.

• Ao clicar, o utilizador navega para uma página dentro do myTeam.

• A página apresenta o conteúdo externo em iframe de ecrã inteiro.

• O nome da entrada é apresentado no cabeçalho da página.

• A navegação do browser (voltar/avançar) funciona normalmente.

• O acesso é protegido por permissões — apenas utilizadores autorizados podem aceder.

---

CORS

Como o pedido é feito pelo browser via JavaScript (fetch), o serviço externo deve permitir pedidos cross-origin:

Header	Valor
Access-Control-Allow-Origin	Origem do myTeam (ex.: https://myteam.empresa.com) ou *
Access-Control-Allow-Methods	POST
Access-Control-Allow-Headers	Content-Type

Guia de Implementação

1. Criar o Endpoint

Criar um endpoint HTTP que aceite POST e leia o parâmetro payload do body:

FUNÇÃO HandleRequest(pedido):

    // 1. Ler payload do body
    payloadJson = pedido.FormData["payload"]
    payload = JSON.Parse(payloadJson)

    // 2. Validar autenticação
    utilizador = ConsultarBD(
        "SELECT * FROM MSUSR WHERE USRUSR = ? AND USRPWD = ?",
        payload.authentication.user,
        payload.authentication.hash
    )

    SE utilizador == null:
        DEVOLVER StatusCode(401)

    // 3. Ler filtros de contexto (apenas para extensibilidade de tabs)
    entityId = payload.filter["entityId"]

    // 4. Processar dados de negócio
    dados = ConsultarDados(entityId, ...)

    // 5. Devolver página HTML
    html = GerarPaginaHTML(dados)
    DEVOLVER StatusCode(200), ContentType("text/html"), Body(html)

2. Estruturar o HTML de Resposta

A página HTML devolvida deve ser autocontida:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <style>
        body { font-family: sans-serif; margin: 16px; }
        table { width: 100%; border-collapse: collapse; }
        th, td { padding: 8px; border: 1px solid #e0e0e0; }
        th { background: #f5f5f5; }
    </style>
</head>
<body>
    <h3>Informação do Cliente</h3>
    <table>
        <tr><th>Código</th><td>CLI001</td></tr>
        <tr><th>Nome</th><td>Empresa Exemplo, Lda.</td></tr>
        <tr><th>NIF</th><td>123456789</td></tr>
    </table>
</body>
</html>

3. Configurar CORS

Garantir que o serviço permite pedidos cross-origin com o header Access-Control-Allow-Origin adequado.

4. Registar no myTeam

Utilizar o ecrã de administração correspondente para registar o URL do endpoint e atribuir permissões.

5. Testar

• Verificar que o endpoint responde corretamente a um POST com payload de teste.

• No myTeam, aceder ao tab ou entrada de menu configurada.

• Confirmar que o conteúdo é apresentado corretamente dentro da aplicação.

• Testar cenários de erro: serviço indisponível, credenciais inválidas, resposta vazia.

---

Comparação entre Tab e Menu

Aspeto	Extensibilidade de Tab	Extensibilidade de Menu
Onde aparece	Separador dentro de um ecrã existente	Entrada na barra lateral de navegação
Módulos disponíveis	ENTD, MVND, MENC	Qualquer (entrada independente)
Filtros de contexto	Específicos do ecrã (entityId, datas)	Nenhum (filter vazio)
Configuração	Módulo 161 — Extensibilidade de tabs	Módulo 89 — Menu de extensibilidade
Comportamento	Carrega dentro do ecrã atual	Navega para nova página dentro da aplicação
Multi-idioma	Sim (nome do tab traduzido)	Não (nome único)

Requisitos Técnicos

#	Requisito	Detalhe
1	Endpoint HTTP POST	Capaz de receber application/x-www-form-urlencoded com o parâmetro payload
2	Parsing de JSON	Para extrair autenticação e filtros do payload
3	Acesso à BD do myTeam	Leitura da tabela MSUSR (mínimo para autenticação) e restantes tabelas conforme necessidade
4	Resposta HTML	Página completa, autocontida, com status 200
5	CORS	Headers de permissão para pedidos cross-origin
6	HTTPS	Recomendado em ambientes de produção