Histórico da Página

...

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 frontend.

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

02. ENDPOINT

Estado

subtle	true
colour	Blue
title	GET

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

...

Nome

Tipo

Descrição

Content-Type (header)

string

'application/json' é o formato do conteúdo

Authorization (Header)

string

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

*required

Estado

subtle	true
colour	Red
title	Required

subscriberId (Path)

string

Identificador único da carteirinha do beneficiário.

*required

04. RESPOSTA

...

Estado

subtle	true
colour	Red
title	Required

04. RESPOSTA

Informações

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.

Campo

Tipo

Descrição

Campo (Protheus)

fields

Estado


subtle	true
title	object

fields.name

Estado

subtle	true
title	string

Nome completo do beneficiário.

BTS_NOMCAR ou BTS_NOMUSR

fields.socialName

Estado

subtle	true
title	string

Nome social do beneficiário.

BTS_NOMSOC

fields.healthInsurerCode

Estado

subtle	true
title	string

Código da operadora de saúde.

BA1_CODINT

fields.companyCode

Estado

subtle	true
title	string

Código da empresa.

BA1_CODEMP

fields.registrationCode

Estado

title
subtle	true

...

	string

Código de registro do

...

beneficiário.	BA1_MATRIC
fields.

...

kinshipCode

Estado

subtle	true
title	string

Código de parentesco

...

.	BA1_TIPREG
fields.

...

digit

Estado

subtle	true
title	string

Dígito de identificação

...

.	BA1_DIGITO
fields.

...

nationalHealthCard

Estado

...

title
subtle	true

...

	string

...

Número do cartão nacional de saúde	BTS_NRCRNA
fields.

...

subscriberId

Estado

...

title
subtle	true

...

	string

...

Identificador único do beneficiário.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.

...

birthDate

...

Estado


subtle	true
title	String (date)

Data de nascimento do beneficiário.

BA1_DATNAS

fields.cardValidity

Estado


subtle	true
title	String (date)

Data de validade do cartão.

BA1_DTVLCR

fields.effectiveDate

Estado


subtle	true
title	String (date)

Data de efetivação do plano de saúde.

BA1_DATINC

fields.cardCopy

Estado

subtle	true
title	string

Identificador da cópia do cartão.

BA1_VIACAR

fields.holderName

Estado

subtle	true
title	string

Nome do titular do plano.

BTS_NOMCAR ou BTS_NOMUSR

fields.holderHealthInsurerCode

Estado

subtle	true
title	string

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

BA1_CODINT

fields.holderCompanyCode

Estado

subtle	true
title	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.

BA1_MATRIC

fields.dependentKinshipCode

Estado

subtle	true
title	string

Código de parentesco do dependente.

BA1_TIPREG

fields.dependentDigit

Estado

subtle	true
title	string

Dígito de identificação do dependente.

BA1_DIGITO

fields.dependentSubscriberId

Estado

subtle	true
title	string

Identificador único do dependente.

BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO

fields.planCode

Estado

subtle	true
title	string

Código do plano.

BI3_CODIGO

fields.planDescription

Estado

subtle	true
title	string

Descrição do plano de saúde.

BI3_NREDUZ

fields.accommodationDescription

Estado

subtle	true
title	string

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

BI4_CODEDI

fields.coverageArea

Estado

subtle	true
title	string

Área de cobertura do plano de saúde.

BI3_ABRANG

fields.planRegulation

Estado

subtle	true
title	string

Tipo de regulamentação do plano.

BI3_APOSRG

fields.planCodeANS

Estado

subtle	true
title	string

Código do plano na ANS.

BI3_SUSEP ou BI3_SCPA

fields.planSegmentation

Estado

subtle	true
title	string

Segmentação do plano.

BI6_DESCRI

fields.subcontractCardName

Estado

subtle	true
title	string

Nome do cartão de subcontrato.

BQC_NOMCAR

fields.healthInsurerCodeANS

Estado

subtle	true
title	string

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

BA0_SUSEP

fields.healthInsurerName

Estado

subtle	true
title	string

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).

layoutConfig

Estado


subtle	true
title	object

layoutConfig.front

Estado


subtle	true
title	object[]

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.

Bloco de código

language	c#
theme	Midnight
title	Exemplo
collapse	true

{

   "fields": {
    "name": "Marli Brenda Viana",
    "socialName": "",
    "healthInsurerCode": "0001",
    "companyCode": "0101",
    "registrationCode": "000007",
    "kinshipCode": "53",
    "digit": "5",
    "nationalHealthCard

...

Informações

icon	false

Dica

icon	false
title	(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.

Campo

Tipo

Descrição

fields

objeto

fields.name

string

Nome completo do beneficiário.

fields.socialName

string

Nome social do beneficiário.

fields.healthInsurerCode

string

Código da operadora de saúde.

fields.companyCode

string

Código da empresa.

fields.registrationCode

string

Código de registro do beneficiário.

fields.kinshipCode

string

Código de parentesco.

fields.digit

string

Dígito de identificação.

fields.nationalHealthCard

string

Número do cartão nacional de saúde

fields.subscriberId

string

Identificador único do beneficiário.

fields.birthDate

string - data

Data de nascimento do beneficiário.

fields.cardValidity

string - data

Data de validade do cartão.

fields.effectiveDate

string - data

Data de efetivação do plano de saúde.

fields.cardCopy

string

Identificador da cópia do cartão.

fields.holderName

string

Nome do titular do plano.

fields.holderHealthInsurerCode

string

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

fields.holderCompanyCode

string

Código da empresa do titular.

fields.holderRegistrationCode

string

Código de registro do titular.

fields.holderKinshipCode

string

Código de parentesco do titular.

fields.holderDigit

string

Dígito de identificação do titular.

fields.holderSubscriberId

string

Identificador único do titular.

fields.dependentName

string

Nome do dependente.

fields.dependentHealthInsurerCode

string

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

fields.dependentCompanyCode

string

Código da empresa do dependente.

fields.dependentRegistrationCode

string

Código de registro do dependente.

fields.dependentKinshipCode

string

Código de parentesco do dependente.

fields.dependentDigit

string

Dígito de identificação do dependente.

fields.dependentSubscriberId

string

Identificador único do dependente.

fields.planCode

string

Código do plano.

fields.planDescription

string

Descrição do plano de saúde.

fields.accommodationDescription

string

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

fields.coverageArea

string

Área de cobertura do plano de saúde.

fields.planRegulation

string

Tipo de regulamentação do plano.

fields.planCodeANS

string

Código do plano na ANS.

fields.planSegmentation

string

Segmentação do plano.

fields.subcontractCardName

string

Nome do cartão de subcontrato.

fields.healthInsurerCodeANS

string

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

fields.healthInsurerName

string

Nome da operadora de saúde.

cardImage

objeto

cardImage.front

string

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

cardImage.back

string

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

layoutConfig

objeto

layoutConfig.front

array de objetos

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

layoutConfig.front.css

string

Estilo CSS para o campo.

layoutConfig.front.values

array de objetos

Valores a serem exibidos no campo.

layoutConfig.front.values.type

string

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

layoutConfig.front.values.value

string

Valor do campo.

layoutConfig.back

array de objetos

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

layoutConfig.back.css

string

Estilo CSS para o campo.

layoutConfig.back.values

array de objetos

Valores a serem exibidos no campo.

layoutConfig.back.values.type

string

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

layoutConfig.back.values.value

string

Valor do campo.

customFields

array de objetos

customFields.field

string

Nome do campo customizado.

customFields.value

string

Valor do campo customizado.

Bloco de código

language	c#
theme	Midnight
title	Exemplo
collapse	true

{

   "fields": {
    "name": "Marli Brenda Viana",
    "socialName": "",
    "healthInsurerCodesubscriberId": "000100010101000007535",
    "companyCodebirthDate": "01011997-10-07",
    "registrationCodecardValidity": "000007",
    "kinshipCodeeffectiveDate": "532020-12-28",
    "digitcardCopy": "506",
    "nationalHealthCardholderName": "LUCAS NONATO",
    "subscriberIdholderHealthInsurerCode": "00010101000007535",
    "birthDateholderCompanyCode": "1997-10-070101",
    "cardValidityholderRegistrationCode": "000007",
    "effectiveDateholderKinshipCode": "2020-12-2801",
    "cardCopyholderDigit": "062",
    "holderNameholderSubscriberId": "LUCAS NONATO00010101000007012",
    "holderHealthInsurerCodedependentName": "Marli Brenda Viana",
    "holderCompanyCodedependentHealthInsurerCode": "01010001",
    "holderRegistrationCodedependentCompanyCode": "0000070101",
    "holderKinshipCodedependentRegistrationCode": "01000007",
    "holderDigitdependentKinshipCode": "253",
    "holderSubscriberIddependentDigit": "000101010000070125",
    "dependentNamedependentSubscriberId": "Marli Brenda Viana00010101000007535",
    "dependentHealthInsurerCodeplanCode": "0001",
    "dependentCompanyCodeplanDescription": "0101PLANO DOS GRANDE",
    "dependentRegistrationCodeaccommodationDescription": "000007INDIVIDUAL",
    "dependentKinshipCodecoverageArea": "53",
 GRUPO DE ESTADOS",
    "dependentDigitplanRegulation": "5PLANO REGULAMENTADO",
    "dependentSubscriberIdplanCodeANS": "00010101000007535123456",
    "planCodeplanSegmentation": "0001AMBULATORIAL",
    "planDescriptionsubcontractCardName": "PLANO DOS GRANDE",
    "accommodationDescriptionhealthInsurerCodeANS": "INDIVIDUAL888888",
    "coverageAreahealthInsurerName": "GRUPOOPERADORA DESAÚDE ESTADOS888888",
  },
  "planRegulationcardImage": "PLANO REGULAMENTADO",{
    "planCodeANSfront": "123456",
    "planSegmentationback": "AMBULATORIAL",
    "subcontractCardName": ""},
    "healthInsurerCodeANSlayoutConfig": "888888",{
    "healthInsurerNamefront": "OPERADORA SAÚDE 888888"
[
   },
  "cardImage": {
    "front": "",
    "backcss": ""
  },
  "layoutConfig": {
    "front": [
      {
        "css": "font-size: 9px;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"
    }
  ]
}

Exemplo de resposta:

...

 {
            "type": "field",
            "value": "accommodationDescription"
          }
        ]
      }
    ]
  },
  "customFields": [
    {
      "field": "meuCampo",
      "value": "Meu valor customizado"
    }
  ]
}

Nota

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 Layout

No 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

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	string

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
collapse	true

{
  "code": "E001",
  "message": "Não foi possível localizar o beneficiário informado no sistema. Por favor, verifique os dados fornecidos e tente novamente.",
  "detailedMessage": "O path informado (subscriberId) não foi encontrado na tabela de beneficiários (BA1). A consulta considerou os seguintes campos: BA1_CODINT, BA1_CODEMP, BA1_MATRIC, BA1_TIPREG e BA1_DIGITO. Verifique os dados enviados e tente novamente."
}

Árvore de páginas

Versões comparadas

Versão antiga 16

Nova versão Atual

Chave

02. ENDPOINT

04. RESPOSTA

04. RESPOSTA

200 - Operação realizada com sucesso

404 - Beneficiário não encontrado