Referência Rápida PHP / API

5 passos para conectar sua aplicação. Funciona com Postman, cURL ou qualquer cliente HTTP.

URL Base: https://api.punchconnect.com/api/v2/zk

Configure Seus Headers de Autenticação

Toda requisição precisa destes headers. Obtenha suas credenciais no painel.

Header	Valor
`X-CLIENT-ID`	Seu ID de cliente da API
`X-CLIENT-SECRET`	Seu segredo de cliente da API
`Content-Type`	application/json
`Accept`	application/json

bashPostman / cURL

curl https://api.punchconnect.com/api/v2/zk/devices \
  -H "X-CLIENT-ID: your_client_id" \
  -H "X-CLIENT-SECRET: your_client_secret" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Listar e Atualizar Dispositivos

Dispositivos são registrados pelo painel. Use a API para listá-los e atualizá-los.

bashGET /devices

curl https://api.punchconnect.com/api/v2/zk/devices \
  -H "X-CLIENT-ID: your_client_id" \
  -H "X-CLIENT-SECRET: your_client_secret" \
  -H "Accept: application/json"

Atualizar um dispositivo:

bashPUT /devices/{id}

curl -X PUT https://api.punchconnect.com/api/v2/zk/devices/1 \
  -H "X-CLIENT-ID: your_client_id" \
  -H "X-CLIENT-SECRET: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Entrance",
    "site_name": "Head Office",
    "site_id": 1,
    "timezone": 1
  }'

Também disponível: GET /devices/{id} para obter detalhes de um dispositivo específico.

Adicionar um Funcionário a um Dispositivo

bashPOST /employees

curl -X POST https://api.punchconnect.com/api/v2/zk/employees \
  -H "X-CLIENT-ID: your_client_id" \
  -H "X-CLIENT-SECRET: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "EMP-0042",
    "uid": 1001,
    "name": "Ahmed Mansouri",
    "card_no": "0012345678",
    "privilege": "user",
    "verify_mode": 1,
    "device_id": 1
  }'

Campo	Tipo	Obrigatório
`user_id`	string	Sim
`uid`	integer	Sim
`name`	string	Sim
`device_id`	integer	Sim
`employee_id`	integer	Não
`card_no`	string	Não
`password`	string	Não
`privilege`	"user" ou "admin"	Não
`verify_mode`	integer (1–15)	Não

Outros endpoints: PUT /employees/{id} (atualizar), DELETE /employees/{ids} (remover, separados por vírgula), GET /devices/{device}/employees (listar funcionários em um dispositivo), POST /employees/{id}/sync-from-device (sincronizar do dispositivo).

Enviar Registros de Presença

bashPOST /attendances/push

curl -X POST https://api.punchconnect.com/api/v2/zk/attendances/push \
  -H "X-CLIENT-ID: your_client_id" \
  -H "X-CLIENT-SECRET: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 5001,
      "uid": 1001,
      "timestamp": "2026-03-10 08:01:23",
      "site_id": 1,
      "site_name": "Head Office",
      "device_name": "Main Entrance",
      "mac_address": "AA:BB:CC:DD:EE:FF"
    }
  ]'

jsonResponse

{
  "status": true,
  "data": [5001]
}

Buscar registros: GET /devices/{device}/attendances. Excluir: DELETE /devices/{device}/attendances/{ids}.

Enviar Comandos ao Dispositivo

bashPOST /commands

curl -X POST https://api.punchconnect.com/api/v2/zk/commands \
  -H "X-CLIENT-ID: your_client_id" \
  -H "X-CLIENT-SECRET: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{ "device_id": 1, "command": "reboot" }'

Comando	O que faz
`reboot`	Reinicia o dispositivo (~30s de inatividade)
`clear_log`	Limpa o registro de presença no dispositivo
`clear_data`	Remove todos os funcionários + registros de presença do dispositivo
`clear_admins`	Remove privilégios de administrador de todos os usuários no dispositivo

Códigos de Erro

Status	Significado
200	Sucesso
401	Credenciais de API inválidas ou ausentes
404	Recurso não encontrado
422	Erro de validação (verifique seus campos)
429	Limite de requisições excedido — reduza a frequência
500	Erro no servidor — tente novamente mais tarde

Próximos passos

Referência da API

Documentação completa dos endpoints

Planos e Preços

Escolha o plano ideal