> ## 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.
# Listar Documentos do Cadastro
> Para saber o que o dossiê já tem antes de pedir de novo.
### Quando usar
Para saber o que o dossiê já tem antes de pedir de novo.
### O que some por padrão
Nada é sobrescrito: a alteração contratual nova não apaga a antiga, vira a versão vigente. Por padrão some só a versão **aprovada** que já foi substituída por uma vigente do mesmo tipo. Documento reprovado, inconclusivo ou ainda em análise aparece sempre. Com `includeHistory`, vem tudo; com `type`, só um tipo.
A lista vem em `documents`, e cada documento traz `verdict`: o veredito que vale hoje, já com a decisão do operador quando houver.
Contexto e vocabulário em [Cadastro documental](/onboarding/cadastro-documental). Autenticação, versionamento e capacidades em [Visão geral da API](/api-reference/onboarding/visao-geral).
## OpenAPI
````yaml get /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:
get:
tags:
- registry
summary: Listar os documentos de um cadastro
description: >
Lista os documentos do dossie, agrupados por tipo e do mais novo para o
mais antigo. Cada
documento traz `verdict`, o veredito que vale hoje (a decisao do
operador, quando houver,
vence o parecer automatico).
Por padrao some so a versao APROVADA que ja foi substituida por uma
vigente do mesmo tipo
(e da mesma pessoa). Documento reprovado, inconclusivo, em analise ou em
processamento
aparece sempre. Com includeHistory, traz todas as versoes.
Nada e sobrescrito: uma alteracao contratual nova nao apaga a antiga,
vira a versao vigente.
operationId: RegistryController_listDocuments
parameters:
- name: id
required: true
in: path
schema:
type: string
description: Id do cadastro.
- name: type
required: false
in: query
schema:
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: So os documentos deste tipo.
- name: includeHistory
required: false
in: query
schema:
type: boolean
description: >-
true traz tambem as versoes aprovadas que ja foram substituidas por
uma mais nova do mesmo tipo.
responses:
'200':
description: >-
Documentos com tipo, versao, status, veredito e data, dentro de
`documents`.
content:
application/json:
schema:
type: object
properties:
documents:
type: array
items:
$ref: '#/components/schemas/RegistryDocument'
example:
documents:
- id: 6612a7f30000000000000031
registryId: 6612a7f30000000000000001
personId: null
type: CONTRATO_SOCIAL
expectedType: CONTRATO_SOCIAL
status: VALIDATED
version: 2
isCurrent: true
supersedesId: 6612a7f30000000000000030
fileUrl: >-
https://.s3.amazonaws.com/presigned/contrato-social-3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e40.pdf
fileName: contrato-social.pdf
mimeType: application/pdf
sizeBytes: 1843200
pageCount: 12
parentDocumentId: null
classification:
type: CONTRATO_SOCIAL
confidence: 0.94
yearReference: null
attempt: 1
lastError: null
statusReason: null
verdict: VALIDO
createdAt: '2026-09-05T13:02:11.000Z'
updatedAt: '2026-09-05T13:07:44.000Z'
'400':
description: Identificador fora do formato ObjectId, ou `type` fora da lista.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 400
message: O identificador informado em "id" 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: >-
Recurso inexistente OU capacidade nao liberada para a organizacao.
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: Cadastro 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
security:
- authorization: []
x-codeSamples:
- lang: cURL
label: cURL
source: >
curl --request GET
'https://gyra-core.gyramais.com.br/v1/registry/6612a7f30000000000000001/documents'
\
--header 'Authorization: Bearer '
- lang: JavaScript
label: Node
source: >
const resposta = await
fetch("https://gyra-core.gyramais.com.br/v1/registry/6612a7f30000000000000001/documents",
{
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/6612a7f30000000000000001/documents",
headers={"Authorization": f"Bearer {token}"},
)
dados = resposta.json()
components:
schemas:
RegistryDocument:
type: object
properties:
id:
type: string
registryId:
type: string
personId:
type: string
nullable: true
description: Pessoa da arvore societaria a que o documento foi anexado.
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
status:
type: string
enum:
- RECEIVED
- CLASSIFYING
- CLASSIFIED
- EXTRACTING
- EXTRACTED
- VALIDATING
- VALIDATED
- FAILED
- MANUAL_REVIEW
- OUT_OF_SCOPE
- REJECTED_QUALITY
version:
type: integer
description: Versao dentro do tipo. Nada e sobrescrito.
isCurrent:
type: boolean
description: true na versao vigente daquele tipo.
supersedesId:
type: string
nullable: true
fileUrl:
type: string
description: URL assinada, com validade.
fileName:
type: string
mimeType:
type: string
sizeBytes:
type: integer
nullable: true
pageCount:
type: integer
nullable: true
parentDocumentId:
type: string
nullable: true
description: Preenchido quando o arquivo trazia varias pecas e foi dividido.
pageRange:
type: string
nullable: true
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
yearReference:
type: integer
nullable: true
description: Ano-calendario, nos tipos que tem (DIRPF, IRPJ/ECF).
attempt:
type: integer
lastError:
type: string
nullable: true
verdict:
type: string
nullable: true
enum:
- VALIDO
- INVALIDO
- INCONCLUSIVO
- ANALISE_MANUAL
- null
description: Veredito do parecer vigente, para a coluna da listagem.
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.