Paginação

Cada recurso de cada API pode possuir ou não paginação, caso a quantidade de registros retornados justifique a mesma. A paginação estará disponível e deverá funcionar independente se o recurso permite filtros por query ou POST. Isso é, filtros e paginação são aplicados de forma independente.

Parâmetros de Requisição

Exemplo de query com paginação

GET {uri}?page=1&page-size=25

Quando existir paginação para o recurso deverão ser utilizados os parâmetros de query abaixo para a navegação dos resultados:

Parâmetro

Descrição

Valor Padrão

Parâmetro

Descrição

Valor Padrão

page

Número da página que está sendo requisitada (o valor da primeira página é 1).

1

page-size

Quantidade total de registros por páginas.

25

O valor padrão será assumido sempre que o parâmetro não estiver preenchido ou estiver nulo

Atributos de Resposta

Exemplo de paginação - Apenas uma página

A paginação das APIs são feitas no objeto principal da API. Por exemplo na API de branches, conforme exemplo abaixo, os registros a serem paginados são os objetos "branches". O mesmo deve ser seguido para as demais APIs, por exemplo, "products" nas APIs de produtos, "resources" na API de resources etc.

{ "data": { "brand": { "name": "EXEMPLO", "companies": [ { "name": "SEGURADORA EXEMPLO", "cnpjNumber": "123456", "branches": [ {...}, {...}, {...} ] } ] } }, "links": { "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches", }, "meta": { "totalRecords": 3, "totalPages": 1 } }

Exemplo de paginação - Primeira página

{ "data": { "..." }, "links": { "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=1&page-size=25", "next": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=2&page-size=25", "last": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=10&page-size=25" }, "meta": { "totalRecords": 250, "totalPages": 10 } }

Exemplo de paginação - Última Página

Além dos dados requisitados, as respostas paginadas também terão em sua estrutura dois objetos adicionais que incluirão parâmetros para facilitar a navegação das páginas:

Links

Os links devem sempre ser validados de acordo com o pattern publicado no swagger.

Quando preenchidos devem ter a mesma estrutura (schema, host, api, versão e recurso) do que esta sendo paginado.

No objeto links, serão retornadas hypermedia (referências para os recursos relacionados) de paginação conforme parâmetros abaixo:

Parâmetro

Descrição

Restrição

Parâmetro

Descrição

Restrição

first

A URI para requisitar a primeira página.

Obrigatório se a resposta não for a primeira página.

last

A URI para requisitar a última página.

Obrigatório se a resposta não for a última página.

prev

A URI para requisitar a página anterior.

Obrigatório quando houver página anterior. Não deve ser enviado quando for a primeira página.

next

A URI para requisitar a próxima página.

Obrigatório quando houver página posterior. Não deve ser enviado quando for a última página.

self

A URI para requisitar a própria página.

  • Quando chamado o método GET deverá retornar o link para o próprio recurso consultado

  • Quando chamado o método POST deverá retornar o link para o recurso criado

  • Quando chamado método PATCH deverá retornar o link para o recurso alterado

Meta

No objeto meta, serão retornadas informações sobre o total de registros disponíveis

Parâmetro

Descrição

Restrição

Parâmetro

Descrição

Restrição

totalRecords

O número total de registros da requisição.

Este atributo é obrigatório.

totalPages

O número total de páginas da requisição.

Este atributo é obrigatório. Se não possuir nenhum registro o valor deve ser 0.

Para cada um desses atributos o tamanho da página especificado na requisição deverá ser utilizado para o cálculo dos valores.

Regras Adicionais

  1. O tamanho máximo da página (page-size) é 1000 registros para qualquer endpoint (a menos que na API esteja especificado outros valores).

  2. A instituição transmissora/detentora pode definir um tamanho máximo da página (page-size) inferior ao tamanho máximo permitido pela API, caso entenda necessário diminuir o limite para atender o SLA de resposta.

  3. Caso a instituição transmissora/detentora defina um tamanho máximo de página (page-size) inferior, se for requisitado uma quantidade de registros maior do que seu limite operacional, e desde que o valor esteja de acordo o tamanho máximo permitido pela API, esta deverá responder entregando os dados e utilizando o page-size do seu limite operacional definido.

  4. A instituição transmissora/detentora deve realizar os ajustes de paginação antes de efetivar a consulta:

  5. Ex: Ao solicitar a segunda pagina 1000 registros, para uma instituição que trabalha com max size 800, a transmissora deve retornar os itens de 801 a 1600.

  6. Se for requisitado uma quantidade de registros maior que o suportado pela API, o retorno será o código HTTP status code 422 Unprocessable Entity, indicando que o servidor entendeu a requisição, mas não é possível processá-la conforme foi solicitado.

  7. Se o retorno de uma chamada apresentar um objeto ao invés de uma lista, os campos totalPages e totalRecords deverão ser igual a 1.

  8. Para as APIs que possuem o endpoint de withdrawal (resgate) na Fase 2, quando não houver ocorrência de resgate, a paginação retornada deve ser totalPages e totalRecords igual a 1. Esse endpoint será padronizado em correção futura para trazer a mesma estrutura/paginação do endpoint de “portabilities”.

  9. Para as APIs que possuem o endpoint de movements (movimentos) na Fase 2, como existem dois objetos principais na chamada, a paginação deve ocorrer sob a soma dos itens retornados em movementsContributions e movementsBenefits, vide exemplo abaixo:

    1. Exemplo:

      1. Lista de movimentos de contribuições: 17 itens retornados

      2. Lista de movimentos de benefícios: 14 itens retornados

      3. Paginação padrão do OPIN descrita na documentação: máximo de 25 itens por página

        1. No exemplo acima, seria necessário 2 páginas para mostrar todos os 31 itens (17+14) presentes na chamada realizada contra o endpoint de movements, onde a primeira página apresentaria 25 registros, e na segunda página teríamos os 6 registros restantes.

        2. Em contrapartida se fosse considerado apenas uma das listas (movementsContribution e movementsBenefits)  para a paginação, teríamos somente um página.

      4. Dessa forma fica estabelecido que a paginação do endpoint de movements deve considerar todos os itens presentes nas duas listas, movementsContribution e movementsBenefits.