> ## 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.
# Confirmar Upload e Analisar
> Segundo passo do envio assíncrono: o arquivo já está no armazenamento e você dispara a análise.
### Quando usar
Segundo passo do envio assíncrono: o arquivo já está no armazenamento e você dispara a análise.
### Os dois campos de tipo
`expectedType` **pede** um tipo e a conferência roda. `typeHint` **afirma** o tipo e a classificação é pulada. Enviando os dois, `typeHint` vence.
O resultado chega pelo `callbackUrl`, pelo webhook da organização, ou por [Status do documento](/api-reference/registry/get-registry-documents-docid-status).
Contexto e vocabulário em [Análise documental](/onboarding/analise-documental). Autenticação, versionamento e capacidades em [Visão geral da API](/api-reference/onboarding/visao-geral).
## OpenAPI
````yaml post /v1/registry/{id}/documents
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/registry/{id}/documents:
post:
tags:
- registry
summary: Confirmar o upload e disparar a analise
description: >
Segundo passo do envio assincrono: confirma o arquivo que ja foi para o
armazenamento e
dispara o pipeline. Responde 202 com o documentId.
O resultado chega por webhook (registry.document.assessed) ou por
get_document_status.
Sobre os dois campos de tipo: `expectedType` PEDE um tipo e a
conferencia roda; `typeHint`
AFIRMA o tipo e a classificacao e pulada. Enviando os dois, typeHint
vence.
operationId: RegistryController_confirmDocument
parameters:
- name: id
required: true
in: path
schema:
type: string
description: Id do cadastro.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmRegistryDocumentDto'
example:
key: >-
presigned/contrato-social-3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e40.pdf
fileName: contrato-social.pdf
expectedType: CONTRATO_SOCIAL
callbackUrl: https://api.suaempresa.com/gyra/kyc
responses:
'202':
description: documentId do documento em processamento (202).
content:
application/json:
schema:
$ref: '#/components/schemas/RegistryConfirmResponse'
example:
documentId: 6612a7f30000000000000031
status: RECEIVED
'400':
description: >-
Corpo invalido (key e fileName sao obrigatorios). A mensagem
concatena todas as falhas por virgula.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 400
message: key should not be empty,key must be a string
'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: >-
Cadastro inexistente, personDocument que nao e pessoa deste cadastro
("Pessoa não encontrada neste cadastro."), ou modulo Onboarding nao
liberado ("Recurso não encontrado.").
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 404
message: Cadastro não encontrado.
'409':
description: O mesmo arquivo (mesmo conteudo) ja esta neste cadastro.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 409
message: Este arquivo já existe neste cadastro.
'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 armazenamento ou o servico de cadastro nao respondeu. Tente de
novo.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 502
message: Não foi possível registrar o documento.
security:
- authorization: []
x-codeSamples:
- lang: cURL
label: cURL
source: >
curl --request POST
'https://gyra-core.gyramais.com.br/v1/registry/6612a7f30000000000000001/documents'
\
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{"key":"presigned/contrato-social-3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e40.pdf","fileName":"contrato-social.pdf","expectedType":"CONTRATO_SOCIAL","callbackUrl":"https://api.suaempresa.com/gyra/kyc"}'
- lang: JavaScript
label: Node
source: >
const resposta = await
fetch("https://gyra-core.gyramais.com.br/v1/registry/6612a7f30000000000000001/documents",
{
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"key": "presigned/contrato-social-3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e40.pdf",
"fileName": "contrato-social.pdf",
"expectedType": "CONTRATO_SOCIAL",
"callbackUrl": "https://api.suaempresa.com/gyra/kyc"
}),
});
const dados = await resposta.json();
- lang: Python
label: Python
source: |
import requests
resposta = requests.post(
"https://gyra-core.gyramais.com.br/v1/registry/6612a7f30000000000000001/documents",
headers={"Authorization": f"Bearer {token}"},
json={
"key": "presigned/contrato-social-3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e40.pdf",
"fileName": "contrato-social.pdf",
"expectedType": "CONTRATO_SOCIAL",
"callbackUrl": "https://api.suaempresa.com/gyra/kyc"
},
)
dados = resposta.json()
components:
schemas:
ConfirmRegistryDocumentDto:
type: object
properties:
typeHint:
type: string
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- PROCURACAO_PJ
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIDAO_JUNTA
- ATA_ASSEMBLEIA
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- CERTIDAO_QSA
- CERTIFICADO_SIMPLES_NACIONAL
- ESOCIAL_PJ
- COMPROVACAO_ESTADO_CIVIL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
description: >-
Afirma o tipo documental do arquivo: o pipeline ADOTA este tipo e
PULA a etapa de classificação. Use quando a origem do arquivo já
garante o tipo (o operador escolheu na tela, o formulário só aceita
aquele documento). Como a classificação não roda, não existe leitura
automática a confrontar e a verificação EXPECTED_TYPE_MATCH sai
SKIP. Não use typeHint para dizer "eu pedi este documento": para
isso existe o expectedType.
expectedType:
type: string
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- PROCURACAO_PJ
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIDAO_JUNTA
- ATA_ASSEMBLEIA
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- CERTIDAO_QSA
- CERTIFICADO_SIMPLES_NACIONAL
- ESOCIAL_PJ
- COMPROVACAO_ESTADO_CIVIL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
description: >-
Tipo documental que a solicitação PEDIU. Não força nada e não pula
etapa alguma: a classificação roda normalmente e o tipo lido é
confrontado com este valor na verificação EXPECTED_TYPE_MATCH. Tipo
lido igual ao pedido, a verificação passa; diferente, reprova o
documento (ou vira ressalva quando a leitura do tipo está com pouca
confiança). É o campo que pega o arquivo legítimo enviado no campo
errado (uma declaração de IR subida como comprovante de residência),
que sem ele seria classificado, validado e aprovado como o tipo que
de fato é. Omitir significa envio livre no dossiê: sem pedido, a
verificação sai SKIP. Combinado com typeHint no mesmo envio, o
typeHint vence e a verificação sai SKIP (não há classificação a
confrontar).
key:
type: string
description: A key devolvida pelo presign, exatamente como veio.
fileName:
type: string
description: Nome do arquivo que fica no dossie.
personDocument:
type: string
description: >-
CPF ou CNPJ de uma pessoa do quadro deste cadastro, para anexar o
documento a ela. Precisa estar na arvore societaria.
callbackUrl:
type: string
description: URL chamada quando o documento terminar de processar.
required:
- key
- fileName
RegistryConfirmResponse:
type: object
properties:
documentId:
type: string
status:
type: string
enum:
- RECEIVED
- CLASSIFYING
- CLASSIFIED
- EXTRACTING
- EXTRACTED
- VALIDATING
- VALIDATED
- FAILED
- MANUAL_REVIEW
- OUT_OF_SCOPE
- REJECTED_QUALITY
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.