Sección 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). 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). |
| 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
nullen sutype. - 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, noerror. - Respuestas revisadas a ojo: sin identificadores internos ni campos administrativos, ≤ 3.000 caracteres.
- Solo los seis
error_typede la página 06. - Búsquedas respetan el
limitrecibido y devuelventotal,limityoffset. - Nombres ≤ 40 caracteres y descripciones ≤ 700.
- Cada herramienta declara
com.asixto/capabilityocapabilities(claves válidas) ycom.asixto/verb. - Cada dominio devuelve sus campos mínimos (página 04).
- 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 | 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 | 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 | Requiere provocar un fallo transitorio en su dependencia. |
| Rotación con dos credenciales activas | 03 | Es un procedimiento operativo suyo. |
| Límites propios por credencial y comprobación de salud | 07 | Se verifican en la incorporación, no en cada ejecución. |
| Disponibilidad ≥ 99,5% | 07 | 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 · 02 | 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 |