> ## Documentation Index > Fetch the complete documentation index at: https://docs.jusfy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Consulta a árvore de relacionamentos > Retorna a rede de relacionamentos de um **CPF ou CNPJ**. Para **CPF**, os dados cadastrais do titular (nome, filiação, nascimento, contatos e endereços) mais os parentes, os sócios e as empresas dele. Para **CNPJ**, os dados cadastrais da empresa mais os relacionamentos societários em **dois níveis** (sócios e empresas do 1º nível, e os deles no 2º). É a consulta mais demorada da API: são vários fornecedores encadeados por requisição. Prever até **4 minutos** de espera. ## OpenAPI ````yaml /openapi/legado.json post /api/consultas/relacionamentos openapi: 3.0.0 info: title: Calculadoras Jusfy API description: >- Rotas sem versão (`/api/...`). Continuam funcionando, mas a versão atual da API é a v1 (`/api/v1`): para integrações novas, use a v1 e siga o [guia de migração](https://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado). A política de versionamento e depreciação está na [política de versionamento](https://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado#pol%C3%ADtica-de-versionamento). version: legacy contact: {} servers: - url: https://api.jusfy.dev/calculators security: [] tags: - name: Calculadoras description: >- Execução das calculadoras jurídicas e consulta dos índices de correção. Cada cálculo recebe um payload, retorna o resultado processado e exige API key no header `x-api-key`. - name: Consultas description: >- Consultas de dados (veículos, condutores e documentos). Cada consulta recebe o documento, retorna os dados encontrados e exige API key no header `x-api-key`. A maioria responde na mesma requisição; o **rastreamento veicular** e o **buscador processual** são assíncronos — devolvem `202` com um protocolo e entregam o resultado por webhook e/ou pelo `GET` do protocolo. - name: JusScore description: >- Consulta de processos judiciais por CPF/CNPJ, com score de risco consolidado e a lista detalhada dos processos. É assíncrona: o POST inicia a consulta e o GET devolve o resultado quando pronto. Exige API key no header `x-api-key`. - name: Consumo description: >- Consumo da própria API key: quantas chamadas cada produto recebeu num período, separando as cobradas das não cobradas. Não exige escopo; exige API key no header `x-api-key`. - name: Health description: >- Verificações de disponibilidade do serviço (liveness e readiness). Rotas abertas, sem autenticação. paths: /api/consultas/relacionamentos: post: tags: - Consultas summary: Consulta a árvore de relacionamentos description: >- Retorna a rede de relacionamentos de um **CPF ou CNPJ**. Para **CPF**, os dados cadastrais do titular (nome, filiação, nascimento, contatos e endereços) mais os parentes, os sócios e as empresas dele. Para **CNPJ**, os dados cadastrais da empresa mais os relacionamentos societários em **dois níveis** (sócios e empresas do 1º nível, e os deles no 2º). É a consulta mais demorada da API: são vários fornecedores encadeados por requisição. Prever até **4 minutos** de espera. operationId: QueriesController_relacionamentos[0] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RelationshipTreeQueryDto' responses: '200': description: >- **O formato depende do documento consultado**: CPF devolve `personal_data` (o exemplo abaixo), CNPJ devolve `company_data`, com outro conjunto de campos — nunca os dois, e nunca nenhum (sem dado é erro). Datas vêm em **`DD/MM/AAAA`**, não em ISO. Pontos de atenção, todos confirmados em captura real: (1) em `business_partners`/`companies`, `relationship_end_date` pode ser a string **`Atual`** no lugar de uma data, quando o vínculo está vigente, e `relationship_type` vem **cru do fornecedor, em inglês** (ex.: `OWNER`); (2) `addresses[].address` costuma começar com a string literal **`"null "`** — o campo junta tipo de logradouro + endereço, e o tipo falta na maioria dos cadastros (na captura, oito de dez endereços); limpe o prefixo antes de exibir; (3) `addresses[].zipcode` vem **`number` em alguns itens e `string` em outros, no mesmo array**; (4) `relatives` só traz dez tipos de parentesco, já traduzidos para pt-BR (`MÃE`, `FILHO(a)`…) — o que o fornecedor manda fora dessa lista é descartado —, o `document` do parente **pode vir vazio**, e a mãe aparece duas vezes (aqui e em `mother_name`); (5) `age` vem `0` também quando **não** foi possível calcular a idade. No CNPJ, `relationships.has_more_relationships: true` significa que havia mais de 100 relacionamentos de 1º nível e as listas foram **truncadas em 100**, e `relationship_end_date` de cada vínculo é **sempre `null`** — quem indica vínculo encerrado é `is_finished`. content: application/json: schema: type: object example: statusCode: 200 message: Consulta concluída com sucesso timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/relacionamentos result: personal_data: document: '52998224725' document_type: CPF name: MARIA DE SOUZA SILVA mother_name: ANTONIA ALVES DE SOUZA birthdate: 12/12/1995 age: 30 gender: F phones: - phone: (61) 991234567 - phone: (61) 32654987 - phone: (61) 998765432 emails: - email: maria.silva@exemplo.com.br addresses: - address: null QD 12 CJ O C 12 C 1 2 neighborhood: PARANOA city: BRASILIA state: DF zipcode: 71571215 - address: null QD 31 CJ H CS 25 neighborhood: PARANOA city: BRASILIA state: DF zipcode: 71573108 - address: ' QD 20 1' neighborhood: PARANOA city: BRASILIA state: DF zipcode: '71572020' relatives: - document: '' name: ANTONIA ALVES DE SOUZA relationship_type: MÃE business_partners: [] companies: - document: '11222333000181' name: 11.222.333 MARIA DE SOUZA SILVA relationship_start_date: 26/05/2023 relationship_end_date: Atual relationship_type: OWNER '400': description: >- Documento inválido. `message` é a **lista** de erros de validação desta API (campo + motivo), diferente dos demais erros, em que é uma string. content: application/json: schema: example: statusCode: 400 code: invalid_request message: - document deve ser um CPF ou CNPJ válido requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/relacionamentos '401': description: >- API key ausente ou que não pertence a nenhum cliente (`code: invalid_api_key`). A `message` diz qual dos dois. content: application/json: examples: missing: summary: Key ausente value: statusCode: 401 message: Missing API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} invalid: summary: Key inválida value: statusCode: 401 message: Invalid API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} '403': description: >- Acesso negado. Dois motivos, distinguidos pelo `code`: o cliente não está ativo (`inactive_client`), ou a API key não tem o escopo deste produto (`insufficient_scope`, com o escopo na `message`). A liberação de produtos é feita pela equipe Jusfy. content: application/json: examples: inactive_client: summary: Cliente não ativo value: statusCode: 403 message: Client is not active code: inactive_client requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} insufficient_scope: summary: Sem o escopo do produto value: statusCode: 403 message: 'Missing scope: ' code: insufficient_scope requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} '404': description: >- CPF válido, mas sem dados cadastrais localizados — sem eles não há árvore a montar. **Só ocorre para CPF**: no CNPJ, documento sem dado chega como `502`. content: application/json: schema: example: statusCode: 404 code: no_data_found message: Nenhum dado encontrado para o documento informado. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/relacionamentos '422': description: >- Consulta recusada. Além do payload rejeitado pelo provedor, cobre o caso de **CPF de menor de idade**, que o provedor de relacionamentos econômicos só atende com a data de nascimento — não suportada nesta API. content: application/json: schema: example: statusCode: 422 code: payload_rejected message: >- Documento pertence a menor de idade; a data de nascimento é obrigatória. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/relacionamentos '429': description: >- Limite de requisições por minuto do cliente neste produto excedido. `Retry-After` diz em quantos segundos a janela vira. Toda resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. content: application/json: schema: example: statusCode: 429 code: rate_limit_exceeded message: >- Rate limit exceeded for consultas.cnh:execute: 60 requests per minute. Retry in 42s. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/consultas/cnh '502': description: >- Erro no provedor da consulta. `message` identifica o provedor que falhou quando essa informação está disponível. Diferente do `503`, não há garantia de que repetir a consulta resolva. content: application/json: schema: example: statusCode: 502 code: upstream_error message: Erro ao consultar o fornecedor de árvore de relacionamentos. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/relacionamentos '504': description: Tempo limite ao falar com o provedor da consulta. content: application/json: schema: example: statusCode: 504 code: upstream_timeout message: Query provider timed out requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/relacionamentos security: - api-key: [] components: schemas: RelationshipTreeQueryDto: type: object properties: document: type: string description: >- CPF ou CNPJ do titular, com ou sem máscara. Separadores (incluindo a barra do CNPJ) são aceitos e ignorados. O dígito verificador é validado antes da consulta. **O formato do resultado depende do documento**: CPF devolve `personal_data`, CNPJ devolve `company_data`. example: '52998224725' required: - document securitySchemes: api-key: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.