Autenticação, escopos e permissões

A chave

Cada conta cria as suas chaves em Configurações › Integrações. A chave começa com pc3d_live_ e tem 256 bits aleatórios. Ela aparece uma vez; o Precificador guarda só um hash, então nem a equipe consegue mostrá-la de novo.

HTTP

GET /v1/conta HTTP/1.1
Host: api.precificador3d.com.br
Authorization: Bearer pc3d_live_EXEMPLO_nao_e_uma_chave_real

Só no cabeçalho Authorization: Bearer …. Chave na URL é recusada com 400 chave_na_url e a chave é suspensa, porque vazou para logs.
Sem cookie e sem CORS: a API é para servidor, não para navegador.
Chave inválida responde 401 sempre igual. Muitas tentativas inválidas do mesmo IP recebem espera cada vez maior. Chave válida nunca é bloqueada por IP (Zapier, Make e n8n Cloud dividem IPs entre muitos clientes).

Escopos

Cada chave tem escopos. Marque só o que a integração usa: uma loja que mostra preço e estoque precisa de produtos:ler e estoque:ler, nada mais.

Escopo	Libera	Permissão de quem cria a chave
`produtos:ler`	conta, canais, produtos, variações e preço por canal	`produtos.ver`
`produtos:custos`	custo, preço sugerido, margem, lucro por hora e valor do pedido	`custos.ver` (valor do pedido: `custos.ver` ou `producao.receber`)
`insumos:ler`	materiais e cores	`produtos.ver`
`estoque:ler`	saldos de peças prontas	`produtos.ver`
`estoque:escrever`	entrada, saída e ajuste no estoque próprio	`estoque_produtos.movimentar`
`estoque_insumos:ler`	saldos de insumos	`estoque_insumos.ver`
`cotacoes:ler`	cotações e itens, com nome e contato do cliente	`cotacoes.ver`
`cotacoes:escrever`	criar cotação em rascunho	`cotacoes.editar`
`cotacoes:status`	mudar o status da cotação (aprovada, recusada, em análise, arquivada), sem enviar nada ao cliente	`cotacoes.enviar`
`pedidos:ler`	pedidos de produção	`producao.ver`
`pedidos:escrever`	criar pedido de produção	`producao.planejar`

Custo e margem

Escopo efetivo

A chave nunca pode mais do que a pessoa que a criou pode hoje. Se a pessoa perder uma permissão, a chave perde junto, na hora. Se ela sair da conta, as chaves dela são revogadas e o dono recebe um e-mail. GET /conta mostra escopos_efetivos. Escopo que falta responde 403 escopo_insuficiente.

Ciclo de vida

Criar: exige a permissão integracoes.gerenciar (por padrão, os perfis Dono e Gerente) e a senha de novo. Ninguém dá a uma chave o que não tem. O dono recebe e-mail a cada chave criada, revogada, suspensa ou expirada.
Expiração: 30 dias, 90 dias, 12 meses (padrão) ou sem expiração. Aviso por e-mail 14 e 3 dias antes.
Último uso: data e IP mascarado aparecem na tela da chave.
Revogar: imediato. Chave revogada não volta.
Quantas: 2 chaves ativas no Bancada, 3 na Oficina e 10 na Farm.
Conta bloqueada ou sem plano ativo: a API responde 403 conta_bloqueada. As chaves não são apagadas e voltam a funcionar quando a conta for liberada.

Boas práticas

Uma chave por integração, com nome claro ("Loja virtual", "Planilha de estoque").
Só os escopos necessários. Evite produtos:custos em integração que não mostra custo.
Guarde em variável de ambiente ou cofre de segredos. Nas ferramentas sem código, use a área de credenciais, nunca o texto do fluxo.
Troque a chave quando alguém que tinha acesso a ela sair da equipe.

Esta página em Markdown · llms.txt