> ## 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.

# Árvore Societária

> Para descobrir de quem pedir documento de sócio, e de onde veio cada pessoa.

### Quando usar

Para descobrir de quem pedir documento de sócio, e de onde veio cada pessoa.

### A origem importa

| `source` | De onde veio |
| - | - |
| `QSA_OFICIAL` | Quadro societário da fonte oficial. O CPF vem mascarado |
| `DOCUMENT_EXTRACTION` | Lido de contrato, estatuto, ata ou certidão |
| `MANUAL` | Criado por um operador |
| `FORM` | Declarado pelo cliente num formulário de solicitação |

`layer` distingue o quadro direto (`1`) do sócio da sócia pessoa jurídica (`2`).

A resposta vem em `persons`. Cada pessoa traz `editedFields`, os campos que alguém da sua equipe corrigiu (a atualização do quadro oficial não passa por cima deles), e `contact`, o contato guardado que recebe os envios. Para corrigir um sócio ou mexer nos contatos, veja [Pessoas, contatos e dados declarados](/api-reference/onboarding/pessoas-e-contatos).

<Note>
  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).
</Note>


## OpenAPI

````yaml get /v1/registry/{id}/persons
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}/persons:
    get:
      tags:
        - registry
      summary: Arvore societaria do cadastro
      description: >
        Socios e administradores do cadastro, por camada e da maior participacao
        para a menor, com a

        origem de cada um: QSA_OFICIAL (quadro societario da fonte oficial),
        DOCUMENT_EXTRACTION (lido

        de contrato, estatuto, ata ou certidao), MANUAL (criado por um operador)
        ou FORM (declarado

        pelo cliente num formulario de solicitacao).


        `editedFields` lista os campos que um operador corrigiu; a atualizacao
        do quadro oficial nao

        passa por cima deles. `contact` e o primeiro contato guardado da pessoa
        (o preferido, senao o

        mais recente), ou null.


        E a base para pedir documento de socio: cada pessoa pode ganhar cadastro
        proprio.
      operationId: RegistryController_persons
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
          description: Id do cadastro.
      responses:
        '200':
          description: >-
            Pessoas com nome, documento, papel, participacao, origem, campos
            corrigidos e o primeiro contato guardado, dentro de `persons`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  persons:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegistryPerson'
              example:
                persons:
                  - id: 6612a7f30000000000000021
                    registryId: 6612a7f30000000000000001
                    entityType: PERSON
                    document: '52998224725'
                    maskedDocument: null
                    name: CARLOS EDUARDO SILVA
                    role: Sócio administrador
                    sharePercent: 60
                    layer: 1
                    parentPersonId: null
                    isBeneficialOwner: true
                    source: FORM
                    linkedRegistryId: null
                    editedFields: []
                    contact:
                      name: CARLOS EDUARDO SILVA
                      email: carlos@aurora.com.br
                      phone: '51999998888'
                      source: FORM
                      preferred: false
                      lastUsedAt: '2026-09-05T14:20:00.000Z'
                  - id: 6612a7f30000000000000022
                    registryId: 6612a7f30000000000000001
                    entityType: PERSON
                    document: null
                    maskedDocument: '***982247**'
                    name: MARIA HELENA SOUZA
                    role: Sócio
                    sharePercent: 38
                    layer: 1
                    parentPersonId: null
                    isBeneficialOwner: true
                    source: QSA_OFICIAL
                    linkedRegistryId: null
                    editedFields: []
                    contact: null
        '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 "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/persons'
            \
              --header 'Authorization: Bearer <token>'
        - lang: JavaScript
          label: Node
          source: >
            const resposta = await
            fetch("https://gyra-core.gyramais.com.br/v1/registry/6612a7f30000000000000001/persons",
            {
              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/persons",
                headers={"Authorization": f"Bearer {token}"},
            )

            dados = resposta.json()
components:
  schemas:
    RegistryPerson:
      type: object
      properties:
        id:
          type: string
        registryId:
          type: string
        entityType:
          type: string
          enum:
            - COMPANY
            - PERSON
        document:
          type: string
          nullable: true
        maskedDocument:
          type: string
          nullable: true
          description: O QSA da Receita devolve o CPF de pessoa fisica mascarado.
        name:
          type: string
        role:
          type: string
          nullable: true
        sharePercent:
          type: number
          nullable: true
        layer:
          type: integer
          description: 1 = quadro societario direto; 2 = socio da socia pessoa juridica.
        parentPersonId:
          type: string
          nullable: true
        isBeneficialOwner:
          type: boolean
        source:
          type: string
          enum:
            - QSA_OFICIAL
            - DOCUMENT_EXTRACTION
            - MANUAL
            - FORM
          description: >-
            De onde a pessoa veio. FORM = declarada pelo cliente num formulario
            de solicitacao.
        sourceDocumentId:
          type: string
          nullable: true
          description: >-
            Documento de onde a pessoa foi lida, quando source e
            DOCUMENT_EXTRACTION.
        editedFields:
          type: array
          items:
            type: string
            enum:
              - name
              - role
              - sharePercent
              - document
          description: >-
            Campos que um operador corrigiu. A atualizacao do quadro oficial e a
            extracao nao passam por cima deles.
        contact:
          type: object
          nullable: true
          description: >-
            Primeiro contato guardado da pessoa (o preferido, senao o mais
            recente). null sem documento completo ou sem contato.
          properties:
            name:
              type: string
            email:
              type: string
              nullable: true
            phone:
              type: string
              nullable: true
            source:
              type: string
              enum:
                - FORM
                - OPERATOR
                - HISTORY
            preferred:
              type: boolean
            lastUsedAt:
              type: string
              format: date-time
        linkedRegistryId:
          type: string
          nullable: true
          description: Cadastro proprio da pessoa, quando ja existe.
    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.