Tema
Autenticação
O seu sistema troca duas credenciais por um token de acesso de curta duração. Esse token vai em todas as outras chamadas.
Credenciais
| Credencial | Onde fica | Para que serve |
|---|---|---|
| E-mail do usuário de API | Portal, tela Tokens de API, coluna E-mail (identificador) | Identifica quem está chamando. |
| Chave da conta (Account Token) | Portal, tela Tokens de API, no alto da tela | Identifica a conta. É secreta. |
Como criar o usuário: Como criar um usuário de API.
Guarde a chave no servidor
Use a chave só no seu servidor. Nunca no navegador, em app de celular ou em repositório de código.
Pegar o token de acesso
http
POST /access/account/get-token
Content-Type: application/jsonNão leva o cabeçalho Authorization.
Corpo
| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
email | texto | sim | E-mail válido do usuário de API. |
token | texto | sim | Chave da conta (Account Token). |
Exemplo
bash
curl -X POST https://v1.api.fastgivr.com.br/access/account/get-token \
-H "Content-Type: application/json" \
-d '{
"email": "usuario-api@suaempresa.com.br",
"token": "SEU_TOKEN_DA_CONTA"
}'js
const BASE_URL = 'https://v1.api.fastgivr.com.br';
async function getAccessToken() {
const response = await fetch(`${BASE_URL}/access/account/get-token`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: process.env.FASTGIVR_API_USER_EMAIL,
token: process.env.FASTGIVR_ACCOUNT_TOKEN,
}),
});
if (!response.ok) {
throw new Error(`FastGivr auth failed: HTTP ${response.status}`);
}
const body = await response.json();
return body.data; // { token, token_type, expires_at, permissions }
}Resposta 200
json
{
"code": 200,
"success": true,
"data": {
"token": "SEU_TOKEN_DE_ACESSO",
"token_type": "Bearer",
"expires_at": "2026-11-03T14:10:00-03:00",
"permissions": [
{ "id": 1, "name": "NOME_DA_PERMISSAO", "guard_name": "api" }
]
},
"message": "Autenticado com sucesso."
}| Campo | O que é |
|---|---|
data.token | O token de acesso. |
data.token_type | Sempre Bearer. |
data.expires_at | Data e hora em que o token deixa de valer (ISO 8601). |
data.permissions | Permissões do usuário de API nesta conta. |
Erros
| Status | Quando | message |
|---|---|---|
401 | O e-mail não existe, a chave está errada ou o usuário não pertence a essa conta. A mensagem é sempre a mesma. | Essas credenciais não correspondem aos nossos registros. |
422 | Faltou email ou token, o e-mail é inválido ou um campo passa de 255 caracteres. | Dados de entrada inválidos. |
429 | Muitas tentativas erradas. Veja abaixo. | Muitas tentativas de login. Por favor, tente novamente em 900 segundos. |
Exemplo de 401:
json
{
"success": false,
"data": null,
"message": "Essas credenciais não correspondem aos nossos registros."
}Muitas tentativas erradas
A API bloqueia por 15 minutos:
- o e-mail, depois de 10 tentativas erradas do mesmo IP;
- o IP, depois de 30 tentativas erradas com qualquer e-mail.
Só as tentativas erradas contam. Uma integração que entra certo nunca é bloqueada, mesmo pedindo um token novo a cada 10 minutos. Um login certo zera a contagem do e-mail.
Recebeu 429? Espere os segundos do cabeçalho Retry-After antes de tentar de novo. Não repita a chamada em seguida: cada tentativa errada conta.
Usar o token
Mande o token no cabeçalho Authorization de toda chamada:
http
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/jsonA conta da chamada é a conta da chave usada para pegar o token.
Validade e renovação
- O token vale 10 minutos a partir da emissão (veja
expires_at). - Para continuar, peça um novo token em
POST /access/account/get-token. - Recomendação: guarde o token em memória e peça outro um pouco antes de
expires_at, ou quando uma chamada voltar401.
js
let cached = null;
async function getValidToken() {
const safetyMarginMs = 60 * 1000;
if (cached && new Date(cached.expires_at).getTime() - Date.now() > safetyMarginMs) {
return cached.token;
}
cached = await getAccessToken();
return cached.token;
}Token vencido ou inválido
Qualquer chamada com token vencido, inválido ou sem o cabeçalho volta:
json
{ "message": "Acesso negado." }com status 401. Peça um novo token e repita a chamada.
Permissões (403)
Algumas operações exigem uma permissão específica do usuário na conta. Sem ela, a resposta é 403:
json
{
"code": 403,
"success": false,
"message": "Você não tem permissão para esta ação nesta conta."
}Exemplo: dividir o recebimento de uma cobrança com outra conta (split) exige a permissão de gerenciar splits. As permissões do usuário de API voltam no campo data.permissions da resposta do token.
Apagou o usuário de API?
Se o usuário de API for apagado no portal, o seu sistema não consegue mais pegar tokens novos com ele (401). Crie outro usuário e atualize as credenciais no seu servidor.