contracts.read
Lista, filtra e visualiza contratos autorizados.
Rota /contracts
Carteira, cadastro e operação de contratos.
Contrato é o vínculo entre cliente, operadora, produtos, vigência e operação. A rota organiza a carteira; o detalhe separa cadastro, premissas, importações, beneficiários, faturamento, conciliação, sinistralidade e renovação.
contracts.manage
Cria, importa, edita e executa ações de ciclo de vida.
billing.read / billing.manage
Consulta ou administra faturamento, planos, preços e conciliação.
claims.read
Acessa sinistralidade e análises relacionadas ao contrato.
Carteira operacional
Priorizar antes de agir
Vigência e renovação
Prioriza contratos por prazo final e destaca os que entram nas janelas de 30, 60, 90 e 180 dias.
Prontidão operacional
Separa contratos com bloqueadores, que requerem atenção ou que estão em dia, sempre com decisão humana.
Pesquisa e filtros
Busca contrato, operadora, cliente ou estipulante e filtra por cliente, status, produto, prontidão e vigência.
Tabela, cards e árvore
A mesma carteira pode ser lida em tabela, cards ou hierarquia de estipulante e subestipulantes.
Treinamento visual
Passo a passo pela interface
As imagens usam somente registros marcados como demonstração e formulários vazios. Identificação da sessão, e-mails e dados de clientes reais foram excluídos do material público.
1. Leia e filtre a carteira
Comece por vigência, distribuição por seguradora e prontidão. Combine busca, cliente, status, produto e prazo; depois escolha tabela, cards ou árvore conforme a análise.
2. Configure identidade e produtos
Selecione o cliente, porte e responsável; depois marque Saúde, Odonto e/ou Vida. Defina matriz ou subestipulante, operadora, ramo e os identificadores oficiais.
3. Revise e crie
Confira vigência e identificadores antes de criar. Premissas, planos, preços, renovação e regras operacionais são tratados depois no detalhe do contrato.
4. Importe com prévia
Escolha entre clientes já cadastrados ou carteira mista. Baixe o modelo correspondente, preencha, analise sem gravar e confirme o lote somente após revisar os vínculos.
5. Continue no detalhe operacional
Use Ver contrato para cadastro e histórico. Use Auditar para abrir as áreas operacionais abaixo, cuja disponibilidade também depende das permissões e do produto.
Cadastro inicial
O que preencher e por quê
| Campo | Regra | API | Como preencher |
|---|---|---|---|
| Cadastro do cliente | Obrigatório | customerId / newCustomer | Selecione um cliente existente ou crie PF/PJ no mesmo fluxo, sem duplicar o cadastro. |
| Porte do cliente | Obrigatório | customerSize | Classificação comercial Pequeno, Médio ou Grande; não substitui o segmento de atuação. |
| Account manager | Obrigatório | accountManagerUserId | Responsável interno pelo acompanhamento comercial e operacional. |
| Nome para exibição | Opcional | name | Nome canônico usado em tabelas e relatórios. Se vazio, a interface sugere operadora e cliente. |
| Linhas contratadas | Obrigatório | hasHealthCoverage / hasDentalCoverage / hasLifeCoverage | Marque Saúde, Odonto e/ou Vida conforme o contrato; a combinação define o domínio técnico. |
| Subestipulante | Condicional | parentContractId | Ative somente quando o contrato herda a matriz comercial de um estipulante do mesmo tenant e domínio. |
| Operadora / Seguradora | Obrigatório | providerId | Escolha a entidade cadastrada; não use o nome livre para contornar o catálogo. |
| Ramo de seguro | Opcional | insuranceLineId | Classificação regulatória recomendada para Vida e demais produtos securitários. |
| Contrato na operadora | Antes da ativação | operatorContractNumber | Identificador oficial fornecido pela operadora. |
| Número da apólice | Quando aplicável | policyNumber | Referência da apólice nos produtos que a utilizam. |
| Código interno / integração | Opcional | externalCode | Chave estável para legado, integração ou conciliação com outra base. |
| Estimativa de vidas | Opcional | estimatedLives | Estimativa inicial; não substitui a base efetivamente importada. |
| Início e fim | Recomendado | startDate / endDate | Vigência que alimenta alertas, renovação e priorização da carteira. |
HEALTH
Saúde: beneficiários, mensalidades, coparticipação, conciliação e sinistralidade.
DENTAL
Odonto: cobertura odontológica, vidas e faturamento próprios quando contratado isoladamente.
LIFE
Vida: apólice, coberturas, capitais e base segurada, sem forçar parâmetros exclusivos de Saúde.
MULTI
Multibenefícios: combinação de linhas no mesmo vínculo contratual e visão operacional por camada.
Estrutura comercial
Estipulante e subestipulante
Estipulante
É a matriz de planos, preços, regra de cobrança e premissas comerciais.
Subestipulante
Mantém sua operação e população, mas herda a base comercial da matriz indicada.
Validações
A matriz deve pertencer ao mesmo tenant e domínio; um contrato não pode apontar para si próprio.
Duas leituras diferentes
Ver contrato ou Auditar
Ver contrato
Abre o registro cadastral: identidade, estrutura comercial, vigência, premissas e histórico de renovação/reajuste.
Auditar
Abre o cockpit por competência: dados, importações, vidas, faturamento, conciliação, coparticipação, sinistros e insights.
Permissões continuam valendo
Botões de escrita e áreas sensíveis aparecem somente quando o perfil possui a permissão correspondente.
Depois do cadastro
Áreas do detalhe operacional
Visão Geral
Identidade, prontidão, cliente e resumo das camadas.
Importações
Entrada governada de beneficiários, faturamento e movimentações.
Beneficiários
População vinculada e situação cadastral por contrato.
Repositório
Documentos e evidências ligados ao contrato.
Premissas Contratuais
Aniversário, renovação, dependentes, coparticipação, particularidades e versões publicadas.
Base Salarial
Base específica usada nas operações aplicáveis.
Automação e Coleta
Fontes, rotinas e evidências de aquisição dos dados.
Movimentações
Entradas, saídas, divergências e resolução operacional.
Conciliação
Cobrado versus esperado, linhas, pendências e aprovação.
Faturamento
Faturas e itens mensais por competência.
Coparticipação
Eventos de utilização quando previstos no contrato.
Renovação
Histórico, reajustes, cenários e publicação governada.
Sinistralidade
Métricas, eventos, alto custo e evolução mensal.
Insights Estratégicos
Leitura executiva derivada dos dados disponíveis.
Simulação, dado oficial e histórico são coisas diferentes. Uma prévia sem fatura deve permanecer identificada como simulação e não pode ser aprovada como conciliação oficial.
API e permissões
Contratos principais da rota
| Endpoint | Permissão | Responsabilidade |
|---|---|---|
| GET /contracts | contracts.read | Carteira, filtros e priorização. |
| GET /contracts/providers | contracts.read | Operadoras e seguradoras disponíveis. |
| GET /contracts/account-managers | contracts.read | Responsáveis elegíveis no tenant. |
| POST /contracts | contracts.manage | Cadastro de contrato. |
| PATCH /contracts/:id | contracts.manage | Edição cadastral com expectedUpdatedAt; conflito concorrente retorna 409. |
| POST /contracts/imports/portfolio/analyze | contracts.manage | Análise da planilha sem aplicar o lote. |
| POST /contracts/imports/portfolio/:importId/apply | contracts.manage | Aplicação do lote revisado. |
| GET /contracts/:id/readiness | contracts.read | Prontidão e bloqueadores para o ciclo de vida. |
| POST /contracts/:id/activate | contracts.manage | Ativação após validações obrigatórias. |
| POST /contracts/:id/suspend | cancel | contracts.manage | Mudança governada do ciclo de vida. |
| GET /contracts/:id/billing-setup | billing.read | Planos, preços e regra de faturamento. |
| GET /contracts/:id/reconciliation | billing.read | Conciliação por competência. |
Checklist operacional
Antes de criar, ativar ou alterar
O cliente correto foi selecionado ou criado como PF/PJ sem duplicidade.
Porte e account manager representam a responsabilidade comercial atual.
Somente as linhas realmente contratadas foram marcadas.
A operadora e, quando aplicável, o ramo regulatório foram conferidos.
Contrato da operadora, apólice e código de integração não foram confundidos.
Subestipulante aponta para a matriz correta, do mesmo tenant e domínio.
Vigência foi revisada para que alertas e renovação tenham datas confiáveis.
Premissas, planos e preços serão configurados e publicados após o cadastro.
Antes de ativar, os bloqueadores de prontidão foram resolvidos.
Antes de excluir, suspensão ou cancelamento foram avaliados para preservar o histórico.