Pular para conteúdo

Começando: Guia de Integração

1. Pré-requisitos

Antes de começar, você vai precisar de:

  • ✅ Credenciais de acesso à API Pontotel (username + password)
  • ✅ Acesso ao ambiente Sandbox para testes
  • ✅ Cliente HTTP (Python requests, JavaScript fetch, cURL, Postman, etc.)

Obtendo Credenciais

Entre em contato com o suporte Pontotel: suporte@pontotel.com.br

Solicite credenciais separadas para Sandbox e Produção.

2. Autenticação

A API utiliza Bearer Token Authentication (JWT). O fluxo é:

  1. Enviar credenciais para POST /login/
  2. Receber access_token (válido por 1 hora)
  3. Incluir Authorization: Bearer {token} em todas as requisições

Endpoint de Login

Text Only
1
POST https://apis.pontotel.com.br/pontotel/api/v4/login/

Request

JSON
1
2
3
4
{
  "username": "seu_usuario",
  "password": "sua_senha"
}

Response (200 OK)

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": 123,
    "username": "seu_usuario",
    "email": "seu@email.com"
  }
}

Exemplos de Login

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import requests
from datetime import datetime, timedelta

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

    def login(self):
        url = f"{self.base_url}/login/"
        payload = {"username": self.username, "password": self.password}

        response = requests.post(url, json=payload)
        response.raise_for_status()

        data = response.json()
        self.token = data["access_token"]
        self.token_expires_at = datetime.now() + timedelta(seconds=data["expires_in"])
        return self.token

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

    def get_headers(self):
        return {
            "Authorization": f"Bearer {self.get_token()}",
            "Content-Type": "application/json"
        }

auth = PontotelAuth(
    username="seu_usuario",
    password="sua_senha",
    base_url="https://apis.pontotel.com.br/pontotel/api/v4"
)
JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class PontotelAuth {
  constructor(username, password, baseUrl) {
    this.username = username;
    this.password = password;
    this.baseUrl = baseUrl;
    this.token = null;
    this.tokenExpiresAt = null;
  }

  async login() {
    const response = await fetch(`${this.baseUrl}/login/`, {
      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 getHeaders() {
    if (!this.token || Date.now() >= this.tokenExpiresAt) {
      await this.login();
    }
    return {
      'Authorization': `Bearer ${this.token}`,
      'Content-Type': 'application/json'
    };
  }
}
Bash
1
2
3
4
5
6
7
# Login e salvar token
TOKEN=$(curl -s -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')

echo "Token: ${TOKEN:0:30}..."

3. Primeira Requisição

Com o token em mãos, faça sua primeira requisição:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
headers = auth.get_headers()

response = requests.get(
    "https://apis.pontotel.com.br/pontotel/api/v4/empregadores/",
    headers=headers
)

data = response.json()
print(f"Total de empregadores: {data['count']}")
for emp in data['results']:
    print(f"  - {emp['razao_social']} (CNPJ: {emp['cnpj']})")
JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
const headers = await auth.getHeaders();

const response = await fetch(
  'https://apis.pontotel.com.br/pontotel/api/v4/empregadores/',
  { headers }
);

const data = await response.json();
console.log(`Total: ${data.count}`);
data.results.forEach(emp => {
  console.log(`  - ${emp.razao_social} (${emp.cnpj})`);
});
Bash
1
2
3
curl -X GET "https://apis.pontotel.com.br/pontotel/api/v4/empregadores/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

4. Testando via Swagger

A documentação interativa permite testar endpoints direto no browser:

  1. Acesse a Referência da API →
  2. Clique em POST /login/ → Try it out
  3. Preencha username e password
  4. Clique em Execute e copie o access_token
  5. Clique no botão Authorize (🔓) no topo
  6. Cole: Bearer seu_token_aqui
  7. Agora todos os endpoints estão autenticados

Próximos Passos