Pular para o conteúdo principal

Paginação e filtros

Todos os recursos seguem as mesmas regras de listagem e de consulta por ID. Os relatórios contábeis e as rotas de plataformas parceiras são as exceções e têm parâmetros próprios.

Listar​

Rota: GET /external/v1/<recurso>.

ParâmetroTipoPadrãoDescrição
pagenúmero1Página desejada, começando em 1. Opcional.
limitnúmero25Itens por página. Opcional. Não há teto aplicado pela API; use até 100 para respostas rápidas.
relationstexto (JSON)—Filtro, ordenação e relações, num objeto JSON enviado como texto e codificado para URL.

Sem relations, a lista vem ordenada do mais recente para o mais antigo (createdAt decrescente).

O parâmetro relations​

relations é um objeto JSON com até quatro chaves:

ChavePara que serveExemplo
whereFiltra pelos campos do registro{"where":{"status":"WINNER"}}
orderByOrdena{"orderBy":{"updatedAt":"desc"}}
includeTraz registros relacionados junto. Não use em contas bancárias e cobranças.{"include":{"Step":true}}
selectLimita os campos devolvidos{"select":{"id":true,"title":true}}

Os nomes de campos são os mesmos das tabelas de cada recurso. Em where, além da igualdade simples, valem operadores como in, not, contains, startsWith, gt, gte, lt e lte:

{
"where": {
"typeCategory": "REVENUE",
"originalDueDate": { "gte": "2026-11-01", "lte": "2026-11-30" },
"tags": { "has": "vip" }
},
"orderBy": { "originalDueDate": "asc" }
}

Exemplo de chamada (o curl -G --data-urlencode cuida da codificação):

curl -G "https://erp-api.ideros.api.br/external/v1/financial-entries" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=50" \
--data-urlencode 'relations={"where":{"typeCategory":"REVENUE"},"orderBy":{"originalDueDate":"asc"}}'
Cuidados com relations
  • JSON inválido é ignorado: se o texto não for um JSON válido, a API descarta o filtro e devolve a lista sem ele. Confira o JSON antes de confiar no resultado.
  • Campo ou relação inexistente responde 400 com uma mensagem genérica de dados inválidos.
  • A empresa é sempre a da sua chave. A API acrescenta o filtro da sua empresa a toda listagem; um companyId enviado em where é substituído. Registros relacionados de outra empresa trazidos por include são removidos da resposta.
  • Registros inativos também aparecem. Para listar só os ativos, filtre {"where":{"isActive":true}}.

Formato da resposta​

{
"items": [
{ "id": "6a1f…", "createdAt": "2026-11-10T13:20:00.000Z", "…": "…" }
],
"meta": {
"itemCount": 25,
"totalItems": 142,
"itemsPerPage": 25,
"totalPages": 6,
"currentPage": 1
}
}
CampoDescrição
itemsRegistros da página.
meta.itemCountQuantidade de registros nesta página.
meta.totalItemsTotal de registros que atendem ao filtro.
meta.itemsPerPageO limit usado.
meta.totalPagesTotal de páginas.
meta.currentPageA página devolvida.

Para percorrer tudo, avance page até currentPage chegar a totalPages.

Buscar por ID​

Rota: GET /external/v1/<recurso>/:id. Devolve o registro como objeto, sem envelope.

ID inexistente não dá 404

Se o ID não existir, ou se o registro for de outra empresa, a resposta é 200 com corpo {}. Confira se o objeto tem id antes de usá-lo.

Criar e atualizar​

  • O corpo é JSON, com os campos da tabela de cada recurso. Datas em ISO 8601 (2026-11-17 ou 2026-11-17T14:30:00.000Z).
  • POST responde 201 com o registro criado; PUT responde 200 com o registro atualizado.
  • A coluna Obrigatório das tabelas segue o cadastro da plataforma: os mesmos campos que a tela exige.
  • Não envie companyId: a empresa vem da sua chave.
  • Não há exclusão pela API. Para inativar um registro, use a tela do Tesselys.

IDs​

Os IDs são textos de 24 caracteres hexadecimais (ex.: 6a1f3c9e8b2d4f0a1c3e5b7d). Guarde o id devolvido na criação para as próximas chamadas, ou use o campo externalCode, quando o recurso tiver, para gravar o código do seu sistema.

Campos garantidos

Conte só com os campos listados na página de cada recurso. Outros campos que eventualmente venham na resposta podem mudar ou sair sem aviso.

Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.