Referência da API da plataforma v1
Gestão (desenvolvedor, equipe Grix e área da loja) e protocolo (aplicação externa). O desenvolvedor publica suas próprias aplicações; a equipe mantém as rotas administrativas; só o dono gerencia a conexão da empresa. Segredos nunca voltam nas respostas — só a dica (últimos 4 caracteres) da credencial instalada.
Esta referência cobre a direção Grix → seu sistema (a plataforma de integrações). A direção oposta, seu sistema → Grix — API pública v1 com chaves por empresa, catálogo, pedidos, eventos, avisos assinados e MCP da área da loja — está em api-publica-v1.md, publicada em /desenvolvedores/documentacao/api-publica (OpenAPI em /desenvolvedores/documentacao/api-v1).
Área pública do desenvolvedor
Interface em /desenvolvedores/. A sessão usa o cookie HttpOnly grix_desenvolvedor_token, SameSite=Lax. Todas as escritas exigem o par cookie grix_csrf e header X-GRIX-CSRF, obtido por GET /api/csrf. Token de sessão e credenciais de sandbox não são devolvidos no JSON.
| Método e rota | Entrada | Resultado |
|---|---|---|
POST /api/desenvolvedores/cadastro | nome, fornecedor, email, senha | Conta, fornecedor próprio e cookie de sessão |
POST /api/desenvolvedores/entrar | email, senha | Sessão com a conta existente |
GET /api/desenvolvedores/eu | — | Usuário e fornecedor vinculado, se houver |
POST /api/desenvolvedores/fornecedor | nome | Adesão de uma conta existente como fornecedor |
POST /api/desenvolvedores/sair | {} | Revogação da sessão |
GET /api/desenvolvedores/aplicacoes | — | Somente aplicações e versões do próprio fornecedor |
POST /api/desenvolvedores/aplicacoes | slug, nome, descricao? | Nova aplicação do fornecedor autenticado |
POST /api/desenvolvedores/aplicacoes/{id}/publicar | url_base, segredo_teste_a, segredo_teste_b | Conformidade e publicação da versão verificada |
Na publicação, o Grix obtém a descrição na origem; o cliente não envia um resultado de teste nem uma aprovação. A descrição precisa corresponder ao slug da aplicação e as ferramentas usam esse prefixo (até 64 caracteres). As duas credenciais são distintas e usadas somente na conformidade. Pode haver escrita nas contas de teste, conforme as ferramentas declaradas. teste_entrada opcional fornece parâmetros específicos de sandbox por ferramenta. O sucesso grava a evidência automática de sandbox e a URL da versão.
Erros: 400 JSON inválido, 401 sessão inválida, 403 CSRF inválido, 404 aplicação inexistente ou alheia, 409 identificador/versão já usado, 413 corpo acima de 32 KB, 422 contrato/conformidade inválido, 429 limite. Conformidade reprovada retorna publicada: false e as checagens. Versão publicada é imutável; uma correção exige versão nova.
Gestão
| Ação | Entrada | Saída |
|---|---|---|
| Criar fornecedor | nome, email_contato? | id |
| Criar aplicação | fornecedor_id, slug, nome, descricao? | id |
| Publicar versão | aplicacao_id, descrição do GET descricao | id, compat_hash |
| Publicar versão remota | aplicacao_id, url_base, segredo? | id, compat_hash |
| Criar instalação | empresa_id, aplicacao_id, versao_id | id (rascunho) |
| Autorizar conta | segredo, config? | aguardando_autorizacao |
| Testar conexão | — | ok, por_capacidade[] |
| Ativar | capacidades[], origem_comercial? | ativa |
| Pausar / reautorizar / desconectar | — / segredo / — | novo estado |
| Estado da instalação | — | estado, dica, último teste, operações abertas |
| Consultar operação | — | estado, tentativas, latência, erro (sem payload) |
| Listar eventos | depois (cursor), limite | eventos após o cursor |
| Extrato | desde? | totais por dimensão |
Erros: 422 regra da plataforma (mensagem útil), 409 conexão duplicada, 404 desconhecido, 401 assinatura do webhook inválida.
Protocolo (sua aplicação expõe)
GET /integracao/v1/descricao→{protocolo: "1.0", contrato: 1, aplicacao, versao, ferramentas[], conhecimento[]?, apresentacoes[]?}POST /integracao/v1/testar→{ok, por_capacidade: [{ferramenta, capacidade, ok, mensagem}]}(sem efeito comercial)POST /integracao/v1/ferramentas/{id}/executarrecebe{entrada, chave, principal, conversa_id}e devolve{estado, resultado?, erro?, mensagem?, referencia_externa?}GET /integracao/v1/operacoes?ref=→ estado atual da operação em processamento- Eventos da origem para o Grix:
POST /api/integracoes/instalacoes/{id}/eventoscom{tipo, id, recurso_ref, versao, correlacao?}; assine o corpo com oevento_segredoda instalação (sha256=+ HMAC-SHA256)
Códigos de erro: entrada_invalida, nao_encontrado, permissao_negada, credencial_invalida (derruba a conexão para com_erro), limite_excedido, origem_indisponivel, tempo_esgotado, conflito, erro_interno. Os três últimos de transporte autorizam nova tentativa com a mesma chave.
Homologação, roteiros, diagnóstico e limites
| Ação | Entrada | Saída |
|---|---|---|
| Registrar homologação | aplicacao_id, versao, ambiente, capacidades[], responsavel, evidencias | id |
| Roteiro de publicação | aplicacao_id, descricao? | passos com o que falta |
| Roteiro de ativação | instalacao_id | passos com o que falta |
| Diagnóstico | instalacao_id | estado, abertas, eventos, consumo, alertas (sem segredos) |
Sem evidência de homologação, a ativação recusa com a lista do que falta. Tetos padrão: 1000 operações/dia e 100 escritas/dia por instalação (config.limites sobrescreve); acima do teto, negada com motivo. Retenção: medição 400 dias, eventos processados 180 dias.
Área da loja (controles do dono)
Catálogo de aplicações, estado da conexão, última verificação, dados pendentes, operações em andamento, situações que precisam de uma pessoa, consumo por dimensão e controles para pausar, reautorizar ou desconectar. Tudo pelos endpoints de gestão acima, montados pela descrição da aplicação: aplicação nova não exige tela nova. A conversa continua no formato do Grix — tela cheia, conversa e painel, com a loja chamando o painel de "tela".
O catálogo de aplicações da loja informa versao_id, versao, endereço e declarações das ferramentas. A interface usa esses dados automaticamente. Ao criar uma instalação, versao_id pode ser omitido para usar a versão publicada mais recente; uma versão de outra aplicação é recusada. Os testes e a autorização remotos usam contexto de empresa sem transação de banco aberta durante a chamada HTTP.