Autenticação
Tipos de chave de API, escopos e onde usar cada chave sem expor dados da loja.
Toda chamada à API precisa de uma chave de API da loja. Cada chave pertence a uma única loja e só faz o que os escopos dela permitem.
Tipos de chave
| Chave publicável | Chave secreta | |
|---|---|---|
| Começa com | pk_ | sk_ |
| Onde usar | Navegador, app, launcher do servidor | Só no seu servidor |
| Escopos que o painel oferece | Catálogo (leitura) e Carrinho e checkout | Todos |
| O que acessa | Catálogo, formas de pagamento, carrinho, checkout, nova tentativa de pagamento e avisos de estoque | Tudo o que os escopos liberarem, inclusive pedidos, clientes, reembolsos, entregas, assinaturas e webhooks |
Requisição com cabeçalho Origin | Aceita | Recusada |
Use a chave publicável para montar a vitrine no seu site: listar produtos, montar o carrinho e fechar o pedido. Use a chave secreta para tudo que envolve dados de clientes ou dinheiro: consultar pedidos, reembolsar, atualizar clientes e confirmar entregas.
Chave secreta nunca vai para o navegador
A MinePag recusa com 403 forbidden qualquer requisição feita com chave secreta que traga o cabeçalho Origin, que todo navegador envia em chamadas fetch para outro domínio. Se o seu servidor ou proxy também adiciona Origin, remova esse cabeçalho nas chamadas com a chave secreta.
Criar uma chave
Só Proprietário e Administrador da loja podem criar e revogar chaves.
Abra as chaves da loja
No painel, entre na loja e abra Desenvolvedores › Chaves de API.
Preencha o formulário
No bloco Criar chave:
- Nome: onde a chave será usada, como "Launcher do servidor" ou "Site da loja". Duas chaves ativas não podem ter o mesmo nome.
- Tipo: Publicável ou Secreta.
- Validade: Não expira, Em 30 dias, Em 90 dias ou Em 1 ano.
- Escopos: marque só o que a integração precisa. A chave publicável só oferece Catálogo (leitura) e Carrinho e checkout.
Copie a chave
Clique em Criar chave. A chave completa aparece uma única vez. Copie e guarde em um cofre de segredos ou em uma variável de ambiente, como MINEPAG_SECRET_KEY, e clique em Já guardei a chave.
Teste a chave
Chame GET /me. A resposta mostra a loja, o tipo e os escopos da chave:
curl https://minepag.com.br/api/v1/me \
-H "Authorization: Bearer $MINEPAG_SECRET_KEY"{
"data": {
"project": { "id": "0193b7c2-4a1e-7c55-9d2f-1a2b3c4d5e01", "slug": "minha-loja", "name": "Minha Loja" },
"apiKey": { "prefix": "sk_Q7m2Kx9PaL3vT8nR", "kind": "secret", "scopes": ["orders:read", "orders:write"] }
},
"meta": { "requestId": "5b0f7a52-0d8e-4b51-9a57-1f0c6b7e2d10" }
}Perdeu a chave?
A MinePag guarda só um hash da chave e não consegue mostrá-la de novo. Revogue a chave perdida e crie outra.
Enviar a chave
Envie a chave no cabeçalho Authorization com o prefixo Bearer:
Authorization: Bearer sk_Q7m2Kx9PaL3vT8nR_…O cabeçalho X-API-Key: <chave> também é aceito, para ferramentas que não permitem mudar o Authorization.
Formato da chave
A chave tem três partes separadas por _: o tipo (pk ou sk), um identificador de 16 caracteres e o segredo. O prefixo (tipo + identificador, como sk_Q7m2Kx9PaL3vT8nR) não é secreto: ele aparece na lista de chaves do painel e no GET /me, e serve para saber qual chave fez cada chamada. Nunca registre a chave inteira em logs.
Escopos
| Escopo | No painel | Rotas que exigem |
|---|---|---|
catalog:read | Catálogo (leitura) | GET /products, GET /products/{productId}, GET /categories |
checkout:write | Carrinho e checkout | /carts/**, POST /coupons/validate, GET /payment-methods, POST /checkout, POST /orders/{orderId}/payments, /stock-alerts/** |
orders:read | Pedidos (leitura) | GET /orders, GET /orders/{orderId}, GET /refunds, GET /refunds/{refundId} |
orders:write | Pedidos (escrita) | POST /orders/{orderId}/cancel, POST /refunds |
customers:read | Clientes (leitura) | GET /customers, GET /customers/{customerId} |
customers:write | Clientes (escrita) | POST /customers, PATCH /customers/{customerId} |
subscriptions:read | Assinaturas (leitura) | GET /subscriptions, GET /subscriptions/{subscriptionId} |
subscriptions:write | Assinaturas (escrita) | POST /subscriptions/{subscriptionId}/cancel |
deliveries:read | Entregas (leitura) | GET /deliveries, GET /deliveries/{id}, GET /entitlements |
deliveries:write | Entregas (escrita) | POST /deliveries/{id}/complete, POST /deliveries/{id}/fail, POST /deliveries/{id}/resend |
webhooks:read | Webhooks (leitura) | GET /webhook-endpoints, GET /webhook-endpoints/{endpointId} |
webhooks:write | Webhooks (escrita) | POST /webhook-endpoints, PATCH e DELETE /webhook-endpoints/{endpointId}, POST /webhook-endpoints/{endpointId}/rotate-secret, POST /webhook-endpoints/{endpointId}/test |
Só GET /me não exige escopo. As rotas do escopo checkout:write aceitam os dois tipos de chave.
As rotas de pedidos, reembolsos, clientes, entregas, acessos liberados, assinaturas e webhooks só aceitam chave secreta. Com a chave publicável, elas respondem 403 forbidden com a mensagem "Esta operação exige uma chave secreta.".
Faltou escopo? A resposta é 403 insufficient_scope e a mensagem diz qual escopo falta.
Combinações comuns
| Integração | Tipo | Escopos |
|---|---|---|
| Vitrine própria (catálogo, carrinho e checkout no navegador) | Publicável | catalog:read, checkout:write |
| Launcher ou site que só mostra produtos | Publicável | catalog:read |
| Sincronizar pedidos com um ERP ou planilha | Secreta | orders:read, customers:read |
| Reembolsar pelo seu sistema de suporte | Secreta | orders:read, orders:write |
| Serviço externo de entrega (ex.: packs) | Secreta | deliveries:read, deliveries:write |
| Cadastrar os próprios webhooks na instalação de um app | Secreta | webhooks:read, webhooks:write |
Revogar e trocar chaves
Para revogar, abra Desenvolvedores › Chaves de API, clique em Revogar na linha da chave e confirme em Revogar chave. Para chaves secretas, o painel pede que você digite o nome da chave para confirmar. A chave para de funcionar na hora e não pode ser reativada: as chamadas passam a receber 401 invalid_api_key.
Para trocar uma chave sem parar a integração, use Trocar na linha da chave:
- Escolha por quanto tempo a chave antiga continua valendo: Por mais 1 hora, Por mais 24 horas (padrão), Por mais 3 dias, Por mais 7 dias ou Deixa de valer agora. Se a chave antiga já expira antes disso, vale a data de expiração dela.
- Digite o nome da chave para confirmar e clique em Trocar chave.
- Copie a chave nova, que aparece uma única vez. Ela tem o mesmo nome, tipo e escopos da antiga e a mesma duração de validade, contada a partir da troca.
- Atualize a variável de ambiente da integração e publique dentro do prazo.
Enquanto o prazo corre, a chave antiga aparece como Trocada, com a data em que deixa de valer, e as duas chaves funcionam. Confira na coluna Último uso que a chave nova está sendo usada. Se terminar antes, revogue a antiga. Depois do prazo, quem ainda usar a chave antiga recebe 401 invalid_api_key.
Chaves com validade param de funcionar sozinhas na data de expiração, com o mesmo erro 401 invalid_api_key. Troque a chave antes.
A criação, a troca e a revogação de chaves ficam registradas em Desenvolvedores › Logs de auditoria, com quem fez e quando.
Boas práticas
- Uma chave por integração. Se uma vazar, você revoga só ela.
- Escopos mínimos. Uma chave que só lê pedidos não consegue reembolsar.
- Validade nas chaves de terceiros. Para agências ou freelancers, use Em 30 dias ou Em 90 dias.
- Guarde fora do código. Use variáveis de ambiente ou um cofre de segredos, nunca o repositório.
- Vazou? Use Trocar com Deixa de valer agora, ou revogue e crie outra. Confira em Logs de auditoria e nos pedidos se houve uso indevido.
Veja também Convenções da API e Erros da API.