Autenticação¶

Visão Geral¶

A API Pontotel utiliza Bearer Token Authentication (JWT) para autenticar requisições.

Fluxo de Autenticação

Enviar credenciais para o endpoint /login/
Receber access_token na resposta
Incluir token no header Authorization: Bearer {token}
Token expira em 1 hora

POST /api/v4/login/

Request¶

JSON
{
  "username": "seu_usuario",
  "password": "sua_senha"
}

Response (200 OK)¶

JSON
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
}

Exemplos de Código¶

PythonJavaScriptcURL

Python
import httpx
from datetime import datetime, timedelta, timezone

class PontotelAuth:
    def __init__(self, username, password, base_url):
        self.username = username
        self.password = password
        self.base_url = base_url
        self.token = None
        self.token_expires_at = None

    async def login(self):
        """Realiza login e obtém token"""
        url = f"{self.base_url}/login/"
        payload = {
            "username": self.username,
            "password": self.password
        }

        async with httpx.AsyncClient() as client:
            response = await client.post(url, json=payload)
            response.raise_for_status()

        data = response.json()
        self.token = data["access_token"]
        self.token_expires_at = datetime.now(tz=timezone.utc) + timedelta(minutes=60)

        return self.token

    async def get_token(self):
        """Retorna token válido, renovando se necessário"""
        if not self.token or datetime.now(tz=timezone.utc) >= self.token_expires_at:
            await self.login()
        return self.token

    async def get_headers(self):
        """Retorna headers com autenticação"""
        return {
            "Authorization": f"Bearer {await self.get_token()}",
            "Content-Type": "application/json"
        }

# Uso
import asyncio

async def main():
    auth = PontotelAuth(
        username="seu_usuario",
        password="sua_senha",
        base_url="https://apis.pontotel.com.br/pontotel/api/v4"
    )

    # Fazer requisições
    headers = await auth.get_headers()
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://apis.pontotel.com.br/pontotel/api/v4/usuarios/",
            headers=headers
        )

asyncio.run(main())

JavaScript
class PontotelAuth {
  constructor(username, password, baseUrl) {
    this.username = username;
    this.password = password;
    this.baseUrl = baseUrl;
    this.token = null;
    this.tokenExpiresAt = null;
  }

  async login() {
    const url = `${this.baseUrl}/login/`;
    const response = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        username: this.username,
        password: this.password
      })
    });

    if (!response.ok) {
      throw new Error(`Login failed: ${response.status}`);
    }

    const data = await response.json();
    this.token = data.access_token;
    this.tokenExpiresAt = Date.now() + (data.expires_in * 1000);

    return this.token;
  }

  async getToken() {
    if (!this.token || Date.now() >= this.tokenExpiresAt) {
      await this.login();
    }
    return this.token;
  }

  async getHeaders() {
    const token = await this.getToken();
    return {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }
}

// Uso
const auth = new PontotelAuth(
  'seu_usuario',
  'sua_senha',
  'https://apis.pontotel.com.br/pontotel/api/v4'
);

// Fazer requisições
const headers = await auth.getHeaders();
const response = await fetch(
  'https://apis.pontotel.com.br/pontotel/api/v4/usuarios/',
  { headers }
);

Bash
# 1. Login
curl -X POST "https://apis.pontotel.com.br/pontotel/api/v4/login/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "seu_usuario",
    "password": "sua_senha"
  }' \
  | jq -r '.access_token' > token.txt

# 2. Usar token
TOKEN=$(cat token.txt)

curl -X GET "https://apis.pontotel.com.br/pontotel/api/v4/usuarios/" \
  -H "Authorization: Bearer $TOKEN"

Segurança¶

Práticas Importantes

Nunca compartilhe credenciais ou tokens
Armazene tokens em variáveis de ambiente ou secret managers
Rotacione credenciais regularmente
Use HTTPS sempre (obrigatório)
Não faça commit de tokens no Git

Armazenamento Seguro¶

Python (.env)JavaScript (.env)

Python
# .env
PONTOTEL_USERNAME=seu_usuario
PONTOTEL_PASSWORD=sua_senha

# código
import os

auth = PontotelAuth(
    username=os.environ.get("PONTOTEL_USERNAME"),
    password=os.environ.get("PONTOTEL_PASSWORD"),
    base_url="https://apis.pontotel.com.br/pontotel/api/v4"
)

JavaScript
// .env
PONTOTEL_USERNAME=seu_usuario
PONTOTEL_PASSWORD=sua_senha

// código
require('dotenv').config();

const auth = new PontotelAuth(
  process.env.PONTOTEL_USERNAME,
  process.env.PONTOTEL_PASSWORD,
  'https://apis.pontotel.com.br/pontotel/api/v4'
);

Expiração e Renovação¶

Tokens expiram em 1 hora (3600 segundos)
Trate erros 401 Unauthorized com uma nova autenticação
Implemente lógica de renovação automática a partir do atributo exp do token

Exemplo de Retry Logic¶

Python
import httpx

transport = httpx.AsyncHTTPTransport(retries=3)

async def realizar_requisicao_com_retentativa(url, headers):
    async with httpx.AsyncClient(transport=transport) as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return response

# Uso
import asyncio

async def main():
    response = await realizar_requisicao_com_retentativa(url, headers)

asyncio.run(main())

Erros comuns¶

Código	Erro	Solução
400	Bad Request	Verificar formato do payload
401	Unauthorized	Credenciais inválidas ou token expirado
403	Forbidden	Sem permissão para o recurso
422	Validation error	Verificar dados enviados no payload
422	Validation error	Erro de autenticação usuário/senha incorreta

Próximos Passos¶

Primeira requisição →