> ## 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. # Webhooks e API Keys > Como obter credenciais de API e configurar webhooks para receber eventos em tempo real. **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. ```bash theme={null} 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: ```json theme={null} { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 86400 } ``` ### Usar Incluir o token em toda chamada HTTP: ```bash theme={null} Authorization: Bearer ``` Exemplo com `curl`: ```bash theme={null} curl -X POST https://gyra-core.gyramais.com.br/v2/report \ -H "Authorization: Bearer " \ -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). | Tipo | Quando dispara | | ----------------- | ----------------------------------------------------------------------------------------------------------- | | `REPORT` | A cada atualização de seção durante o processamento do relatório (granular, muitos disparos por relatório). | | `REPORT_FINISHED` | Relatório totalmente processado: todas as integrações concluíram e o resultado final está disponível. | | `REPORT_STATUS` | Analista humano aprovou ou rejeitou manualmente o relatório (via `analyze` ou `re-analyze`). | | `REPORT_EXPORTED` | Exportação (PDF ou XLS) do relatório foi gerada e está disponível por URL, ou falhou. | | `CREDIT_POLICY` | Política de crédito foi avaliada e o status mudou (resultado final do motor de regras). | | `OPERATION` | Operação (fluxo multi-relatório com cadeia de políticas) concluiu com status final. | ### Configurar ```bash theme={null} curl -X POST https://gyra-core.gyramais.com.br/webhook \ -H "Authorization: Bearer " \ -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: ```json theme={null} { "organizationId": "6612a7f30000000000000001", "webhookType": "REPORT_FINISHED", "data": { ... } } ``` O conteúdo de `data` varia por tipo: **`REPORT_FINISHED`** ```json theme={null} { "content": { "reportId": "6612a7f30000000000000001", "policyId": "6612a7f30000000000000010", "isFinalized": true, "finalizedAt": "2026-04-23T14:30:45Z", "errors": { "sections": ["PROCESSES"] } }, "compress": false } ``` **`REPORT`** (seção individual concluída) ```json theme={null} { "content": { "...dados da seção..." }, "compress": false } ``` Os dados da seção concluída vêm em `content`. **`REPORT_STATUS`** (decisão manual do analista) ```json theme={null} { "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`** ```json theme={null} { "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`** ```json theme={null} { "content": { "reportId": "6612a7f30000000000000001", "policyId": "6612a7f30000000000000010", "version": 3, "status": "APPROVED", "risk": "LOW", "score": 720, "date": "2026-04-23T14:30:45Z" } } ``` **`OPERATION`** ```json theme={null} { "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](https://webhook.site) para capturar o POST, ou ngrok para expor o seu localhost. ## Próximos passos Como a GYRA+ emite eventos ao longo do ciclo de vida. Arquitetura geral dos endpoints. Usar as credenciais via agente de IA. Primeira análise ponta a ponta.