# 08 · Certificación

Esta página lista las comprobaciones que su servidor debe pasar antes de entrar en producción y en
qué orden ocurre cada fase. El modelo de incorporación es sin revisión manual de su código: usted
registra el servidor, una batería determinista lo evalúa y recibe el mismo informe que vemos
nosotros.

> **Primeros clientes.** La incorporación es **asistida**: estas mismas comprobaciones se acuerdan y
> se ejecutan junto a su equipo. La lista de abajo no cambia por eso: es el criterio de aceptación, y
> conviene que la use como su propia lista de pruebas desde el primer día.

## Fases

| # | Fase | Qué ocurre |
|---|---|---|
| 1 | **Registro** | Se dan de alta la URL de su servidor, la credencial y la URL de su entorno de pruebas. Eso es todo: no se declaran endpoints ni esquemas, y el catálogo no se configura en ningún panel: cada herramienta llega ya clasificada por el `_meta` de su definición ([página 02](./02-tool-contract.md)). **Hoy ese alta la hace su contacto técnico con los datos que usted entrega**; la pantalla para hacerlo usted mismo, autenticado en la aplicación, llega con la etapa 2 ([README](./README.md)). |
| 2 | **Certificación** | La batería corre de inmediato contra su entorno de pruebas y devuelve un informe por comprobación. Sin aprobación no hay activación. |
| 3 | **Conversaciones de prueba** | Sus herramientas quedan disponibles para un agente de pruebas (chat y llamada) sin tráfico de clientes finales. |
| 4 | **Activación** | Se enciende escenario por escenario, con su nivel y sus interruptores por acción. Usted decide alcance y canales. |
| 5 | **Vigilancia** | La batería se repite de forma periódica y ante cada cambio de catálogo; una regresión desactiva la capacidad. Es la última pieza en entrar: hasta entonces, la vigilancia es por monitoreo de errores y aviso a su equipo. |

Las comprobaciones que escriben se ejecutan **solo** contra el entorno de pruebas declarado. La
batería nunca escribe en su producción.

## Comprobaciones

`Bloqueante` impide la activación. `Aviso` queda en el informe y no bloquea.

### Protocolo y transporte

| Comprobación | Criterio | Severidad |
|---|---|---|
| Descubrimiento y versión | `server/discover` responde y anuncia la revisión `2026-07-28` | Bloqueante |
| Catálogo válido | Todos los esquemas compilan y los nombres son únicos | Bloqueante |
| Esquemas cerrados | `additionalProperties: false` | Bloqueante |
| **Opcionales nullable** | Todo parámetro fuera de `required` admite `null` | Bloqueante |
| `required` mínimo | Sin campos exigidos que su sistema pueda resolver por defecto | Aviso |
| Nombres y longitudes | Nombre ≤ 40 y `^[a-z0-9_]+$`; `description` ≤ 700 | Bloqueante |
| Una operación por herramienta | Sin parámetro que multiplexe acciones | Bloqueante |
| Rechazo de entrada inválida | Fuera de esquema: error de contrato del SDK. Dentro de esquema pero inválida para el negocio: `error_type: "VALIDATION"`. En ningún caso un fallo del servidor | Bloqueante |
| Anotaciones coherentes | Una escritura no se declara de solo lectura | Bloqueante |
| **Clasificación presente** | Cada herramienta trae `com.asixto/capability` (o `capabilities` en plural) con claves válidas, y `com.asixto/verb` | Bloqueante |
| **Campos mínimos por dominio** | La respuesta trae lo exigido en la página 04 | Bloqueante |
| Orden estable del catálogo | Dos consultas, mismo orden | Aviso |
| Descripciones limpias | Sin instrucciones dirigidas al modelo | Aviso |

### Autenticación

| Comprobación | Criterio | Severidad |
|---|---|---|
| Sin credencial | 401 con `WWW-Authenticate` | Bloqueante |
| Credencial inválida o caducada | 401, no 500 | Bloqueante |
| Audiencia ajena | Rechazada | Bloqueante |
| Metadatos de recurso protegido (RFC 9728) | Publicados y coherentes. Aviso porque el nivel 2 (token rotable) no los requiere | Aviso |
| TLS | Certificado válido y vigente | Bloqueante |

### Garantías de negocio

| Comprobación | Criterio | Severidad |
|---|---|---|
| Idempotencia | Misma clave de `_meta` dos veces, un solo efecto | Bloqueante |
| Propiedad del registro | Identificador ajeno → `PERMISSION` | Bloqueante |
| Estado terminal | Transición inválida → `VALIDATION` con el estado actual | Bloqueante |
| Dato crítico | Franja ocupada y monto alterado rechazados | Bloqueante |
| Fuga de datos | Sin identificadores internos, datos de terceros ni trazas | Bloqueante |
| Forma del error | `error_type` de los seis canónicos + `user_message` | Bloqueante |
| **Sin resultados = éxito** | Búsqueda vacía devuelve lista vacía y `total: 0`, no `error` | Bloqueante |
| Vacío vs caído vs inexistente | Tres respuestas distinguibles | Bloqueante |

### Rendimiento

| Comprobación | Criterio | Severidad |
|---|---|---|
| Latencia p95 | ≤ 2 s sobre la muestra de la batería | Aviso |
| Tiempo de espera | Ninguna llamada supera 30 s | Bloqueante |
| Tamaño de respuesta | ≤ 3.000 caracteres | Bloqueante |
| Paginación | Búsquedas con `limit`, `offset` y `total`, respetando el `limit` recibido | Bloqueante |
| Forma para voz | Sin URLs ni correos; ≤ 3 elementos; fecha ISO + pronunciable | Bloqueante |

## Autoevaluación previa

Antes de registrar, verifique por su cuenta. Ahorra una vuelta completa:

- [ ] Cada herramienta probada con el Inspector y con un test automatizado.
- [ ] Esquemas cerrados en todas.
- [ ] 401 correcto sin credencial y con credencial inválida.
- [ ] Todo parámetro opcional acepta `null` en su `type`.
- [ ] Escritura invocada dos veces con la misma clave de `_meta`: un solo efecto.
- [ ] Escritura invocada con un identificador de otro contacto: `PERMISSION`.
- [ ] Operación sobre una entidad en estado terminal: `VALIDATION`.
- [ ] Búsqueda sin resultados: **éxito** con lista vacía y `total: 0`, no `error`.
- [ ] Respuestas revisadas a ojo: sin identificadores internos ni campos administrativos, ≤ 3.000 caracteres.
- [ ] Solo los seis `error_type` de la [página 06](./06-errors.md).
- [ ] Búsquedas respetan el `limit` recibido y devuelven `total`, `limit` y `offset`.
- [ ] Nombres ≤ 40 caracteres y descripciones ≤ 700.
- [ ] Cada herramienta declara `com.asixto/capability` o `capabilities` (claves válidas) y `com.asixto/verb`.
- [ ] Cada dominio devuelve sus campos mínimos ([página 04](./04-capabilities.md)).
- [ ] Ningún token en sus logs.

## Requisitos que no se verifican desde fuera

Estos no aparecen arriba porque **ninguna batería puede comprobarlos** desde el exterior de su
sistema. Forman parte del criterio de aceptación igualmente, y se declaran en el registro:

| Requisito | Página | Por qué no es verificable desde fuera |
|---|---|---|
| TTL ≥ 7 días y escritura atómica del almacén de idempotencia | [05](./05-guarantees.md) | La batería solo observa dos llamadas seguidas; no ve su almacén ni espera una semana. |
| Consultar la clave de idempotencia **antes** de las guardas | [05](./05-guarantees.md) | Desde fuera, el orden correcto y el incorrecto se parecen hasta que ocurre un reintento real sobre una entidad ya modificada. |
| Guardar solo los éxitos | [05](./05-guarantees.md) | Requiere provocar un fallo transitorio en su dependencia. |
| Rotación con dos credenciales activas | [03](./03-authentication.md) | Es un procedimiento operativo suyo. |
| Límites propios por credencial y comprobación de salud | [07](./07-limits.md) | Se verifican en la incorporación, no en cada ejecución. |
| Disponibilidad ≥ 99,5% | [07](./07-limits.md) | Se mide en producción a lo largo del mes, no en una batería. |
| No exponer borrado duro ni campos que el titular no deba cambiar | [04](./04-capabilities.md) · [02](./02-tool-contract.md) | Se revisa al leer su catálogo, que es la única parte donde interviene una persona. |

Dicho de otro modo: la batería comprueba **la forma**; lo de esta tabla es **compromiso**, y es lo
que se revisa si algún día hay un incidente.

## Recertificación

| Cambio | Requiere |
|---|---|
| Herramienta nueva | Certificación de esa herramienta |
| Cambio de esquema de una herramienta existente | Recertificación de esa herramienta |
| Renombrar una herramienta | Certificación como nueva; la anterior se retira |
| Cambio de credencial o de URL | Nueva verificación de autenticación |
| Cambio interno sin efecto en el contrato | Nada. La vigilancia periódica lo cubre |