For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/mobile/api.md (or send Accept: text/markdown).
API mobile
Como a app fala com o servidor — sessões, alcançabilidade e payloads.
Passo a passo para iniciantes
Pré-requisitos: Leia os dois guias para iniciantes abaixo e conclua a configuração local do celular. Coloque os valores Expo em apps/mobile/.env.local; defina EXPO_PUBLIC_API_URL como um host de back-end que seu dispositivo pode alcançar. Um checkout somente para celular não tem back-end da web, então inicie ou conecte um separadamente. Uma exportação Expo bem-sucedida prova o pacote JavaScript, não a aceitação do dispositivo ou da compra.
Termos rápidos: um espaço de trabalho consiste em usuários, dados e configurações separados de uma equipe. O servidor é o back-end confiável; mantenha as chaves do provedor fora do navegador e do código do telefone. Uma migração é uma alteração de versão do banco de dados que cria ou atualiza tabelas. Um modelo de IA é o mecanismo que responde; o catálogo de modelos é a lista do servidor de IDs e preços de modelos disponíveis. Um provedor é um serviço externo, como IA, e-mail ou serviço de cobrança. Um direito é uma concessão que permite que um espaço de trabalho use um recurso. Um webhook é uma mensagem que um serviço envia para o URL de outro serviço.
1. Em apps/mobile/.env.local, defina EXPO_PUBLIC_API_URL como o endereço de backend em execução acessível pelo seu telefone; não use localhost de um dispositivo físico.
2. Siga a configuração local do Mobile para iniciar o Expo, fazer login e abrir a área de trabalho, configurações e telas de bate-papo.
3. Espere dados autenticados do mesmo espaço de trabalho. Se as solicitações expirarem, verifique a rede do telefone e do computador e inicie o back-end separadamente em uma finalização de compra somente para dispositivos móveis.
Para código personalizado, comece com o prompts/README.md fornecido e copie o prompt mais próximo: prompts/new-app-screen.md para uma tela de aplicativo ou prompts/new-landing-page.md para uma página pública. Para trabalho de servidor, banco de dados ou provedor, dê ao seu agente de codificação a tarefa deste guia e peça-lhe para ler AGENTS.md, .ai/PROJECT_CONTEXT.md e espelhos .ai/ correspondentes; inspecione os arquivos de origem exatos nomeados aqui; listar arquivos e verificações antes de editar; preservar a propriedade do espaço de trabalho e os segredos apenas do servidor; e mostrar a diferença. Informe o comportamento desejado, campos de entrada e saída, funções permitidas, sucessos e erros esperados e a conta de teste, provedor ou dispositivo. Use valores de amostra; nunca cole um segredo real.
Entenda o escopo nativo
Expo inclui autenticação/sessão nativa e links diretos junto com espaço de trabalho, configurações, bate-papo e superfícies de compra RevenueCat. O comportamento comercial compartilhado e a autorização permanecem no back-end/pacotes da web; clientes nativos em apps/mobile/src chamam essas APIs sem incorporar credenciais de provedor.
Use o BFF autenticado por sessão
As rotas /api/mobile cobrem direitos, disponibilidade de compra RevenueCat e sincronização de servidor, organização, membros, convites, auditoria, chaves API, webhooks, domínios, programações e solicitações de recursos. Eles preservam a propriedade do espaço de trabalho e as verificações de funções. Eles são diferentes do contrato público sk_ de chave de portador /api/v1.
Use seu EXPO_PUBLIC_API_URL acessível por dispositivo e a origem/esquema configurado; variáveis públicas Expo nunca contêm credenciais de provedor.
Verifique em destinos nativos
Verifique estados de carregamento/erro/vazio, reconecte, sessão expirada, ações de gerenciamento proibidas e retornos de link direto no dispositivo/construção que você pretende oferecer suporte. Uma exportação Expo prova agrupamento, não entrega nativa ou aceitação de compra.
Instalação e configuração
A app chama a API em /api/mobile e a superfície versionada /api/v1 com a sessão do membro em vez de suposições de cookies da web app. EXPO_PUBLIC_API_URL é a única origem que o cliente conhece; é pública por design e não transporta secrets.
Os tokens de sessão vêm do fluxo Better Auth Expo e ficam guardados no armazenamento seguro nativo — nunca em AsyncStorage em claro nem em configuração embebida no bundle.
GET /api/mobile/entitlement # access state for the member
GET /api/mobile/organization # active workspace context
GET /api/mobile/usage # current-month AI spend, meter caps, and credit balance
GET /api/mobile/appearance # synced appearance bundle (GET/PUT)
POST /api/v1/ai-tasks # authorized work, same as web
Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=Fluxo de implementação
Resolve a sessão armazenada antes do primeiro pedido autenticado, atualiza-a quando o servidor reporta expiração e termina sessão limpamente quando é revogada. Trata API inalcançável e sessão inválida como estados diferentes — um tenta de novo, o outro volta ao acesso.
Mantém os payloads idênticos ao contrato web: o servidor aplica as mesmas regras de workspace, entitlement e validação independentemente de qual cliente chamou.
Verificação e resolução de problemas
Testa falhas em modo avião, tokens expirados a meio da sessão, sessões revogadas e um arranque a frio com um token válido armazenado. Um pedido que falha fechado (negado) está correto; um que falha aberto é um bug a corrigir antes do release.