Qué resuelve
Documentación de API muestra el contrato OpenAPI destinado a integraciones del propio tenant.
La pantalla utiliza el spec curado de /api/v1/openapi.
Autenticación
Las llamadas de la API del tenant utilizan una API key en el header:
X-Api-Key
La key se genera desde Configuración → API.
Qué spec se muestra
La pantalla no utiliza el spec completo /api/openapi. Ese spec puede contener rutas administrativas internas de Structura y no debe exponerse a los comercios.
El Help debe mantener esta distinción explícita.
Swagger UI
La pantalla carga Swagger UI y habilita:
- navegación por endpoints;
- deep linking;
- Try it out;
- persistencia de autorización.
La UI está forzada a esquema visual claro para la documentación.
Flujo de integración
- Generar API key en Configuración → API.
- Abrir Documentación de API.
- Identificar el endpoint necesario.
- Autorizar con la API key.
- Probar primero en un contexto seguro.
- Implementar usando exactamente el contrato publicado.
Seguridad
La API key es credencial. No debe publicarse en frontend público, repositorios ni documentación compartida.
No compartas una key para que otro sistema administre rutas internas: el contrato de tenant es el límite de integración.
Diagnóstico
401/403: revisar API key y permisos del tenant.
Endpoint no aparece: puede no pertenecer al contrato público del tenant.
Try it out falla: separar autenticación, payload y estado del endpoint.
Se necesita una ruta admin: no usar la API pública del tenant para intentar acceder a ella.