> ## 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.
# Status do Documento
> O envio respondeu `202` e você precisa acompanhar.
### Quando usar
O envio respondeu `202` e você precisa acompanhar. Devolve o mesmo corpo do resultado completo.
### Prefira webhook a polling
Status terminais: `VALIDATED`, `FAILED`, `OUT_OF_SCOPE`, `MANUAL_REVIEW`, `REJECTED_QUALITY`. Enquanto não for um deles, o documento ainda está no pipeline.
Assinar `registry.document.assessed` evita o laço de polling por completo.
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 get /v1/registry/documents/{docId}/status
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/documents/{docId}/status:
get:
tags:
- registry
summary: Status e resultado de um documento em analise
description: >
Consulta um documento pelo id, sem precisar do id do cadastro. E o
caminho de polling
depois de um 202 do validate_document.
Status terminais: VALIDATED, FAILED, OUT_OF_SCOPE, MANUAL_REVIEW,
REJECTED_QUALITY.
Enquanto nao for terminal, o documento ainda esta no pipeline.
Devolve o mesmo corpo do resultado completo, incluindo `statusReason`
(por que parou num
terminal que nao e falha tecnica) e `stages` (o que rodou e o que veio
reaproveitado).
PREFIRA WEBHOOK: assine registry.document.assessed em vez de fazer
polling em laco.
operationId: RegistryController_documentStatus
parameters:
- name: docId
required: true
in: path
schema:
type: string
description: >-
Id do documento, devolvido pelo validate_document ou pelo
confirm_registry_document.
responses:
'200':
description: >-
Documento com status, classification, extraction, validation e
assessment.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistryDocumentResult'
example:
documentId: 6612a7f30000000000000031
registryId: 6612a7f30000000000000001
type: CONTRATO_SOCIAL
expectedType: CONTRATO_SOCIAL
expectedTypes: []
status: VALIDATED
version: 2
isCurrent: true
classification:
type: CONTRATO_SOCIAL
confidence: 0.94
alternatives:
- type: ALTERACAO_CONTRATUAL
confidence: 0.21
ambiguous: false
statusReason: null
stages:
executed:
- CLASSIFY
- EXTRACT
- VALIDATE
reused: []
extraction:
cnpj:
value: '11444777000161'
confidence: 0.97
page: 1
companyName:
value: AURORA COMPONENTES INDUSTRIAIS LTDA
confidence: 0.96
page: 1
signatureDate:
value: '2021-04-30T00:00:00.000Z'
confidence: 0.93
page: 8
capitalAmount:
value: 1200000
confidence: 0.95
page: 3
capitalCurrency:
value: BRL
confidence: 0.99
page: 3
quotaUnitValue:
value: null
confidence: 0
page: null
partners:
- name:
value: CARLOS EDUARDO SILVA
confidence: 0.96
page: 1
document:
value: '52998224725'
confidence: 0.95
page: 1
documentType:
value: CPF
confidence: 0.99
page: 1
sharePercent:
value: 60
confidence: 0.95
page: 3
isAdministrator:
value: true
confidence: 0.92
page: 4
representation:
regime:
value: ISOLADA
confidence: 0.95
page: 4
signersRequired:
value: 1
confidence: 0.95
page: 4
clauseNumber:
value: CLÁUSULA 8ª
confidence: 0.94
page: 4
clauseExcerpt:
value: >-
A administração da sociedade caberá isoladamente ao
sócio CARLOS EDUARDO SILVA...
confidence: 0.94
page: 4
certification:
certificationKind:
value: ORGAO_EMISSOR
confidence: 0.97
page: 1
certificationDetail:
value: Chancela digital da Junta Comercial
confidence: 0.96
page: 1
verificationCode:
value: A1B2C3D4E5
confidence: 0.98
page: 1
fieldConfidences:
cnpj: 0.97
companyName: 0.96
capitalAmount: 0.95
validation:
checks:
- code: EXPECTED_DOCUMENT_MATCH
result: PASS
message: O CNPJ do documento é o mesmo da análise.
evidence:
page: 1
excerpt: CNPJ 11.444.777/0001-61
source: DETERMINISTIC
- code: QSA_SHARE_SUM
result: WARN
message: >-
A soma das participações fecha 98%, fora da tolerância
de 0,5 ponto.
evidence:
page: 3
excerpt: CARLOS EDUARDO SILVA 60% ... MARIA HELENA SOUZA 38%
source: DETERMINISTIC
reconciliation:
qsaMatched: true
assessment:
verdict: VALIDO
score: 0.91
justification: >-
Documento íntegro, titularidade confirmada e registro na
Junta conferido. A soma das quotas ficou 2 pontos abaixo de
100%, o que é ressalva e não impedimento.
evidences: []
ruleSetVersion: org-v7
contentHash: 9f2b7c1e4a...
feedbackVerdict: null
feedbackComment: null
feedbackAt: null
feedbackUserId: null
effectiveVerdict: VALIDO
decidedByOperator: false
processedAt: '2026-09-05T13:07:44.000Z'
attempt: 1
'400':
description: Identificador fora do formato ObjectId (24 caracteres hexadecimais).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 400
message: O identificador informado em "docId" não é válido.
'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: >-
Documento inexistente na organizacao, ou modulo Onboarding nao
liberado (nesse caso a mensagem e "Recurso não encontrado."). As
duas coisas respondem 404 de proposito: para quem nao tem o modulo,
a rota nao existe.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 404
message: Documento não encontrado.
'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 cadastro nao respondeu. Tente de novo.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 502
message: Não foi possível consultar o status do documento.
security:
- authorization: []
x-codeSamples:
- lang: cURL
label: cURL
source: >
curl --request GET
'https://gyra-core.gyramais.com.br/v1/registry/documents/6612a7f30000000000000001/status'
\
--header 'Authorization: Bearer '
- lang: JavaScript
label: Node
source: >
const resposta = await
fetch("https://gyra-core.gyramais.com.br/v1/registry/documents/6612a7f30000000000000001/status",
{
method: "GET",
headers: { Authorization: `Bearer ${token}` },
});
const dados = await resposta.json();
- lang: Python
label: Python
source: |
import requests
resposta = requests.get(
"https://gyra-core.gyramais.com.br/v1/registry/documents/6612a7f30000000000000001/status",
headers={"Authorization": f"Bearer {token}"},
)
dados = resposta.json()
components:
schemas:
RegistryDocumentResult:
type: object
description: Resultado completo de um documento, da classificacao ao parecer.
properties:
documentId:
type: string
registryId:
type: string
type:
type: string
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- ATA_ASSEMBLEIA
- PROCURACAO_PJ
- CERTIDAO_JUNTA
- CERTIDAO_QSA
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIFICADO_SIMPLES_NACIONAL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- ESOCIAL_PJ
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- COMPROVACAO_ESTADO_CIVIL
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
description: O tipo LIDO pela classificacao.
expectedType:
type: string
nullable: true
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- ATA_ASSEMBLEIA
- PROCURACAO_PJ
- CERTIDAO_JUNTA
- CERTIDAO_QSA
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIFICADO_SIMPLES_NACIONAL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- ESOCIAL_PJ
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- COMPROVACAO_ESTADO_CIVIL
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
- null
description: O tipo PEDIDO no envio. Sustenta a verificacao EXPECTED_TYPE_MATCH.
expectedTypes:
type: array
items:
type: string
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- ATA_ASSEMBLEIA
- PROCURACAO_PJ
- CERTIDAO_JUNTA
- CERTIDAO_QSA
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIFICADO_SIMPLES_NACIONAL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- ESOCIAL_PJ
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- COMPROVACAO_ESTADO_CIVIL
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
description: O CONJUNTO pedido, quando o item nasceu de um requisito societario.
status:
type: string
enum:
- RECEIVED
- CLASSIFYING
- CLASSIFIED
- EXTRACTING
- EXTRACTED
- VALIDATING
- VALIDATED
- FAILED
- MANUAL_REVIEW
- OUT_OF_SCOPE
- REJECTED_QUALITY
version:
type: integer
isCurrent:
type: boolean
classification:
type: object
nullable: true
description: O que a classificacao concluiu, com as alternativas consideradas.
properties:
type:
type: string
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- ATA_ASSEMBLEIA
- PROCURACAO_PJ
- CERTIDAO_JUNTA
- CERTIDAO_QSA
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIFICADO_SIMPLES_NACIONAL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- ESOCIAL_PJ
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- COMPROVACAO_ESTADO_CIVIL
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
confidence:
type: number
description: 0 a 1.
alternatives:
type: array
items:
type: object
properties:
type:
type: string
enum:
- CONTRATO_SOCIAL
- ALTERACAO_CONTRATUAL
- ESTATUTO_SOCIAL
- REQUERIMENTO_EMPRESARIO
- ATA_ASSEMBLEIA
- PROCURACAO_PJ
- CERTIDAO_JUNTA
- CERTIDAO_QSA
- IRPJ_ECF
- DECLARACAO_FATURAMENTO
- CERTIFICADO_SIMPLES_NACIONAL
- DEMONSTRACOES_FINANCEIRAS
- EXTRATO_BANCARIO
- CERTIDAO_PGFN_PJ
- CERTIDAO_FGTS
- CADIN_FEDERAL
- CADIN_ESTADUAL
- ESOCIAL_PJ
- DOC_IDENTIDADE
- COMPROVANTE_RESIDENCIA
- DIRPF
- COMPROVANTE_RENDA
- CERTIDAO_PF
- PROCURACAO_PF
- COMPROVACAO_ESTADO_CIVIL
- FORA_DE_ESCOPO
- NAO_IDENTIFICADO
confidence:
type: number
ambiguous:
type: boolean
description: true quando outra alternativa passou de 0,35 de confianca.
statusReason:
type: string
nullable: true
description: Por que o documento parou num terminal que nao e falha tecnica.
stages:
type: object
nullable: true
description: O que rodou nesta tentativa e o que veio reaproveitado.
properties:
executed:
type: array
items:
type: string
enum:
- CLASSIFY
- EXTRACT
- VALIDATE
reused:
type: array
items:
type: object
properties:
stage:
type: string
enum:
- CLASSIFY
- EXTRACT
- VALIDATE
fromAttempt:
type: integer
extraction:
type: object
nullable: true
additionalProperties: true
description: >-
Os campos lidos. A FORMA DEPENDE DO TIPO identificado: cada um dos
25 tipos tem o seu conjunto, documentado campo a campo em
https://developers.gyramais.com.br/api-reference/kyc/formatos-de-retorno.
Todo campo folha vem como { value, confidence, page }; campo ausente
vem com value null e confidence 0.
fieldConfidences:
type: object
nullable: true
additionalProperties:
type: number
description: Confianca por caminho de campo.
validation:
type: object
nullable: true
properties:
checks:
type: array
items:
$ref: '#/components/schemas/RegistryCheck'
reconciliation:
type: object
nullable: true
additionalProperties: true
description: Conferencia contra a fonte oficial.
assessment:
type: object
nullable: true
properties:
verdict:
type: string
enum:
- VALIDO
- INVALIDO
- INCONCLUSIVO
- ANALISE_MANUAL
description: >-
O parecer da IA. NAO e o veredito que vale: use
effectiveVerdict.
score:
type: number
description: 0 a 1.
justification:
type: string
description: Por que, em portugues.
evidences:
type: array
items:
type: object
properties:
page:
type: integer
nullable: true
excerpt:
type: string
nullable: true
checkCode:
type: string
ruleSetVersion:
type: string
description: Qual versao da regua julgou este documento.
contentHash:
type: string
nullable: true
description: Selo do parecer, conferivel na rota de integridade.
feedbackVerdict:
type: string
nullable: true
enum:
- VALIDO
- INVALIDO
- INCONCLUSIVO
- ANALISE_MANUAL
- null
description: A decisao que um operador registrou, quando houve.
feedbackComment:
type: string
nullable: true
feedbackAt:
type: string
nullable: true
format: date-time
feedbackUserId:
type: string
nullable: true
effectiveVerdict:
type: string
nullable: true
enum:
- VALIDO
- INVALIDO
- INCONCLUSIVO
- ANALISE_MANUAL
- null
description: >-
O VEREDITO QUE VALE HOJE (feedbackVerdict ?? verdict). Leia
este.
decidedByOperator:
type: boolean
description: true quando quem decidiu foi uma pessoa, e nao o pipeline.
processedAt:
type: string
nullable: true
format: date-time
attempt:
type: integer
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.
RegistryCheck:
type: object
properties:
code:
type: string
description: 'Codigo da verificacao no catalogo (ex.: EXPECTED_DOCUMENT_MATCH).'
result:
type: string
enum:
- PASS
- WARN
- FAIL
- SKIP
description: 'WARN e ressalva: aparece no parecer e nao reprova sozinha.'
message:
type: string
description: Frase em portugues explicando o resultado.
evidence:
type: object
nullable: true
description: Onde no documento a verificacao se apoiou.
properties:
page:
type: integer
nullable: true
excerpt:
type: string
nullable: true
checkCode:
type: string
details:
type: array
items:
type: string
description: Indicios individuais, quando a verificacao produz varios.
source:
type: string
enum:
- DETERMINISTIC
- RECONCILIATION
- LLM
description: Quem produziu o resultado.
rfi:
type: integer
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.