Integra Anonimatum nei tuoi sistemi

Guida rapida

Tre passaggi: crea la chiave API, verificala e anonimizza il tuo primo documento.

1. Crea una chiave API nell'App: Profilo → Chiavi API → «Genera chiave API». Copiala subito: non verrà più mostrata. Se non vedi la sezione, il tuo piano non include l'accesso all'API oppure lo gestisce l'amministratore del tuo gruppo.
2. Salvala come variabile d'ambiente e verifica il piano del tuo gruppo con GET /api/public/plan.
3. Invia il documento a POST /api/public/ai/anonymize con le opzioni di IA che ti servono. La risposta è il documento anonimizzato nel suo formato originale.

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

I parametri degli endpoint multipart si inviano come campi del modulo (-F). Il consumo viene scalato dal piano del gruppo a cui appartiene la chiave.

Autenticazione

X-API-Key

Header per le integrazioni machine-to-machine. Ogni chiave appartiene a un utente e a un gruppo: ne usa i permessi, il piano e la quota.

Authorization: Bearer

JWT della sessione utente, lo stesso che usa l'App. Utile se integri Anonimatum in un'applicazione con accesso tramite Politeia.

Isolamento

Una risorsa di un altro gruppo restituisce 404, mai 403: l'API non rivela se esiste.

Revoca

Revoca una chiave da Profilo → Chiavi API; smette di funzionare immediatamente. Non inserire mai le chiavi nel codice o nei repository.

Limiti

Limiti tecnici nella versione 1.9.0 (per indirizzo IP o per richiesta):

Ogni operazione scala inoltre pagine o documenti dal piano del gruppo. Controlla il consumo con GET /api/public/usage/current e /usage/remaining, oppure verifica in anticipo con POST /usage/validate-operation.

Errori

Gli errori usano il formato standard { errorCode, message, status }. I più comuni:

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
}

Gestisci i casi in base a errorCode, non al testo del messaggio, che può cambiare o essere tradotto.

Webhook

Un webhook avvisa il tuo sistema con un POST JSON firmato quando termina un batch in coda o una pubblicazione. La notifica non contiene mai nomi di file, titoli, testo o indirizzi email: solo identificativi, stati e, per i batch, un link di download da usare con la tua chiave API.

Eventi

Registralo con la tua chiave API

POST /api/public/webhooks restituisce il secret (whsec_…) una sola volta; salvalo come variabile d'ambiente. Un webhook creato con una chiave API riceve solo gli eventi dell'utente di quella chiave; l'amministratore del gruppo può creare webhook per tutto il gruppo dal pannello dell'App. Inoltre: GET, PUT e DELETE /{id}, POST /{id}/rotate-secret, POST /{id}/test e GET /{id}/deliveries. Fino a 10 per gruppo; l'URL deve essere 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"]}'

Verifica la firma

Ogni notifica contiene l'header X-Anonimatum-Signature: t=<unix>,v1=<hex>, dove v1 è un HMAC-SHA256 calcolato con il secret completo (compreso il prefisso whsec_) su «t.body». Vengono inviati anche X-Anonimatum-Event, X-Anonimatum-Event-Id e X-Anonimatum-Delivery.

1. Leggi il body grezzo, senza analizzare né riformattare il JSON.
2. Separa t e v1 dall'header e rifiuta la notifica se t si discosta di oltre 300 secondi dal tuo orologio.
3. Calcola HMAC-SHA256(secret, t + "." + body) in esadecimale e confrontalo con v1 in tempo costante.
4. Elimina i duplicati tramite X-Anonimatum-Event-Id: un nuovo tentativo ha lo stesso id.
5. Rispondi 2xx entro 5 secondi ed elabora in seguito.

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

Qualsiasi risposta non 2xx (i reindirizzamenti non vengono seguiti) o più lenta di 5 secondi conta come errore. Dopo il primo tentativo, i nuovi tentativi avvengono a 1 min, 5 min, 30 min, 2 h e 6 h (6 tentativi in totale); il registro delle consegne mostra lo stato, il codice HTTP e il tentativo successivo.

Se preferisci non esporre un endpoint, interroga lo stato dei batch con GET /api/public/batch-jobs e scarica i job completati con GET /api/public/batch-jobs/{id}/output.

Connettore MCP per assistenti IA

Anonimatum espone la stessa API come server MCP (Model Context Protocol). L'assistente agisce come il tuo utente e il tuo gruppo dopo che lo hai autorizzato nell'App.

URL del server MCP

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

Claude

Su claude.ai → Impostazioni → Connettori, aggiungi un connettore personalizzato con l'URL MCP e autorizza l'accesso nella schermata di consenso di Anonimatum.

ChatGPT

Su chatgpt.com → Impostazioni → Connettori, aggiungi l'URL MCP e completa l'autorizzazione OAuth. La disponibilità dei connettori personalizzati dipende dal tuo piano ChatGPT.

Grok

Su grok.com → Connettori, aggiungi l'URL MCP e autorizza l'accesso.

Cursor, Claude Code e altri client MCP

Se il client supporta OAuth con reindirizzamento locale, basta l'URL. Altrimenti usa l'autorizzazione manuale nell'App (Profilo → Connettori): ti fornisce un token e un mcp.json pronto da incollare.

Strumenti esposti

• listar_operaciones — Elenca le operazioni disponibili per il tuo utente (lo stesso catalogo del riferimento, senza endpoint di amministrazione o interni).
• describir_operacion — Metodo, percorso, parametri e modalità di invio dei file per un'operazione.
• ejecutar_operacion — Esegue un'operazione; le risposte binarie includono un link di download monouso.
• iniciar_subida_fichero — Restituisce un URL di caricamento monouso, consigliato per documenti di grandi dimensioni (fino a 250 MB).
• subir_fichero — Carica un file di piccole dimensioni in Base64 con una sola chiamata.
• iniciar_subida_por_partes / subir_parte_fichero — Caricamento a blocchi per i client che non possono eseguire un POST diretto.

Le operazioni irreversibili (eliminare, deanonimizzare) richiedono la conferma esplicita dell'utente in quel turno. Con un piano scaduto l'assistente riceve PLAN_EXPIRED e deve riportare il messaggio senza riprovare. Puoi revocare ogni connessione da Profilo → Connettori.

Esempio di mcp.json (autorizzazione manuale)

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

SDK

Accesso su richiesta

SDK ufficiali per Python (sincrono e asyncio) e TypeScript/JavaScript (Node 18+) basati su questo stesso riferimento. Il repository è privato: chiedi l'accesso a Politeia tramite il modulo di contatto. Puoi anche generare un client a partire dal file OpenAPI.

Repository dell'SDK (privato)