Caminho

Como duas entidades se ligam — e se essa ligação significa alguma coisa.

GET /api/v1/caminho

Caminho

cURL

curl --request GET \
  --url https://api.example.com/api/v1/caminho

de · string · required

CNPJ (8 ou 14 dígitos) ou id de pessoa.

para · string · required

CNPJ (8 ou 14 dígitos) ou id de pessoa.

curl "https://brain.pandoragraph.com/api/v1/caminho?de=00000000&para=00360305" \
  -H "Authorization: Bearer pk_sua_chave"

Resposta real, Banco do Brasil contra Caixa Econômica:

{
  "dado": {
    "conectadas": false,
    "caminhoExiste": true,
    "ligacao": "geografica",
    "relevante": false,
    "porque": "o caminho passa só por mesma região, que não liga uma entidade a outra: milhões de empresas compartilham isso",
    "saltos": 4,
    "caminho": [
      { "id": "00000000",       "tipo": "CompanyRoot" },
      { "id": "00000000444235", "tipo": "CompanyEstablishment" },
      { "id": "2611606",        "tipo": "Municipality" },
      { "id": "00360305102888", "tipo": "CompanyEstablishment" },
      { "id": "00360305",       "tipo": "CompanyRoot" }
    ]
  }
}

Existe caminho, tem só 4 saltos, e ele não significa nada: os dois bancos têm agência na mesma cidade. É por isso que conectadas vem false.

Agora o caso que interessa. Mesma pergunta, outro par — Petrobras contra Caixa Econômica:

curl "https://brain.pandoragraph.com/api/v1/caminho?de=33000167&para=00360305" \
  -H "Authorization: Bearer pk_sua_chave"

{
  "dado": {
    "conectadas": true,
    "caminhoExiste": true,
    "ligacao": "societaria",
    "relevante": true,
    "porque": "as duas se ligam por sócio em comum",
    "saltos": 4,
    "caminho": [
      { "id": "33000167",         "tipo": "CompanyRoot" },
      { "id": "***650110**::████", "tipo": "Person" },
      { "id": "00743065",         "tipo": "CompanyRoot" },
      { "id": "***424857**::████", "tipo": "Person" },
      { "id": "00360305",         "tipo": "CompanyRoot" }
    ],
    "arestas": ["PARTNER_OF", "PARTNER_OF", "PARTNER_OF", "PARTNER_OF"]
  }
}

Os dois têm 4 saltos. O de cima passa por município e não liga ninguém a ninguém; este passa por duas pessoas que são sócias das empresas na ponta, e é uma cadeia societária de verdade. Só ligacao e relevante separam os dois — o número de saltos é igual.

O nome das pessoas vem preenchido na resposta da API, dentro do id, no formato ***650110**::NOME COMPLETO. Aqui na documentação ele está tarjado porque esta página é pública e são pessoas reais; o CPF já vem mascarado da própria fonte.

E vale a regra de sempre: constar no quadro societário é o que o registro afirma, não titularidade — e o casamento é por nome, então homônimo é possível.

Leia conectadas, não saltos

Duas empresas quaisquer se ligam em pouquíssimos saltos por natureza jurídica, CNAE ou município. O caminho existe e não significa nada.

Estes dois caminhos reais têm o mesmo tamanho e a mesma forma:

CompanyRoot → LegalNature → CompanyRoot     as duas são LTDA
CompanyRoot → Person      → CompanyRoot     a mesma pessoa é sócia das duas

Uma integração que lesse só o número de saltos trataria os dois igual. Por isso conectadas reflete a relevância, não a existência do caminho.

O caso extremo é real e tem 2 saltos — Caixa Econômica contra Correios:

{
  "dado": {
    "conectadas": false,
    "caminhoExiste": true,
    "ligacao": "atributo_comum",
    "relevante": false,
    "porque": "o caminho passa só por mesma classificação cadastral, que não liga uma entidade a outra: milhões de empresas compartilham isso",
    "saltos": 2,
    "caminho": [
      { "id": "00360305", "tipo": "CompanyRoot" },
      { "id": "2011",     "tipo": "LegalNature" },
      { "id": "34028316", "tipo": "CompanyRoot" }
    ]
  }
}

Duas empresas a dois saltos uma da outra, e o que as liga é terem a mesma natureza jurídica. Qualquer integração que tratasse “2 saltos” como proximidade acabaria relacionando os Correios com a Caixa.

Tipos de ligação

ligacao	relevante	o que é
societaria	sim	pessoa em comum entre as duas
dinheiro_publico	sim	contrato, licitação, empenho, despesa
eleitoral	sim	doação, candidatura, partido
endereco	sim	mesmo endereço — indício, não prova
geografica	não	mesmo município ou UF
atributo_comum	não	mesma natureza jurídica ou CNAE

caminho[] e arestas[] continuam crus para você auditar a conclusão.

Sem caminho dentro do limite de saltos você recebe 200 com caminhoExiste: false — e isso não prova que não exista ligação, só que não achamos dentro do limite. Base fora do ar é 503, nunca conectadas: false.