Integra Anonimatum en tus sistemas

Inicio rápido

Tres pasos: crear la API key, comprobarla y anonimizar el primer documento.

1. Crea una API key en la App: Perfil → API keys → «Generar API key». Copia la clave en ese momento: no se vuelve a mostrar. Si no ves la sección, tu plan no incluye acceso por API o la gestiona el administrador del grupo.
2. Guárdala como variable de entorno y comprueba el plan del grupo con GET /api/public/plan.
3. Envía el documento a POST /api/public/ai/anonymize con las opciones de IA que quieras. La respuesta es el documento anonimizado en su 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

Los parámetros de los endpoints multipart se envían como campos del formulario (-F). La cuota se descuenta del plan del grupo de la clave.

Autenticación

X-API-Key

Cabecera para integraciones máquina a máquina. Cada clave pertenece a un usuario y a un grupo: usa sus permisos, su plan y su cupo.

Authorization: Bearer

JWT de sesión de usuario, el mismo que usa la App. Útil si integras Anonimatum en una aplicación con inicio de sesión de Politeia.

Aislamiento

Un recurso de otro grupo responde 404, nunca 403: la API no revela si existe.

Revocación

Revoca una clave en Perfil → API keys; deja de funcionar de inmediato. No incluyas claves en el código ni en repositorios.

Límites

Límites técnicos vigentes en la versión 1.9.0 (por dirección IP o por petición):

Además, cada operación descuenta páginas o documentos del plan del grupo. Consulta el uso con GET /api/public/usage/current y /usage/remaining, o valida antes con POST /usage/validate-operation.

Errores

Los errores siguen el formato estándar { errorCode, message, status }. Los más habituales:

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
}

Decide por errorCode, no por el texto de message, que puede cambiar o traducirse.

Webhooks

Un webhook avisa a tu sistema con un POST JSON firmado cuando termina un lote de la cola o una publicación. El aviso nunca lleva nombres de fichero, títulos, textos ni correos: solo identificadores, estados y, en los lotes, un enlace de descarga que se usa con tu API key.

Eventos

Alta con tu API key

POST /api/public/webhooks devuelve el secreto (whsec_…) una sola vez; guárdalo como variable de entorno. Un webhook creado con una API key solo recibe los eventos del usuario de esa clave; el administrador del grupo puede crear webhooks para todo el grupo desde el panel de la App. También: GET, PUT y DELETE /{id}, POST /{id}/rotate-secret, POST /{id}/test y GET /{id}/deliveries. Máximo 10 por grupo; la URL debe 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"]}'

Verificar la firma

Cada aviso lleva la cabecera X-Anonimatum-Signature: t=<unix>,v1=<hex>, donde v1 es HMAC-SHA256 con el secreto completo (incluido el prefijo whsec_) sobre «t.cuerpo». También llegan X-Anonimatum-Event, X-Anonimatum-Event-Id y X-Anonimatum-Delivery.

1. Lee el cuerpo crudo, sin parsear ni reformatear el JSON.
2. Separa t y v1 de la cabecera y rechaza el aviso si t se aleja más de 300 segundos de tu reloj.
3. Calcula HMAC-SHA256(secreto, t + "." + cuerpo) en hexadecimal y compáralo con v1 en tiempo constante.
4. Deduplica por X-Anonimatum-Event-Id: un reintento trae el mismo id.
5. Responde 2xx en menos de 5 segundos y procesa después.

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

Cualquier respuesta que no sea 2xx (las redirecciones no se siguen) o que tarde más de 5 segundos cuenta como fallo. Tras el primer intento se reintenta a 1 min, 5 min, 30 min, 2 h y 6 h (6 intentos en total); el registro de entregas muestra el estado, el código HTTP y el siguiente intento.

Si prefieres no exponer un endpoint, consulta el estado de los lotes con GET /api/public/batch-jobs y descarga los terminados con GET /api/public/batch-jobs/{id}/output.

Conector MCP para asistentes de IA

Anonimatum expone la misma API como servidor MCP (Model Context Protocol). El asistente actúa con tu usuario y tu grupo, tras autorizarlo en la App.

URL del servidor MCP

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

Claude

En claude.ai → Configuración → Conectores, añade un conector personalizado con la URL MCP y autoriza el acceso en la pantalla de consentimiento de Anonimatum.

ChatGPT

En chatgpt.com → Configuración → Conectores, añade la URL MCP y completa la autorización OAuth. La disponibilidad de conectores personalizados depende de tu plan de ChatGPT.

Grok

En grok.com → Conectores, añade la URL MCP y autoriza el acceso.

Cursor, Claude Code y otros clientes MCP

Si el cliente admite OAuth con redirección local, basta con la URL. Si no, usa la concesión manual en la App (Perfil → Conectores): te da un token y un mcp.json listo para pegar.

Herramientas que expone

• listar_operaciones — Lista las operaciones disponibles para tu usuario (mismo catálogo que la referencia, sin administración ni endpoints internos).
• describir_operacion — Método, ruta, parámetros y cómo enviar ficheros a una operación.
• ejecutar_operacion — Ejecuta una operación; las respuestas binarias incluyen un enlace de descarga de un solo uso.
• iniciar_subida_fichero — Devuelve una URL de subida de un solo uso, recomendada para documentos grandes (hasta 250 MB).
• subir_fichero — Sube un fichero pequeño en Base64 en una sola llamada.
• iniciar_subida_por_partes / subir_parte_fichero — Subida por partes para clientes que no pueden hacer un POST directo.

Las operaciones irreversibles (borrar, desanonimizar) exigen confirmación explícita del usuario en ese turno. Con el plan expirado, el asistente recibe PLAN_EXPIRED y debe transmitir el mensaje sin reintentar. Puedes revocar cada conexión en Perfil → Conectores.

Ejemplo de mcp.json (concesión manual)

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

SDK

Acceso bajo petición

SDK oficiales para Python (síncrono y asyncio) y TypeScript/JavaScript (Node 18+) sobre esta misma referencia. El repositorio es privado: pide acceso a Politeia desde el formulario de contacto. También puedes generar un cliente a partir del OpenAPI.

Repositorio de los SDK (privado)