Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.gyramais.com.br/llms.txt

Use this file to discover all available pages before exploring further.

Resumo: para integrar a GYRA+ com seu backend, você precisa de credenciais de API (clientId + clientSecret) e, opcionalmente, de webhooks para receber o resultado da análise sem polling. As credenciais são solicitadas via suporte; os webhooks são configurados pela própria API.

​
API Keys

​
Obter credenciais

Não existe tela de criação de API Keys no toolbox. Para obter credenciais de acesso à API, envie um e-mail para atendimento@gyramais.com informando:
  • Organização e ambiente de uso (produção, staging, etc.).
  • Nome reconhecível da integração (ex: backend-produção, n8n-staging).
A equipe retorna com o clientId e o clientSecret. Guarde o clientSecret no seu gerenciador de segredos, ele não é recuperável depois.

​
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. 
curl -X POST https://gyra-core.gyramais.com.br/auth/authenticate \
  -H "gyra-client-id: seu-client-id" \
  -H "gyra-client-secret: seu-client-secret"
Resposta: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

​
Usar

Incluir o token em toda chamada HTTP: 
Authorization: Bearer <token>
Exemplo com curl: 
curl -X POST https://gyra-core.gyramais.com.br/v2/report \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "43591367000130",
    "policyId": "6612a7f30000000000000001"
  }'

​
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.
Webhooks são configurados via API, não há tela no toolbox para gerenciá-los. Os endpoints são POST /webhook, GET /webhook, DELETE /webhook/:id.

​
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).
TipoQuando dispara
REPORTA cada atualização de seção durante o processamento do relatório (granular, muitos disparos por relatório).
REPORT_FINISHEDRelatório totalmente processado: todas as integrações concluíram e o resultado final está disponível.
REPORT_STATUSAnalista humano aprovou ou rejeitou manualmente o relatório (via analyze ou re-analyze).
REPORT_EXPORTEDExportação (PDF ou XLS) do relatório foi gerada e está disponível por URL, ou falhou.
CREDIT_POLICYPolítica de crédito foi avaliada e o status mudou (resultado final do motor de regras).
OPERATIONOperação (fluxo multi-relatório com cadeia de políticas) concluiu com status final.

​
Configurar

curl -X POST https://gyra-core.gyramais.com.br/webhook \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "REPORT_FINISHED",
    "url": "https://seu-sistema.com/webhooks/gyra",
    "apiKey": "opcional-chave-enviada-no-header-api-key"
  }'
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: 
{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "REPORT_FINISHED",
  "data": { ... }
}
O conteúdo de data varia por tipo: REPORT_FINISHED 
{
  "content": {
    "reportId": "6612a7f30000000000000001",
    "policyId": "6612a7f30000000000000010",
    "isFinalized": true,
    "finalizedAt": "2026-04-23T14:30:45Z",
    "errors": { "sections": ["PROCESSES"] }
  },
  "compress": false
}
REPORT (seção individual concluída) 
{
  "content": { "...dados da seção..." },
  "compress": false
}
O envelope externo também traz sectionTypeId e integration. REPORT_STATUS (decisão manual do analista) 
{
  "reportId": "6612a7f30000000000000001",
  "analysis": {
    "userId": "user-id-ou-'Política de crédito'",
    "userName": "Nome do analista",
    "status": "REPORT_APPROVED",
    "date": "2026-04-23T14:35:00Z"
  },
  "lastAnalysis": { "..." }
}
REPORT_EXPORTED 
{
  "reportId": "6612a7f30000000000000001",
  "exportUrl": "https://...assinado...",
  "exportedAt": "2026-04-23T14:40:00Z"
}
Em caso de falha, exportUrl vem null e o payload inclui error. CREDIT_POLICY 
{
  "content": {
    "reportId": "6612a7f30000000000000001",
    "policyId": "6612a7f30000000000000010",
    "version": 3,
    "status": "APPROVED",
    "risk": "LOW",
    "score": 720,
    "date": "2026-04-23T14:30:45Z"
  }
}
OPERATION 
{
  "operationId": "6612a7f30000000000000100",
  "operationResultId": "6612a7f30000000000000101",
  "document": "43591367000130",
  "status": "APPROVED"
}

​
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.

​
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. Envie e-mail para atendimento@gyramais.com pedindo novas credenciais.
Sim. Útil para separar ambientes (dev, staging, prod) ou integrações diferentes. Peça ao suporte quantas precisar.
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.

Rodar uma análise

Primeira análise ponta a ponta.