> ## 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.
# Consultar Solicitação
> Para acompanhar item a item e ver o estado de entrega de cada destinatário.
### Quando usar
Para acompanhar item a item e ver o estado de entrega de cada destinatário.
### O estado que mais importa
`recipients[].status` em **`FAILED`** quer dizer que a mensagem **não chegou**. É o caso de ligar para o cliente, e é por isso que vale assinar `collection.message.failed`.
`items[].files[]` traz o parecer de cada arquivo, quando o item aceita mais de um. Item com `signedDocumentAvailable: true` tem via assinada para [baixar](/api-reference/onboarding/via-assinada).
O link de cada destinatário **não** volta aqui: ele só existe na resposta de criação e na de [envio](/api-reference/collection/post-collections-id-send).
Contexto e vocabulário em [Solicitações de coleta](/onboarding/solicitacoes). Autenticação, versionamento e capacidades em [Visão geral da API](/api-reference/onboarding/visao-geral).
## OpenAPI
````yaml get /v1/collections/{id}
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/collections/{id}:
get:
tags:
- collections
summary: Detalhe de uma solicitacao
description: >
Traz os itens (com status e o parecer de cada um), os destinatarios (com
o estado da
entrega), o cadastro alvo em `registry`, a contagem em `progress` e a
trilha. O link de cada
destinatario NAO volta aqui: ele so existe na resposta de criacao e na
de envio.
Status de item: PENDING, ALREADY_ON_FILE, SUBMITTED, PROCESSING,
VALIDATED, REJECTED,
MANUAL_REVIEW, AWAITING_OPERATOR (a IA avaliou e espera decisao humana),
WAIVED, EXPIRED.
Estado do destinatario: PENDING, DELIVERED, OPENED, IN_PROGRESS,
COMPLETED, FAILED e
NO_ITEMS (nao sobrou item para essa pessoa).
FAILED no destinatario quer dizer que a MENSAGEM nao chegou. E o caso de
ligar para o cliente.
operationId: CollectionController_findOne
parameters:
- name: id
required: true
in: path
schema:
type: string
description: Id da solicitacao.
responses:
'200':
description: Solicitacao com itens, destinatarios, links e trilha.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
example:
id: 6612a7f30000000000000051
registryId: 6612a7f30000000000000001
templateId: 6612a7f30000000000000041
templateSlug: onboarding-pj
templateName: Onboarding PJ
templateVersion: 3
status: SENT
responseMode: REVIEW
channel: BOTH
reminders:
- 2
- 5
behavior:
acceptPartial: false
requestResendOnReject: true
notifyOnComplete: true
skipItemsAlreadyOnFile: true
message: Precisamos destes documentos para liberar seu limite.
dueAt: '2026-09-15T23:59:59.000Z'
sentAt: '2026-09-05T14:20:00.000Z'
completedAt: null
canceledAt: null
subjectName: AURORA COMPONENTES INDUSTRIAIS LTDA
subjectDocument: '11444777000161'
items:
- id: 6612a7f30000000000000071
collectionId: 6612a7f30000000000000051
recipientId: 6612a7f30000000000000061
order: 1
kind: DOCUMENT
documentType: CONTRATO_SOCIAL
label: Contrato social consolidado
instructions: >-
Envie a última alteração consolidada, com a chancela da
Junta.
required: true
rules:
maxAgeDays: 365
allowMultipleFiles: true
maxFiles: 5
status: PENDING
registryDocumentId: null
attempt: null
verdict: null
score: null
rejectionReason: null
submittedAt: null
resendCount: 0
files: []
signatureMode: INDIVIDUAL
signaturePackage: null
resolvedAt: null
recipients:
- id: 6612a7f30000000000000061
collectionId: 6612a7f30000000000000051
name: Ana Souza
document: '52998224725'
email: ana@exemplo.com.br
phone: 5551999998888
role: Sócia administradora · 60%
registryPersonId: 6612a7f30000000000000021
status: DELIVERED
emailDelivery: DELIVERED
whatsappDelivery: SENT
deliveryError: null
tokenExpiresAt: '2026-09-15T23:59:59.000Z'
lastSentAt: '2026-09-05T14:20:03.000Z'
openedAt: null
completedAt: null
remindersSent: 0
lastReminderAt: null
revoked: false
createdAt: '2026-09-05T14:19:58.000Z'
updatedAt: '2026-09-05T14:20:03.000Z'
'400':
description: >-
Corpo ou parametro invalido. A mensagem aponta o campo, e concatena
todas as falhas por virgula.
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: >-
Solicitacao inexistente na organizacao, ou modulo nao liberado
("Recurso não encontrado.").
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 404
message: Solicitação 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
security:
- authorization: []
x-codeSamples:
- lang: cURL
label: cURL
source: >
curl --request GET
'https://gyra-core.gyramais.com.br/v1/collections/6612a7f30000000000000001'
\
--header 'Authorization: Bearer '
- lang: JavaScript
label: Node
source: >
const resposta = await
fetch("https://gyra-core.gyramais.com.br/v1/collections/6612a7f30000000000000001",
{
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/collections/6612a7f30000000000000001",
headers={"Authorization": f"Bearer {token}"},
)
dados = resposta.json()
components:
schemas:
Collection:
type: object
description: Uma solicitacao de coleta com itens, destinatarios e trilha.
properties:
id:
type: string
registryId:
type: string
templateId:
type: string
nullable: true
templateSlug:
type: string
nullable: true
templateName:
type: string
nullable: true
templateVersion:
type: integer
nullable: true
status:
type: string
enum:
- DRAFT
- SENT
- IN_PROGRESS
- COMPLETED
- EXPIRED
- CANCELED
responseMode:
type: string
enum:
- AUTOMATIC
- REVIEW
channel:
type: string
enum:
- WHATSAPP
- EMAIL
- BOTH
- NONE
description: 'NONE: a plataforma nao avisou ninguem e quem entrega o link e voce.'
reminders:
type: array
items:
type: integer
description: Dias apos o envio.
behavior:
type: object
additionalProperties: true
description: O comportamento herdado do modelo.
message:
type: string
nullable: true
description: Recado do operador ao destinatario.
dueAt:
type: string
nullable: true
format: date-time
sentAt:
type: string
nullable: true
format: date-time
completedAt:
type: string
nullable: true
format: date-time
canceledAt:
type: string
nullable: true
format: date-time
subjectName:
type: string
nullable: true
description: Resumo do cadastro alvo, para evitar uma segunda chamada.
subjectDocument:
type: string
nullable: true
items:
type: array
items:
$ref: '#/components/schemas/CollectionItem'
recipients:
type: array
items:
$ref: '#/components/schemas/CollectionRecipient'
events:
type: array
items:
type: object
properties:
id:
type: string
action:
type: string
actorType:
type: string
enum:
- USER
- API_USER
- RECIPIENT
- SYSTEM
itemId:
type: string
nullable: true
recipientId:
type: string
nullable: true
payload:
type: object
nullable: true
additionalProperties: true
createdAt:
type: string
format: date-time
description: A trilha, append-only. O detalhe traz os 100 eventos mais recentes.
registry:
type: object
nullable: true
description: 'O cadastro alvo: id, document, name e entityType.'
properties:
id:
type: string
document:
type: string
name:
type: string
nullable: true
entityType:
type: string
enum:
- COMPANY
- PERSON
itemsTotal:
type: integer
itemsResolved:
type: integer
itemsAwaitingOperator:
type: integer
description: Itens esperando decisao humana (AWAITING_OPERATOR ou MANUAL_REVIEW).
progress:
type: object
additionalProperties:
type: integer
description: >-
Contagem de itens (total, resolved, validated, awaitingOperator,
rejected, pending) e de destinatarios (recipientsTotal,
recipientsExpected, recipientsCompleted, recipientsWithoutItems).
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.
CollectionItem:
type: object
properties:
id:
type: string
collectionId:
type: string
recipientId:
type: string
nullable: true
order:
type: integer
kind:
type: string
enum:
- DOCUMENT
- IDENTITY
- CONSENT
- SIGNATURE
- FORM
- CUSTOM
documentType:
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
label:
type: string
description: O que o destinatario le.
instructions:
type: string
nullable: true
required:
type: boolean
rules:
type: object
additionalProperties: true
description: >-
Regras da coleta para este item (recencia, formatos, metodos de
identidade).
status:
type: string
enum:
- PENDING
- ALREADY_ON_FILE
- SUBMITTED
- PROCESSING
- VALIDATED
- REJECTED
- MANUAL_REVIEW
- AWAITING_OPERATOR
- WAIVED
- EXPIRED
registryDocumentId:
type: string
nullable: true
description: O documento que este item gerou no cadastro.
attempt:
type: integer
nullable: true
verdict:
type: string
nullable: true
enum:
- VALIDO
- INVALIDO
- INCONCLUSIVO
- ANALISE_MANUAL
- null
score:
type: number
nullable: true
rejectionReason:
type: string
nullable: true
description: Motivo tecnico, para o operador.
submittedAt:
type: string
nullable: true
format: date-time
resendRequestedAt:
type: string
nullable: true
format: date-time
resendCount:
type: integer
files:
type: array
items:
type: object
properties:
id:
type: string
order:
type: integer
registryDocumentId:
type: string
nullable: true
status:
type: string
enum:
- PENDING
- ALREADY_ON_FILE
- SUBMITTED
- PROCESSING
- VALIDATED
- REJECTED
- MANUAL_REVIEW
- AWAITING_OPERATOR
- WAIVED
- EXPIRED
verdict:
type: string
nullable: true
enum:
- VALIDO
- INVALIDO
- INCONCLUSIVO
- ANALISE_MANUAL
- null
score:
type: number
nullable: true
attempt:
type: integer
nullable: true
rejectionReason:
type: string
nullable: true
fileName:
type: string
nullable: true
mimeType:
type: string
nullable: true
sizeBytes:
type: integer
nullable: true
submittedAt:
type: string
nullable: true
format: date-time
resolvedAt:
type: string
nullable: true
format: date-time
description: >-
Um por arquivo enviado, com o parecer de cada um. Vazio no item que
ainda nao recebeu nada.
consentType:
type: string
nullable: true
enum:
- SCR
- null
consentTemplateId:
type: string
nullable: true
consentTemplateVersion:
type: integer
nullable: true
optinId:
type: string
nullable: true
consentAcceptedAt:
type: string
nullable: true
format: date-time
formSpec:
type: object
nullable: true
additionalProperties: true
description: O formulario pedido.
formPrefill:
type: object
nullable: true
additionalProperties: true
description: O que a extracao sugeriu.
formAnswer:
type: object
nullable: true
additionalProperties: true
description: O que a pessoa respondeu.
identityProvider:
type: string
nullable: true
identityStatus:
type: string
nullable: true
identityEvaluation:
type: object
nullable: true
additionalProperties: true
description: >-
A avaliacao da verificacao em portugues (veredito, similaridade,
prova de vida, sinais de antifraude). O payload cru do provedor NAO
vem aqui.
identityMediaCount:
type: integer
nullable: true
description: >-
Quantas imagens estao guardadas. Os enderecos saem por acao
explicita, que fica na trilha.
identityStartedAt:
type: string
nullable: true
format: date-time
signedDocumentId:
type: string
nullable: true
signatureMode:
type: string
enum:
- INDIVIDUAL
- JOINT
signaturePackage:
type: string
nullable: true
enum:
- SIGNATURE
- SIGNATURE_AND_IDENTITY
- null
signatureProgress:
type: object
nullable: true
description: '"2 de 4 assinaram", ja pronto.'
properties:
total:
type: integer
signed:
type: integer
missing:
type: array
items:
type: string
description: Nome das partes obrigatorias que faltam.
awaitingIdentity:
type: array
items:
type: string
description: Assinaram o texto e esperam a verificacao de identidade.
awaitingContact:
type: array
items:
type: string
description: Partes sem contato para receber o link.
complete:
type: boolean
description: true quando a via em PDF pode nascer.
label:
type: string
signatories:
type: array
items:
type: object
additionalProperties: true
description: Uma parte do documento conjunto. O documento vem mascarado.
reviewDecision:
type: string
nullable: true
enum:
- APPROVED
- RESEND_REQUESTED
- WAIVED
- null
reviewComment:
type: string
nullable: true
reviewedAt:
type: string
nullable: true
format: date-time
reviewedByUserId:
type: string
nullable: true
alreadyOnFileReason:
type: string
nullable: true
description: Por que o item nasceu ALREADY_ON_FILE, em portugues.
resolvedAt:
type: string
nullable: true
format: date-time
signedDocumentAvailable:
type: boolean
description: >-
true quando ha via assinada para baixar em GET
/v1/collections/{id}/items/{itemId}/signed-document.
identityEmailCandidateCount:
type: integer
description: >-
Quantos e-mails foram oferecidos para a verificacao por e-mail
(nunca quais).
CollectionRecipient:
type: object
properties:
id:
type: string
collectionId:
type: string
name:
type: string
document:
type: string
nullable: true
email:
type: string
nullable: true
phone:
type: string
nullable: true
description: E.164.
role:
type: string
nullable: true
registryPersonId:
type: string
nullable: true
status:
type: string
enum:
- PENDING
- DELIVERED
- OPENED
- IN_PROGRESS
- COMPLETED
- FAILED
- NO_ITEMS
description: >-
FAILED quer dizer que a MENSAGEM nao chegou. NO_ITEMS: nao sobrou
item para essa pessoa.
emailDelivery:
type: string
enum:
- PENDING
- SENT
- DELIVERED
- FAILED
whatsappDelivery:
type: string
enum:
- PENDING
- SENT
- DELIVERED
- FAILED
deliveryError:
type: string
nullable: true
tokenExpiresAt:
type: string
nullable: true
format: date-time
lastSentAt:
type: string
nullable: true
format: date-time
openedAt:
type: string
nullable: true
format: date-time
completedAt:
type: string
nullable: true
format: date-time
remindersSent:
type: integer
lastReminderAt:
type: string
nullable: true
format: date-time
revoked:
type: boolean
link:
type: string
nullable: true
description: So volta na criacao e na reemissao. O token cru nunca e persistido.
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.