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âmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
page | número | 1 | Página desejada, começando em 1. Opcional. |
limit | número | 25 | Itens por página. Opcional. Não há teto aplicado pela API; use até 100 para respostas rápidas. |
relations | texto (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:
| Chave | Para que serve | Exemplo |
|---|---|---|
where | Filtra pelos campos do registro | {"where":{"status":"WINNER"}} |
orderBy | Ordena | {"orderBy":{"updatedAt":"desc"}} |
include | Traz registros relacionados junto. Não use em contas bancárias e cobranças. | {"include":{"Step":true}} |
select | Limita 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"}}'
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
400com 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
companyIdenviado emwhereé substituído. Registros relacionados de outra empresa trazidos porincludesã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
}
}
| Campo | Descrição |
|---|---|
items | Registros da página. |
meta.itemCount | Quantidade de registros nesta página. |
meta.totalItems | Total de registros que atendem ao filtro. |
meta.itemsPerPage | O limit usado. |
meta.totalPages | Total de páginas. |
meta.currentPage | A 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.
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-17ou2026-11-17T14:30:00.000Z). POSTresponde201com o registro criado;PUTresponde200com 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.
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.
A nossa equipe ajuda você a configurar e usar esse recurso.