Exibir origem

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

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

Campo	Tipo	Descrição	Campo (Protheus)
fields	objeto
fields.name	string	Nome completo do beneficiário.	BTS_NOMCAR ou BTS_NOMUSR
fields.socialName	string	Nome social do beneficiário.	BTS_NOMSOC
fields.healthInsurerCode	string	Código da operadora de saúde.	BA1_CODINT
fields.companyCode	string	Código da empresa.	BA1_CODEMP
fields.registrationCode	string	Código de registro do beneficiário.	BA1_MATRIC
fields.kinshipCode	string	Código de parentesco.	BA1_TIPREG
fields.digit	string	Dígito de identificação.	BA1_DIGITO
fields.nationalHealthCard	string	Número do cartão nacional de saúde	BTS_NRCRNA
fields.subscriberId	string	Identificador único do beneficiário.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.birthDate	string - data	Data de nascimento do beneficiário.	BA1_DATNAS
fields.cardValidity	string - data	Data de validade do cartão.	BA1_DTVLCR
fields.effectiveDate	string - data	Data de efetivação do plano de saúde.	BA1_DATINC
fields.cardCopy	string	Identificador da cópia do cartão.	BA1_VIACAR
fields.holderName	string	Nome do titular do plano.	BTS_NOMCAR ou BTS_NOMUSR
fields.holderHealthInsurerCode	string	Código da operadora de saúde do titular.	BA1_CODINT
fields.holderCompanyCode	string	Código da empresa do titular.	BA1_CODEMP
fields.holderRegistrationCode	string	Código de registro do titular.	BA1_MATRIC
fields.holderKinshipCode	string	Código de parentesco do titular.	BA1_TIPREG
fields.holderDigit	string	Dígito de identificação do titular.	BA1_DIGITO
fields.holderSubscriberId	string	Identificador único do titular.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.dependentName	string	Nome do dependente.	BTS_NOMCAR ou BTS_NOMUSR
fields.dependentHealthInsurerCode	string	Código da operadora de saúde do dependente.	BA1_CODINT
fields.dependentCompanyCode	string	Código da empresa do dependente.	BA1_CODEMP
fields.dependentRegistrationCode	string	Código de registro do dependente.	BA1_MATRIC
fields.dependentKinshipCode	string	Código de parentesco do dependente.	BA1_TIPREG
fields.dependentDigit	string	Dígito de identificação do dependente.	BA1_DIGITO
fields.dependentSubscriberId	string	Identificador único do dependente.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.planCode	string	Código do plano.	BI3_CODIGO
fields.planDescription	string	Descrição do plano de saúde.	BI3_NREDUZ
fields.accommodationDescription	string	Descrição da acomodação do plano.	BI4_CODEDI
fields.coverageArea	string	Área de cobertura do plano de saúde.	BI3_ABRANG
fields.planRegulation	string	Tipo de regulamentação do plano.	BI3_APOSRG
fields.planCodeANS	string	Código do plano na ANS.	BI3_SUSEP ou BI3_SCPA
fields.planSegmentation	string	Segmentação do plano.	BI6_DESCRI
fields.subcontractCardName	string	Nome do cartão de subcontrato.	BQC_NOMCAR
fields.healthInsurerCodeANS	string	Código da operadora de saúde na ANS.	BA0_SUSEP
fields.healthInsurerName	string	Nome da operadora de saúde.	BA0_NOMINT
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.

Campo	Tipo	Descrição	Campo (Protheus)
fields	objeto
fields.name	string	Nome completo do beneficiário.	BTS_NOMCAR ou BTS_NOMUSR
fields.socialName	string	Nome social do beneficiário.	BTS_NOMSOC
fields.healthInsurerCode	string	Código da operadora de saúde.	BA1_CODINT
fields.companyCode	string	Código da empresa.	BA1_CODEMP
fields.registrationCode	string	Código de registro do beneficiário.	BA1_MATRIC
fields.kinshipCode	string	Código de parentesco.	BA1_TIPREG
fields.digit	string	Dígito de identificação.	BA1_DIGITO
fields.nationalHealthCard	string	Número do cartão nacional de saúde	BTS_NRCRNA
fields.subscriberId	string	Identificador único do beneficiário.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.birthDate	string - data	Data de nascimento do beneficiário.	BA1_DATNAS
fields.cardValidity	string - data	Data de validade do cartão.	BA1_DTVLCR
fields.effectiveDate	string - data	Data de efetivação do plano de saúde.	BA1_DATINC
fields.cardCopy	string	Identificador da cópia do cartão.	BA1_VIACAR
fields.holderName	string	Nome do titular do plano.	BTS_NOMCAR ou BTS_NOMUSR
fields.holderHealthInsurerCode	string	Código da operadora de saúde do titular.	BA1_CODINT
fields.holderCompanyCode	string	Código da empresa do titular.	BA1_CODEMP
fields.holderRegistrationCode	string	Código de registro do titular.	BA1_MATRIC
fields.holderKinshipCode	string	Código de parentesco do titular.	BA1_TIPREG
fields.holderDigit	string	Dígito de identificação do titular.	BA1_DIGITO
fields.holderSubscriberId	string	Identificador único do titular.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.dependentName	string	Nome do dependente.	BTS_NOMCAR ou BTS_NOMUSR
fields.dependentHealthInsurerCode	string	Código da operadora de saúde do dependente.	BA1_CODINT
fields.dependentCompanyCode	string	Código da empresa do dependente.	BA1_CODEMP
fields.dependentRegistrationCode	string	Código de registro do dependente.	BA1_MATRIC
fields.dependentKinshipCode	string	Código de parentesco do dependente.	BA1_TIPREG
fields.dependentDigit	string	Dígito de identificação do dependente.	BA1_DIGITO
fields.dependentSubscriberId	string	Identificador único do dependente.	BA1_CODINT + BA1_CODEMP + BA1_MATRIC + BA1_TIPREG + BA1_DIGITO
fields.planCode	string	Código do plano.	BI3_CODIGO
fields.planDescription	string	Descrição do plano de saúde.	BI3_NREDUZ
fields.accommodationDescription	string	Descrição da acomodação do plano.	BI4_CODEDI
fields.coverageArea	string	Área de cobertura do plano de saúde.	BI3_ABRANG
fields.planRegulation	string	Tipo de regulamentação do plano.	BI3_APOSRG
fields.planCodeANS	string	Código do plano na ANS.	BI3_SUSEP ou BI3_SCPA
fields.planSegmentation	string	Segmentação do plano.	BI6_DESCRI
fields.subcontractCardName	string	Nome do cartão de subcontrato.	BQC_NOMCAR
fields.healthInsurerCodeANS	string	Código da operadora de saúde na ANS.	BA0_SUSEP
fields.healthInsurerName	string	Nome da operadora de saúde.	BA0_NOMINT
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.

{

   "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"
    }
  ]
}

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.

{
  "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."
}

05. TABELAS UTILIZADAS

Coloque o link das tabelas relacionadas