Scopes (M2M)

Cada token M2M carrega scopes granulares. A API valida o scope exigido em toda rota protegida: se o token nao tiver o scope necessario, a chamada retorna 403 scope_insufficient.

Princípio de menor privilegio: peca apenas os scopes que sua integracao usa.

Como funcionam

1. Provisionamento (Backoffice Zemo): os scopes permitidos sao definidos na sua credencial (client_id / client_secret) no momento do cadastro.
2. Emissao do token (POST /v1/auth/token): voce pode pedir um subconjunto dos scopes da credencial pelo campo scopes. Se omitir, o token recebe todos os scopes permitidos da credencial.
3. Validacao: a resposta do token inclui o array scopes concedido. Cada endpoint exige o scope correspondente (tabela abaixo).

curl -X POST https://receivables-api.zemocapital.com/v1/auth/token \
  -H "X-Client-Id: $CLIENT_ID" -H "X-Client-Secret: $CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["simulation:create", "operation:create", "operation:read"]}'
# -> {"access_token": "eyJ...", "expires_in": 900, "scopes": [...]}

• Pedir um scope fora do permitido na credencial -> 403 scope_not_allowed (o detail lista allowed_scopes).
• Chamar um endpoint sem o scope exigido no token -> 403 scope_insufficient (o detail lista required e granted).

Veja os dois erros em Codigos de Erro.

Tabela de scopes

Scope	Acesso concedido	Endpoints principais
simulation:create	Simular antecipacao	POST /v1/simulate, POST /v1/stock/simulate-anticipation
operation:read	Consultar operacoes	GET /v1/operations, GET /v1/operations/{id}
operation:create	Criar operacoes (direta e via estoque)	POST /v1/operations/direct, POST /v1/stock/request-anticipation
operation:cancel	Cancelar operacoes	POST /v1/operations/{id}/cancel
stock:read	Consultar itens de estoque	GET /v1/stock, GET /v1/stock/{id}
stock:write	Registrar / cancelar itens de estoque	POST /v1/stock, POST /v1/stock/{id}/cancel
title:read	Consultar titulos	GET /v1/titles, GET /v1/titles/{id}
assignor:read	Consultar cedentes	GET /v1/assignors, GET /v1/assignors/{id}
assignor:write	Criar / editar cedentes	POST / PUT / PATCH /v1/assignors
payer:read	Consultar sacados	GET /v1/payers, GET /v1/payers/{id}
payer:write	Criar / editar sacados	POST / PUT / PATCH /v1/payers
webhook:read	Listar webhooks	GET /v1/webhooks
webhook:write	Criar / editar / remover webhooks	POST / PUT / PATCH / DELETE /v1/webhooks
bank-account:read	Consultar contas bancarias	GET /v1/bank-accounts
originator:read	Consultar dados do originador	GET /v1/originators

Regra de derivacao (metodo -> scope)

Para a maioria dos recursos o scope segue o metodo HTTP:

• GET / HEAD -> scope :read do recurso (ex.: GET /v1/payers -> payer:read).
• POST / PUT / PATCH / DELETE -> scope :write do recurso (ex.: PATCH /v1/payers/{id} -> payer:write).
• Acoes /cancel e /expire exigem o scope de escrita do recurso pai. Operacoes usam o scope dedicado operation:cancel.

Endpoints sem scope mapeado (ex.: GET /v1/products, GET /v1/health, POST /v1/auth/token) exigem apenas um token valido, sem scope especifico.

Os scopes exigidos por cada endpoint individual tambem aparecem na Referencia Tecnica (OpenAPI/Scalar).