Migrar desde claves

Tus claves de integración siguen funcionando igual. Mismos scopes, misma lista de IPs, misma caducidad, mismo límite de peticiones por clave. No tienes que cambiar nada, y los interruptores de los agentes (pausar todos, el de la plataforma) no las afectan.

Lo que una clave de integración no puede hacer es usar los endpoints de datos: KPIs, listados y reportes responden 403 agent_required.

Por qué pasarla a un agente

• Datos: el mismo sistema puede leer KPIs, compras, gastos o contactos con los permisos que le des.
• Autor: lo que emite queda firmado por el agente en el historial de cambios, no por una clave anónima.
• Control: topes de importe y de comprobantes por día, autonomía por acción, pausa automática y puntuación de seguridad.
• Responsable: siempre hay una persona que responde por la integración, y si se va del negocio el agente se suspende en vez de seguir funcionando sin dueño.

Cada scope, en permisos

Scope	Módulo · nivel en el agente	Autonomía que hace falta
invoices:read	ventas.facturas · Ver	—
invoices:write	ventas.facturas · Operar	invoice.issue y document.send_email en automático
documents:read	ventas.notas, ventas.guias, compras.retenciones, compras.facturas · Ver	—
documents:write	Los mismos cuatro · Operar	document.issue y document.send_email en automático
contacts:write	contactos · Operar	—
catalog:read	catalogo.productos · Ver	—

Las liquidaciones de compra cuelgan de compras.facturas; las retenciones, de compras.retenciones.

Paso a paso

1. Crea un agente con la plantilla Integración ERP. Ya trae Operar en facturas, notas, guías, retenciones, facturas de proveedor y contactos, emisión y correos en automático y un tope de 500 comprobantes al día. Ver Crear un agente.

2. Ajústalo a lo que hacía la clave. Compara con la tabla de arriba: si la clave solo tenía invoices:write e invoices:read, baja los demás módulos a Ver o a Ninguno. Baja también lo que el ERP no lee (la plantilla parte de Solo lectura). Prohíbe los cobros y los pagos: una integración no los usa.

3. Pon topes. Un importe máximo por comprobante que tenga sentido para tu negocio corta de raíz un error de tu ERP que facture 10.000 USD por 100.

4. Crea la clave del agente con las mismas IPs que la clave vieja.

5. Añade Idempotency-Key a cada emisión si tu ERP no la enviaba: para un agente es obligatoria.

6. Despliega y comprueba. GET /me debe devolver el bloque agente. Emite una factura y mira en Olympus que aparece con el agente como autor.

7. Revoca la clave de integración desde Configuración → Integraciones.

Qué cambia en tu código

Antes	Con el agente
403 insufficient_scope, con details.required	403 insufficient_permissions, con details.modulo y details.nivel
—	403 agent_action_requires_approval o agent_action_forbidden si la autonomía no deja emitir
—	429 agent_limit_exceeded al pasar un tope del día
—	403 agent_paused, agents_paused, agent_suspended y 503 agents_disabled
Idempotency-Key opcional	Obligatoria al emitir: sin ella, 400 idempotency_key_required
Datos del comprador en claro	Enmascarados si el agente no tiene datos.personales (Integración ERP lo trae activado); sin él, tampoco hay PDF ni XML
GET /me → clave.scopes con los scopes	clave.scopes vacío; los permisos están en agente.permisos
Límite de peticiones por clave	Por agente, compartido por todas sus claves
Establecimiento por defecto de la clave	Las claves de agente no lo tienen: envía establecimiento en el payload o se usa el principal del negocio (o el de sus sucursales, si está limitado a algunas)
Cualquier sucursal	Solo las del agente: otra responde 403 branch_not_allowed al emitir y 404 al consultar
Crear clientes automáticamente, opción de la clave	Solo si el agente tiene contactos · Operar cuando se crea la clave
Caducidad opcional	90 días por defecto: planifica la rotación

Revisa el establecimiento antes de cambiar la clave

Si tu clave de integración tenía un establecimiento y un punto de emisión por defecto distintos de los del negocio y tu payload no los envía, con la clave del agente las facturas saldrían con otra numeración. Añade establecimiento al payload antes de cambiar de clave. Ver Establecimientos y secuenciales.

Lo demás no cambia: el formato de los payloads y de las respuestas, Idempotency-Key, referencia_externa, los estados y los errores de validación son los mismos.

Lo siguiente

• Autonomía y límites: los topes que conviene poner a una integración.
• Seguridad: lista de IPs y rotación.