Como funcionam tokens e custos na API do Sherlocker

As consultas da API consomem tokens diretamente da conta Sherlocker associada ao usuário ou workspace dono do token de API.

Regra principal

Cada endpoint ou módulo pode ter um custo próprio em tokens.
O custo é descontado da conta vinculada ao token usado na requisição.
O consumo só deve ser definitivo quando a consulta retorna dados.
Se a consulta não retornar dados, o token não deve permanecer consumido.

Exemplos de custo por categoria

A tabela oficial de custos informa valores por consulta. Exemplos da documentação:

Gratuito: Pessoa Física por CPF; Pessoa Jurídica por CNPJ.
1 token: empresas de uma pessoa, empregos, telefones, e-mails, pessoas relacionadas, busca reversa por telefone, CPFs por e-mail, veículos por CPF/CNPJ, veículo por placa, licitações, domínios, dívidas e benefícios.
2 tokens: endereços, regularidades, imóveis urbanos, propriedades rurais, processos por CPF/CNPJ e processo por número.
7 tokens: perfil patrimonial completo por CPF ou CNPJ.
12 tokens: perfil cadastral completo por CNPJ.
15 tokens: perfil cadastral completo por CPF.

Diferença entre plataforma, mapa e API

Na plataforma visual, navegar pelo mapa, usar a lupa ou expandir visualmente relacionamentos não consome tokens por si só. O consumo acontece quando o usuário abre um nó/sidebar e executa módulos pagos que retornam dados.

Na API, o raciocínio equivalente é: o consumo está ligado ao endpoint/módulo chamado pelo token de API, não à navegação visual.

Como controlar custos em integrações

Comece por endpoints gratuitos ou baratos para validar se o alvo é correto.
Use perfis agregados quando fizer sentido operacional, mas lembre que eles custam mais tokens.
Evite rodar consultas caras em lote sem deduplicar CPF/CNPJ/placa/e-mail.
Guarde logs internos de consulta: endpoint, identificador, status, horário e workspace.
Se receber 402, o saldo de tokens pode ser insuficiente.

Fonte oficial

Consulte sempre a tabela atualizada em Custos da API Sherlocker.