Como realizar login via API com usuario e senha

Sys
,
1

Este guia descreve como autenticar na plataforma Puca com usuário e senha, obter o JWT e usá-lo nas demais APIs.

O login é feito sempre no módulo Base. O token gerado vale para os outros módulos (CRUD, CRM, Flow, Fin, Tax, etc.).

Para integração contínua com usuário robô, prefira o fluxo por API Key descrito em Documentação da API padrão do Puca. Este artigo cobre o login interativo / script com usuário e senha.

Endpoint

Método: POST
Content-Type: application/json
Autenticação nesta chamada: nenhuma (o login é público)

https://{dominio}/puca-base-api/puca-user/system_user/login

O {dominio} é o host do tenant, por exemplo meunegocio.puca.app.

Corpo da requisição

{
  "username": "seu-usuario",
  "password": "sua-senha"
}
Campo Obrigatório Descrição
username sim Login do usuário. A API normaliza para minúsculas e remove espaços nas pontas.
password sim Senha em texto puro.

Resposta de sucesso

HTTP 200

O corpo é o JWT em string (não um objeto { "token": "..." }).

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Algumas bibliotecas HTTP devolvem a string já parseada; outras devolvem JSON com aspas ("eyJ..."). Remova aspas extras se houver.

O JWT é assinado com RS256 e contém, entre outros campos:

  • domain — tenant
  • exp — expiração (unix)
  • user.puca_pid, user.username

A validade padrão do token é de 7 dias.

Resposta de erro

HTTP 403

{
  "statusCode": 403,
  "message": "Usuário e/ou senha inválido(s)"
}

A API espera cerca de 3 segundos antes de responder o erro (mitigação de força bruta). Usuário inexistente e senha errada usam a mesma mensagem.

Exemplos

Substitua SEU_DOMINIO, SEU_USUARIO e SUA_SENHA.

cURL

TOKEN=$(curl -sS -X POST \
  "https://SEU_DOMINIO/puca-base-api/puca-user/system_user/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"SEU_USUARIO","password":"SUA_SENHA"}' \
  | tr -d '"')

echo "$TOKEN"

JavaScript (fetch)

const response = await fetch(
  'https://SEU_DOMINIO/puca-base-api/puca-user/system_user/login',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'SEU_USUARIO',
      password: 'SUA_SENHA',
    }),
  },
)

if (!response.ok) {
  const err = await response.json()
  throw new Error(err.message)
}

let token = await response.text()
token = token.replace(/^"|"$/g, '').trim()

Como usar o token nas próximas chamadas

Envie o JWT no header Authorization. O prefixo Bearer é opcional (a API remove se existir).

Também são aceitos:

  • header PucaAuthorization
  • query string puca_jwt

Conferir se o token está válido

curl -sS \
  "https://SEU_DOMINIO/puca-base-api/puca-user/system_user/auth/check" \
  -H "Authorization: ${TOKEN}"

Resposta esperada (HTTP 200):

{
  "authenticated": true,
  "domain": "seu-dominio",
  "user": {
    "puca_pid": "...",
    "username": "seu-usuario"
  }
}

Chamar outro módulo (CRUD)

curl -sS \
  "https://SEU_DOMINIO/puca-crud-api/view/crud-especification" \
  -H "Authorization: ${TOKEN}"

Regras importantes

  1. Um novo login invalida o token anterior. Se o mesmo usuário autenticar de novo, o JWT antigo passa a ser rejeitado.
  2. Não use a mesma conta no navegador e em um script se os dois precisarem ficar logados ao mesmo tempo. Para integração contínua, prefira um usuário de serviço / API Key de robô.
  3. O token não é renovado automaticamente. Quando expirar, faça login de novo.
  4. Não compartilhe usuário, senha nem JWT. Trate o token como credencial.

Problemas comuns

Sintoma Causa típica
HTTP 403 + “Usuário e/ou senha inválido(s)” Credencial errada, usuário inativo ou domínio/tenant errado
HTTP 403 com ~3 s de atraso Esperado em falha de autenticação
HTTP 401 nas APIs depois do login Token mal copiado (aspas extras), expirado, ou sessão invalidada por outro login
Token some ao logar no sistema pela tela A tela de login do sistema substitui a sessão anterior

Checklist rápido

  1. POST em /puca-base-api/puca-user/system_user/login
  2. Body JSON com username e password
  3. Guardar a string JWT da resposta
  4. Repetir o token em Authorization nas demais APIs
  5. Validar com GET /puca-base-api/puca-user/system_user/auth/check