> ## 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 Solicitação
> Você quer que o próprio cliente entregue o que falta.
### Quando usar
Você quer que o próprio cliente entregue o que falta. Escolha o modelo, o cadastro e os destinatários.
### O cadastro é obrigatório
Por `document` (o cadastro é resolvido ou criado) **ou** por `registryId`. Um dos dois.
### Canal `NONE`: você entrega o link
A plataforma não avisa ninguém. A solicitação é criada, os links voltam em `links[]`, e o lembrete também não sai. É o caminho para quem já fala com o cliente pelo canal próprio.
### O que o cadastro já tem não é pedido de novo
Para pedir mesmo assim, liste as chaves de item em `forceItemKeys`.
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 post /v1/collections
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:
post:
tags:
- collections
summary: Criar uma solicitacao de documentos ao cliente
description: >
Cria o pedido a partir de um MODELO e manda o link para um ou mais
destinatarios.
O modelo diz O QUE se pede (documento, formulario, termo, assinatura,
identidade); aqui voce diz
PARA QUEM e SOBRE QUEM. Use list_collection_templates para descobrir os
modelos disponiveis.
O cadastro e obrigatorio, por `document` (CNPJ/CPF, e o cadastro e
resolvido ou criado) ou por
`registryId`. Um dos dois.
CANAL: EMAIL, WHATSAPP, BOTH, ou NONE. Com NONE a plataforma NAO avisa
ninguem: a solicitacao e
criada, os links voltam na resposta (publicUrl e links[]) e quem entrega
e voce. Lembrete tambem
nao sai. E o caminho para quem ja fala com o cliente pelo canal proprio.
O que o cadastro ja tem e validado nao e pedido de novo. Para pedir
mesmo assim, liste as chaves
em `forceItemKeys`.
Com `draft: true` (ou send: false), cria sem enviar.
operationId: CollectionController_create
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionDto'
example:
template: onboarding-pj
document: 11.444.777/0001-61
recipients:
- name: Ana Souza
document: 529.982.247-25
email: ana@exemplo.com.br
phone: 5551999998888
role: Sócia administradora · 60%
dueInDays: 10
channel: BOTH
responseMode: REVIEW
message: Precisamos destes documentos para liberar seu limite.
callbackUrl: https://api.suaempresa.com/gyra/kyc
send: true
responses:
'201':
description: >-
Solicitacao com id, status, dueAt, publicUrl, links[] por
destinatario e a lista de itens.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionCreateResponse'
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'
collectionId: 6612a7f30000000000000051
publicUrl: >-
https://toolbox.gyramais.com.br/envio/2f8cQ1r7aWxK9pLmN3bV5tYzE6uH0sJdR4gXoC8ifAe
notified: true
links:
- recipientId: 6612a7f30000000000000061
name: Ana Souza
document: '52998224725'
link: >-
https://toolbox.gyramais.com.br/envio/2f8cQ1r7aWxK9pLmN3bV5tYzE6uH0sJdR4gXoC8ifAe
publicUrl: >-
https://toolbox.gyramais.com.br/envio/2f8cQ1r7aWxK9pLmN3bV5tYzE6uH0sJdR4gXoC8ifAe
'400':
description: Corpo invalido. A mensagem concatena todas as falhas por virgula.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 400
message: Informe o documento ou o identificador do cadastro.
'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: >-
Modelo inexistente ("Modelo não encontrado."), registryId
inexistente ("Cadastro não encontrado.") ou modulo nao liberado para
a organizacao ("Recurso não encontrado.").
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 404
message: Modelo 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 solicitacoes nao respondeu. Tente de novo.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: 502
message: Não foi possível criar a solicitação.
security:
- authorization: []
x-codeSamples:
- lang: cURL
label: cURL
source: >
curl --request POST
'https://gyra-core.gyramais.com.br/v1/collections' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{"template":"onboarding-pj","document":"11.444.777/0001-61","recipients":[{"name":"Ana Souza","document":"529.982.247-25","email":"ana@exemplo.com.br","phone":"+5551999998888","role":"Sócia administradora · 60%"}],"dueInDays":10,"channel":"BOTH","responseMode":"REVIEW","message":"Precisamos destes documentos para liberar seu limite.","callbackUrl":"https://api.suaempresa.com/gyra/kyc","send":true}'
- lang: JavaScript
label: Node
source: >
const resposta = await
fetch("https://gyra-core.gyramais.com.br/v1/collections", {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"template": "onboarding-pj",
"document": "11.444.777/0001-61",
"recipients": [
{
"name": "Ana Souza",
"document": "529.982.247-25",
"email": "ana@exemplo.com.br",
"phone": "+5551999998888",
"role": "Sócia administradora · 60%"
}
],
"dueInDays": 10,
"channel": "BOTH",
"responseMode": "REVIEW",
"message": "Precisamos destes documentos para liberar seu limite.",
"callbackUrl": "https://api.suaempresa.com/gyra/kyc",
"send": true
}),
});
const dados = await resposta.json();
- lang: Python
label: Python
source: |
import requests
resposta = requests.post(
"https://gyra-core.gyramais.com.br/v1/collections",
headers={"Authorization": f"Bearer {token}"},
json={
"template": "onboarding-pj",
"document": "11.444.777/0001-61",
"recipients": [
{
"name": "Ana Souza",
"document": "529.982.247-25",
"email": "ana@exemplo.com.br",
"phone": "+5551999998888",
"role": "Sócia administradora · 60%"
}
],
"dueInDays": 10,
"channel": "BOTH",
"responseMode": "REVIEW",
"message": "Precisamos destes documentos para liberar seu limite.",
"callbackUrl": "https://api.suaempresa.com/gyra/kyc",
"send": True
},
)
dados = resposta.json()
components:
schemas:
CreateCollectionDto:
type: object
properties:
template:
type: string
description: 'Slug do modelo (ex.: onboarding-pj).'
document:
type: string
description: CNPJ ou CPF do cadastro.
registryId:
type: string
description: Identificador do cadastro (Registry).
recipients:
type: array
items:
$ref: '#/components/schemas/CollectionRecipientDto'
parties:
type: array
items:
$ref: '#/components/schemas/CollectionPartyDto'
dueInDays:
type: number
default: 7
message:
type: string
description: Recado do operador ao destinatário.
responseMode:
type: string
enum:
- AUTOMATIC
- REVIEW
description: Sobrepõe o modo de resposta do modelo.
channel:
type: string
enum:
- WHATSAPP
- EMAIL
- BOTH
- NONE
description: >-
Sobrepõe o canal de envio do modelo. Use `NONE` para a plataforma
não avisar ninguém: a solicitação é criada, os links são gerados e
voltam na resposta (`publicUrl` quando há um destinatário, `links[]`
sempre), e quem entrega é você. Lembrete também não sai.
callbackUrl:
type: string
description: Webhook do integrador (mesmo HMAC X-Gyra-Signature do cadastro).
forceItemKeys:
type: array
items:
type: string
draft:
type: boolean
description: Cria a solicitação sem disparar o envio (rascunho).
send:
type: boolean
default: true
required:
- template
- recipients
CollectionCreateResponse:
allOf:
- $ref: '#/components/schemas/Collection'
- type: object
properties:
collectionId:
type: string
description: O mesmo valor de `id`.
publicUrl:
type: string
nullable: true
description: >-
O link, quando ha um destinatario so. Com varios, vem null e a
resposta e `links`.
links:
type: array
items:
type: object
properties:
recipientId:
type: string
name:
type: string
document:
type: string
nullable: true
link:
type: string
publicUrl:
type: string
description: O mesmo endereco de `link`.
description: >-
Um link por destinatario enviado. Nao vem quando a solicitacao e
criada como rascunho (draft true ou send false).
notified:
type: boolean
description: >-
false quando o canal e NONE: ninguem foi avisado e quem entrega
o link e voce.
description: >-
A solicitacao criada. Quando ela e enviada na criacao, traz tambem os
links: com channel NONE e por aqui que voce recebe o link para entregar.
Os links so existem nesta resposta e na de envio.
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.
CollectionRecipientDto:
type: object
properties:
name:
type: string
document:
type: string
description: CPF/CNPJ do destinatário (só dígitos).
email:
type: string
phone:
type: string
description: Telefone em E.164 (+5551900001234).
role:
type: string
description: 'Ex.: "Sócio administrador · 47%".'
registryPersonId:
type: string
description: Pessoa da árvore societária do cadastro.
signatureRole:
type: string
enum:
- SIGNATARIO
- TESTEMUNHA
- INTERVENIENTE
default: SIGNATARIO
description: >-
Papel desta pessoa nos itens de assinatura conjunta. Ignorado quando
a solicitação não tem item conjunto.
signatureRequired:
type: boolean
default: true
required:
- name
CollectionPartyDto:
type: object
properties:
name:
type: string
description: Nome completo, como consta no documento.
document:
type: string
description: CPF ou CNPJ da parte.
role:
type: string
enum:
- SIGNATARIO
- TESTEMUNHA
- INTERVENIENTE
default: SIGNATARIO
required:
type: boolean
default: true
required:
- name
- document
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
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.