CONTEÚDO

  1. Introdução
  2. Endpoint
  3. Parâmetros
  4. 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 frontend.


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

02. ENDPOINT

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

03. PARÂMETROS

NomeTipoDescriçã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>.

subscriberId (Path)string

Identificador único da carteirinha do beneficiário.

04. RESPOSTA

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.

CampoTipoDescriçãoCampo (Protheus)
fields 



fields.name 

Nome completo do beneficiário.BTS_NOMCAR ou BTS_NOMUSR
fields.socialName

Nome social do beneficiário.

BTS_NOMSOC

fields.healthInsurerCode

Código da operadora de saúde.

BA1_CODINT

fields.companyCode 

Código da empresa.

BA1_CODEMP

fields.registrationCode 

Código de registro do beneficiário.

BA1_MATRIC

fields.kinshipCode 

Código de parentesco.

BA1_TIPREG

fields.digit 

Dígito de identificação.

BA1_DIGITO

fields.nationalHealthCard 

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

BTS_NRCRNA

fields.subscriberId 

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

Data de nascimento do beneficiário.

BA1_DATNAS

fields.cardValidity 

Data de validade do cartão.

BA1_DTVLCR

fields.effectiveDate 

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

BA1_DATINC

fields.cardCopy 

Identificador da cópia do cartão.

BA1_VIACAR

fields.holderName 

Nome do titular do plano.BTS_NOMCAR ou BTS_NOMUSR
fields.holderHealthInsurerCode 

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

BA1_CODINT

fields.holderCompanyCode 

Código da empresa do titular.

BA1_CODEMP

fields.holderRegistrationCode

Código de registro do titular.

BA1_MATRIC

fields.holderKinshipCode 

Código de parentesco do titular.

BA1_TIPREG

fields.holderDigit 

Dígito de identificação do titular.

BA1_DIGITO

fields.holderSubscriberId 

Identificador único do titular.BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.dependentName 

Nome do dependente.BTS_NOMCAR ou BTS_NOMUSR
fields.dependentHealthInsurerCode 

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

BA1_CODINT

fields.dependentCompanyCode

Código da empresa do dependente.

BA1_CODEMP

fields.dependentRegistrationCode 

Código de registro do dependente.

BA1_MATRIC

fields.dependentKinshipCode 

Código de parentesco do dependente.

BA1_TIPREG

fields.dependentDigit 

Dígito de identificação do dependente.

BA1_DIGITO

fields.dependentSubscriberId 

Identificador único do dependente.BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.planCode 

Código do plano.

BI3_CODIGO

fields.planDescription 

Descrição do plano de saúde.

BI3_NREDUZ

fields.accommodationDescription 

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

BI4_CODEDI

fields.coverageArea 

Área de cobertura do plano de saúde.

BI3_ABRANG

fields.planRegulation 

Tipo de regulamentação do plano.

BI3_APOSRG

fields.planCodeANS 

Código do plano na ANS.

BI3_SUSEP ou BI3_SCPA

fields.planSegmentation 

Segmentação do plano.

BI6_DESCRI

fields.subcontractCardName 

Nome do cartão de subcontrato.

BQC_NOMCAR

fields.healthInsurerCodeANS 

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

BA0_SUSEP

fields.healthInsurerName 

Nome da operadora de saúde.

BA0_NOMINT

cardImage 



cardImage.front 

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

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



layoutConfig.front 

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

Estilo CSS para o campo.
layoutConfig.front.values

Valores a serem exibidos no campo.
layoutConfig.front.values.type

Tipo do campo, podendo ser: custom, field ou text.
layoutConfig.front.values.value

Valor do campo.
layoutConfig.back

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

Estilo CSS para o campo.
layoutConfig.back.values

Valores a serem exibidos no campo.
layoutConfig.back.values.type

Tipo do campo, podendo ser: custom, field ou text.
layoutConfig.back.values.value

Valor do campo.
customFields 



customFields.field

Nome do campo customizado.
customFields.value

Valor do campo customizado.
{

   "fields": {
    "name": "Marli Brenda Viana",
    "socialName": "",
    "healthInsurerCode": "0001",
    "companyCode": "0101",
    "registrationCode": "000007",
    "kinshipCode": "53",
    "digit": "5",
    "nationalHealthCard": "",
    "subscriberId": "00010101000007535",
    "birthDate": "1997-10-07",
    "cardValidity": "",
    "effectiveDate": "2020-12-28",
    "cardCopy": "06",
    "holderName": "LUCAS NONATO",
    "holderHealthInsurerCode": "",
    "holderCompanyCode": "0101",
    "holderRegistrationCode": "000007",
    "holderKinshipCode": "01",
    "holderDigit": "2",
    "holderSubscriberId": "00010101000007012",
    "dependentName": "Marli Brenda Viana",
    "dependentHealthInsurerCode": "0001",
    "dependentCompanyCode": "0101",
    "dependentRegistrationCode": "000007",
    "dependentKinshipCode": "53",
    "dependentDigit": "5",
    "dependentSubscriberId": "00010101000007535",
    "planCode": "0001",
    "planDescription": "PLANO DOS GRANDE",
    "accommodationDescription": "INDIVIDUAL",
    "coverageArea": "GRUPO DE ESTADOS",
    "planRegulation": "PLANO REGULAMENTADO",
    "planCodeANS": "123456",
    "planSegmentation": "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"
    }
  ]
}

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 será gerado. Este arquivo contém as definições para os campos que aparecerão no cartão, incluindo o layout de posicionamento e estilo CSS.

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.

CampoTipoDescrição
code

Código identificador do erro.
message

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

Mensagem técnica e mais detalhada do erro.
{
  "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."
}