MV sistemas Beneficiário e carteira API

openapi: 3.2.0
info:
  title: Integração Hub Operadora Beneficiário e carteira API
  version: 1.0.0
  description: '**Personal Health · Integração Hub Operadora** reúne as APIs que levam ao **app Personal** os serviços da **operadora de saúde**: dados do beneficiário e da carteirinha, **rede credenciada** (guia médico), guias e utilização do plano, dependentes, **histórico de relacionamento** com o beneficiário, **cadastros auxiliares** para telas e filtros (UF, município, bairro, recursos e especialidades) e **tokens** para fluxos que exigem confirmação rápida.


    A integração é voltada a **operadoras** com **contrato ativo** junto à **MV Global Health** no ecossistema Personal.


    Inclua em **todas** as requisições o cabeçalho **`x-api-key`** fornecido pelo time de integração. O ambiente disponível é **somente Produção**.


    Detalhes de parâmetros, formatos de data e regras próprias da sua operação devem ser alinhados no **contrato técnico** e com o time de integração; esta documentação serve como **referência geral**.

    '
servers:
- url: https://api.globalhealth.mv/prod/personal-hub-operadora-api
  description: Ambiente de PRODUÇÃO
security:
- x-api-key: []
tags:
- name: Beneficiário e carteira
  description: Consulta de dados cadastrais, carteirinhas por CPF e dependentes do titular.
paths:
  /api/Funcoes/GetBeneficiario/{numerocarteira}:
    get:
      tags:
      - Beneficiário e carteira
      summary: GetBeneficiario
      description: 'Retorna os **dados cadastrais e do plano** do beneficiário a partir do **número da carteirinha**, incluindo informações de cobertura, contatos e vigência conforme regras da operadora.


        O retorno pode contemplar beneficiários **na base local** ou em **intercâmbio** com outra operadora, conforme o vínculo do titular. Não há parâmetros de consulta além do número da carteira informado na URL.

        '
      parameters:
      - name: numerocarteira
        in: path
        required: true
        schema:
          type: string
        description: Número da carteira utilizado para localizar o beneficiário.
      responses:
        '200':
          description: Dados cadastrais e contratuais do beneficiário localizados pela carteirinha.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VwClinicApiBeneficiario'
        '400':
          description: Requisição inválida.
        '401':
          description: Não autorizado.
        '404':
          description: Beneficiário não encontrado para a carteira informada.
        '500':
          description: Erro interno do servidor.
  /api/Funcoes/GetCarteira/{numerocpf}:
    get:
      tags:
      - Beneficiário e carteira
      summary: GetCarteira
      description: 'Lista as **carteirinhas ativas** vinculadas ao **CPF** informado — útil quando o usuário possui mais de um vínculo ou precisa escolher em qual plano deseja atuar.


        São retornadas apenas carteiras com **situação ativa** na data da consulta. Informe o CPF **somente no path** (em geral **11 dígitos**, sem máscara ou conforme contrato técnico).

        '
      parameters:
      - name: numerocpf
        in: path
        required: true
        schema:
          type: string
        description: CPF do beneficiário (em geral 11 dígitos; formato conforme acordo de integração).
      responses:
        '200':
          description: 'Lista de carteiras ativas para o CPF (pode ser vazia se não houver vínculo ou nenhuma carteira ativa).

            '
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VwClinicApiBeneficiario'
        '400':
          description: Requisição inválida (ex. CPF em formato incorreto).
        '401':
          description: Não autorizado.
        '500':
          description: Erro interno do servidor.
  /api/Funcoes/GetDependentes/{numerocarteira}:
    get:
      tags:
      - Beneficiário e carteira
      summary: GetDependentes
      description: 'Lista os **dependentes** vinculados ao **titular** cuja carteirinha foi informada — agregados e familiares ativos no mesmo contrato, conforme regras da operadora.


        Retorna apenas integrantes **ativos** da família, **exceto o próprio titular**. Não há parâmetros adicionais além da carteira do titular na URL.

        '
      parameters:
      - name: numerocarteira
        in: path
        required: true
        schema:
          type: string
        description: Número da carteirinha do **titular** (não use a carteira de um dependente neste endpoint).
      responses:
        '200':
          description: Lista de dependentes (pode ser vazia).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VwClinicApiDependentes'
        '400':
          description: Requisição inválida.
        '401':
          description: Não autorizado.
        '500':
          description: Erro interno do servidor.
components:
  schemas:
    VwClinicApiDependentes:
      type: object
      description: Dados de um **dependente** vinculado ao titular informado na consulta (carteirinha, situação no plano, acomodação, etc.).
      additionalProperties: true
      properties:
        cdmatricula:
          type: string
          description: Identificador interno do dependente no plano.
        nrcpf:
          type: string
        snativo:
          type: string
          description: Indica se o dependente está ativo no plano (ex. **S** / **N**).
        dsacomodacao:
          type: string
          description: Descrição do tipo de acomodação do plano.
        cdmatalternativa:
          type: string
          description: Código alternativo da carteira do **dependente**.
        nmsegurado:
          type: string
        cdmatalternativatitular:
          type: string
          description: Código alternativo da carteira do **titular**.
    VwClinicApiBeneficiario:
      type: object
      description: 'Conjunto de **dados cadastrais, do plano e da carteirinha** do beneficiário. O JSON pode usar **camelCase** ou **PascalCase**. Em cenários de **intercâmbio** entre operadoras, alguns campos podem vir vazios ou nulos.


        Datas e textos longos seguem o **formato acordado** com a operadora (em geral datas em texto legível).

        '
      additionalProperties: true
      properties:
        dtvalidade:
          type: string
          description: Data de validade impressa ou lógica da carteirinha.
        nmuf:
          type: string
          description: Nome ou identificação da UF (base local ou intercâmbio).
        nrtelefone:
          type: string
        dsmultiempresa:
          type: string
          description: Descrição do cedente multiempresa.
        dscomplemento:
          type: string
        cdcontratointerno:
          type: string
        dsendereco:
          type: string
        cdregistroms:
          type: string
          description: Código de registro na ANS do plano (pode não ser informado em intercâmbio).
        dsregulamentacaoplano:
          type: string
        dsrazaosocial:
          type: string
        dstipounidade:
          type: string
          description: Tipo ou nome da operadora contratada.
        nrcelular:
          type: string
        nrendereco:
          type: string
        tpsexo:
          type: string
        nrcep:
          type: string
        cdcontrato:
          type: string
        dsempresa:
          type: string
        dscpt:
          type: string
          description: Informação de CPT / patologia (texto ou `NAO HA`).
        tpcontratacao:
          type: string
          description: Ex. INDIVIDUAL/FAMILIAR, COLETIVO POR ADESÃO, etc.
        cdempresa:
          type: string
        cdmultiempresa:
          type: string
        dtcontratacao:
          type: string
        nrans:
          type: string
        tpusuario:
          type: string
          description: Tipo de usuário no plano; em intercâmbio pode vir vazio.
        cdplano:
          type: string
        dstipo:
          type: string
          description: TITULAR, DEPENDENTE, AGREGADO ou vazio.
        dsfantasiaempresa:
          type: string
        snresponsavelfinanceiro:
          type: string
          description: S/N — responsável financeiro.
        nrcns:
          type: string
        cdmatricula:
          type: string
        tppessoa:
          type: string
          description: J (jurídica) ou F (física), conforme tipo de contrato.
        cdmatriculatem:
          type: string
        dtadesao:
          type: string
        cdmatalternativa:
          type: string
          description: Código alternativo da carteira (ex. 16 posições em intercâmbio).
        dscoberturaoferecida:
          type: string
        nmcidade:
          type: string
        dsplano:
          type: string
          description: Nome comercial do plano / descrição.
        nmmae:
          type: string
        dtnascimento:
          type: string
        dsbairro:
          type: string
        snativo:
          type: string
          description: Indica se o beneficiário está ativo no plano (ex. **S** / **N**).
        dtcancelamento:
          type: string
        dtcadastro:
          type: string
        dsemail:
          type: string
        nmsegurado:
          type: string
        nmSocial:
          type: string
        nridade:
          type: string
          description: Idade do beneficiário no formato exibido ao usuário.
        dsacomodacao:
          type: string
        dsabrangenciageografica:
          type: string
        dszona:
          type: string
        dtultimacobranca:
          type: string
        nrcpf:
          type: string
          description: CPF com 11 dígitos (completado com zeros à esquerda quando aplicável).
        dstabelapreco:
          type: string
        dsdadosoperadora:
          type: string
          description: Texto com telefone da operadora.
        tpcontrato:
          type: string
        tpcarteira:
          type: string
          description: Ex. LOW_COST, COOPERADO, PADRAO.
        tpbeneficiario:
          type: string
          description: LOCAL ou INTERCAMBIO.
        dsareaatuacaproduto:
          type: string
          description: Área de atuação / abrangência descritiva.
        txrodape:
          type: string
          description: Texto de rodapé (site, telefones).
        nrtelefonesac:
          type: string
        redeatendimento:
          type: string
          description: Código/tipo de rede (MASTER, ESPECIAL, BASICO, etc.).
        atend:
          type: string
          description: Informações de rede de atendimento ou mensagem institucional associada à carteira.
        nomecontratante:
          type: string
        dtvigencia:
          type: string
          description: Data de vigência do contrato.
        nrvia:
          type: string
          description: Número da via da carteira.
  securitySchemes:
    x-api-key:
      type: apiKey
      name: x-api-key
      in: header