Integrieren Sie Anonimatum in Ihre Systeme

Schnellstart

Drei Schritte: API-Schlüssel erstellen, prüfen und Ihr erstes Dokument anonymisieren.

1. Erstellen Sie einen API-Schlüssel in der App: Profil → API-Schlüssel → „API-Schlüssel generieren“. Kopieren Sie ihn sofort: Er wird nicht erneut angezeigt. Wenn Sie den Bereich nicht sehen, enthält Ihr Tarif keinen API-Zugang oder der Administrator Ihrer Gruppe verwaltet ihn.
2. Speichern Sie ihn als Umgebungsvariable und prüfen Sie den Tarif Ihrer Gruppe mit GET /api/public/plan.
3. Senden Sie das Dokument an POST /api/public/ai/anonymize mit den benötigten KI-Optionen. Die Antwort ist das anonymisierte Dokument im Originalformat.

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

Parameter von Multipart-Endpunkten werden als Formularfelder (-F) gesendet. Der Verbrauch wird vom Tarif der Gruppe abgezogen, zu der der Schlüssel gehört.

Authentifizierung

X-API-Key

Header für Machine-to-Machine-Integrationen. Jeder Schlüssel gehört zu einem Benutzer und einer Gruppe und nutzt deren Berechtigungen, Tarif und Kontingent.

Authorization: Bearer

Sitzungs-JWT des Benutzers, dasselbe, das die App verwendet. Nützlich, wenn Sie Anonimatum in eine Anwendung mit Politeia-Anmeldung einbetten.

Isolierung

Eine Ressource einer anderen Gruppe liefert 404, nie 403: Die API verrät nicht, ob sie existiert.

Widerruf

Widerrufen Sie einen Schlüssel unter Profil → API-Schlüssel; er funktioniert ab sofort nicht mehr. Legen Sie Schlüssel niemals im Code oder in Repositories ab.

Limits

Technische Limits in Version 1.9.0 (pro IP-Adresse oder pro Anfrage):

Jeder Vorgang zieht außerdem Seiten oder Dokumente vom Tarif der Gruppe ab. Prüfen Sie den Verbrauch mit GET /api/public/usage/current und /usage/remaining oder validieren Sie vorab mit POST /usage/validate-operation.

Fehler

Fehler verwenden das Standardformat { errorCode, message, status }. Die häufigsten:

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
}

Verzweigen Sie anhand von errorCode, nicht anhand des Meldungstexts, der sich ändern oder übersetzt werden kann.

Webhooks

Ein Webhook benachrichtigt Ihr System per signiertem JSON-POST, wenn ein Batch aus der Warteschlange oder eine Veröffentlichung abgeschlossen ist. Die Benachrichtigung enthält niemals Dateinamen, Titel, Text oder E-Mail-Adressen: nur Kennungen, Status und bei Batches einen Download-Link, den Sie mit Ihrem API-Schlüssel verwenden.

Ereignisse

Registrierung mit Ihrem API-Schlüssel

POST /api/public/webhooks gibt das Secret (whsec_…) nur einmal zurück; speichern Sie es als Umgebungsvariable. Ein mit einem API-Schlüssel erstellter Webhook erhält nur die Ereignisse des Benutzers dieses Schlüssels; der Gruppenadministrator kann gruppenweite Webhooks im App-Panel anlegen. Außerdem: GET, PUT und DELETE /{id}, POST /{id}/rotate-secret, POST /{id}/test und GET /{id}/deliveries. Bis zu 10 pro Gruppe; die URL muss https verwenden.

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"]}'

Signatur prüfen

Jede Benachrichtigung enthält den Header X-Anonimatum-Signature: t=<unix>,v1=<hex>, wobei v1 ein HMAC-SHA256 mit dem vollständigen Secret (einschließlich des Präfixes whsec_) als Schlüssel über „t.body“ ist. Außerdem werden X-Anonimatum-Event, X-Anonimatum-Event-Id und X-Anonimatum-Delivery gesendet.

1. Lesen Sie den Roh-Body, ohne das JSON zu parsen oder neu zu formatieren.
2. Trennen Sie t und v1 aus dem Header und lehnen Sie die Benachrichtigung ab, wenn t mehr als 300 Sekunden von Ihrer Uhr abweicht.
3. Berechnen Sie HMAC-SHA256(secret, t + "." + body) als Hex und vergleichen Sie es in konstanter Zeit mit v1.
4. Deduplizieren Sie anhand von X-Anonimatum-Event-Id: Ein Wiederholungsversuch trägt dieselbe ID.
5. Antworten Sie innerhalb von 5 Sekunden mit 2xx und verarbeiten Sie danach.

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

Jede Antwort außer 2xx (Weiterleitungen werden nicht verfolgt) oder eine Antwort, die länger als 5 Sekunden dauert, gilt als Fehlschlag. Nach dem ersten Versuch erfolgen Wiederholungen nach 1 Min., 5 Min., 30 Min., 2 Std. und 6 Std. (insgesamt 6 Versuche); das Zustellprotokoll zeigt Status, HTTP-Code und nächsten Versuch.

Wenn Sie keinen Endpunkt bereitstellen möchten, fragen Sie den Batch-Status mit GET /api/public/batch-jobs ab und laden Sie abgeschlossene Jobs mit GET /api/public/batch-jobs/{id}/output herunter.

MCP-Connector für KI-Assistenten

Anonimatum stellt dieselbe API als MCP-Server (Model Context Protocol) bereit. Der Assistent handelt als Ihr Benutzer und Ihre Gruppe, nachdem Sie ihn in der App autorisiert haben.

URL des MCP-Servers

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

Claude

Fügen Sie unter claude.ai → Einstellungen → Connectors einen benutzerdefinierten Connector mit der MCP-URL hinzu und autorisieren Sie den Zugriff auf dem Zustimmungsbildschirm von Anonimatum.

ChatGPT

Fügen Sie unter chatgpt.com → Einstellungen → Connectors die MCP-URL hinzu und schließen Sie die OAuth-Autorisierung ab. Die Verfügbarkeit benutzerdefinierter Connectors hängt von Ihrem ChatGPT-Tarif ab.

Grok

Fügen Sie unter grok.com → Connectors die MCP-URL hinzu und autorisieren Sie den Zugriff.

Cursor, Claude Code und andere MCP-Clients

Unterstützt der Client OAuth mit lokaler Weiterleitung, genügt die URL. Andernfalls nutzen Sie die manuelle Freigabe in der App (Profil → Connectors): Sie erhalten ein Token und eine einfügefertige mcp.json.

Bereitgestellte Tools

• listar_operaciones — Listet die für Ihren Benutzer verfügbaren Vorgänge auf (gleicher Katalog wie die Referenz, ohne Admin- oder interne Endpunkte).
• describir_operacion — Methode, Pfad, Parameter und Art der Dateiübermittlung für einen Vorgang.
• ejecutar_operacion — Führt einen Vorgang aus; binäre Antworten enthalten einen einmalig nutzbaren Download-Link.
• iniciar_subida_fichero — Liefert eine einmalig nutzbare Upload-URL, empfohlen für große Dokumente (bis 250 MB).
• subir_fichero — Lädt eine kleine Datei als Base64 in einem einzigen Aufruf hoch.
• iniciar_subida_por_partes / subir_parte_fichero — Upload in Teilen für Clients, die keinen direkten POST ausführen können.

Irreversible Vorgänge (Löschen, De-Anonymisieren) erfordern die ausdrückliche Bestätigung des Benutzers im selben Schritt. Bei abgelaufenem Tarif erhält der Assistent PLAN_EXPIRED und muss die Meldung ohne erneuten Versuch weitergeben. Jede Verbindung können Sie unter Profil → Connectors widerrufen.

Beispiel für mcp.json (manuelle Freigabe)

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

SDK

Zugang auf Anfrage

Offizielle SDKs für Python (synchron und asyncio) und TypeScript/JavaScript (Node 18+), basierend auf genau dieser Referenz. Das Repository ist privat: Fordern Sie den Zugang bei Politeia über das Kontaktformular an. Sie können auch einen Client aus der OpenAPI-Datei generieren.

SDK-Repository (privat)