12. API para Pronto Atendimento - Conexa

1 1. Visão Geral
2 2. Problema de Negócio
- 2.1 2.1 Cenário anterior
- 2.2 2.2 Riscos identificados
3 3. Objetivo da Solução
4 4. CASO DE USO
5 5. Fluxo de Uso (Jornada)
- 5.1 5.1 Fluxo simplificado
6 6. Arquitetura de Funcionamento
7 7. Parâmetros de Configuração
- 7.1 7.1 Parâmetros obrigatórios
- 7.2 7.2 Configuração recomendada
8 8. Regras de Negócio
9 9. Integração entre Sistemas
10 10. Configuração – Mobile Saúde
- 10.1 10.1 Acesso
- 10.2 10.2 Parâmetros
- 10.3 10.3 Aplicação
11 11. Configuração – ERP / Sistema do Cliente
12 12. Validação e Testes
- 12.1 12.1 Funcionais
- 12.2 12.2 Integração
- 12.3 12.3 Edge cases
13 13. Troubleshooting
- 13.1 13.1 Problema
- 13.2 13.2 Causa
- 13.3 13.3 Solução
14 14. Riscos Identificados
15 15. Boas Práticas / Recomendações
16 16. Checklist de Implementação

1. Visão Geral

A funcionalidade Pronto Atendimento - Conexa permite a integração do aplicativo Mobile Saúde com o serviço de telemedicina da Conexa, possibilitando que beneficiários acessem atendimento médico remoto de forma rápida e autenticada.

A funcionalidade realiza a geração de um link mágico (magic link) que autentica automaticamente o usuário no sistema da Conexa, eliminando a necessidade de login manual.

2. Problema de Negócio

2.1 Cenário anterior

Antes da implementação:

Não havia integração direta com serviço de pronto atendimento digital
Usuários precisavam acessar plataformas externas manualmente
Processo de autenticação era separado do app Mobile Saúde
Baixa adesão ao serviço por fricção no acesso

2.2 Riscos identificados

Experiência ruim do usuário (múltiplos logins)
Baixa utilização do serviço de telemedicina
Inconsistência de dados entre sistemas
Dependência de autenticação manual

3. Objetivo da Solução

A solução tem como objetivo:

Integrar o serviço de pronto atendimento da Conexa ao app Mobile Saúde
Permitir acesso com autenticação automática (SSO via magic link)
Reduzir fricção no acesso ao atendimento
Garantir sincronização de dados do beneficiário

4. CASO DE USO

4.1 Descrição da situação

Um cliente da Mobile Saúde desejava oferecer atendimento médico remoto 24h para seus beneficiários, porém enfrentava dificuldades:

Usuários precisavam criar login separado na Conexa
Alto abandono no processo de acesso
Inconsistência cadastral entre sistemas

Impacto:

Baixa utilização do serviço
Reclamações de usuários
Perda de valor percebido do app

4.2 Como resolvemos

Foi implementada a funcionalidade Pronto Atendimento - Conexa com geração automática de magic link, permitindo:

Autenticação transparente
Sincronização automática de dados do paciente
Redirecionamento direto para atendimento

4.3 Passo a passo da solução (com parametrização)

Acessar: Configurador público → Funcionalidades
Selecionar: Pronto Atendimento - Conexa
Configurar:

token = abc123xyz_token_conexa

Mover a funcionalidade para: Funcionalidades ATIVAS

Sincronizar configuração
Validar:

Acessar app
Clicar na funcionalidade
Verificar redirecionamento automático

O token deve ser fornecido pela Conexa e estar válido

5. Fluxo de Uso (Jornada)

Usuário acessa o app Mobile Saúde
Clica em "Pronto Atendimento - Conexa"
Sistema Mobile solicita dados à Conexa
Conexa gera magic link
Usuário é redirecionado automaticamente
Atendimento é iniciado já autenticado

5.1 Fluxo simplificado

[Início]

→ [Usuário acessa funcionalidade]

→ [Mobile chama API Conexa]

→ [Conexa gera magic link]

→ [Redirect para navegador]

→ [Usuário autenticado]

→ [Atendimento iniciado]

→ [Fim]

6. Arquitetura de Funcionamento

A solução funciona via integração entre:

Mobile Saúde (frontend + backend)
APIs da Conexa

Fluxo técnico:

Mobile consome APIs REST da Conexa
Dados do paciente são sincronizados
Link mágico é gerado pela Conexa
Redirecionamento ocorre via navegador

7. Parâmetros de Configuração

7.1 Parâmetros obrigatórios

Parâmetro	Descrição	Valores aceitos

Parâmetro	Descrição	Valores aceitos
token	Token de autenticação da API Conexa	String fornecida pela Conexa

7.2 Configuração recomendada

token: fornecido pelo ambiente produtivo da Conexa

8. Regras de Negócio

O usuário deve possuir CPF ou número do cartão válido
Dados devem estar atualizados para sincronização
O paciente deve existir ou ser criado na Conexa

Caso não seja possível identificar o paciente, o fluxo falha

9. Integração entre Sistemas

Sistemas envolvidos:

Mobile Saúde
API Conexa

Requisitos:

Token válido
Dados consistentes do paciente (CPF, nome, nascimento)

Divergência de dados pode impedir geração do link

10. Configuração – Mobile Saúde

10.1 Acesso

Painel público → Funcionalidades

10.2 Parâmetros

Token da Conexa

10.3 Aplicação

Ativar funcionalidade
Sincronizar
Testar no app

11. Configuração – ERP / Sistema do Cliente

Garantir envio correto de dados do beneficiário:
Nome
CPF
Data de nascimento
Número da carteirinha
Garantir consistência com dados da Conexa

12. Validação e Testes

12.1 Funcionais

Clique na funcionalidade
Redirecionamento correto

12.2 Integração

Mobile → Conexa
Geração de magic link

12.3 Edge cases

Paciente não encontrado
CPF inválido
Token expirado

13. Troubleshooting

13.1 Problema

Usuário não é redirecionado

13.2 Causa

Token inválido
Falha na API Conexa
Dados inconsistentes

13.3 Solução

Validar token
Conferir payload enviado
Testar endpoints manualmente

Endpoints que podem ser validados manualmente

1 - Obtém paciente número do cartão de convênio

URL acionada: https://apidocs.conexasaude.com.br/v1/enterprise/index.html#operation/patientByHealthCardNumber

2 - Caso falha no passo 1, obtém paciente ativo pelo CPF

URL acionada: https://apidocs.conexasaude.com.br/v1/enterprise/index.html#operation/anypatientByCpf

3 - Insere/Atualiza dados do paciente no sistema da Conexa

URL acionada: https://apidocs.conexasaude.com.br/v1/enterprise/index.html#operation/familyGroup

Dados inseridos/atualizado: Nome, email, data de nascimento, sexo, cpf e número do cartão.

4 - Ativa o paciente no sistema da conexa

URL acionada: https://apidocs.conexasaude.com.br/v1/enterprise/index.html#operation/v2PatientActivateById

5 - Gera o link mágico

URL acionada: https://apidocs.conexasaude.com.br/v1/enterprise/index.html#operation/generateMagicLinkPatient

14. Riscos Identificados

Dependência da API Conexa
Token expirado
Falha de sincronização de dados
Indisponibilidade do serviço externo (APIs do Conexa estarem offline)

15. Boas Práticas / Recomendações

Validar dados antes da chamada
Monitorar erros de integração
Utilizar ambiente sandbox antes de produção
Garantir atualização cadastral

16. Checklist de Implementação

[ ] Token configurado corretamente

[ ] Funcionalidade ativada

[ ] Integração validada

[ ] Teste de acesso realizado

[ ] Caso de uso validado