Autenticação

Como gerar a chave de API e como enviá-la em cada requisição.

A API aceita dois tipos de credencial no mesmo header. Para integrações, use a chave de API; o JWT é o que o painel usa.

Credencial	Começa com	Para quê	Dura
Chave de API	v4pay_test_ ou v4pay_live_	Integrações — seu sistema chamando a API	Até você revogar
JWT	eyJ	Sessão do painel; também serve para criar chaves	por padrão 1 hora (o painel renova sozinho enquanto em uso)

Gerar uma chave de API

1. Faça login para obter um JWT

   curl -X POST https://v4pay-api.vercel.app/auth/login \
     -H "Content-Type: application/json" \
     -d '{ "email": "[e-mail]", "password": "sua-senha" }'
   

   A resposta traz data.accessToken.

2. Crie a chave

   curl -X POST https://v4pay-api.vercel.app/api-keys \
     -H "Authorization: Bearer SEU_JWT" \
     -H "Content-Type: application/json" \
     -d '{ "name": "ERP da loja", "environment": "live" }'
   

   environment é live (produção) ou test. Sem o campo, é produção — e chave de produção só existe para conta aprovada: antes da aprovação de produção, o pedido com live responde 409 com codigo: PRODUCAO_NAO_LIBERADA. Comece com uma chave de teste (Ambiente de testes).

   {
     "data": {
       "id": "b7e1…",
       "name": "ERP da loja",
       "prefix": "v4pay_live_3f9a2c1",
       "environment": "live",
       "active": true,
       "key": "v4pay_live_3f9a2c1e8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a"
     }
   }
   

   O campo key aparece só nesta resposta. O V4 Pay guarda apenas um hash; depois disso ninguém — nem o suporte — consegue recuperar a chave. Se perder, crie outra.

Enviar a chave

Em todas as rotas protegidas, no header Authorization, com o prefixo Bearer:

Authorization: Bearer v4pay_live_3f9a2c1e8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a

O servidor reconhece a chave pelo prefixo v4pay_; qualquer outra coisa é tratada como JWT. O que vem depois — test_ ou live_ — é só leitura: o ambiente de verdade está gravado com a chave no servidor, e chaves antigas sem essa marca valem como produção.

Gerenciar chaves

Ação	Rota
Listar (mostra só o prefixo e o ambiente; teste e produção juntas)	GET /api-keys
Ativar / desativar	PUT /api-keys/{id} com { "active": false }
Revogar de vez	DELETE /api-keys/{id}

Uma chave desativada ou revogada responde 401 com { "error": "Chave de API inválida ou revogada" }.

Erros de autenticação

Este é o único lugar da API onde error vem como string, não como objeto:

{ "error": "Token JWT ou chave de API ausente" }

Situação	Status	Mensagem
Header ausente ou sem Bearer	401	Token JWT ou chave de API ausente
Chave desconhecida ou revogada	401	Chave de API inválida ou revogada
JWT inválido ou vencido	401	Token inválido ou expirado

Boas práticas

• Uma chave por integração, com um name que diga onde ela vive — facilita revogar só a certa.
• Nunca coloque a chave em código de frontend nem em URL. Ela dá controle total da sua loja.
• Guarde em variável de ambiente ou cofre de segredos.