> ## 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. > ## Agent Instructions > A GYRA+ tem um servidor MCP oficial: https://mcp.gyramais.com.br/mcp. A autenticação é o login do próprio usuário na plataforma, não uma credencial separada. Instalação em https://developers.gyramais.com.br/mcp/instalacao. > Prefira as tools do MCP a montar chamadas HTTP na mão quando o usuário já tem o conector ligado. > Para analisar crédito de um CNPJ ou CPF, use create_report_v2 e assine um webhook em vez de fazer polling. > Para ler um documento (contrato social, comprovante de residência, imposto de renda, balanço), use validate_document: a entrada é um arquivo só e a plataforma reconhece o tipo sozinha. > Para pedir documentos ao cliente final, use create_collection com o slug de um modelo obtido em list_collection_templates. > Documento (CNPJ/CPF) é dado pessoal: não o repita em log nem o envie a serviços de terceiros. # Criar ou Atualizar Assinatura > Para assinar os eventos do módulo e parar de fazer polling. ### Quando usar Para assinar os eventos do módulo e parar de fazer polling. ### Lista de eventos vazia quer dizer todos Quem está começando não sabe de quais precisa, e escolher antes de conhecer produz assinatura errada e evento perdido em silêncio. ### O segredo aparece uma vez Ele volta em claro **só nesta resposta**, na criação e na rotação. Confira a assinatura com `HMAC_SHA256(segredo, ".")` e recuse o que estiver fora de uma janela de cinco minutos. Contexto e vocabulário em [Eventos de webhook](/api-reference/onboarding/eventos-de-webhook). Autenticação, versionamento e capacidades em [Visão geral da API](/api-reference/onboarding/visao-geral). ## OpenAPI ````yaml post /v1/webhook/endpoints openapi: 3.0.0 info: title: GYRA+ API - MCP Server description: >- API da Gyra+ para analise de credito. Spec curada para uso com agentes AI via MCP. version: '1.0' contact: {} servers: - url: https://gyra-core.gyramais.com.br description: Producao security: [] paths: /v1/webhook/endpoints: post: tags: - collections summary: Criar ou atualizar uma assinatura de webhook description: > Cria (sem id) ou atualiza (com id) uma assinatura de webhook. A mesma assinatura pode escutar eventos do Onboarding e eventos de relatorio e credito. Quando os eventos de relatorio e credito nao puderem ser gravados (o endereco precisa responder a um POST de teste no momento do cadastro), a resposta continua 200 e traz `warning` com o motivo. LISTA DE EVENTOS VAZIA QUER DIZER TODOS. Quem esta comecando nao sabe de quais precisa, e escolher antes de conhecer produz assinatura errada e evento perdido em silencio. O segredo e gerado pela plataforma e devolvido UMA VEZ, na criacao. Ele e por assinatura: um endpoint comprometido nao permite forjar evento para os outros. A URL precisa ser publica; endereco interno e recusado, e o nome e resolvido de novo a cada tentativa de entrega. Confira a assinatura com HMAC_SHA256(segredo, ".") e recuse o que estiver fora de uma janela de cinco minutos. operationId: WebhookController_save parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SaveWebhookEndpointDto' example: url: https://api.suaempresa.com/gyra/webhook label: Produção, esteira de crédito events: - registry.document.assessed - collection.completed - collection.message.failed enabled: true responses: '200': description: >- Assinatura salva. Na criacao e na rotacao, inclui o secret em claro (unica vez). content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointSaved' example: id: 6612a7f30000000000000091 url: https://api.suaempresa.com/gyra/webhook label: Produção, esteira de crédito events: - registry.document.assessed - collection.completed - collection.message.failed enabled: true secretHint: …a91f4c secret: >- whsec_4f1c9e2b7a6d3058c1e2f4a9b8d7c6e5f0a1b2c3d4e5f60718293a4b5ca91f4c createdAt: '2026-09-05T18:40:00.000Z' organizationId: 6612a7f30000000000000009 consecutiveFailures: 0 lastDeliveryStatus: null lastDeliveryError: null lastDeliveryAt: null updatedAt: '2026-09-06T10:12:00.000Z' '400': description: >- Corpo invalido (URL fora do formato, evento repetido, rotulo acima de 80 caracteres). A mensagem concatena todas as falhas por virgula. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: 400 message: url must be a URL address '401': description: >- Token ausente, expirado ou invalido. Gere outro em POST /auth/authenticate. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: 401 message: Token de acesso inválido. '403': description: O usuario autenticado nao tem a permissao exigida pela rota. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: 403 message: Você não tem permissão para acessar este recurso. '404': description: >- id de assinatura inexistente na atualizacao, ou modulo nao liberado ("Recurso não encontrado."). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: 404 message: Assinatura de webhook não encontrada. '500': description: >- Falha nossa. Tente de novo; se persistir, acione o suporte com o horario da chamada. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: 500 message: Internal server error '502': description: O servico de webhooks nao respondeu. Tente de novo. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: 502 message: Não foi possível salvar a assinatura. security: - authorization: [] x-codeSamples: - lang: cURL label: cURL source: > curl --request POST 'https://gyra-core.gyramais.com.br/v1/webhook/endpoints' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{"url":"https://api.suaempresa.com/gyra/webhook","label":"Produção, esteira de crédito","events":["registry.document.assessed","collection.completed","collection.message.failed"],"enabled":true}' - lang: JavaScript label: Node source: > const resposta = await fetch("https://gyra-core.gyramais.com.br/v1/webhook/endpoints", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ "url": "https://api.suaempresa.com/gyra/webhook", "label": "Produção, esteira de crédito", "events": [ "registry.document.assessed", "collection.completed", "collection.message.failed" ], "enabled": true }), }); const dados = await resposta.json(); - lang: Python label: Python source: | import requests resposta = requests.post( "https://gyra-core.gyramais.com.br/v1/webhook/endpoints", headers={"Authorization": f"Bearer {token}"}, json={ "url": "https://api.suaempresa.com/gyra/webhook", "label": "Produção, esteira de crédito", "events": [ "registry.document.assessed", "collection.completed", "collection.message.failed" ], "enabled": True }, ) dados = resposta.json() components: schemas: SaveWebhookEndpointDto: type: object properties: id: type: string description: Ausente cria; presente atualiza. url: type: string example: https://api.suaempresa.com/gyra/webhook description: URL publica, http ou https, com dominio. label: type: string description: >- Como a assinatura aparece na tela. Na atualizacao, omitir mantem o atual; string vazia limpa. maxLength: 80 events: description: >- Vazio ou ausente quer dizer TODOS os eventos, inclusive os de relatorio e credito. Sem repeticao. type: array items: type: string enabled: type: boolean description: Religar zera o contador de falhas seguidas. apiKey: type: string description: >- Valor enviado no cabecalho api-key, so nos eventos de relatorio e credito (esses nao usam a assinatura HMAC). required: - url WebhookEndpointSaved: type: object properties: id: type: string url: type: string label: type: string nullable: true events: type: array items: type: string enabled: type: boolean secretHint: type: string secret: type: string description: >- O segredo em claro, no formato whsec_ seguido de 64 caracteres hexadecimais. SO VEM AQUI, na criacao e na rotacao. Guarde no seu cofre. warning: type: string description: >- Presente so quando os eventos de relatorio e credito nao foram salvos; diz o motivo. createdAt: type: string format: date-time updatedAt: type: string format: date-time ApiError: type: object description: >- Formato unico de erro da API. Nao faca match exato da mensagem: use o code. properties: code: type: integer description: Codigo HTTP. message: type: string description: >- Mensagem em portugues. Em erro de validacao, traz TODAS as falhas concatenadas por virgula. securitySchemes: authorization: type: http scheme: bearer bearerFormat: JWT description: Enter JWT token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.