API Reference

Como utilizar o OData

Esta página tem como objetivo orientar no uso do OData de forma simples e eficaz.

Consultas

As rotas da API pública podem ser consultadas utilizando OData, que é um protocolo padronizado para simplificar o consumo de APIs REST. Para a maioria das consultas, os principais parâmetros para conhecer são os seguintes:

  • $filter
  • $orderby
  • $skip
  • $top

IMPORTANTE: Todas as consultas retornam, no máximo, 100 registros por requisição.

Filtro

Para filtrar as informações em uma rota, você deve utilizar o parâmetro $filter. Veja este primeiro exemplo de uma consulta de Usuários com o filtro $filter=name eq 'lucas', retornando os valores que possuem nome igual a lucas:

https://api.nibo.com.br/accountant/api/v1/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=name eq 'lucas'

Veja este exemplo de requisição utilizando filtros aplicados: retorna apenas usuários não administradores, com nome exatamente igual a 'joão' e e-mail que começa com 'joão@gmail'.

https://api.nibo.com.br/accountant/api/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=isAdmin eq false and name eq 'joão' and startswith(email, 'joão@gmail')

Paginação

As consultas (GET) retornam os parâmetros totalAllItems contendo o número de todos os registros encontrados e total que representa o número de registros encontrados após aplicar os filtros, e você pode utilizar os parâmetros $top, $skip e $orderby para realizar a paginação.

Neste exemplo, temos os parâmetros $top=10, $skip=20 e $orderby=name para indicar que o retorno deverá ser da terceira página, contendo 10 itens por página e ordenado alfabeticamente pelo nome do usuário.

https://api.nibo.com.br/accountant/api/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=isAdmin eq true&$orderby=name&$skip=20&$top=10

Juntando tudo

Veja este exemplo de uma consulta de Usuários:

  • $filter=isAdmin eq true - Filtra apenas usuários administradores.
  • $top=20 - Tamanho da página (20 itens).
  • $skip=0 - Página 1 (não pulou itens de páginas anteriores).
  • $orderby=name - Ordenado alfabeticamente pelo nome.
https://api.nibo.com.br/accountant/api/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=isAdmin eq true&$orderby=name&$top=20&$skip=0

Como usar o OData

O OData oferece recursos robustos para consultas flexíveis e eficientes, permitindo criar requisições altamente personalizáveis. Com sua sintaxe padronizada, você pode construir consultas que combinam filtros avançados para extrair dados precisos.

O OData garante desempenho consistente mesmo com grandes volumes. Essa combinação de recursos permite que cada requisição retorne exatamente o necessário, no formato mais adequado para seu cenário.

Explore todos os operadores, sintaxes avançadas e padrões recomendados na documentação oficial completa em odata.org, onde você encontrará exemplos práticos e orientações detalhadas para o uso.