Los datos de cada workspace viven en una celda: una copia completa de la
plataforma en una región (us1 en Estados Unidos, co1 en Colombia, br1
en Brasil). Delante de todas las celdas hay un solo punto de entrada, el
edge, que recibe cada petición y la lleva a la celda correcta.
Para ti esto significa una cosa: la API vive en un único host,
api.qomni.ai, con el producto y la versión en la ruta
(https://api.qomni.ai/agents/v1), y la URL nunca lleva región. Tu código es
el mismo para un cliente en Bogotá y para uno en São Paulo.
La app web también tiene un único host, app.qomni.ai: el portal y la página
de cada producto dentro de cada workspace, en
app.qomni.ai/{workspace}/{producto} (por ejemplo app.qomni.ai/acme/agents).
Las direcciones antiguas de cada producto (agents.qomni.ai/acme…) redirigen
ahí.
Por qué hay celdas
Las grabaciones y transcripciones de llamadas tienen reglas legales distintas en cada país. Guardar los datos de un workspace en su propio país hace más simple cumplirlas y más corto el camino de cada petición. La alternativa, una sola base de datos para todo el mundo, obligaría a elegir un país para todos.
Qomni eligió no trasladar esa decisión a tu código. Por eso la celda va dentro
de la clave de API (sk_agents_live_co1_…) y el edge la lee de ahí. No hay un
parámetro de región, ni un host por país, ni nada que puedas configurar mal.
El recorrido de una petición
- El edge identifica la petición. Lee el prefijo de la clave
(
sk_<product>_<mode>_<cell>_…) y comprueba su checksum. Una clave mal copiada se rechaza aquí, con401 api_key_malformed, sin llegar a ningún servidor. - Encuentra la celda. Con una clave de API, la celda está en la clave.
En la app web, una página de producto (
app.qomni.ai/{workspace}/{producto}/…) va a la celda del workspace de su ruta; el resto deapp.qomni.ai(tus workspaces, los ajustes, el inicio de sesión) no vive en ninguna celda. Una dirección antigua de producto (agents.qomni.ai/acme/…) no llega a ninguna celda: el edge responde308hacia la misma página enapp.qomni.ai/acme/agents/…. - Firma un token de edge. Vale 10 segundos, sirve para una sola petición y va ligado al host público, a la celda y a tu dirección IP.
- Reenvía la petición al servicio de esa celda que sirve la ruta, con la ruta tal cual. Cuál es ese servicio no se ve desde fuera. El origen sólo acepta peticiones que traigan el token: nadie puede saltarse el edge llamando a un origen directamente.
La respuesta trae el header X-Request-Id. Guárdalo en tus logs: es lo que
soporte usa para encontrar tu petición.
Errores del edge
Tienen la misma forma que los errores de la API.
| Código | Cuándo |
|---|---|
api_key_missing, api_key_malformed |
Falta el header Authorization, o la clave no tiene la forma o el checksum esperados. |
realtime_session_invalid |
La sesión del WebSocket no existe o expiró. Vale 60 segundos. |
origin_unavailable |
La celda no respondió. No se hizo nada: reintenta con backoff. |
unknown_api |
404: el primer segmento de la ruta en api.qomni.ai no nombra ninguna API (/payroll/v1/…). |
api_host_moved |
404: el host es la dirección antigua de la API (agents-api.qomni.ai). Usa https://api.qomni.ai/agents/v1. |
not_found, method_not_allowed |
La ruta o el método no existen en esa API. |
product_host_moved |
410: un método distinto de GET o HEAD en la dirección antigua de un producto (agents.qomni.ai). Envía la petición a app.qomni.ai/{workspace}/{producto}. |
host_moved |
404: el host es la dirección antigua de un producto, que ya no sirve páginas. |
Límites
- Tu código nunca elige la celda. No hay parámetro, host ni header para eso.
- La dirección antigua de la API (
agents-api.qomni.ai) no redirige: responde404 api_host_movedcon la URL base nueva. - Una clave sólo vale en su celda. Usarla en otra responde
421 wrong_cell. En la práctica no ocurre: la celda de la clave es la del workspace que la creó. - Los datos no se mueven entre celdas. Un workspace nace en una celda y se queda ahí.
- El edge no guarda ni lee tus datos: sólo enruta y firma.
Ver también
- API keys y autenticación: qué lleva cada parte de la clave.
- Errores: qué hacer con cada código.
- Idempotencia y reintentos: cómo reintentar un
origin_unavailablesin crear dos veces.