---
title: "O edge e as células"
description: "Onde vivem os dados do seu workspace, o que o edge faz com cada requisição e por que seu código nunca escolhe região."
version: "pt-br"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# O edge e as células

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

```mermaid
flowchart LR
  S[Seu servidor] -- "sk_agents_live_co1_…" --> E[Edge]
  E -- "token de 10 s" --> C1[(Célula co1<br/>api)]
  E -.-> C2[(Célula us1)]
  E -.-> C3[(Célula br1)]
```

1. **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, com `401 api_key_malformed`, sem chegar a nenhum
   servidor.
2. **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 de `app.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 responde `308` para a mesma página em
   `app.qomni.ai/acme/agents/…`.
3. **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.
4. **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](/pt-br/concepts/errors/) 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:
  responde `404 api_host_moved` com 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](/pt-br/concepts/authentication/): o que leva cada parte da chave.
- [Erros](/pt-br/concepts/errors/): o que fazer com cada código.
- [Idempotência e novas tentativas](/pt-br/concepts/idempotency/): como repetir um `origin_unavailable` sem criar duas vezes.

Source: https://docs.qomni.ai/pt-br/concepts/edge/index.mdx
