Cobrança

Os dois motores consomem tokens do workspace: o mesmo pool usado pela interface web do Sherlocker. Os princípios são idênticos — o que muda é a unidade de preço: o Motor de CPF/CNPJ cobra por análise; o Motor de Borderô cobra por entidade única do arquivo.

Preço em definição durante o beta. Não fixe um custo em código. Todos os valores de tokens nesta página são ilustrativos.

O débito acontece na criação — e é fail-closed

Os tokens são debitados no momento do POST, antes de o motor rodar. A confirmação varia por motor:

CPF/CNPJ (POST /analyses): a resposta 202 Accepted confirma o débito com os campos tokens_charged (quanto foi debitado) e balance (saldo após o débito), informados em melhor esforço — se a consulta de saldo falhar no momento da resposta, os campos podem estar ausentes, o que não altera a cobrança em si.
Borderô (POST /operations): a cobrança acontece normalmente na criação, mas não aparece no payload — a resposta 202 traz apenas operation_id, status e created_at. Acompanhe débitos e estornos no extrato de tokens do workspace, no app Sherlocker.

Se o saldo do workspace for insuficiente, o POST falha com 402 insufficient_tokens e nada é cobrado nem executado — o erro traz os campos required e balance para você saber quanto falta. Requisições rejeitadas com qualquer erro (400, 401, 402, 403, 409, 422) nunca cobram.

Quanto custa em cada motor

CPF/CNPJ
Borderô

Cada POST /analyses debita o preço de uma análise:

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "status": "pending",
  "tokens_charged": 10,
  "balance": 990,
  "poll_after_seconds": 2,
  "request_id": "req-uuid"
}

`completed` cobra sempre, inclusive verdict `incompleto`

Uma análise que termina completed é cobrada sempre, mesmo quando o verdict é incompleto. O motivo: o motor executou o trabalho (rodou todos os blocos da engine) e incompleto significa apenas que uma ou mais fontes de dados externas ficaram indisponíveis durante a execução.Nesse caso, use o campo coverage da resposta do GET /analyses/{id} para ver exatamente quais fontes falharam (coverage[].status: "failed") e quais foram consultadas. Veja Ciclo de vida.

O custo de uma operação é por entidade única do borderô — não por título e não por arquivo:

custo = (cedente + sacados únicos) × preço unitário de análise

Cada entidade única gera uma análise do Motor de CPF/CNPJ — e é essa análise que é cobrada. Títulos não têm custo próprio: o mesmo sacado em 10 títulos conta uma vez.

Exemplo numérico

Um borderô com 42 títulos, do mesmo cedente, sacados contra 11 empresas distintas:

	Quantidade
Títulos no arquivo	42
Cedente	1
Sacados únicos	11
Entidades cobradas	12

Com um preço unitário ilustrativo de 1 token por análise, a operação debita 12 tokens — não 42. Borderôs concentrados (muitos títulos, poucos sacados) custam proporcionalmente menos por título do que borderôs pulverizados.

A cobrança não aparece no payload da API de borderô — nem na resposta do POST, nem no GET /operations/{id}. O débito por operação (e o estorno em failed) fica registrado no extrato de tokens do workspace, no app Sherlocker.

O débito é após o parse

No borderô, o débito acontece depois do parse do CNAB — é o parse que revela quantas entidades únicas o arquivo tem. Arquivo ausente, cedente_cnpj inválido ou CNAB que não parseia retorna 400 validation_error e nada é cobrado.

Estorno automático em `failed`

Nos dois motores: se o processamento terminar com status: "failed" (falha interna do motor), os tokens debitados na criação são estornados automaticamente. O estorno é assíncrono — ele não aparece no body do GET, mas fica registrado no extrato de tokens do workspace no app Sherlocker.

Replay idempotente não cobra

Reenviar o POST com a mesma Idempotency-Key e o mesmo conteúdo dentro da janela de 24 horas retorna 200 OK com o body original da 202 — sem nova cobrança. É por isso que, em retries de timeout ou erro de rede, você deve reusar a mesma key. Veja Idempotência.

Resumo: cenário × cobrança

Cenário	HTTP	Cobra tokens?
Nova análise criada (`POST /analyses`)	`202`	Sim — preço de uma análise
Nova operação criada (`POST /operations`)	`202`	Sim — entidades únicas × preço unitário, após o parse (não aparece no payload)
Replay idempotente (mesma key + mesmo conteúdo)	`200`	Não
Borderô: arquivo ausente / CNAB que não parseia / `cedente_cnpj` inválido	`400`	Não (o débito só acontece após o parse)
Run termina `failed`	—	Cobrado na criação e estornado automaticamente
Análise termina `completed` com verdict `incompleto`	—	Sim (o trabalho foi executado)
Requisição rejeitada com erro (`400`, `401`, `402`, `403`, `409`, `422`)	`4xx`	Não

Saldo e recarga

O saldo de tokens e a recarga (top-up) são gerenciados no app Sherlocker: a API /v1 compartilha o mesmo pool de tokens do workspace. O extrato do workspace no app mostra os débitos por análise/operação e os estornos de runs failed.

Próximos passos

Idempotência

Retry seguro sem risco de cobrança dupla

Ciclo de vida

Status, verdicts e o campo coverage

Erros

Formato RFC 7807 e o erro insufficient_tokens

Começando

Conceitos

Motor de CPF/CNPJ

Motor de Borderô (títulos & NFe)

Referência comum

Acesso e suporte

O débito acontece na criação — e é fail-closed

Quanto custa em cada motor

`completed` cobra sempre, inclusive verdict `incompleto`

Exemplo numérico

O débito é após o parse

Estorno automático em `failed`

Replay idempotente não cobra

Resumo: cenário × cobrança

Saldo e recarga

Próximos passos

Idempotência

Ciclo de vida

Erros

​O débito acontece na criação — e é fail-closed

​Quanto custa em cada motor

​completed cobra sempre, inclusive verdict incompleto

​Exemplo numérico

​O débito é após o parse

​Estorno automático em failed

​Replay idempotente não cobra

​Resumo: cenário × cobrança

​Saldo e recarga

​Próximos passos

Idempotência

Ciclo de vida

Erros

O débito acontece na criação — e é fail-closed

Quanto custa em cada motor

`completed` cobra sempre, inclusive verdict `incompleto`

Exemplo numérico

O débito é após o parse

Estorno automático em `failed`

Replay idempotente não cobra

Resumo: cenário × cobrança

Saldo e recarga

Próximos passos