Skip to content

Starting: Integration Guide

1. Prerequisites

Before you begin, you will need:

  • Access credentials to the Pontotel API (username + password)
  • Access to Sandbox environment for testing
  • HTTP Client (Python) requests, JavaScript fetch, cURL, Postman, etc.)

Getting Credentials

Contact Pontotel support: support@pontotel.com.br

Request separate credentials for Sandbox and Production.

2. Authentication

API uses Bearer Token Authentication (JWT) The flow is:

  1. Send credentials to POST /login/
  2. Receive access_token (valid by 1 hour)
  3. Include Authorization: Bearer {token} on all requests

Login Endpoint

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

Request

JSON
1
2
3
4
{
  "username": "your_username",
  "password": "your_password"
}

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": "your_username",
    "email": "seu@email.com"
  }
}

Examples of 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="your_username",
    password="your_password",
    base_url="https://apis.pontotel.com.br/pontotel/api/v4"
)

==="JavaScript"

Text Only
 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
```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 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": "your_username", "password": "your_password"}' \
  | jq -r '.access_token')

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

3. First request

With the token in your hands, make your first request:

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"

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
```javascript
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. Testing via Swagger

Interactive documentation allows testing direct endpoints in the browser:

  1. Access API Reference →
  2. Click POST /login/ → Try it out
  3. Fill username and password
  4. Click Run and copy the access_token
  5. Click the button Authorize (
  6. Cole: Bearer seu_token_aqui
  7. Now all endpoints are authenticated

Next Steps