Extrato de Utilização e Coparticipação

Informações

Avisos
  1. Só são suportadas integrações no padrão REST.
  2. O campo "Regra de preenchimento" esclarece quais regras / validações serão aplicadas ou quais os conteúdos serão permitidos ou rejeitados. As ações descritas aqui devem ser implementadas por seus WS, evitando que os conteúdos inválidos sejam criticados pelo nosso sistema de integrações.
Critérios de preenchimento
AbreviaçãoNomeDescrição
MMandatórioO preenchimento do atributo é obrigatório. Caso o atributo esteja nulo ou em branco, seu "response" será rejeitado.
CCondicionalO atributo pode tornar-se obrigatório quando um ou mais atributos auxiliares for preenchido / atualizado.
OPOpcional

Seu preenchimento não é obrigatório. Pode-se enviar NULL para objetos, ou arrays vazios para tipos Array

Método "extrato"

Demonstra o conteúdo a ser exibido no extrato de utilização (obedece o padrão PIN-SS Componente Utilização) além de permitir exibição de informações sobre coparticipação.

Regras de negócio

  • De acordo com o componente de utilização, seu método deve permitir:
    • Consultar as últimas seis competências, conforme RN 389;
    • Retornar os eventos realizados pelo beneficiário logado e de todo o seu grupo família, tendo coparticipação ou não;
    • Se o beneficiário solicitado for o titular, retornar a sua movimentação e de todo o grupo familiar
    • Se o beneficiário solicitado for um dependente tipo cônjuge ou companheiro(a), retornar a sua movimentação e a dos demais dependentes, excluindo o titular
    • Se o beneficiário solicitado for outro tipo de dependente, retornar apenas a sua própria movimentação
    • Será adicionado ao corpo da requisição as informações enviadas no atributo integracao no retorno do login.
  • O Webservice deverá retornar os eventos reconhecidos pela operadora, independente da ocorrência de glosa de valor, considerando-se todos os eventos realizados na rede credenciada, referenciada, cooperada ou fora da rede, quando houver cobertura para reembolso – Trecho extraído da RN 389
  • No corpo da requisição serão enviado o objeto integração do retorno do login.

Endpoint

Endpoint
Método
Header Content-Type
Descrição

exemplo.com/extrato

Atenção

O endpoint obrigatoriamente deve terminar com "/extrato".

POST

application/json

Endpoint de extrato

Parâmetros de entrada

ParâmetroObrigatórioTipoDescrição
integracaoMObjetoInformações necessárias para realizar a identificação do beneficiário no sistema. A estrutura aqui enviada será enviada no corpo das demais requisições de integração junto com os dados preenchidos pelo beneficiário no sistema.
anoMStringAno do extrato (YYYY)
mesMStringMês do extrato (MM)

Request body

{
  "integracao": {
    "<chave>": "<valor>"
  },
  "ano": "<ano>",
  "mes": "<mes>"
}

Objetos e atributos de retorno

Atenção

Os atributos devem seguir exatamente os mesmos nomes indicados nesta documentação, caso contrário, serão rejeitados pelo validador de integração.

Exemplo do atributo "extrato":

  • Extrato
  • extrato-utilizacao
  • ExtratoUtilizacao
  • extrato (thumbs up)

Descrição dos objetos e atributos de retorno - Sucesso

Está indicado abaixo a estrutura de retorno do seu método de extrato. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal
AtributoCritérioTipoDescriçãoRegra de preenchimento
statusM

Boolean

Indica que a requisição foi bem sucedida

True 

extratoMArray de objetos "detalheExtrato"Retornar um array de objetos “detalheExtrato“.

Retornar uma lista de objetos “detalheExtrato“ (definição abaixo).

Quando nenhum resultado for obtido, retornar o array vazio.

alertaOPStringCaso queira enviar um alerta para os beneficiário no ato da apresentação dos débitos, insira o conteúdo aqui. Utilize textos curtos para facilitar a leitura.

Formato: Texto Livre. 

Objeto detalheExtrato
AtributoCritérioTipoDescriçãoRegra de preenchimento
nomeBeneficiarioM

String

Nome do beneficiário que aparecerá no extrato

Formato: Texto livre.

matriculaBeneficiarioMString

Matrícula do beneficiário em seu sistema de gestão

ASCII (nao permite especiais). 

codigoEventoMString

Código do evento a ser exibido no extrato


Formato: Texto livre.

descricaoEventoMStringDescrição do evento a ser exibido

Formato: Texto livre.

dataAtendimentoMStringData de execução do serviço / atendimentoFormato: YYYY-MM-DD
codigoExecutanteMString

Código de identificação do prestador executante no seu sistema.

Formato: ASCII (nao permite especiais). 


nomeExecutanteMString

Nome do prestador executante.

Formato: Texto livre.

cpfCnpjExecutanteMNumber

Indique o CPF ou CNPJ do executante do serviço

Formato: CPF ou CNPJ. 

codigoTipoServicoMStringCódigo do tipo de serviço realizado. O código de serviços será utilizado para agrupar os procedimentos e apresentar os subtotais exigidos pela RN 389

Formato: ASCII (nao permite especiais). 

Recomenda-se observância à RN 329

descricaoTipoServicoMString

Descrição do tipo de serviço realizado, exemplo:

Consultas, Exames/Terapias, Internação, Odontologia, outras despesas, entre outras. 

Assim como o atributo codigoTipoServico, servirá como agrupador para apresentação de subtotais exigidos pela RN 389.

Formato: Texto livre.

Recomenda-se observância à RN 329

quantidadeMStringQuantidade executada.Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)
valorServicoOPStringIndique o valor individualizado do evento, se houver ou se desejar exibi-lo individualmente. Se não for enviado, apenas será exibida a descrição do evento, sem valor individualizado (RN 389 permite esse comportamento).Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)
valorCoparticipacaoOPStringIndique o valor da coparticipação, se houver ou se desejar exibi-la.Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)
codigoContratoMStringCódigo do contrato do beneficiário. Este código será utilizado para organizar as informações por contrato nas interfaces do produto

O código enviado neste campo deve ter relação com a estrutura de contratos do login do usuário.

Retorno da API - Sucesso

{
    "status": true,
    "extrato": [
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Pariatur ut.",
            "descricaoEvento": "Error maxime ducimus harum mollitia. Possimus ipsam illum omnis facere rerum quibusdam.",
            "dataAtendimento": "2019-03-01",
            "codigoExecutante": "2480",
            "nomeExecutante": "Sr. Elias Lovato Neto",
            "cpfCnpjExecutante": 34529305562,
            "codigoTipoServico": "8908",
            "descricaoTipoServico": "Possimus modi.",
            "quantidade": "6.50",
            "valorServico": "553.70",
            "valorCoparticipacao": "199.33",
            "codigoContrato": "5144"
        },
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Dicta illum est.",
            "descricaoEvento": "Ut molestias blanditiis totam. Molestiae animi illum in at qui sed sed.",
            "dataAtendimento": "2019-03-16",
            "codigoExecutante": "5488",
            "nomeExecutante": "Dr. Srta. Renata Paz Aguiar Sobrinho",
            "cpfCnpjExecutante": 61728051509,
            "codigoTipoServico": "8576",
            "descricaoTipoServico": "Reprehenderit est odio.",
            "quantidade": "7.88",
            "valorServico": "521.14",
            "valorCoparticipacao": "151.13",
            "codigoContrato": "6670"
        },
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Beatae ducimus quas.",
            "descricaoEvento": "Harum eaque consequatur repellat quia et voluptate. Quibusdam omnis assumenda dolorem. Delectus aut incidunt magnam deserunt.",
            "dataAtendimento": "2019-03-05",
            "codigoExecutante": "4548",
            "nomeExecutante": "Srta. Mia Rocha Rios",
            "cpfCnpjExecutante": 15312001333,
            "codigoTipoServico": "4424",
            "descricaoTipoServico": "Voluptatem aut earum eum.",
            "quantidade": "7.10",
            "valorServico": "496.61",
            "valorCoparticipacao": "74.49",
            "codigoContrato": "2291"
        },
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Laborum non dolorum.",
            "descricaoEvento": "Suscipit distinctio corporis est aut. Iusto et laborum beatae voluptate accusamus qui cum beatae. Totam sint corporis molestias.",
            "dataAtendimento": "2019-03-08",
            "codigoExecutante": "2491",
            "nomeExecutante": "Sr. Dr. Gian Gabriel da Rosa",
            "cpfCnpjExecutante": 99167550193,
            "codigoTipoServico": "9697",
            "descricaoTipoServico": "Soluta sint.",
            "quantidade": "4.37",
            "valorServico": "51.06",
            "valorCoparticipacao": "4.60",
            "codigoContrato": "1978"
        },
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Pariatur nam.",
            "descricaoEvento": "Explicabo itaque dolorem omnis natus. Quia esse temporibus aut. Deleniti et quidem velit dicta voluptatem ipsum et.",
            "dataAtendimento": "2019-03-20",
            "codigoExecutante": "6241",
            "nomeExecutante": "Sra. Benjamin Ferminiano Torres Jr.",
            "cpfCnpjExecutante": 30044162200,
            "codigoTipoServico": "7901",
            "descricaoTipoServico": "Aut natus dolore officiis.",
            "quantidade": "2.55",
            "valorServico": "241.57",
            "valorCoparticipacao": "65.22",
            "codigoContrato": "4362"
        },
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Illum blanditiis magnam.",
            "descricaoEvento": "Doloremque recusandae aspernatur impedit ut iusto qui iusto. A corporis sapiente doloremque et. Ut necessitatibus dolor vitae adipisci et aut.",
            "dataAtendimento": "2019-03-04",
            "codigoExecutante": "9339",
            "nomeExecutante": "Dr. Giovane Dias",
            "cpfCnpjExecutante": 97755576230,
            "codigoTipoServico": "7058",
            "descricaoTipoServico": "Iste quas.",
            "quantidade": "4.65",
            "valorServico": "362.17",
            "valorCoparticipacao": "18.11",
            "codigoContrato": "2972"
        },
        {
            "nomeBeneficiario": "Derlandy Belchior",
            "matriculaBeneficiario": "3020170703122646",
            "codigoEvento": "Earum iure.",
            "descricaoEvento": "Sapiente aut voluptatem at doloremque. Vitae placeat non soluta aut dolor non. Deserunt eligendi quaerat quia mollitia omnis facere.",
            "dataAtendimento": "2019-03-08",
            "codigoExecutante": "4796",
            "nomeExecutante": "Srta. Srta. Amanda Ashley Marés Jr.",
            "cpfCnpjExecutante": 77682219157,
            "codigoTipoServico": "1845",
            "descricaoTipoServico": "Sit vero et provident.",
            "quantidade": "8.56",
            "valorServico": "354.01",
            "valorCoparticipacao": "14.16",
            "codigoContrato": "0962"
        }
    ]
}

Descrição dos objetos e atributos de retorno - Falha

Está indicado abaixo a estrutura de retorno do seu método de extrato. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal
AtributoCritérioTipoDescriçãoRegra de preenchimento
statusM

Boolean

Indica que a requisição foi mal sucedida.false
motivoCriticaMStringMotivo pelo qual não foi possível realizar a requisição.

Este campo é obrigatório quando o status igual a false.

Formato: Texto Livre

Retorno da API - Falha

{
    "status": false,
    "motivoCritica": ""
}