> ## 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.
# Cadastro documental
> O dossiê de um CNPJ ou CPF no Onboarding: documentos vigentes, completude, situação, dados declarados pelo cliente, quadro societário, contatos, renovação e trilha de auditoria.
**Resumo:** o cadastro (`Registry`) é a entidade canônica do Onboarding. Ele é criado uma vez por CNPJ ou CPF dentro da sua organização, guarda os documentos entregues, o que o cliente declarou nos formulários e os contatos de cada pessoa, calcula sozinho a **completude** e a **situação**, e é o que a solicitação aponta. No toolbox, ele fica em **Onboarding**, **Clientes**.
## Identidade do cadastro
Um cadastro é a dupla organização + documento. O mesmo CNPJ em duas organizações são dois cadastros independentes, e criar de novo o mesmo documento devolve o cadastro que já existe em vez de duplicar.
| Campo | O que é |
| - | - |
| `document` | CNPJ ou CPF, só dígitos |
| `entityType` | `COMPANY` (CNPJ) ou `PERSON` (CPF) |
| `name` | Razão social ou nome, dos dados oficiais |
| `kycStatus` | Situação do cadastro (abaixo) |
| `completeness` | Percentual de slots preenchidos com documento válido e vigente |
## Situação do cadastro
| Situação | O que quer dizer |
| - | - |
| `PENDING` | Criado, ainda sem documento validado |
| `PROCESSING` | Há documento no meio da análise |
| `UP_TO_DATE` | Tudo validado, sem pendência |
| `ATTENTION` | Divergência, vencimento próximo ou parecer com ressalva |
| `EXPIRED` | Renovação vencida |
| `RENEWING` | Há uma solicitação de renovação em curso |
`RENEWING` é situação própria e não um `ATTENTION` qualquer: a pergunta "quem está sendo renovado agora?" é a que a operação filtra, e misturá-la com divergência de documento escondia as duas.
## Documentos do cadastro
Cada arquivo entregue vira um documento do cadastro, com **versão** e marca de vigência (`isCurrent`). Nada é sobrescrito: a alteração contratual nova não apaga a antiga, ela vira a versão vigente e a anterior continua consultável.
O ciclo de vida de um documento está em [Análise documental](/onboarding/analise-documental).
### Dados básicos oficiais
O cadastro carrega os dados oficiais do CNPJ ou CPF (razão social, situação cadastral, quadro societário) e pode ser atualizado sob demanda. É contra esses dados que os checks de titularidade confrontam o que foi lido no arquivo.
## Dados declarados pelo cliente
Tudo o que o cliente respondeu nos [formulários](/onboarding/formularios) das solicitações daquele cadastro fica no próprio cadastro, agrupado por formulário: campos prontos e campos livres. Só entra resposta enviada; a sugestão que ninguém confirmou não é declaração do cliente.
* **A resposta mais recente vale.** Quando o mesmo campo foi respondido de novo, as respostas anteriores ficam no histórico do campo, e a tela marca **Alterado**.
* **Contestação fica marcada.** O campo em que a pessoa discordou do dado oficial sugerido aparece como **Contestado**.
* **Cada campo tem o nome da variável da esteira.** É a chave `form..`, a mesma dos [dados de entrada](/esteiras/dados-de-entrada) que fórmulas e regras usam. No toolbox, clicar no nome copia.
No cadastro de pessoa física, a tela também mostra onde ela foi **declarada como sócia** nos formulários de empresas.
## Quadro societário
Para um cadastro `COMPANY`, a plataforma monta o quadro de sócios e administradores juntando quatro origens:
| Origem | Rótulo na tela | De onde veio |
| - | - | - |
| `QSA_OFICIAL` | **Receita** | Quadro societário da fonte oficial |
| `DOCUMENT_EXTRACTION` | **Documento** | Lido do contrato social, estatuto, ata ou certidão |
| `FORM` | **Formulário** | Declarado pelo cliente no formulário de uma solicitação |
| `MANUAL` | **Equipe** | Criado por um operador |
O formulário só preenche lacuna: completa o CPF de quem a fonte oficial mostra mascarado e acrescenta o sócio que o quadro ainda não tem. O que o cliente declarou e não casou com ninguém do quadro aparece à parte, em **Informados no formulário e fora do quadro**, em vez de sumir.
### Corrigir um sócio
Um operador pode corrigir nome, vínculo, participação e documento de um sócio. A correção fica guardada como da equipe, e a consulta à fonte oficial **não a sobrescreve** depois. Na tela, o sócio corrigido leva a marca **Corrigido pela equipe**.
### Cadastro próprio do sócio
Uma pessoa do quadro pode ganhar cadastro próprio (o CPF dela vira um `Registry` `PERSON`), ligado ao da empresa. É assim que se pede documento de sócio sem sair do dossiê da empresa.
## Contatos
Cada pessoa (o titular do cadastro e cada sócio) tem uma lista de contatos guardada pelo **documento** dela, e não por solicitação. A lista junta três origens:
| Origem | Rótulo na tela | De onde veio |
| - | - | - |
| `FORM` | **Formulário** | O cliente informou num formulário (o e-mail e o telefone de cada sócio, ou os do próprio titular) |
| `OPERATOR` | **Incluído pela equipe** | Alguém da sua organização digitou |
| `HISTORY` | **Histórico de envios** | O contato já recebeu uma solicitação antes |
O mesmo par de e-mail e telefone é o mesmo contato, venha de onde vier.
**Quem recebe os envios automáticos** (como a [etapa Solicitação](/esteiras/etapas#solicitação) da esteira e o quadro de partes do contrato) é o primeiro da lista: o contato **fixado** pela equipe, quando existe um; sem escolha, o mais recente. A tela diz o motivo ao lado do contato que recebe.
Remover um contato guardado o tira da lista, e o mesmo contato vindo de envios anteriores some junto. Um contato que só existe no histórico pode ser **ocultado**. Nos dois casos, ele só volta se for usado num envio depois disso.
Como o formulário grava o contato de cada sócio na hora da resposta, a esteira já encontra o sócio declarado antes de ele receber a primeira solicitação.
## Renovação periódica
O cadastro tem plano de renovação: a data em que ele precisa ser revisitado e para quem o pedido vai. A renovação pode vir da política (`POLICY`) ou ser uma exceção manual daquele cadastro (`MANUAL`), com data e contatos próprios. Sem contatos definidos no cadastro, a renovação vai para os destinatários da última solicitação enviada.
Quando a renovação dispara, ela cria uma solicitação com `origin: RENEWAL`, e o cadastro entra em `RENEWING`.
Pausar a renovação é reversível com um clique e mantém o dossiê inteiro.
## Trilha de auditoria e integridade
Toda ação sobre o cadastro e sobre cada documento entra numa trilha **append-only**: quem fez, quando, com que id de evento. Não existe update nem delete de linha de trilha, correção se faz gravando uma linha nova.
Cada parecer emitido é selado com um `contentHash`. A rota de integridade recalcula o hash do conteúdo armazenado e compara com o selo gravado na trilha, o que responde "este parecer é o mesmo que foi emitido na época?" sem depender de confiança no banco.
## Remoção
Cadastro nunca é apagado de verdade: a remoção é lógica (soft delete). E remover exige permissão própria (`can-remove-registry`), concedida a **Administrador**, **Owner**, **Superuser** e **Gestor de Crédito**. Analista e coordenador não removem.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.