Skip to main content
NovoUse a GYRA+ direto do Claude com o nosso conector MCP. Você entra com o seu próprio login, e o agente enxerga só o que você enxerga.Conectar →
Resumo: tudo o que liga o seu sistema ao nosso está em Configurações, API & MCP: você gera a credencial de API ali mesmo, cadastra webhooks e conecta o MCP. Não é mais preciso pedir credencial ao suporte.

Onde fica

Clique no logo da organização, no topo do menu lateral, e em API e MCP. Isso abre Configurações, aba API & MCP. A tela mostra, no topo, o endereço da API e o formato da autenticação, e em seguida três seções na ordem em que você precisa delas: credenciais, webhooks e MCP.
É área de administradores. As credenciais desta tela dão acesso aos dados da organização inteira; compartilhe com cuidado.

Chaves de API

Gerar uma credencial

1

Configurações, API & MCP

Na seção Credenciais de API, clique em criar.
2

Dar um nome reconhecível

Use algo que você reconheça na hora de revogar: backend-producao, n8n-homologacao, esteira-credito.
3

Copiar o par

A tela mostra o clientId e o clientSecret e só fecha quando você confirma que copiou.
O clientSecret aparece uma vez, na criação, e nunca mais: guardamos apenas o hash dele e não existe rota que o devolva. Ao fechar o painel, o valor é apagado da tela.Quem perdeu o segredo cria outra credencial e revoga a antiga, que é a operação certa de qualquer forma: um segredo que alguém precisou reler já esteve em algum lugar que não devia.

Revogar

A listagem mostra cada credencial com o clientId e a data de criação, e cada linha tem a ação de revogar. Revogar apaga a credencial dos dois lados: ela para de autenticar imediatamente.

Quantas você quiser

Uma por integração e por ambiente é o padrão saudável: dá para revogar a de homologação sem derrubar a produção.

Quem pode

Quem tem a permissão gerenciar configurações (Administrador, Owner, Superuser). O mesmo perfil que cadastra webhook.

Gerar token

O clientId + clientSecret são trocados por um token de acesso com validade de 24 horas. Seu backend precisa renovar o token antes de expirar.
O token é um JWT e carrega a claim aud com o valor toolbox. Se o seu sistema lê as claims do token, espere esse valor. Fora isso, trate o token como opaco: use-o só no cabeçalho Authorization.
Resposta:

Usar

Incluir o token em toda chamada HTTP:
Exemplo com curl:

Webhooks

Permitem que a GYRA+ notifique seu backend quando algo relevante acontece (relatório concluído, política avaliada, exportação gerada, decisão manual de analista), em vez de você ficar fazendo polling. Você configura webhooks pela tela, na mesma aba API & MCP, ou pela API. Na tela você escolhe a URL, marca os eventos por categoria, testa o endereço com um disparo real e gira o segredo quando precisar. O catálogo de eventos vem do backend, então evento novo aparece ali sozinho.
Existem duas famílias de eventos, e as duas aparecem na mesma lista:
  • Relatórios e crédito, documentada nesta página e em Criar Webhook;
  • Onboarding (cadastros e solicitações), com envelope e assinatura próprios, documentada em Eventos de webhook.

Tipos de evento

Cada webhook é registrado para um único tipo. Se você quer receber mais de um tipo, registre webhooks separados (mesma URL ou URLs diferentes).
Os webhooks da organização são copiados para o relatório na criação dele. Se você registrar um tipo novo depois, ele não dispara para relatórios que já existiam.

Configurar

Parâmetros:
  • type (obrigatório): um dos tipos da tabela acima.
  • url (obrigatório): endpoint HTTPS que vai receber o POST.
  • apiKey (opcional): se informado, a GYRA+ envia esse valor no header api-key de cada requisição, útil para o seu endpoint validar origem.

Estrutura do payload

Todo webhook entrega um POST com o formato:
O conteúdo de data varia por tipo: REPORT_FINISHED
REPORT (seção individual concluída)
Os dados da seção concluída vêm em content. REPORT_STATUS (decisão manual do analista)
REPORT_EXPORTED
Em caso de falha, exportUrl vem null e o payload inclui error. CREDIT_POLICY
COMMITTEE_FINISHED (deliberação do comitê concluída)
O payload é enxuto de propósito: decisão e síntese. Os votos individuais dos agentes e a auditoria ficam em GET /committee/deliberations/{reportId}, e a leitura combinada com os pareceres por seção em GET /report/{id}/insights. Se a deliberação falhar, status vem ERROR, decision não vem e o payload inclui error. OPERATION

Retry

A GYRA+ faz até 3 tentativas de entrega com backoff exponencial (1s, ~2s, ~5s). Se o seu endpoint retornar 429 com header Retry-After, a GYRA+ respeita o tempo antes de tentar de novo. Depois disso, o envio é descartado, planeje idempotência e fallback com polling em GET /v2/report/:id para eventuais perdas.

Boas práticas

  • Responda 2xx rapidamente e processe o payload de forma assíncrona na sua fila interna.
  • Use externalId no POST /v2/report para amarrar o webhook de volta ao seu pedido/cliente.
  • Escolha o tipo certo: REPORT_FINISHED para a maioria dos fluxos (uma entrega por relatório), REPORT só se você precisa reagir seção a seção.
  • Fallback com polling em GET /v2/report/:id caso o seu endpoint fique indisponível.

Conector de IA (MCP)

A terceira seção da tela liga o MCP da GYRA+ ao seu assistente. Ele não usa credencial de API: a autenticação é o seu próprio login da plataforma, com e-mail e senha ou Google. Ver Instalação do MCP.

Restringir acesso via SSO-only

Por padrão, SSO (Google e Microsoft) convive com login por senha. Se você quer forçar SSO-only na sua organização, entre em contato com atendimento@gyramais.com para habilitar essa configuração.

Perguntas frequentes

Não tem como recuperar: guardamos só o hash. Crie uma credencial nova em Configurações, API & MCP e revogue a antiga.
Sim, e é o recomendado: uma por integração e por ambiente (dev, homologação, produção). Você cria quantas precisar pelo painel, sem pedir a ninguém.
Não. Desde setembro de 2026 a credencial é gerada por você mesmo em Configurações, API & MCP. O suporte segue disponível para dúvidas, mas não é mais o caminho para obter a chave.
Webhook é push (GYRA+ te avisa quando o relatório fica pronto). Polling é pull (você consulta GET /v2/report/:id até concluir). Webhook é mais eficiente, mas exige endpoint público HTTPS.
Use ferramentas como webhook.site para capturar o POST, ou ngrok para expor o seu localhost.

Próximos passos

Webhooks (conceito)

Como a GYRA+ emite eventos ao longo do ciclo de vida.

Como Funciona a API

Arquitetura geral dos endpoints.

MCP da GYRA+

Usar as credenciais via agente de IA.

Onboarding

O módulo documental, e os eventos que ele emite.