Quickstart

Neste guia você envia um borderô CNAB 400, acompanha o processamento até a conclusão e busca o resultado hierárquico da análise — cedente, sacados, títulos e as violações de regra (issues) de cada nó. É a mesma esteira de análise da interface web do Sherlocker, agora acessível por API. Não confunda com o Motor de Análise (documentado aqui), que avalia o risco de um CNPJ ou CPF individual. O Motor de Borderô analisa o borderô inteiro — e usa o Motor de Análise por baixo para cada entidade.

Pré-requisitos

Acesso ao beta: a feature analysis_engine precisa estar habilitada no seu workspace. Solicite em Solicitar acesso.
Chave de API: criada no app Sherlocker em Settings → API Keys. As chaves têm prefixo slhk_ e são exibidas uma única vez — guarde em local seguro.
Saldo de tokens: a operação consome tokens do mesmo pool do workspace usado no app — um débito por entidade única do borderô (veja Cobrança).
Arquivo CNAB 400 remessa (.rem) — Banco Paulista 611, 444 colunas, Windows-1252 — com no máximo 128 MiB.
CNPJ do cedente da operação (14 dígitos, com ou sem formatação).

A base URL dos exemplos é https://221b-api.sherlocker.com.br/api/v1. A autenticação é feita pelo header Authorization: Bearer slhk_sua_chave_aqui; os Motores não aceitam ?token= na URL.

Crie a operação

Envie um POST /operations como multipart/form-data — o arquivo vai direto no form, sem base64:

Parte	Tipo	Obrigatória	Descrição
`file`	arquivo	Sim	CNAB 400 remessa (`.rem`). Máx. 128 MiB
`xmls`	arquivo	Não	ZIP com os XMLs de NFe (`nfeProc`) dos títulos. Máx. 512 MiB
`cedente_cnpj`	texto	Sim	CNPJ do cedente, 14 dígitos ou formatado (dígito verificador validado)
`engine_id`	texto	Não	ID da engine; omitido ou `template-padrao` → template do sistema
`purpose`	texto	Não	Finalidade da análise (auditoria LGPD)
`legal_basis`	texto	Não	Base legal LGPD para os sacados PF

curl -X POST "https://221b-api.sherlocker.com.br/api/v1/operations" \
  -H "Authorization: Bearer slhk_sua_chave_aqui" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "cedente_cnpj=12345678000195" \
  -F "engine_id=template-padrao"

import requests

with open("bordero.rem", "rb") as cnab, open("nfes.zip", "rb") as xmls:
    resp = requests.post(
        "https://221b-api.sherlocker.com.br/api/v1/operations",
        headers={"Authorization": "Bearer slhk_sua_chave_aqui"},
        files={"file": cnab, "xmls": xmls},
        data={"cedente_cnpj": "12345678000195", "engine_id": "template-padrao"},
    )
print(resp.status_code)  # 202
operation = resp.json()
operation_id = operation["operation_id"]

import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("bordero.rem"), "bordero.rem");
form.append("xmls", await openAsBlob("nfes.zip"), "nfes.zip");
form.append("cedente_cnpj", "12345678000195");
form.append("engine_id", "template-padrao");

const resp = await fetch(
  "https://221b-api.sherlocker.com.br/api/v1/operations",
  {
    method: "POST",
    headers: { Authorization: "Bearer slhk_sua_chave_aqui" },
    body: form,
  },
);
console.log(resp.status); // 202
const operation = await resp.json();
const operation_id = operation.operation_id;

Resposta (202 Accepted):

{
  "operation_id": "b2c3d4e5-0000-0000-0000-000000000001",
  "status": "queued",
  "created_at": "2026-07-09T12:00:00.000Z"
}

Guarde o operation_id: é com ele que você consulta o status e o resultado. A cobrança (uma por entidade única do borderô — cedente + sacados únicos) acontece normalmente na criação, mas não aparece no payload: acompanhe débitos e estornos no extrato de tokens do workspace, no app Sherlocker.O header Idempotency-Key é opcional. Se você enviá-lo, reenviar o mesmo payload com a mesma key devolve 200 com o body original (sem nova operação nem nova cobrança); a mesma key com payload diferente devolve 409 idempotency_conflict. Sem o header, cada POST cria uma operação nova. Veja Idempotência.

Acompanhe até a conclusão

Consulte GET /operations/{id} até o status ficar terminal (completed ou failed). O vocabulário de status é queued → processing → completed | failed. Não há header Retry-After nem campo de intervalo no body — consulte a cada ~2 segundos (consultar mais rápido não acelera o resultado, e o limite global é de 100 requisições por minuto por IP):

OPERATION_ID="b2c3d4e5-0000-0000-0000-000000000001"

while true; do
RESP=$(curl -s "https://221b-api.sherlocker.com.br/api/v1/operations/$OPERATION_ID" \
 -H "Authorization: Bearer slhk_sua_chave_aqui")
STATUS=$(echo "$RESP" | jq -r '.status')
echo "status: $STATUS"

if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
echo "$RESP" | jq .
break
fi

sleep 2
done

import time

while True:
    resp = requests.get(
        f"https://221b-api.sherlocker.com.br/api/v1/operations/{operation_id}",
        headers={"Authorization": "Bearer slhk_sua_chave_aqui"},
    )
    op = resp.json()
    print(f"status: {op['status']}")

    if op["status"] in ("completed", "failed"):
        break

    time.sleep(2)

let op;
while (true) {
  const resp = await fetch(
    `https://221b-api.sherlocker.com.br/api/v1/operations/${operation_id}`,
    {
      headers: { Authorization: "Bearer slhk_sua_chave_aqui" },
    },
  );
  op = await resp.json();
  console.log(`status: ${op.status}`);

  if (op.status === "completed" || op.status === "failed") break;

  await new Promise((r) => setTimeout(r, 2000));
}

Resposta (200) — o envelope de status traz sempre todos os campos:

{
  "id": "b2c3d4e5-0000-0000-0000-000000000001",
  "status": "completed",
  "file_name": "bordero.rem",
  "file_size": 4440,
  "engine_id": "0b3c6c7e-9d2a-4f1b-8e5d-2a1b3c4d5e6f",
  "titulo_count": 12,
  "approved_count": 9,
  "blocked_count": 2,
  "alert_count": 1,
  "created_at": "2026-07-09T12:00:00.000Z",
  "queued_at": "2026-07-09T12:00:00.000Z",
  "processing_at": "2026-07-09T12:00:02.000Z",
  "completed_at": "2026-07-09T12:02:15.000Z",
  "error": null
}

titulo_count, approved_count, blocked_count e alert_count são null até completed. A soma approved_count + blocked_count + alert_count sempre fecha com titulo_count — alert_count inclui os títulos com análise incompleta (fonte de dados indisponível).
completed_at só aparece preenchido em completed; error (string) só em failed.
Operações que terminam em failed são estornadas automaticamente.

Busque o resultado hierárquico

Com a operação completed, chame o GET /operations/{id}/result. Por padrão (?filter=issues) a resposta poda os títulos aprovados e os sacados sem problemas — você recebe só o que precisa de atenção:

cURL

curl "https://221b-api.sherlocker.com.br/api/v1/operations/$OPERATION_ID/result" \
  -H "Authorization: Bearer slhk_sua_chave_aqui"

Resposta (200):

{
  "operation_id": "b2c3d4e5-0000-0000-0000-000000000001",
  "cedente": {
    "id": "c0a80001-0000-0000-0000-000000000001",
    "cnpj": "12345678000195",
    "razao_social": "CEDENTE LTDA",
    "status": "blocked",
    "issues": [
      {
        "rule_id": "CEDENTE_PROTESTOS",
        "rule_name": "Protestos",
        "category": "blocking",
        "status": "blocked",
        "message": "Cedente: Protestos encontrados",
        "detail": { "field": "protestos", "actual": "3", "expected": "0" },
        "data_sources": [
          {
            "name": "cenprot",
            "fetched_at": "2026-07-06T09:00:00.000Z",
            "age_days": 3
          }
        ]
      }
    ],
    "sacados": [
      {
        "id": "c0a80001-0000-0000-0000-000000000002",
        "cnpj_cpf": "98765432000188",
        "razao_social": "SACADO SA",
        "tipo": "PJ",
        "status": "alerted",
        "issues": [],
        "titulos": [
          {
            "id": "c0a80001-0000-0000-0000-000000000003",
            "numero": "DOC-001",
            "valor": 1234.56,
            "data_vencimento": "2026-08-01",
            "nfe_chave": "35230612345678000195550010000000011000000011",
            "status": "alerted",
            "issues": [
              {
                "rule_id": "TITULO_NFE_DIVERGENCIA",
                "rule_name": "Divergência com NFe",
                "category": "alert",
                "status": "alerted",
                "message": "Título: valor diverge da NFe",
                "detail": {
                  "field": "valor",
                  "actual": "1234.56",
                  "expected": "1230.00"
                },
                "data_sources": [
                  {
                    "name": "nfe",
                    "fetched_at": "2026-07-09T12:01:00.000Z",
                    "age_days": 0
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "summary": {
    "total_titulos": 12,
    "approved": 9,
    "blocked": 2,
    "alerted": 1,
    "total_value": 100000,
    "approved_value": 80000,
    "blocked_value": 15000,
    "alerted_value": 5000,
    "sacados": { "total": 5, "with_issues": 2 },
    "cedente": { "status": "blocked" }
  },
  "engine_id": "0b3c6c7e-9d2a-4f1b-8e5d-2a1b3c4d5e6f",
  "engine_name": "Motor Borderô",
  "timestamp": "2026-07-09T12:02:15.000Z",
  "coverage": [
    {
      "provider": "rfb",
      "requested": 6,
      "succeeded": 5,
      "failed_keys": ["98765432000188"]
    }
  ],
  "degraded_rules": [
    { "rule_id": "SACADO_SERASA", "provider": "serasa", "titulos_affected": 2 }
  ]
}

Variações do endpoint:

?filter=all — devolve a árvore completa, incluindo títulos aprovados e sacados sem problemas. Qualquer outro valor retorna 400 com a mensagem Invalid filter value. Use "issues" or "all"..
?include=execution_plan — lista separada por vírgulas de blocos extras; adiciona o campo execution_plan à resposta (hoje sempre []).
Chamar o /result antes de a operação chegar a completed retorna 409 conflict com detail no formato Operation has not completed yet. Current status: processing.

O summary sempre reflete o dataset completo — ele não muda com ?filter.

Interprete o resultado

O resultado é uma árvore: cedente → sacados → títulos, cada nó com um status e uma lista de issues (violações de regra).

Conceito	Como ler
`status` de qualquer nó	`approved` \| `blocked` \| `alerted`
Rollup (worst-of)	O status do título deriva das issues do título; o do sacado é o pior entre as issues próprias e os títulos; o do cedente é o pior entre as issues próprias e os sacados
`issues[]`	Cada issue traz `rule_id`, `rule_name`, `category` (`blocking` \| `alert`), `status` (`blocked` \| `alerted`), `message`, `detail` (`{field, actual, expected}`) e `data_sources` (`{name, fetched_at, age_days}`)
`summary`	Contagens e valores do dataset completo: `total_titulos`, `approved`/`blocked`/`alerted`, `total_value`/`approved_value`/`blocked_value`/`alerted_value`, `sacados.total`/`sacados.with_issues` e `cedente.status`
`coverage[]`	Por provider consultado: `requested`, `succeeded` e `failed_keys` (documentos que falharam)
`degraded_rules[]`	Regras que não puderam ser avaliadas por fonte indisponível: `rule_id`, `provider`, `titulos_affected`
`titulo.nfe_chave`	Chave da NFe vinculada ao título (`null` se não houver); problemas de NFe aparecem como issues do título

Fonte de dados indisponível não vira issue — vira degraded_rules (e aparece em coverage). No summary, os títulos afetados contam como alerted. Se a sua esteira exige cobertura total, trate degraded_rules não-vazio na sua regra de aprovação.Um filtro típico — listar as issues bloqueantes da operação:

Python

result = requests.get(
    f"https://221b-api.sherlocker.com.br/api/v1/operations/{operation_id}/result",
    headers={"Authorization": "Bearer slhk_sua_chave_aqui"},
).json()

for sacado in result["cedente"]["sacados"]:
    for titulo in sacado["titulos"]:
        for issue in titulo["issues"]:
            if issue["category"] == "blocking":
                print(f"{titulo['numero']}  sacado={sacado['cnpj_cpf']}  "
                      f"[{issue['rule_id']}] {issue['message']}")

Tratamento de erros

Todos os erros seguem RFC 7807 (Content-Type: application/problem+json). Use o campo code para decidir o que fazer — o campo type é apenas um identificador. Os erros de validação do multipart chegam field-level em errors[], com os campos file, xmls e cedente_cnpj: Resposta (400):

{
  "type": "https://docs.sherlocker.com.br/problems/validation_error",
  "title": "Validation Error",
  "status": 400,
  "code": "validation_error",
  "detail": "One or more fields failed validation.",
  "errors": [
    { "field": "file", "message": "No file provided" },
    { "field": "cedente_cnpj", "message": "cedente_cnpj is required" }
  ],
  "instance": "/v1?request_id=req-uuid-here"
}

Outras mensagens comuns: Invalid CNPJ format (dígito verificador do cedente_cnpj), falha de parse do CNAB e arquivos acima do teto (128 MiB para file, 512 MiB para xmls). O gateway limita o multipart completo a 768 MiB, incluindo campos e framing. Como nada foi parseado, nada é cobrado. Os demais códigos: 401 unauthorized, 402 insufficient_tokens, 403 feature_not_enabled, 409 idempotency_conflict e 422 no_engine — registro completo em Erros.

O que você construiu

Um fluxo completo de análise de borderô: POST /operations multipart (202) → polling em GET /operations/{id} (queued/processing → completed) → resultado hierárquico em GET /operations/{id}/result.
Um consumo enxuto do resultado: ?filter=issues (padrão) entrega só os nós com problemas; ?filter=all entrega a árvore completa.
Interpretação de issues, summary, coverage e degraded_rules — incluindo a validação de NFe via issues do título e nfe_chave.

Próximos passos

Ciclo de vida

Estados da operação, envelope de status e o endpoint /result

Idempotência

Idempotency-Key opcional no borderô — replay e conflitos

Cobrança

Modelo por entidade única, com exemplo numérico e estorno

Títulos e NFe

O shape do título na árvore do resultado e a validação de NFe

Começando

Conceitos

Motor de CPF/CNPJ

Motor de Borderô (títulos & NFe)

Referência comum

Pré-requisitos

Tratamento de erros

O que você construiu

Próximos passos

Ciclo de vida

Idempotência

Cobrança

Títulos e NFe

​Pré-requisitos

​Tratamento de erros

​O que você construiu

​Próximos passos

Ciclo de vida

Idempotência

Cobrança

Títulos e NFe

Pré-requisitos

Tratamento de erros

O que você construiu

Próximos passos