Extrato de Utilização e Coparticipação
Informações
Avisos
- Só são suportadas integrações no padrão REST.
- 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ção | Nome | Descrição |
|---|---|---|
| M | Mandatório | O preenchimento do atributo é obrigatório. Caso o atributo esteja nulo ou em branco, seu "response" será rejeitado. |
| C | Condicional | O atributo pode tornar-se obrigatório quando um ou mais atributos auxiliares for preenchido / atualizado. |
| OP | Opcional | 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âmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| integracao | M | Objeto | Informaçõ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. |
| ano | M | String | Ano do extrato (YYYY) |
| mes | M | String | Mês do extrato (MM) |
{
"integracao": {
"<chave>": "<valor>"
},
"ano": "<ano>",
"mes": "<mes>"
}
Request body
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":
Extratoextrato-utilizacaoExtratoUtilizacao- extrato
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
| Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
| status | M | Boolean | Indica que a requisição foi bem sucedida | True |
| extrato | M | Array 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. |
| alerta | OP | String | Caso 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
| Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
| nomeBeneficiario | M | String | Nome do beneficiário que aparecerá no extrato | Formato: Texto livre. |
| matriculaBeneficiario | M | String | Matrícula do beneficiário em seu sistema de gestão | ASCII (nao permite especiais). |
| codigoEvento | M | String | Código do evento a ser exibido no extrato | Formato: Texto livre. |
| descricaoEvento | M | String | Descrição do evento a ser exibido | Formato: Texto livre. |
| dataAtendimento | M | String | Data de execução do serviço / atendimento | Formato: YYYY-MM-DD |
| codigoExecutante | M | String | Código de identificação do prestador executante no seu sistema. | Formato: ASCII (nao permite especiais). |
| nomeExecutante | M | String | Nome do prestador executante. | Formato: Texto livre. |
| cpfCnpjExecutante | M | Number | Indique o CPF ou CNPJ do executante do serviço | Formato: CPF ou CNPJ. |
| codigoTipoServico | M | String | Có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 |
| descricaoTipoServico | M | String | 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 |
| quantidade | M | String | Quantidade executada. | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) |
| valorServico | OP | String | Indique 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) Atenção Caso não deseje exibir a coluna de valor do serviço, NÃO ENVIE o atributo "valorServico". Enviar este atributo com ZERO (0) ou nulo (null) fará com que o valor do serviço seja exibido com ZERO. |
| valorCoparticipacao | OP | String | Indique o valor da coparticipação, se houver ou se desejar exibi-la. | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) Atenção Importante: é através deste atributo que os valores serão exibidos no relatório de coparticipação OU de utilização. Um caso prático para entendimento: Se um determinado beneficiário teve uma utilização de R$ 100,00 e coparticipação de R$ 10,00 para determinado evento, seu método deve enviar DUAS VEZES o mesmo evento. Uma vez o atributo valorCoparticipacao deve vir ZERADO (dessa forma vamos colocar o evento no relatório de utilização) e mandar novamente a mesma linha, só que COM VALOR de coparticipação - e com isso colocaremos o evento no relatório de coparticipação. Ou seja: o que define se um evento aparece no relatório de utilização OU coparticipação é o atributo valorCoparticipacao |
| codigoContrato | M | String | Có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
| Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
| status | M | Boolean | Indica que a requisição foi mal sucedida. | false |
| motivoCritica | M | String | Motivo 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": ""
}
Mobile Saúde - 2019