Central de ajuda › Instalação

API pública e webhooks

Integre registros, prova, titulares, varreduras e uso ao seu sistema; receba eventos por webhook assinado.

A API pública dá ao seu sistema acesso aos mesmos dados do painel: registros de consentimento (com a prova de cada um), sites, pedidos de titulares, documentos e aceites, varreduras e uso. Os webhooks avisam o seu sistema quando algo acontece. Disponível nos planos Pro e Business.

Especificação OpenAPI 3.1 (para Postman, Insomnia ou gerar cliente): /v1/api/openapi.json.

Autenticação

Em API e webhooks → Nova chave (donos e administradores), dê um nome, escolha as permissões e, se quiser, uma validade. A chave (acp_live_…) aparece uma única vez: guardamos só o hash dela. Envie em toda chamada:

curl https://consent.accesssecurity.com.br/v1/api/consents?limit=100 \
  -H "Authorization: Bearer acp_live_…"

A chave é da empresa (não de uma pessoa) e só enxerga os dados dela. Use do seu servidor — nunca no navegador ou num app. Revogar vale na hora. A trilha de auditoria registra o que a chave altera (ex.: api:Integração ERP (acp_live_ab12cd…)).

Permissões

Rotas

Paginação, datas e erros

• Listas respondem { "data": [...], "nextCursor": "…" }, mais novos primeiro. Para a próxima página, repita a chamada com ?cursor=<nextCursor>; null = acabou. limit vai de 1 a 200 (padrão 50).
• Datas saem em ISO 8601 (UTC). Nos filtros from/to, use ISO (2026-10-15T00:00:00Z) ou o dia (2026-10-15, dia inteiro no horário de Brasília).
• Erros: { "statusCode": 403, "message": "…" } — 400 parâmetro inválido, 401 chave ausente/inválida/revogada/vencida, 403 plano sem API, empresa suspensa ou chave sem a permissão, 404 não encontrado (inclusive dado de outra empresa), 409 conflito (ex.: varredura já na fila), 429 limite.
• Limite por chave: Pro: 120 por minuto · Business: 600 por minuto. Cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; no 429, espere o Retry-After (segundos).

Prova de um registro

GET /v1/api/consents/{id}/proof devolve o registro, o hash recalculado, o elo com o registro anterior e o seguinte do mesmo site e, nos planos com prova verificável, a âncora diária gravada no armazenamento imutável. Veja como conferir sozinho em Prova verificável.

Regras que continuam valendo

A API usa as mesmas regras do painel: varredura só com domínio verificado e dentro da cota mensal do plano; PATCH /sites não muda domínios, aparência nem a versão do aviso (isso afeta a verificação e a prova, e fica no painel); o aviso de cookies nunca para por limite.

Webhooks

Em API e webhooks → Novo webhook, informe um endereço https:// público e os eventos. O segredo (whsec_…) aparece uma vez (dá para gerar outro). Até 10 endereços por conta. Use Enviar teste para conferir.

Todo envio é um POST com Content-Type: application/json e o corpo:

{
  "id": "evt_6f1c…",            // igual em todas as tentativas: use para não processar duas vezes
  "type": "request.created",
  "createdAt": "2026-10-15T13:02:11.120Z",
  "tenantId": "…",
  "data": { … }
}

• consent.recorded chega em lotes de até 100 registros por site (data.records, mesmos campos de GET /v1/api/consents), em geral um minuto depois do registro. Começa quando o endereço passa a assinar o evento (sem histórico). Em site com muito tráfego isso é muito volume: se só precisa de números, prefira consent.daily_summary (um por dia, por volta de 1h10 de Brasília, com as decisões do dia anterior por site).
• request.created sai quando o titular confirma o e-mail (o pedido abre e o prazo começa); request.updated quando o status muda, entra nota ou resposta; request.overdue quando o prazo de 15 dias vence.
• scan.new_cookies traz os cookies e serviços que a varredura achou e o aviso não declara; proof.chain_broken avisa que a verificação de integridade encontrou problema.

Assinatura

O cabeçalho X-AccessConsent-Signature: t=<unix>,v1=<hex> traz o HMAC-SHA256, com o seu segredo, de `${t}.${corpo}`. Confira antes de confiar no conteúdo e recuse t com mais de 5 minutos. Outros cabeçalhos: X-AccessConsent-Event, X-AccessConsent-Event-Id e X-AccessConsent-Delivery.

import crypto from 'node:crypto';

// Use o corpo BRUTO (exatamente os bytes recebidos), não o JSON já convertido.
function verify(secret, header, rawBody, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // evita reenvio antigo
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return parts.v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

app.post('/webhooks/access-consent', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(process.env.ACCESS_CONSENT_WHSEC, req.get('X-AccessConsent-Signature') ?? '', req.body.toString('utf8'))) {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // event.id é o mesmo em todas as tentativas: ignore se já processou.
  res.status(204).end(); // responda rápido (até 10 s) e processe depois
});

Entrega, novas tentativas e desativação

• Responda com qualquer 2xx em até 10 segundos. Outra resposta, redirecionamento (não seguimos), erro de rede ou demora = nova tentativa: 1 min, 5 min, 15 min, 1 h, 2 h, 4 h, 8 h e 8 h (9 tentativas, cerca de 23 horas). Depois disso, a entrega fica como falhou e pode ser reenviada no painel.
• Entrega é pelo menos uma vez e a ordem não é garantida: deduplique pelo id e use createdAt para ordenar.
• Endereço com 10 ou mais falhas seguidas e falhando há 24 horas é desativado; os donos da conta recebem e-mail. As entregas pendentes voltam a sair quando você reativa.
• O histórico de entregas (status, código HTTP, erro, tempo) fica em API e webhooks → Entregas.

Endereços aceitos

Só https:// em porta 443 ou 8443, sem usuário e senha na URL. Por segurança, o endereço é resolvido no cadastro e em cada envio, e recusamos IPs privados, locais, de link-local (inclusive o de metadados de nuvem), CGNAT e reservados. A conexão vai para o IP conferido.

Atualizado em 18/10/2026. Dúvidas: [email protected].