Histórico da Página

CONTEÚDO

Introdução
Endpoint
Parâmetros
Resposta

01. INTRODUÇÃO

Esta API retorna os dados da carteirinha do beneficiário informado, incluindo as imagens do cartão frente e verso. As informações relacionadas à montagem dos dados da carteirinha são retornadas, bem como campos customizados, permitindo uma configuração dinâmica da exibição do cartão no frontendpermite criar um novo lote de importação de beneficiários em massa na operadora. Os beneficiários serão gerados com um protocolo ao serem importados na rotina de análise de beneficiários (PLSA977AB), permitindo que a operadora analise e aprove a inclusão no grupo familiar (PLSA174).

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

02. ENDPOINT

Estado


colour	BlueGreen
title	GETPOST

/totvsHealthPlans/familyContract/v1/beneficiaries/{subscriberId}/cardimportBatches

03. PARÂMETROS

Nome	Tipo	Localização	Descrição
Content-

Type (header)

Type

string

'

header

multipart/form-data ou application/json

' é o

(dependendo do formato do

conteúdo

corpo da requisição).

Authorization

(Header)

string

header

Token de acesso obtido via a API de autenticação, no formato Bearer <access_token>.

Estado

subtle	true
colour	Red
title	Required

subscriberId (Path)

healthInsurerCode

string

Identificador único da carteirinha do beneficiário.

body/form

Código da operadora

Estado

subtle	true
colour	Red
title	Required

...

companyCode

...

string

...

icon	false

Dica
200 - Operação realizada com sucesso

Retorna os dados da carteirinha do beneficiário, incluindo informações pessoais, planos de saúde, imagens do cartão e configurações de layout.

body/form

Código da empresa

Estado

subtle	true

...

colour

...

Red

...

title

...

Required

...

contractCode

...

string

...

body/form

Código do contrato

Estado

subtle	true

...

colour

...

BTS_NOMSOC

...

Estado

subtle	true
title	string

...

BA1_CODINT

...

Red
title	Required

contractVersion

string

body/form

Versão do contrato

Estado

subtle	true

...

colour

...

BA1_CODEMP

...

Estado

subtle	true
title	string

...

BA1_MATRIC

...

Red
title	Required

subcontractCode

string

body/form

Código do subcontrato

Estado

subtle	true

...

colour

...

BA1_TIPREG

...

Estado

subtle	true
title	string

...

BA1_DIGITO

...

Red
title	Required

subcontractVersion

string

body/form

Versão do subcontrato

Estado

subtle	true

...

colour

...

BTS_NRCRNA

...

Estado

subtle	true
title	string

...

Red
title	Required

loginUser

string

body/form

Login do portal

Estado

subtle	true

...

BA1_DATNAS

...

BA1_DTVLCR

...

colour	Red
title	Required

file

form-data

Arquivo CSV com os beneficiários

Estado

subtle	true

...

BA1_DATINC

...

Estado

subtle	true
title	string

...

BA1_VIACAR

...

colour	Red
title	Required

fileBase64

string

body

Arquivo CSV em Base64

Estado

subtle	true

...

colour

...

Estado

subtle	true
title	string

...

BA1_CODINT

...

Red
title	Required

fileName

string

body

Nome do arquivo CSV

Estado

subtle	true

...

colour	Red
title	Required

Informações
Pode-se enviar o arquivo CSV dos beneficiários via file (form-data) ou fileBase64 (body) com o fileName.

Bloco de código

language	c#
theme	Midnight
title	Exemplo de Body
collapse	true

{
  "healthInsurerCode": "0001",
  "companyCode": "1017",
  "contractCode": "000000000001",
  "contractVersion": "001",
  "subcontractCode": "000000001",
  "subcontractVersion": "001",
  "loginUser": "TOTVS",
  "fileBase64": "QjJOX0NPRFNFUTtCMk5fQ1BGVVNSO0IyTl9OT01VU1I7QjJOX0RBVE5BUztCMk5...",
  "fileName": "modelo-importacao-beneficiarios.csv"
}

04. RESPOSTA

Informações

icon	false

Dica
201 - Operação realizada com sucesso

O sistema cria um novo lote na rotina de Lotes de Importação de Beneficiários (PLCTO001) com status Recebido, e anexa o arquivo CSV ao banco de conhecimento do lote.

Campo

Tipo

Descrição

Campo (Protheus)

batchCode

string

Código da empresa do titular.

BA1_CODEMP

fields.holderRegistrationCode

Estado

subtle	true
title	string

Código de registro do titular.

BA1_MATRIC

fields.holderKinshipCode

Estado

subtle	true
title	string

Código de parentesco do titular.

BA1_TIPREG

fields.holderDigit

Estado

subtle	true
title	string

Dígito de identificação do titular.

BA1_DIGITO

fields.holderSubscriberId

Estado

subtle	true
title	string

Identificador único do titular.

BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO

fields.dependentName

Estado

subtle	true
title	string

Nome do dependente.

BTS_NOMCAR ou BTS_NOMUSR

fields.dependentHealthInsurerCode

Estado

subtle	true
title	string

Código da operadora de saúde do dependente.

BA1_CODINT

fields.dependentCompanyCode

Estado

subtle	true
title	string

Código da empresa do dependente.

BA1_CODEMP

fields.dependentRegistrationCode

Estado

subtle	true
title	string

Código de registro do dependente.Lote

BA1BJ5_MATRICCODLOT

fields.dependentKinshipCode status

Estado

subtle	true
title	string

Código de parentesco do dependente.

BA1_TIPREG

Status do Lote

BJ5_STATUS

importDatefields.dependentDigit

Estado


subtle	true
title	string

Dígito de identificação do dependente.

(DATE)

Data da importação

BJ5_DATIMP

importTime

BA1_DIGITO

fields.dependentSubscriberId

Estado

subtle	true
title	string

Identificador único do dependente.

BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO

Hora da importação

BJ5_HORIMP

loginUserfields.planCode

Estado

subtle	true
title	string

Código do plano.

Usuário que gerou o lote

BJ5_USRLOG

healthInsurerCode

BI3_CODIGO

fields.planDescription

Estado

subtle	true
title	string

Descrição do plano de saúde.

Código da operadora

BJ5_CODOPE

companyCode

BI3_NREDUZ

fields.accommodationDescription

Estado

subtle	true
title	string

Descrição da acomodação do plano.

Código da empresa

BJ5_CODEMP

contractCode

BI4_CODEDI

fields.coverageArea

Estado

subtle	true
title	string

Área de cobertura do plano de saúde.

Código do contrato

BJ5_CONEMP

contractVersion

BI3_ABRANG

fields.planRegulation

Estado

subtle	true
title	string

Tipo de regulamentação do plano.

Versão do contrato

BJ5_VERCON

subcontractCode

BI3_APOSRG

fields.planCodeANS

Estado

subtle	true
title	string

Código do plano na ANS.

BI3_SUSEP ou BI3_SCPA

subcontrato

BJ5_SUBCON

subcontractVersionfields.planSegmentation

Estado

subtle	true
title	string

Segmentação Versão do plano.subcontrato

BI6BJ5_DESCRIVERSUB

fields.subcontractCardName subcontractDescription

Estado

subtle	true
title	string

Nome Descrição do cartão de subcontrato.

BQC_NOMCARDESCRI

fields.healthInsurerCodeANS totalCount

Estado


subtle	true
title	stringINTEGER

Código da operadora de saúde na ANS.

BA0_SUSEP

Total de beneficiários do lote

BJ5_QTDTOT

importedCountfields.healthInsurerName

Estado


subtle	true
title	stringINTEGER

Nome da operadora de saúde.

BA0_NOMINT

cardImage

Estado

subtle

true

title

object

cardImage.front

Estado

subtle	true
title	string

Imagem em base64 da frente do cartão (formato PNG).

cardImage.back

Estado

subtle	true
title	string

Imagem em base64 da verso do cartão (formato PNG).

Total de beneficiários importados (em processamento, pode variar)

BJ5_QTDIMP

errorCount

layoutConfig

Estado

subtle

true

title

object

layoutConfig.front

Estado


subtle	true
title	object[]INTEGER

Configurações de layout para a frente do cartão.

layoutConfig.front.css

Estado

subtle	true
title	string

Estilo CSS para o campo.

layoutConfig.front.values

Estado

subtle

true

title

object[]

Valores a serem exibidos no campo.

layoutConfig.front.values.type

Estado

subtle	true
title	string

Tipo do campo, podendo ser: custom, field ou text.

layoutConfig.front.values.value

Estado

subtle	true
title	string

Valor do campo.

layoutConfig.back

Estado

subtle

true

title

object[]

Configurações de layout para o verso do cartão.

layoutConfig.back.css

Estado

subtle	true
title	string

Estilo CSS para o campo.

layoutConfig.back.values

Estado

subtle

true

title

object[]

Valores a serem exibidos no campo.

layoutConfig.back.values.type

Estado

subtle	true
title	string

Tipo do campo, podendo ser: custom, field ou text.

layoutConfig.back.values.value

Estado

subtle	true
title	string

Valor do campo.

customFields

Estado

subtle

true

title

object[]

customFields.field

Estado

subtle	true
title	string

Nome do campo customizado.

customFields.value

Estado

subtle	true
title	string

Valor do campo customizado.

Total de beneficiários com erro (em processamento, pode variar)

BJ5_QTDERR

Campos Customizados

O campo customFields permite que o cliente adicione campos personalizados à resposta, oferecendo flexibilidade para configurar os dados da carteirinha conforme necessário. Utilize o ponto de entrada: PE PTBENCARD Campos Customizados para Carteirinha Virtual no Portal do Beneficiário

Imagens do Cartão

As imagens do cartão (frente e verso) são fornecidas em formato PNG, com tamanho de 420x240 pixels. As imagens são nomeadas como front-card.png e back-card.png e estão localizadas no diretório do servidor:

RootPath: \portais-saude\portal-beneficiario\card\

Arquivo de Configuração de LayoutNo mesmo diretório das imagens, um arquivo de configuração chamado layout-config.json. Este arquivo contém as definições para os campos que aparecerão no cartão, incluindo o layout de posicionamento e estilo CSS.
Para mais detalhes sobre a configuração da imagem e do layout, consulte a documentação Configuração do Layout Customizado da Carteirinha

Bloco de código

language	c#
theme	Midnight
title	Exemplo
collapse	true

{

   "fields": {
    "namebatchCode": "Marli Brenda Viana00000155",
    "socialNamestatus": "1",
    "healthInsurerCodeimportDate": "0001",
    "companyCode": "0101",
    "registrationCode": "000007",
    "kinshipCode": "53",
    "digit": "5",
    "nationalHealthCard": "",
    "subscriberId": "00010101000007535",
    "birthDate": "1997-10-072025-08-22",
    "cardValidityimportTime": "",
    "effectiveDate": "2020-12-28",
    "cardCopy": "0617:07:17",
    "holderNameloginUser": "LUCAS NONATOVINIEMP",
    "holderHealthInsurerCodehealthInsurerCode": "",
    "holderCompanyCode": "0101",
    "holderRegistrationCode": "000007",
    "holderKinshipCode": "01",
    "holderDigit": "2",
    "holderSubscriberId": "00010101000007012",
    "dependentName": "Marli Brenda Viana",
    "dependentHealthInsurerCode": "0001",
    "dependentCompanyCodecompanyCode": "01011017",
    "dependentRegistrationCodecontractCode": "000007000000000001",
    "dependentKinshipCodecontractVersion": "53001",
    "dependentDigitsubcontractCode": "5000000001",
    "dependentSubscriberIdsubcontractVersion": "00010101000007535001",
    "planCodesubcontractDescription": "0001",
CONTRATO    "planDescription": "PLANO DOS GRANDE",
    "accommodationDescription": "INDIVIDUAL",
    "coverageArea": "GRUPO DE ESTADOSDE IMPOT. DE BENEFICIARIOS",
    "planRegulationtotalCount": "PLANO REGULAMENTADO"8,
    "planCodeANSimportedCount": "123456"0,
    "planSegmentationerrorCount": "AMBULATORIAL",
    "subcontractCardName": "",
    "healthInsurerCodeANS": "888888",
    "healthInsurerName": "OPERADORA SAÚDE 888888"
  },
  "cardImage": {
    "front": "",
    "back": ""
  },
  "layoutConfig": {
    "front": [
      {
        "css": "font-size: 9px;font-weight: bold;top: 50px; width: 200px; left: 300px;",
        "values": [
          {
            "type": "custom",
            "value": "meuCampo"
          }
        ]
      },
      {
        "css": "font-size: 9px;font-weight: bold;top: 70px; width: 200px; left: 20px;",
        "values": [
          {
            "type": "field",
            "value": "planDescription"
          },
          {
            "type": "field",
            "value": "accommodationDescription"
          }
        ]
      },
      {
        "css": "font-size: 8px;top: 117px; width: 70px; left: 330px;",
        "values": [
          {
            "type": "text",
            "value": "VÁLIDO ATÉ:"
          }
        ]
      }
    ],
    "back": [
      {
        "css": "font-size: 9px;font-weight: bold;top: 70px; width: 200px; left: 100px;",
        "values": [
          {
            "type": "field",
            "value": "planDescription"
          },
          {
            "type": "field",
            "value": "accommodationDescription"
          }
        ]
      }
    ]
  },
  "customFields": [
    {
      "field": "meuCampo",
      "value": "Meu valor customizado"
    }
  ]
}

Nota

0
}

Informações

icon	false

Aviso
400 - Formato de JSON inválido. O corpo da requisição não está em um formato JSON válido. Verifique a estrutura e tente novamente.

Aviso
400 - Erro ao processar o arquivo CSV. Não foi possível obter o arquivo CSV. Verifique se o arquivo está disponível e se está em um formato válido.

Aviso
400 - Os campos do cabeçalho do arquivo não correspondem ao modelo esperado para a importação de beneficiários.

Aviso
400 - O arquivo CSV do lote está vazio e não contém dados de beneficiários para processar.

Aviso
400 - Falha na validação dos dados. "Mensagem de erro do MVC"

Aviso
400 - Parâmetro obrigatório não informado. O parâmetro obrigatório deve ser enviado na requisição.

Aviso
404 - Contrato informado não encontrado. O contrato informado não foi encontrado na tabela BQC. Verifique se o número do contrato está correto e devidamente cadastrado no sistema.

Aviso
406 - Formato de dados inválido. Os dados enviados não estão no formato form-data. Verifique se o Content-Type da requisição está definido como multipart/form-data e se os campos foram corretamente estruturados

Informações

icon	false

Aviso
404 - Beneficiário não encontrado

Caso o subscriberId informado não seja encontrado no sistema, a API retornará o código de erro E001 com uma mensagem detalhada

.

Campo

Tipo

Descrição

code

Estado


subtle	true
title	stringINTEGER

Código identificador do erro.

message

Estado

subtle	true
title	string

Literal no idioma da requisição descrevendo o erro para o usuário.

detailedMessage

Estado

subtle	true
title	string

Mensagem técnica e mais detalhada do erro.

Bloco de código

language	c#
theme	Midnight
title	Exemplo JSON de Erro
collapse	true

{
  "codestatus": "E001"400,
  "message": "NãoErro foiao possívelprocessar localizar o beneficiário informado no sistema. Por favor, verifique os dados fornecidos e tente novamente.arquivo CSV",
  "detailedMessage": "O path informado (subscriberId) nãoNão foi encontradopossível naobter tabelao de beneficiários (BA1)arquivo CSV. AVerifique consultase considerouo osarquivo seguintesestá campos: BA1_CODINT, BA1_CODEMP, BA1_MATRIC, BA1_TIPREG e BA1_DIGITO. Verifique os dados enviados e tente novamentedisponível e se está em um formato válido."
}

Árvore de páginas

Versões comparadas

Versão antiga 1

Nova versão Atual

Chave

CONTEÚDO

01. INTRODUÇÃO

02. ENDPOINT

03. PARÂMETROS

200 - Operação realizada com sucesso

04. RESPOSTA

201 - Operação realizada com sucesso

400 - Formato de JSON inválido.
O corpo da requisição não está em um formato JSON válido. Verifique a estrutura e tente novamente.

400 - Erro ao processar o arquivo CSV.
Não foi possível obter o arquivo CSV. Verifique se o arquivo está disponível e se está em um formato válido.

400 - Os campos do cabeçalho do arquivo não correspondem ao modelo esperado para a importação de beneficiários.

400 - O arquivo CSV do lote está vazio e não contém dados de beneficiários para processar.

400 - Falha na validação dos dados.
"Mensagem de erro do MVC"

400 - Parâmetro obrigatório não informado.
O parâmetro obrigatório deve ser enviado na requisição.

404 - Contrato informado não encontrado.
O contrato informado não foi encontrado na tabela BQC. Verifique se o número do contrato está correto e devidamente cadastrado no sistema.

406 - Formato de dados inválido.
Os dados enviados não estão no formato form-data. Verifique se o Content-Type da requisição está definido como multipart/form-data e se os campos foram corretamente estruturados

404 - Beneficiário não encontrado

.

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 1

Nova versão Atual

Chave

CONTEÚDO

01. INTRODUÇÃO

02. ENDPOINT

03. PARÂMETROS

200 - Operação realizada com sucesso

04. RESPOSTA

201 - Operação realizada com sucesso

400 - Formato de JSON inválido.O corpo da requisição não está em um formato JSON válido. Verifique a estrutura e tente novamente.

400 - Erro ao processar o arquivo CSV.Não foi possível obter o arquivo CSV. Verifique se o arquivo está disponível e se está em um formato válido.

400 - Os campos do cabeçalho do arquivo não correspondem ao modelo esperado para a importação de beneficiários.

400 - O arquivo CSV do lote está vazio e não contém dados de beneficiários para processar.

400 - Falha na validação dos dados."Mensagem de erro do MVC"

400 - Parâmetro obrigatório não informado.O parâmetro obrigatório deve ser enviado na requisição.

404 - Contrato informado não encontrado.O contrato informado não foi encontrado na tabela BQC. Verifique se o número do contrato está correto e devidamente cadastrado no sistema.

406 - Formato de dados inválido.Os dados enviados não estão no formato form-data. Verifique se o Content-Type da requisição está definido como multipart/form-data e se os campos foram corretamente estruturados

404 - Beneficiário não encontrado

.

400 - Formato de JSON inválido.
O corpo da requisição não está em um formato JSON válido. Verifique a estrutura e tente novamente.

400 - Erro ao processar o arquivo CSV.
Não foi possível obter o arquivo CSV. Verifique se o arquivo está disponível e se está em um formato válido.

400 - Falha na validação dos dados.
"Mensagem de erro do MVC"

400 - Parâmetro obrigatório não informado.
O parâmetro obrigatório deve ser enviado na requisição.

404 - Contrato informado não encontrado.
O contrato informado não foi encontrado na tabela BQC. Verifique se o número do contrato está correto e devidamente cadastrado no sistema.

406 - Formato de dados inválido.
Os dados enviados não estão no formato form-data. Verifique se o Content-Type da requisição está definido como multipart/form-data e se os campos foram corretamente estruturados