Os dados de cada workspace vivem em uma célula: uma cópia completa da
plataforma em uma região (us1 nos Estados Unidos, co1 na Colômbia, br1
no Brasil). Na frente de todas as células há um único ponto de entrada, o
edge, que recebe cada requisição e a leva à célula correta.
Para você isso significa uma coisa: a API vive em um único host,
api.qomni.ai, com o produto e a versão na rota
(https://api.qomni.ai/agents/v1), e a URL nunca leva região. Seu código é
o mesmo para um cliente em Bogotá e para um em São Paulo.
O app web também tem um único host, app.qomni.ai: o portal e a página
de cada produto dentro de cada workspace, em
app.qomni.ai/{workspace}/{producto} (por exemplo app.qomni.ai/acme/agents).
Os endereços antigos de cada produto (agents.qomni.ai/acme…) redirecionam
para lá.
Por que existem células
Gravações e transcrições de chamadas têm regras legais diferentes em cada país. Guardar os dados de um workspace no próprio país torna mais simples cumpri-las e mais curto o caminho de cada requisição. A alternativa, um único banco de dados para o mundo todo, obrigaria a escolher um país para todos.
A Qomni escolheu não passar essa decisão para o seu código. Por isso a célula vai dentro
da chave de API (sk_agents_live_co1_…) e o edge a lê de lá. Não há um
parâmetro de região, nem um host por país, nem nada que você possa configurar errado.
O percurso de uma requisição
- O edge identifica a requisição. Lê o prefixo da chave
(
sk_<product>_<mode>_<cell>_…) e verifica o checksum. Uma chave copiada errado é rejeitada aqui, com401 api_key_malformed, sem chegar a nenhum servidor. - Encontra a célula. Com uma chave de API, a célula está na chave.
No app web, uma página de produto (
app.qomni.ai/{workspace}/{producto}/…) vai para a célula do workspace da sua rota; o resto deapp.qomni.ai(seus workspaces, as configurações, o login) não vive em nenhuma célula. Um endereço antigo de produto (agents.qomni.ai/acme/…) não chega a nenhuma célula: o edge responde308para a mesma página emapp.qomni.ai/acme/agents/…. - Assina um token de edge. Vale 10 segundos, serve para uma única requisição e fica ligado ao host público, à célula e ao seu endereço IP.
- Reenvia a requisição ao serviço dessa célula que atende a rota, com a rota tal como está. Qual é esse serviço não se vê de fora. A origem só aceita requisições que tragam o token: ninguém pode pular o edge chamando uma origem diretamente.
A resposta traz o header X-Request-Id. Guarde-o nos seus logs: é o que o
suporte usa para encontrar sua requisição.
Erros do edge
Têm a mesma forma que os erros da API.
| Código | Quando |
|---|---|
api_key_missing, api_key_malformed |
Falta o header Authorization, ou a chave não tem a forma ou o checksum esperados. |
realtime_session_invalid |
A sessão do WebSocket não existe ou expirou. Vale 60 segundos. |
origin_unavailable |
A célula não respondeu. Nada foi feito: tente de novo com backoff. |
unknown_api |
404: o primeiro segmento da rota em api.qomni.ai não nomeia nenhuma API (/payroll/v1/…). |
api_host_moved |
404: o host é o endereço antigo da API (agents-api.qomni.ai). Use https://api.qomni.ai/agents/v1. |
not_found, method_not_allowed |
A rota ou o método não existem nessa API. |
product_host_moved |
410: um método diferente de GET ou HEAD no endereço antigo de um produto (agents.qomni.ai). Envie a requisição para app.qomni.ai/{workspace}/{producto}. |
host_moved |
404: o host é o endereço antigo de um produto, que já não serve páginas. |
Limites
- Seu código nunca escolhe a célula. Não há parâmetro, host nem header para isso.
- O endereço antigo da API (
agents-api.qomni.ai) não redireciona: responde404 api_host_movedcom a nova URL base. - Uma chave só vale na célula dela. Usá-la em outra responde
421 wrong_cell. Na prática isso não acontece: a célula da chave é a do workspace que a criou. - Os dados não se movem entre células. Um workspace nasce em uma célula e fica lá.
- O edge não guarda nem lê seus dados: só roteia e assina.
Veja também
- API keys e autenticação: o que leva cada parte da chave.
- Erros: o que fazer com cada código.
- Idempotência e novas tentativas: como repetir um
origin_unavailablesem criar duas vezes.