# Autenticação, escopos e permissões

> Chave de API por conta, enviada no cabeçalho Authorization, com escopos limitados às permissões de quem a criou.

URL: https://precificador3d.com.br/docs/api/autenticacao

## 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

> **Só com o escopo "ver custos":** Custo, preço sugerido, margem, lucro por hora e valor do pedido só aparecem com o escopo `produtos:custos` **e** se quem criou a chave tiver a permissão `custos.ver` no momento da chamada. Sem isso, os campos **não existem** na resposta (não vêm como `null`).

## 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.