Como Conectar ZKTeco ao Odoo: Integração via API Cloud (Sem VPN, Sem Software Local)
A maioria das integrações ZKTeco-Odoo exige acesso à rede local, VPNs ou IPs fixos. Aprenda como conectar ZKTeco ao Odoo — incluindo Odoo Online e Odoo.sh — usando uma API REST na nuvem, sem complicações de rede.
Introduction
Se você já pesquisou como conectar ZKTeco ao Odoo, provavelmente descobriu que a resposta é mais complicada do que deveria. Dezenas de tópicos no fórum da comunidade Odoo fazem a mesma pergunta, e as respostas quase sempre levam aos mesmos becos sem saída: bibliotecas Python que só funcionam na rede local do dispositivo, túneis VPN que o time de TI detesta, ou configurações de IP fixo que expõem sua rede à internet.
Este tutorial apresenta uma abordagem diferente. Em vez de lutar contra as limitações da rede local, vamos usar uma API REST na nuvem para fazer a ponte entre seu relógio de ponto biométrico ZKTeco e o Odoo — seja Odoo Online, Odoo.sh ou uma instância self-hosted.
O Problema: Por Que a Integração ZKTeco-Odoo É Tão Difícil
Dispositivos biométricos ZKTeco (leitores de impressão digital, terminais de reconhecimento facial) estão em todo lugar. São acessíveis, confiáveis e amplamente utilizados em empresas brasileiras para controle de ponto Odoo. Odoo é um dos ERPs open-source mais populares. Conectar os dois deveria ser simples. Mas não é.
Veja por quê.
As Ferramentas Tradicionais São Limitadas à Rede Local
As ferramentas mais comuns para comunicar com dispositivos ZKTeco são:
pyzk — Uma biblioteca Python que se comunica com dispositivos ZKTeco pela rede local. Exige acesso direto ao dispositivo na mesma rede. É open-source, mas possui bugs conhecidos com firmwares mais recentes e manutenção limitada.
node-zklib — O equivalente em Node.js. Mesma restrição: a máquina executando o código precisa estar na mesma rede que o dispositivo. Existem múltiplos forks, nenhum é definitivo.
Módulos da Odoo App Store — Existem vários módulos que prometem integrar ZKTeco com Odoo. Quase todos usam pyzk ou node-zklib por baixo, o que significa que herdam a mesma limitação de rede local.
Isso Não Funciona para Odoo na Nuvem
Se você usa Odoo Online (a plataforma SaaS da Odoo), não é possível instalar bibliotecas Python customizadas. Ponto final. A abordagem com pyzk é impossível.
Se você usa Odoo.sh (a plataforma PaaS da Odoo), não é possível instalar pacotes Python a nível de sistema que precisam de acesso a hardware na rede local. O pyzk falha novamente.
Mesmo que você tenha Odoo self-hosted em um VPS ou servidor na nuvem, sua instância Odoo está em um data center e seu dispositivo ZKTeco está no escritório. Não estão na mesma rede. Para fazer o pyzk funcionar, você precisa de uma dessas gambiarras:
Túnel VPN entre a rede do escritório e o servidor — adiciona complexidade, latência e custo recorrente.
Port forwarding no roteador do escritório para expor o dispositivo à internet — um risco de segurança significativo.
IP fixo na sua conexão de internet — nem todos os provedores oferecem, e ainda exige port forwarding.
Nenhuma dessas soluções é aceitável para uso em produção, especialmente se você gerencia dispositivos em múltiplas filiais.
A Abordagem Cloud: Configure Uma Vez, Acesse de Qualquer Lugar
Existe uma arquitetura melhor. Em vez do Odoo acessar sua rede local para puxar dados do dispositivo, o dispositivo envia os dados para a nuvem do PunchConnect, e o Odoo busca de lá via uma API REST padrão.
Você configura o dispositivo uma única vez pelo painel do PunchConnect. Depois disso, os dados de ponto fluem automaticamente para a nuvem. Sua instância Odoo busca os dados através de uma API REST padrão — sem software local, sem VPN, sem IP fixo. Apenas chamadas HTTPS de qualquer lugar.
Isso funciona com todos os modelos de deploy do Odoo: Online, .sh e self-hosted. Consulte nossa documentação da API para a referência completa dos endpoints.
ZKTeco Device ──(auto-sync)──> PunchConnect Cloud ──(REST API)──> Odoo
│
└──(Webhook)──> Your server (optional)Passo a Passo: Conectar ZKTeco ao Odoo com PunchConnect
Pré-requisitos
Um dispositivo ZKTeco (a maioria dos modelos modernos é compatível — incluindo K-series, uFace, SpeedFace, ProFace e MB-series).
Uma instância Odoo (qualquer versão, qualquer modelo de hospedagem).
Uma conta PunchConnect. Comece seu teste grátis de 7 dias — sem necessidade de cartão de crédito.
Passo 1: Registre Seu Dispositivo no PunchConnect
Após criar sua conta PunchConnect, você receberá um token de API (com prefixo pc_live_). Use-o para registrar seu dispositivo.
Python:
JavaScript (Node.js):
```javascript
const API_TOKEN = "pc_live_your_token_here";
const BASE_URL = "https://api.punchconnect.com";
const response = await fetch(${BASE_URL}/v1/devices, {
method: "POST",
headers: {
Authorization: Bearer ${API_TOKEN},
"Content-Type": "application/json",
},
body: JSON.stringify({
serial_number: "BFGH234900045",
name: "Main Entrance - Floor 1",
location: "Headquarters",
}),
});
const device = await response.json();
console.log(Device ID: ${device.id});
console.log(Status: ${device.status});
```
import requests
API_TOKEN = "pc_live_your_token_here"
BASE_URL = "https://api.punchconnect.com"
# Register a new device
response = requests.post(
f"{BASE_URL}/v1/devices",
headers={
"Authorization": f"Bearer {API_TOKEN}",
"Content-Type": "application/json"
},
json={
"serial_number": "BFGH234900045",
"name": "Main Entrance - Floor 1",
"location": "Headquarters"
}
)
device = response.json()
print(f"Device ID: {device['id']}")
print(f"Status: {device['status']}")Passo 2: Conecte o Dispositivo
Após o registro, siga as instruções de configuração no painel do PunchConnect para conectar seu dispositivo ZKTeco. O processo leva cerca de 5 minutos por dispositivo — você vai inserir algumas configurações no painel administrativo do dispositivo, e ele começará a sincronizar automaticamente.
Em até 60 segundos após a configuração, o dispositivo aparece como "online" no seu painel. Você pode verificar pela API:
response = requests.get(
f"{BASE_URL}/v1/devices",
headers={"Authorization": f"Bearer {API_TOKEN}"}
)
for device in response.json()["data"]:
print(f"{device['name']}: {device['status']}")
# Output: "Main Entrance - Floor 1: online"Passo 3: Configure Webhooks para Ponto em Tempo Real
Para sincronização de ponto em tempo real, configure um webhook. O PunchConnect enviará eventos de ponto via POST para sua URL conforme eles acontecem — sem necessidade de polling.
Cada POST do webhook inclui um payload JSON com o ID do funcionário, timestamp, informações do dispositivo e direção da marcação (entrada/saída).
Se você não pode receber webhooks (por exemplo, no Odoo Online), pule para o Passo 4 — você pode consultar a API em intervalos regulares.
response = requests.post(
f"{BASE_URL}/v1/webhooks",
headers={
"Authorization": f"Bearer {API_TOKEN}",
"Content-Type": "application/json"
},
json={
"url": "https://your-odoo-instance.com/api/punchconnect/webhook",
"events": ["attendance.created"],
"secret": "your_webhook_secret"
}
)
webhook = response.json()
print(f"Webhook ID: {webhook['id']}")
print(f"Status: {webhook['status']}")Passo 4: Busque Dados de Ponto no Odoo
Aqui tudo se conecta. Este script Python busca registros de ponto no PunchConnect e cria lançamentos de presença no Odoo usando a API XML-RPC do Odoo.
Isso funciona em qualquer máquina com acesso à internet — um cron job no seu servidor, uma ação agendada no Odoo, ou até uma função serverless.
Você pode executar este script como uma ação agendada no Odoo (ir.cron) rodando a cada 10-15 minutos, um cron job em qualquer servidor, ou um handler de webhook que processa registros em tempo real a partir do Passo 3.
import requests
import xmlrpc.client
from datetime import datetime, timedelta
# ---------- PunchConnect Config ----------
PC_TOKEN = "pc_live_your_token_here"
PC_BASE = "https://api.punchconnect.com"
# ---------- Odoo Config ----------
ODOO_URL = "https://your-company.odoo.com"
ODOO_DB = "your-database"
ODOO_USER = "admin@yourcompany.com"
ODOO_PASSWORD = "your_api_key"
# ---------- Connect to Odoo ----------
common = xmlrpc.client.ServerProxy(f"{ODOO_URL}/xmlrpc/2/common")
uid = common.authenticate(ODOO_DB, ODOO_USER, ODOO_PASSWORD, {})
models = xmlrpc.client.ServerProxy(f"{ODOO_URL}/xmlrpc/2/object")
# ---------- Fetch Recent Attendance from PunchConnect ----------
since = (datetime.utcnow() - timedelta(hours=1)).isoformat() + "Z"
response = requests.get(
f"{PC_BASE}/v1/attendance",
headers={"Authorization": f"Bearer {PC_TOKEN}"},
params={
"since": since,
"limit": 100
}
)
records = response.json()["data"]
print(f"Fetched {len(records)} attendance records")
# ---------- Sync to Odoo ----------
for record in records:
# Look up the Odoo employee by badge ID
employee_ids = models.execute_kw(
ODOO_DB, uid, ODOO_PASSWORD,
"hr.employee", "search",
[[["barcode", "=", record["employee_id"]]]]
)
if not employee_ids:
print(f"No Odoo employee found for badge {record['employee_id']}, skipping")
continue
employee_id = employee_ids[0]
punch_time = record["timestamp"]
if record["direction"] == "in":
# Create check-in record
models.execute_kw(
ODOO_DB, uid, ODOO_PASSWORD,
"hr.attendance", "create",
[{"employee_id": employee_id, "check_in": punch_time}]
)
print(f"Check-in recorded for employee {employee_id} at {punch_time}")
elif record["direction"] == "out":
# Find open attendance and set check-out
open_attendance = models.execute_kw(
ODOO_DB, uid, ODOO_PASSWORD,
"hr.attendance", "search",
[[
["employee_id", "=", employee_id],
["check_out", "=", False]
]],
{"limit": 1, "order": "check_in desc"}
)
if open_attendance:
models.execute_kw(
ODOO_DB, uid, ODOO_PASSWORD,
"hr.attendance", "write",
[open_attendance, {"check_out": punch_time}]
)
print(f"Check-out recorded for employee {employee_id} at {punch_time}")Bônus: Sincronize Funcionários para o Dispositivo
Você também pode enviar funcionários do Odoo para o dispositivo ZKTeco via PunchConnect, para que novos contratados apareçam automaticamente no dispositivo:
# Fetch employees from Odoo
employees = models.execute_kw(
ODOO_DB, uid, ODOO_PASSWORD,
"hr.employee", "search_read",
[[["active", "=", True]]],
{"fields": ["id", "name", "barcode"]}
)
# Sync to PunchConnect (which syncs to the device)
response = requests.post(
f"{PC_BASE}/v1/employees/sync",
headers={
"Authorization": f"Bearer {PC_TOKEN}",
"Content-Type": "application/json"
},
json={
"employees": [
{
"id": str(emp["barcode"]),
"name": emp["name"]
}
for emp in employees
if emp["barcode"]
]
}
)
result = response.json()
print(f"Synced {result['synced']} employees, {result['errors']} errors")Odoo Online vs Self-Hosted: Qual Abordagem Funciona em Cada Caso?
Se você usa Odoo Online, não é possível instalar bibliotecas Python customizadas. A abordagem pyzk/node-zklib é impossível. Uma API REST na nuvem como o PunchConnect é sua única opção viável para integração biométrica com ZKTeco.
Se você usa Odoo.sh, não é possível instalar pacotes a nível de sistema que se comunicam com hardware local. Mesmo resultado — as ferramentas tradicionais baseadas em LAN não funcionam.
Se você tem Odoo self-hosted em um VPS ou servidor na nuvem, você poderia tecnicamente configurar VPN + pyzk, mas leva horas para configurar, exige monitoramento contínuo da VPN/rede, e quebra quando seu provedor muda seu IP. Com o PunchConnect, a configuração leva menos de 30 minutos e funciona em todas as suas filiais a partir de uma única API.
A abordagem tradicional também limita você ao polling (executar um script periodicamente para puxar dados do dispositivo). O PunchConnect suporta webhooks em tempo real, então eventos de ponto chegam ao Odoo em segundos após a marcação.
Para empresas com múltiplas filiais, a diferença é ainda mais expressiva. Uma configuração baseada em VPN exige configuração separada por unidade. O PunchConnect gerencia todos os dispositivos a partir de um painel e uma API — seja com 2 dispositivos ou 200.
Preços
O PunchConnect custa $200 por dispositivo (licença única) mais $50/ano para renovações a partir do Ano 2. Não há cobrança por usuário, o que faz diferença em escala — seja com 10 funcionários ou 10.000 por dispositivo, o preço é o mesmo.
Descontos por volume estão disponíveis: 10+ dispositivos a $180, 25+ a $160, 50+ com preço sob consulta. Veja a tabela completa na nossa página de preços.
O PunchConnect já opera em produção com cargas de trabalho atendendo mais de 24.000 funcionários em múltiplas unidades — então ele suporta escala real.
Perguntas Frequentes
É possível conectar ZKTeco ao Odoo Online sem instalar software local? Sim. O PunchConnect é uma API REST na nuvem — seu dispositivo ZKTeco sincroniza dados com a nuvem do PunchConnect, e sua instância Odoo Online busca esses dados via chamadas HTTPS padrão. Sem software local, sem VPN, sem IP fixo.
O PunchConnect atende as exigências da CLT e Portaria 671 para controle de ponto eletrônico? O PunchConnect fornece registros de ponto com timestamp preciso, identificação do funcionário e do dispositivo. Os registros podem ser integrados ao seu sistema de ponto eletrônico no Odoo para atender as exigências da CLT e da Portaria 671, que regulamenta o controle de jornada de trabalho no Brasil.
Dados biométricos ficam protegidos de acordo com a LGPD? O PunchConnect processa registros de ponto (ID do funcionário, timestamp, direção), não armazena templates biométricos. A biometria fica no próprio dispositivo ZKTeco. Mesmo assim, recomendamos que sua política de dados esteja em conformidade com a LGPD, especialmente ao coletar e armazenar dados de presença de funcionários.
Quais modelos de relógio de ponto ZKTeco são compatíveis? A maioria dos modelos modernos é compatível, incluindo K-series, uFace, SpeedFace, ProFace e MB-series. Se o seu dispositivo possui capacidade de conexão web/cloud integrada, ele vai funcionar. Entre em contato se tiver dúvidas sobre um modelo específico.
Quanto tempo leva para os dados de ponto chegarem ao Odoo? Com webhooks, eventos de ponto chegam à sua instância Odoo em segundos após a marcação. Se você usar polling (por exemplo, no Odoo Online onde não é possível receber webhooks), o atraso depende do intervalo configurado — tipicamente 5-15 minutos.
Comece Agora
Conectar ZKTeco ao Odoo não precisa envolver VPNs, IPs fixos ou scripts locais frágeis. A abordagem via API cloud é mais simples, mais segura e funciona com todos os modelos de deploy do Odoo — atendendo às necessidades de controle de ponto da sua empresa.
Comece seu teste grátis de 7 dias — sem necessidade de cartão de crédito. Registre seu dispositivo e conecte-o pelo painel em cerca de 15 minutos. Depois, execute o script de sincronização acima ou configure webhooks para ponto em tempo real.
Se você tem dúvidas sobre a integração ou precisa de ajuda com um modelo específico de relógio de ponto biométrico ZKTeco, entre em contato pela nossa página. Temos experiência com praticamente todas as variantes de firmware ZKTeco disponíveis no mercado.