Visão geral

A API de integração do AlfaControl permite que sistemas externos consultem registros de acesso e recebam eventos em tempo real via webhook. É voltada para parceiros como sistemas de gestão escolar, ERPs e plataformas de RH que precisam sincronizar dados de entrada e saída de pessoas.

Cada cliente do AlfaControl pode criar múltiplas configurações de integração, cada uma com sua própria API key e lista de eventos habilitados.

URL base

https://control.alfasolucoes.cloud

Dois grupos de endpoints

Autenticação

API Key (parceiros externos)

Utilize o header X-Api-Key em todas as requisições ao endpoint /api/v1/integracao/**. A chave identifica automaticamente o cliente (tenant) — não é necessário passar IDs adicionais.

curl https://control.alfasolucoes.cloud/api/v1/integracao/acessos \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

JWT Bearer Token (admin)

Os endpoints /api/integracoes/** são usados pelo painel de administração e requerem autenticação via JWT. Obtenha o token via login.

TOKEN=$(curl -s -X POST \
  https://control.alfasolucoes.cloud/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"seu@email.com","senha":"suasenha"}' \
  | jq -r '.token')

curl https://control.alfasolucoes.cloud/api/integracoes \
  -H "Authorization: Bearer $TOKEN"

Início rápido

Siga estes 3 passos para começar a consultar acessos em menos de 5 minutos.

curl -s -X POST \
  https://control.alfasolucoes.cloud/api/integracoes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Meu Sistema"}' | jq .

ALFACONTROL_API_KEY=sua_chave_aqui

curl -s \
  "https://control.alfasolucoes.cloud/api/v1/integracao/acessos\
?resultado=ENTRADA,SAIDA\
&dataInicio=2026-05-01T00:00:00\
&dataFim=2026-05-31T23:59:59\
&page=0&size=50" \
  -H "X-Api-Key: $ALFACONTROL_API_KEY" | jq .

Configuração no painel

Esta seção detalha como criar e gerenciar integrações diretamente pelo painel do AlfaControl, sem precisar usar a API.

Quem pode configurar

Acessando a página

No painel, localize o grupo SISTEMA na barra lateral esquerda e clique em Integrações. A página exibe todas as integrações ativas do cliente com as colunas Nome, Webhook, Eventos, Data de criação e Ações.

Criando uma integração

Encontrando o ID do Cliente

O campo clienteId aparece nos payloads de webhook e nas respostas da API. Para localizar o ID do seu cliente:

1. No painel, clique em Configurações (grupo SISTEMA na barra lateral).
2. No cartão Meu Perfil, localize a linha "ID do Cliente".
3. Clique no ícone de copiar ao lado do número.

// Configurações → Meu Perfil → ID do Cliente: 789
// Esse mesmo valor aparece nos payloads:
{
  "clienteId": 789,
  "pessoaNome": "João Silva",
  "resultado": "ENTRADA"
  // ...
}

Gerenciando integrações existentes

Referência de endpoints

{
  "content": [
    {
      "id": 12345,
      "clienteId": 789,
      "matricula": "2024001",
      "pessoaNome": "João Silva",
      "pessoaDocumento": "123.456.789-00",
      "resultado": "ENTRADA",
      "dataHora": "2026-05-27T09:30:00",
      "dispositivoNome": "Catraca Principal",
      "dispositivoSentido": "Entrada",
      "tipoIdentificacao": "FACIAL"
    }
  ],
  "totalElements": 1250,
  "totalPages": 25,
  "number": 0,
  "size": 50,
  "first": true,
  "last": false
}

curl -s \
  "https://control.alfasolucoes.cloud/api/v1/integracao/acessos\
?resultado=ENTRADA&dataInicio=2026-05-01T00:00:00&size=100" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" | jq .content

curl -s -X POST \
  https://control.alfasolucoes.cloud/api/integracoes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Minha Integração",
    "webhookUrl": "https://meusite.com/webhooks/acesso",
    "eventosHabilitados": ["ENTRADA", "SAIDA"]
  }' | jq .

{
  "id": 42,
  "revendaId": 10,
  "clienteId": 789,
  "nome": "Minha Integração",
  "apiKey": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "webhookUrl": "https://meusite.com/webhooks/acesso",
  "eventosHabilitados": ["ENTRADA", "SAIDA"],
  "ativo": true
}

curl -s https://control.alfasolucoes.cloud/api/integracoes \
  -H "Authorization: Bearer $TOKEN" | jq .

curl -s -X PUT \
  https://control.alfasolucoes.cloud/api/integracoes/42 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Integração v2",
    "webhookUrl": "https://meusite.com/webhooks/v2",
    "eventosHabilitados": ["ENTRADA", "SAIDA", "NEGADO"]
  }' | jq .

curl -s -X DELETE \
  https://control.alfasolucoes.cloud/api/integracoes/42 \
  -H "Authorization: Bearer $TOKEN"
# Resposta: 204 No Content (sem body)

curl -s -X POST \
  https://control.alfasolucoes.cloud/api/integracoes/42/regenerar-chave \
  -H "Authorization: Bearer $TOKEN" | jq .apiKey

Webhooks

Configure uma webhookUrl HTTPS na sua integração e o AlfaControl enviará um POST com o payload do acesso em tempo real, cada vez que um dos eventos habilitados ocorrer.

Como funciona

• O AlfaControl faz um POST para sua URL com Content-Type: application/json.
• Seu endpoint deve responder com qualquer status 2xx em até 10 segundos.
• Em caso de falha ou timeout, o sistema retenta até 3 vezes com backoff linear (1s, 2s).
• Respostas 4xx (404, 401, etc.) são tratadas como erro permanente — sem retry.
• A URL deve ser HTTPS. URLs HTTP são rejeitadas no cadastro.

Payload enviado

{
  "evento": "ACESSO",
  "id": 12345,
  "clienteId": 789,
  "matricula": "2024001",
  "pessoaNome": "João Silva",
  "pessoaDocumento": "123.456.789-00",
  "resultado": "ENTRADA",
  "dataHora": "2026-05-27T09:30:00",
  "dispositivoNome": "Catraca Principal",
  "dispositivoSentido": "Entrada",
  "tipoIdentificacao": "FACIAL"
}

Exemplo de receptor (Node.js)

app.post('/webhooks/acesso', express.json(), (req, res) => {
  const { evento, resultado, pessoaNome, matricula, dataHora } = req.body;

  if (evento !== 'ACESSO') return res.sendStatus(400);

  console.log(`[${dataHora}] ${resultado} — ${pessoaNome} (${matricula})`);

  // processe o evento aqui...

  res.sendStatus(200); // sempre responda 2xx em até 10s
});

Tipos de evento

Estes são os valores possíveis para o campo resultado (tanto na consulta de acessos quanto no payload do webhook).

Códigos de erro

Limites e boas práticas

Boas práticas

• Use paginação incremental: sincronize com dataInicio do último registro processado.
• Prefira webhooks à polling para eventos em tempo real — reduz latência e carga na API.
• Seu endpoint webhook deve ser idempotente: o mesmo id pode chegar mais de uma vez em caso de retry.
• Armazene a API key em variável de ambiente ou cofre de segredos, nunca em código-fonte.
• Se suspeitar de vazamento da chave, regenere imediatamente pelo painel — a chave anterior é invalidada no instante da regeneração.
• Filtre apenas os eventosHabilitados que seu sistema consome para reduzir volume de webhooks e dados na consulta.