API beneficiaryPosition - Endpoint: Pesquisa de Beneficiários

CONTEÚDO

Visão Geral
Exemplo de utilização
1. Pesquisa de Beneficiários
2. Tabela de Código de Erros
Tela Pesquisa de Beneficiários
1. Outras Ações / Ações relacionadas
Tela Pesquisa de Beneficiários
1. Principais Campos e Parâmetros
Tabelas utilizadas

01. VISÃO GERAL

Este documento tem como objetivo demonstrar a utilização do endpoint de pesquisa de beneficiários, que faz parte da api beneficiaryPosition do Produto TOTVS Saúde Planos Linha Protheus (totvsHealthPlans).

/totvsHealthPlans/v1/beneficiaryPosition/{subscriberId}/search

Esse endpoint é utilizado na nova tela de Gestão do Beneficiário, desenvolvida em PO UI. (Biblioteca de componentes baseado em Angular)

Clique aqui para detalhes sobre como habilitar o serviço de APIs

02. EXEMPLO DE UTILIZAÇÃO

Pesquisa de Beneficiários

Retorna os beneficiários da pesquisa informado.

Endpoint

https://<url>:porta>/rest/totvsHealthPlans/v1/beneficiaryPosition/search

Parâmetros

Authorization (header)	Cabeçalho usado para autorização das requisições	*required
Content-Type (header)	'application/json' é o formato do conteúdo	*required
key (query)	Chave de pesquisa dos beneficiários, sendo: Nome (BA1_NOMUSR) Carteirinha (BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO) CPF (BA1_CPFUSR) Nome Social (BA1_NOMSOC)	*required
page (query)	Paginação da Coleção
pageSize (query)	Quantidade de Itens por Página
order (query)	Ordenação da Coleção
fields (query)	Filtro de campos dos registros
filter (query)	Indica o filtro querystring recebido (pode se utilizar um filtro oData)

Request

Não possui body!

Operação realizada com sucesso (200)

beneficiaries		Beneficiários encontrados na pesquisa
beneficiaries.card		Carteirinha do beneficiário Campo: BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO
beneficiaries.name		Nome do beneficiário Campo: BA1_NOMUSR
beneficiaries.socialName		Nome social do beneficiário Campo: BA1_NOMSOC
beneficiaries.type		Tipo do beneficiário, sendo: T (Titular), D (Dependente) e A (Agregado) Campo: BA1_TIPUSU
beneficiaries.kinship		Grau de parentesco do beneficiário Campo: BRP_DESCRI (Relacionamento pelo BA1_GRAUPA)
beneficiaries.situation		Situação atual do beneficiário, sendo: Ativo, Bloqueado ou Bloqueio Futuro Campo: BA1_DATBLO
hasNext		Indica se ainda existem registros a serem retornados
remainingRecords		Quantidade de registros ainda existem para retorno

Exemplo de retorno - Sucesso

{
  "beneficiaries": [
    {
      "card": "00010094000004017",
      "name": "MARIANA SANTOS DA SILVA",
      "socialname": "",
      "type": "T",
      "kinship": "BENEFICIARIO TITULAR",
      "situation": "Ativo"
    },
    {
      "card": "00011008000026021",
      "name": "JAQUELINE MARIANE ROSA SILVEIRA",
      "socialname": "",
      "type": "D",
      "kinship": "FILHO",
      "situation": "Ativo"
    },
    {
      "card": "00011008000027010",
      "name": "HERNANDES ALVES DA SILVA",
      "socialname": "MARIA HERNANDES",
      "type": "T",
      "kinship": "BENEFICIARIO TITULAR",
      "situation": "Ativo"
    },
    {
      "card": "00011008000029020",
      "name": "MARIA DO CARMO",
      "socialname": "",
      "type": "D",
      "kinship": "CONJUGE/ COMPANHEIRO",
      "situation": "Ativo"
    },
    {
      "card": "00011012000001019",
      "name": "MARIANA LARISSA MARIAH RAMOS",
      "socialname": "",
      "type": "T",
      "kinship": "BENEFICIARIO TITULAR",
      "situation": "Ativo"
    }
  ],
  "hasNext": false,
  "remainingRecords": 0
}

Mensagens de Erros

code		Código identificador do erro. (Tabela de Erros)
message		Literal no idioma da requisição descrevendo o erro para o usuário.
detailedMessage		Mensagem técnica e mais detalhada do erro.

Exemplo de retorno - Falha

{
  "code": "E001",
  "message": "Beneficiário não encontrado.",
  "detailedMessage": "Não foi encontrado nenhum beneficiário com a matricula 00011008000026010"
}

Tabela de Código de Erros

Código de erros informado no Json de retorno com falha:

Code	message	detailedMessage	Status Code
E001	Nenhuma chave de busca informada.	Obrigatório informar no query param a chave (key) de busca do beneficiário.	400

03. TELA PESQUISA DE BENEFICIÁRIOS

Outras Ações / Ações relacionadas

Ação	Descrição
Não se aplica	Não se aplica

04. TELA PESQUISA DE BENEFICIÁRIOS

Principais Campos e Parâmetros

Campo	Descrição
BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO	Carteirinha de pesquisa do beneficiário
BA1_NOMUSR	Nome de pesquisa do beneficiário
BA1_CPFUSR	CPF de pesquisa do beneficiário
BA1_NOMSOC	Nome social do beneficiário

05. TABELAS UTILIZADAS

BA1 - Beneficiários
BRP - Graus de Parentesco

Árvore de páginas