Saltar a contenido

Comenzando: Guía de Integración

1. Prerrequisitos

Antes de empezar, necesitarás:

  • Credenciales de acceso a la API Puntotel (username + password)
  • Acceso al entorno Sandbox para pruebas
  • Cliente HTTP (Python requests, JavaScript fetchcURL, Postman, etc.)

Obtendo Credenciales

Póngase en contacto con el soporte Pontotel: soporte@puntotel.com.br

Solicita credenciales separadas para Sandbox y Producción.

2. Autenticación

La API utiliza Bearer Token Authentication (JWT). El flujo es:

  1. Enviar credenciales para POST /login/
  2. Recibirr access_token (válido por 1 hora)
  3. Incluir Authorization: Bearer {token} en todas las solicitudes

Endpoint de Login

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

Request

JSON
1
2
3
4
{
  "username": "tu_usuario",
  "password": "tu_contrasena"
}

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

Ejemplos 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="tu_usuario",
    password="tu_contrasena",
    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": "tu_usuario", "password": "tu_contrasena"}' \
  | jq -r '.access_token')

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

3. Primera solicitud

Con el token en manos, haga su primera requisición:

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 vía Swagger

La documentación interactiva permite probar variables directas en el navegador:

  1. Acceda a Referencia de API →
  2. Haga clic en POST /login/ → Try it out
  3. Rellena username y password
  4. Haga clic en Ejecutar y copie el access_token
  5. Haga clic en el botón Authorize ()) en la cima
  6. Cole: Bearer seu_token_aqui
  7. Ahora todos los endpoints están autenticados

Siguientes pasos