A maior parte da evidência de conformidade já existe nos seus sistemas — no diretório de identidades, no gestor de vulnerabilidades, no sistema de tickets, no RH. A API existe para trazer essa evidência para os controlos automaticamente, com data e proveniência, em vez de alguém tirar prints todos os trimestres.

Disponibilidade

O acesso à API e a webhooks está disponível no plano Enterprise e como add-on nos planos Professional. Ver Preços.

Autenticação

A API é REST sobre HTTPS e autentica por token de serviço. Crie o token em Administração → API, atribuindo-lhe o âmbito mínimo necessário (domínios e operações). Os tokens podem ter data de expiração e são revogáveis a qualquer momento.

curl https://api.icomply.pt/v1/controls \
  -H "Authorization: Bearer $ICOMPLY_TOKEN" \
  -H "Accept: application/json"

Nunca coloque tokens em código-fonte versionado nem no browser. Use o cofre de segredos da sua infraestrutura. Cada utilização do token fica registada no registo de auditoria.

Principais recursos

/v1/controls — ler e atualizar controlos, estados e responsáveis.
/v1/requirements — requisitos dos frameworks e respetivos mapeamentos.
/v1/evidence — carregar, listar e substituir evidência.
/v1/risks — registo de risco, scoring e associação a controlos.
/v1/tasks — tarefas, prazos e responsáveis.
/v1/findings — achados de auditoria e ações CAPA.
/v1/audits — auditorias, âmbito e resultados.
/v1/vendors — fornecedores, avaliações e criticidade.
/v1/reports — geração de relatórios de estado por framework.

Carregar evidência por API

O caso de uso mais valioso. Envie o ficheiro e associe-o a um ou mais controlos; a plataforma trata do versionamento e da propagação a todos os requisitos mapeados.

POST /v1/evidence Authorization: Bearer $ICOMPLY_TOKEN Content-Type: multipart/form-data

[email protected]
control_ids[]=ctrl_mfa_enforced
control_ids[]=ctrl_access_review
valid_from=2026-07-01
valid_until=2026-10-01
source=okta-automation

O campo source é importante: identifica que a evidência foi produzida automaticamente e por que sistema — informação que os auditores valorizam, porque remove intervenção manual da cadeia.

Webhooks

Em vez de consultar a API periodicamente, subscreva eventos. Configure endpoints em Administração → Webhooks.

control.status_changed — um controlo mudou de estado.
evidence.expiring — evidência a aproximar-se do fim da validade.
evidence.expired — evidência expirou.
task.assigned / task.overdue — tarefas.
finding.created — novo achado de auditoria.
capa.due — ação CAPA com prazo próximo.
risk.escalated — risco subiu acima do apetite definido.

Cada entrega é assinada com HMAC-SHA256 no cabeçalho X-iComply-Signature. Valide sempre a assinatura antes de processar. Entregas falhadas são repetidas com backoff exponencial.

Integrações típicas

Identidade e acessos

Ligue o seu provedor de identidade (Entra ID, Okta, Google Workspace) para alimentar revisões de acessos e evidência de MFA. Combinado com SCIM, elimina a não conformidade mais comum: contas de ex-colaboradores ativas.

Segurança e vulnerabilidades

Envie achados do seu gestor de vulnerabilidades para os controlos correspondentes, com SLA de remediação. A evidência do controlo passa a ser o estado real, não uma declaração.

Tickets e mudança

Ligue Jira, ServiceNow ou equivalente para que tarefas de remediação e CAPA vivam onde as equipas técnicas já trabalham, mantendo o estado sincronizado na iComply.

RH

Sincronize entradas, saídas e conclusão de formação obrigatória — evidência direta para controlos de Governance de Pessoas e de sensibilização em segurança.

Comunicação

Envie notificações de controlos em risco, evidência expirada e achados novos para Slack ou Teams via webhook.

BI e relatórios

Exporte estado de conformidade e risco para Power BI, Looker ou Tableau para painéis executivos com outras métricas do negócio.

Limites e paginação

Rate limit — por token; os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset indicam o estado. Trate 429 com backoff.
Paginação — por cursor, com limit e cursor; siga next_cursor até vir nulo.
Idempotência — envie Idempotency-Key em operações de escrita para evitar duplicados em retentativas.
Versionamento — a versão está no caminho (/v1/). Alterações incompatíveis só ocorrem em versões novas, com período de sobreposição anunciado.

Tratamento de erros

As respostas de erro seguem um formato consistente, com um código legível por máquina e uma mensagem para humanos:

{
  "error": {
    "code": "control_not_found",
    "message": "No control matches id 'ctrl_xyz'.",
    "request_id": "req_01J9F2K7Q"
  }
}

Registe sempre o request_id — acelera muito o apoio quando precisa de investigar um caso concreto com a nossa equipa.

Boas práticas

Um token por integração. Facilita revogar sem afetar o resto.
Âmbito mínimo. Um token que só carrega evidência não precisa de ler o registo de risco.
Rotação periódica. Defina expiração e trate a rotação como um controlo com cadência.
Prefira webhooks a polling. Menos carga, reação mais rápida.
Preencha sempre source e datas de validade na evidência automatizada — sem isso perde-se metade do valor em auditoria.