Integre o Anonimatum nos seus sistemas

Início rápido

Três passos: crie a chave de API, verifique-a e anonimize o seu primeiro documento.

1. Crie uma chave de API na App: Perfil → Chaves de API → «Gerar chave de API». Copie-a de imediato: não volta a ser mostrada. Se não vir a secção, o seu plano não inclui acesso à API ou é o administrador do seu grupo que o gere.
2. Guarde-a como variável de ambiente e verifique o plano do seu grupo com GET /api/public/plan.
3. Envie o documento para POST /api/public/ai/anonymize com as opções de IA de que necessita. A resposta é o documento anonimizado no seu formato original.

export ANONIMATUM_API_KEY="tu_api_key"

# 1. Comprueba la clave: plan y cupo del grupo
curl -H "X-API-Key: $ANONIMATUM_API_KEY" \
  https://api.anonimatum.com/api/public/plan

# 2. Opciones de IA disponibles (rgpd, fechas, direcciones, qr…)
curl -H "X-API-Key: $ANONIMATUM_API_KEY" \
  https://api.anonimatum.com/api/public/ai/options

# 3. Primer anonimizado: PDF, Word, Excel o PowerPoint
curl -X POST https://api.anonimatum.com/api/public/ai/anonymize \
  -H "X-API-Key: $ANONIMATUM_API_KEY" \
  -F "file=@resolucion.pdf" \
  -F "aiOptions=rgpd,direcciones,qr" \
  -F "backgroundColor=black" \
  -F "textContent=none" \
  --output resolucion-anonimizada.pdf

Os parâmetros dos endpoints multipart são enviados como campos de formulário (-F). O consumo é descontado do plano do grupo a que a chave pertence.

Autenticação

X-API-Key

Cabeçalho para integrações máquina a máquina. Cada chave pertence a um utilizador e a um grupo: utiliza as respetivas permissões, plano e quota.

Authorization: Bearer

JWT da sessão do utilizador, o mesmo que a App utiliza. Útil se integrar o Anonimatum numa aplicação com início de sessão Politeia.

Isolamento

Um recurso de outro grupo devolve 404, nunca 403: a API não revela se existe.

Revogação

Revogue uma chave em Perfil → Chaves de API; deixa de funcionar de imediato. Nunca inclua chaves no código nem em repositórios.

Limites

Limites técnicos na versão 1.9.0 (por endereço IP ou por pedido):

Cada operação desconta também páginas ou documentos do plano do grupo. Consulte o consumo com GET /api/public/usage/current e /usage/remaining, ou valide previamente com POST /usage/validate-operation.

Erros

Os erros utilizam o formato padrão { errorCode, message, status }. Os mais comuns:

HTTP/1.1 403
Content-Type: application/json

{
  "errorCode": "PLAN_EXPIRED",
  "message": "Tu plan ha expirado. Contacta con el equipo de Politeia para renovarlo o activar un plan.",
  "status": 403
}

Trate os casos com base em errorCode e não no texto da mensagem, que pode mudar ou ser traduzido.

Webhooks

Um webhook notifica o seu sistema com um POST JSON assinado quando termina um lote em fila ou uma publicação. A notificação nunca inclui nomes de ficheiros, títulos, texto ou endereços de email: apenas identificadores, estados e, no caso dos lotes, uma ligação de transferência a utilizar com a sua chave de API.

Eventos

Registe-o com a sua chave de API

POST /api/public/webhooks devolve o segredo (whsec_…) uma única vez; guarde-o como variável de ambiente. Um webhook criado com uma chave de API só recebe os eventos do utilizador dessa chave; o administrador do grupo pode criar webhooks para todo o grupo a partir do painel da App. Também: GET, PUT e DELETE /{id}, POST /{id}/rotate-secret, POST /{id}/test e GET /{id}/deliveries. Até 10 por grupo; o URL tem de ser https.

curl -X POST https://api.anonimatum.com/api/public/webhooks \
  -H "X-API-Key: $ANONIMATUM_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://erp.ejemplo.es/anonimatum/webhook","events":["batch.completed","batch.failed"]}'

Verifique a assinatura

Cada notificação inclui o cabeçalho X-Anonimatum-Signature: t=<unix>,v1=<hex>, em que v1 é um HMAC-SHA256 calculado com o segredo completo (incluindo o prefixo whsec_) sobre «t.body». São também enviados X-Anonimatum-Event, X-Anonimatum-Event-Id e X-Anonimatum-Delivery.

1. Leia o corpo em bruto, sem analisar nem reformatar o JSON.
2. Separe t e v1 do cabeçalho e rejeite a notificação se t diferir mais de 300 segundos do seu relógio.
3. Calcule HMAC-SHA256(secret, t + "." + body) em hexadecimal e compare-o com v1 em tempo constante.
4. Elimine duplicados através de X-Anonimatum-Event-Id: uma nova tentativa tem o mesmo id.
5. Responda 2xx em menos de 5 segundos e processe depois.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.ANONIMATUM_WEBHOOK_SECRET; // whsec_… completo

app.post("/anonimatum/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const parts = Object.fromEntries(
    (req.get("X-Anonimatum-Signature") ?? "").split(",").map((p) => p.split("=", 2))
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);
  const expected = crypto.createHmac("sha256", SECRET).update(t + ".").update(req.body).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "utf8");
  const ok = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected, "utf8"), given);
  if (!ok) return res.sendStatus(401);
  // Deduplica por req.get("X-Anonimatum-Event-Id") y procesa después.
  res.sendStatus(204);
});

Python (Flask)

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["ANONIMATUM_WEBHOOK_SECRET"].encode()  # whsec_… completo

@app.post("/anonimatum/webhook")
def webhook():
    body = request.get_data()  # cuerpo crudo, sin parsear
    header = request.headers.get("X-Anonimatum-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        abort(400)
    if abs(time.time() - t) > 300:
        abort(400)
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(401)
    # Deduplica por request.headers["X-Anonimatum-Event-Id"] y procesa después.
    return "", 204

Qualquer resposta que não seja 2xx (os redirecionamentos não são seguidos) ou que demore mais de 5 segundos conta como falha. Após a primeira tentativa, as novas tentativas ocorrem a 1 min, 5 min, 30 min, 2 h e 6 h (6 tentativas no total); o registo de entregas mostra o estado, o código HTTP e a tentativa seguinte.

Se preferir não expor um endpoint, consulte periodicamente o estado dos lotes com GET /api/public/batch-jobs e descarregue os trabalhos concluídos com GET /api/public/batch-jobs/{id}/output.

Conector MCP para assistentes de IA

O Anonimatum expõe a mesma API como servidor MCP (Model Context Protocol). O assistente atua como o seu utilizador e o seu grupo depois de o autorizar na App.

URL do servidor MCP

https://gateway.politeiasoft.com/anonimatum/mcp

Claude

Em claude.ai → Definições → Conectores, adicione um conector personalizado com o URL MCP e autorize o acesso no ecrã de consentimento do Anonimatum.

ChatGPT

Em chatgpt.com → Definições → Conectores, adicione o URL MCP e conclua a autorização OAuth. A disponibilidade de conectores personalizados depende do seu plano do ChatGPT.

Grok

Em grok.com → Conectores, adicione o URL MCP e autorize o acesso.

Cursor, Claude Code e outros clientes MCP

Se o cliente suportar OAuth com redirecionamento local, basta o URL. Caso contrário, utilize a autorização manual na App (Perfil → Conectores): obtém um token e um mcp.json pronto a colar.

Ferramentas disponibilizadas

• listar_operaciones — Lista as operações disponíveis para o seu utilizador (o mesmo catálogo da referência, sem endpoints de administração nem internos).
• describir_operacion — Método, caminho, parâmetros e forma de enviar ficheiros para uma operação.
• ejecutar_operacion — Executa uma operação; as respostas binárias incluem uma ligação de transferência de utilização única.
• iniciar_subida_fichero — Devolve um URL de carregamento de utilização única, recomendado para documentos grandes (até 250 MB).
• subir_fichero — Carrega um ficheiro pequeno em Base64 numa única chamada.
• iniciar_subida_por_partes / subir_parte_fichero — Carregamento por partes para clientes que não conseguem fazer um POST direto.

As operações irreversíveis (eliminar, desanonimizar) exigem a confirmação explícita do utilizador nesse turno. Com um plano expirado, o assistente recebe PLAN_EXPIRED e deve transmitir a mensagem sem repetir o pedido. Pode revogar cada ligação em Perfil → Conectores.

Exemplo de mcp.json (autorização manual)

{
  "mcpServers": {
    "anonimatum": {
      "url": "https://gateway.politeiasoft.com/anonimatum/mcp",
      "headers": { "Authorization": "Bearer <token de la concesión manual>" }
    }
  }
}

SDK

Acesso mediante pedido

SDK oficiais para Python (síncrono e asyncio) e TypeScript/JavaScript (Node 18+) criados a partir desta mesma referência. O repositório é privado: peça acesso à Politeia através do formulário de contacto. Também pode gerar um cliente a partir do ficheiro OpenAPI.

Repositório do SDK (privado)