MVP Open Gateway

Link do caso de uso: Open Gateway

Requisitos

Requisitos Funcionais

• [RF001] Consultar data do último SIM Swap: A API permite que o consumidor consulte a data e hora do último evento de SIM Swap associado a uma linha móvel.

• [RF002] Verificar se houve SIM Swap em um período passado: A API permite verificar se ocorreu SIM Swap dentro de um intervalo definido.

• [RF003] Validar período máximo de verificação: O campo maxAge aceita valores entre 1 e 2400 horas e possui valor padrão de 240 horas quando não informado.

• [RF004] Identificar número da linha via token ou payload: A API identifica o número da linha através do campo phoneNumber obrigatório no corpo da requisição.

• [RF005] Retornar erros padronizados CAMARA: O sistema mapeia erros para Status Codes HTTP padrão e retorna uma estrutura JSON de erro contendo status, code e message.

Requisitos Não Funcionais

• [RNF001] Segurança e Autenticação: A API é protegida através de validação de headers de autenticação. Toda requisição deve conter os headers client_id e access_token.

• [RNF002] Padronização de formatos: Os números de telefone são aceitos e normalizados pelo sistema, removendo símbolos especiais como '+', de acordo com o padrão E.164.

• [RNF003] Observabilidade: A API registra todas as requisições e respostas através do componente LogGenerate. Cada requisição e resposta é logada com informações da operação (retrieve-date ou check), dados da requisição e dados da resposta.

• [RNF004] Extensibilidade: A estrutura de tratamento de erros é extensível, permitindo adicionar novos códigos de erro através do mapeamento de exceções personalizadas.

Regras de Negócio

• [RN001] Regra de identificação do número: A API requer obrigatoriamente o campo phoneNumber no corpo da requisição para identificar a linha móvel.

• [RN002] Limite regulatório de monitoramento: O campo maxAge na operação de check deve estar entre 1 e 2400 horas.

• [RN003] Tratamento de dados indisponíveis: Quando a data do SIM Swap não puder ser fornecida porque o número não existe ou não foi encontrado no banco de dados SPS, a API retorna erro 404 SIM_SWAP.UNKNOWN_PHONE_NUMBER em vez de retornar null.

• [RN004] – Definição de SIM Swap: São considerados SIM Swap eventos registrados na tabela do banco de dados SPS que indicam qualquer mudança na relação MSISDN <-> IMSI, incluindo trocas de SIM por perda ou dano, portabilidade numérica, multisim, nova ativação de SIM para um MSISDN previamente existente ou nova assinatura associada a um número reutilizado.

• [RN005] – Uso para prevenção a fraude: A API é destinada a ser utilizada para avaliação de risco em autenticação baseada em SMS, proteção contra Account Takeover (detectando trocas recentes de SIM) e validação de operações sensíveis como chamadas de call center e transações críticas.

• [RN006] – Serviço não aplicável: O serviço é aplicável a qualquer número de telefone que possua registros na tabela do banco de dados SPS. Se o número não possuir registros ou não existir no banco de dados, a API retorna erro 404 UNKNOWN_PHONE_NUMBER.

Cronograma

RF	Descrição	Início	Tempo em dias	Data Real entrega	Maker	%
01	Construção da API em JAVA QUARKUS para conexão entre o SPS e APIs Open Gw (Sensedia)	15/12/2025	10 dias	06/01/2026	Paula Nunes e Lucas Lacerda	100%
02	Ajustes no código da API conforme orientação do Marcus Valério e Marcos Devoti	07/01/2026	3 dias	12/01/2026	Lucas Lacerda	100%

Histórico

• 22/12/2025:
  • Mensagens entre Sensedia, Algar e Brain para retomada da configuração dos conectores
  • Preencher RFs e cronograma neste link.

• 06/01/2025:
  • Reunião de demonstração da API de conexão JAVA QUARKUS para Marcus Valério e Marcos Devoti..

Equipe

• Paula Nunes
• Lucas Lacerda
• Marcus Brunelli