Objeto Legal Person

Envia o cadastro de uma pessoa jurídica para análise de fraude e KYC. A QI Tech executa a sua árvore de decisão contra os dados enviados e devolve em analysis_status o resultado que a sua política determinou — veja Dinâmica dos status.

Comece pelo payload mínimo

São apenas 3 campos obrigatórios. Vá direto para Payload mínimo.

Onde entram as chaves do SDK

Em Legal Person, face e documentos de identidade ficam dentro de legal_representatives[], e o source.session_id fica na raiz. Essa é a principal diferença em relação a Pessoa Física — veja Integrando os dados do SDK.

Payload mínimo

Payload mínimo — 3 campos obrigatórios
{
  "id": "87654321",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "11.111.111/0001-11"
}

Resposta:

{
  "id": "87654321",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}

Campos adicionais

Quanto mais dados forem enviados, mais validações são possíveis de se fazer no motor de regras.

Enviar um cadastro

ENDPOINT

/onboarding/legal_person

MÉTODO

POST

Query parameters

analyze boolean opcional — padrão true Com true, a sua árvore de decisão é executada. Com false, o cadastro é apenas registrado (sem cobrança) e a resposta retorna not_analysed.

import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"

payload = {
    "id": "87654321",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "11.111.111/0001-11"
}

response = requests.post(
    f"{BASE_URL}/onboarding/legal_person",
    params={"analyze": "true"},
    json=payload,
    headers={"Authorization": API_KEY},
    timeout=30,
)

response.raise_for_status()
print(response.json()["analysis_status"])

<?php

$baseUrl = 'https://api.sandbox.caas.qitech.app';
$apiKey  = 'YOUR_API_KEY';

$payload = [
    'id'                => '87654321',
    'registration_date' => '2026-08-07T11:37:15-03:00',
    'document_number'   => '11.111.111/0001-11'
];

$ch = curl_init($baseUrl . '/onboarding/legal_person?analyze=true');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Onboarding retornou HTTP {$status}: {$body}");
}

echo json_decode($body, true)['analysis_status'];

const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";

const payload = {
  id: "87654321",
  registration_date: "2026-08-07T11:37:15-03:00",
  document_number: "11.111.111/0001-11"
};

async function createLegalPerson() {
  const response = await fetch(
    `${BASE_URL}/onboarding/legal_person?analyze=true`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY
      },
      body: JSON.stringify(payload)
    },
  );

  if (!response.ok) {
    throw new Error(`Onboarding retornou HTTP ${response.status}`);
  }

  const result = await response.json();
  console.log(result.analysis_status);
  return result;
}

createLegalPerson();

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CreateLegalPerson {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "id": "87654321",
              "registration_date": "2026-08-07T11:37:15-03:00",
              "document_number": "11.111.111/0001-11"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/onboarding/legal_person?analyze=true"))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(30))
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Onboarding retornou HTTP " + response.statusCode() + ": " + response.body());
        }

        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class CreateLegalPerson
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";

    public static async Task Main()
    {
        var payload = new
        {
            id = "87654321",
            registration_date = "2026-08-07T11:37:15-03:00",
            document_number = "11.111.111/0001-11"
        };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            $"{BaseUrl}/onboarding/legal_person?analyze=true", content);

        var body = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
        {
            throw new InvalidOperationException(
                $"Onboarding retornou HTTP {(int)response.StatusCode}: {body}");
        }

        Console.WriteLine(body);
    }
}

curl -X POST \
  'https://api.sandbox.caas.qitech.app/onboarding/legal_person?analyze=true' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "id": "87654321",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "11.111.111/0001-11"
  }'

Campos do objeto

Obrigatórios

idstringobrigatórioIdentificador da análise. 1 a 50 caracteres. Único por requisição — repetido retorna HTTP 409.registration_datedatetimeobrigatórioData e hora do cadastro, com fuso horário. Mesmo formato de Natural Person.document_numberstringobrigatórioCNPJ com pontuação, no formato XX.XXX.XXX/XXXX-XX. 18 caracteres.

Dados da empresa

registration_idstringopcionalIdentificador do cadastro no seu sistema. Assume o valor de id quando omitido.legal_namestringopcionalRazão social.trading_namestringopcionalNome fantasia.foundation_datedateopcionalData de constituição no formato YYYY-MM-DD.websitestringopcionalSite da empresa. Até 10.000 caracteres.activitystringopcionalDescrição da atividade econômica.activity_codestringopcionalCNAE no formato XX.XX-X-XX. Exatamente 10 caracteres.merchant_category_codeenumopcionalMCC de 4 dígitos conforme ISO 18245. Aceita apenas códigos da lista oficial.tierstringopcionalPorte da empresa. Até 10 caracteres. Ex.: mei, epp, me.annual_revenuesintegeropcionalFaturamento anual em centavos.monthly_revenuesintegeropcionalFaturamento mensal em centavos.

Contato e localização

emailsarrayopcionalLista de objetos Email. Cada item exige email.phonesarrayopcionalLista de objetos Phone. Cada item exige international_dial_code, area_code e number.addressobjectopcionalObjeto Address. Se enviado, exige postal_code.documentsobjectopcionalDocumentos da empresa. Aceita apenas ie, company_statute e proof_of_address — veja o aviso abaixo, Dados do SDK e Objetos compartilhados.sourceobjectopcionalOrigem da requisição. É aqui na raiz que o session_id do Device Scan deve ser enviado — veja Dados do SDK.

Quadro societário

legal_representativesarrayopcionalLista de objetos LegalRepresentative. É dentro deste array que entram face e documentos de identidade (RG, CNH) — veja Dados do SDK.partnersarrayopcionalLista de objetos Partner com os sócios da empresa.final_beneficiariesarrayopcionalLista de objetos FinalBeneficiary com os beneficiários finais.

Classificação e extras

analysis_typestringopcionalTipo de análise, quando sua conta tem mais de um fluxo configurado.client_categorystringopcionalCategoria do cliente na sua plataforma.partnership_keystringopcionalIdentificador da parceria associada.related_account_typestringopcionalTipo de conta relacionada.custom_dataobjectopcionalCampos personalizados. Requer schema previamente cadastrado pela QI Tech.

Payload completo
{
  "id": "87654321",
  "registration_id": "cad-pj-1234",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "client_category": "Premium Account",
  "legal_name": "Empresa Exemplo LTDA",
  "trading_name": "Barbearia do John",
  "document_number": "11.111.111/0001-11",
  "foundation_date": "1992-09-15",
  "website": "www.exemplo.com.br",
  "activity": "Barber Shops",
  "activity_code": "96.02-5-01",
  "merchant_category_code": "0742",
  "tier": "epp",
  "annual_revenues": 180000000,
  "monthly_revenues": 15000000,
  "emails": [{ "email": "contato@exemplo.com.br" }],
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "postal_code": "04570-140",
    "country": "BRA"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "999999999",
      "type": "commercial"
    }
  ],
  "source": {
    "channel": "web",
    "platform": "web",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },
  "documents": {
    "company_statute": {
      "ocr_key": "d8fa2fb0-5199-47c3-daae-bd8ef03f4ea9"
    },
    "proof_of_address": {
      "document_analysis_id": "e9ab3ac1-62aa-48d4-ebbf-ce9fa14a5fb0"
    }
  },
  "legal_representatives": [
    {
      "id": "rep-001",
      "name": "Maria Sample",
      "document_number": "222.222.222-22",
      "birthdate": "1985-03-22",
      "mother_name": "Ana Sample",
      "pleaded_pep": false,
      "face": {
        "type": "zaig_sdk",
        "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
      },
      "documents": {
        "cnh": {
          "register_number": "05163811694",
          "issuer_state": "SP",
          "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
        }
      }
    }
  ],
  "partners": [
    {
      "name": "Maria Sample",
      "document_number": "222.222.222-22"
    }
  ],
  "final_beneficiaries": [
    {
      "name": "Maria Sample",
      "document_number": "222.222.222-22"
    }
  ]
}

Campos não previstos são rejeitados

O schema usa additionalProperties: false. Qualquer campo fora dos listados retorna HTTP 400.

RG e CNH não vão na raiz

Na raiz de Legal Person, documents aceita apenas ie, company_statute e proof_of_address. Documentos de identidade pertencem ao representante legal, dentro de legal_representatives[].documents. Enviá-los na raiz retorna HTTP 400.

Formatos de campo

`document_number` — CNPJ

Formato XX.XXX.XXX/XXXX-XX, com pontuação, 18 caracteres. Apenas dígitos é rejeitado.

`activity_code` — CNAE

Formato XX.XX-X-XX, exatamente 10 caracteres. Ex.: 96.02-5-01.

`registration_date`

Mesmo formato de Natural Person: ISO 8601 com fuso horário, offset terminado em :00/:30 ou sufixo Z.

Valores monetários

annual_revenues e monthly_revenues são inteiros em centavos. R$ 150.000,00 → 15000000.

Representantes, sócios e beneficiários

Os três arrays aceitam os mesmos campos de identificação de uma pessoa física (name, document_number, birthdate, gender, nationality, mother_name, occupation, emails, phones, address, pleaded_pep).

Somente legal_representatives[] aceita face e documents — é ali que entram as chaves de biometria e OCR do representante. Veja Integrando os dados do SDK.

Testando no Sandbox

A decisão é determinística, definida pelo primeiro dígito do CNPJ:

Primeiro dígito	Resultado
`9`	`automatically_approved`
`8`	`automatically_reproved`
`7`	`pending`
`6`	Análise manual, com aprovação posterior
`5`	Análise manual, com reprovação posterior
`4`	`automatically_challenged`
`0` a `3`	`in_manual_analysis`

Aviso importante

Não utilize dados reais de pessoas jurídicas no ambiente de Sandbox.

Erros

Status	Situação	Como resolver
400	Campo obrigatório ausente, formato inválido ou campo não previsto.	Veja a `description` da resposta.
400	`rg`/`cnh` na raiz de `documents`.	Mova para `legal_representatives[]`.
400	`custom_data` sem schema cadastrado.	Solicite o cadastro ao suporte.
401	Header `Authorization` ausente ou chave desativada.	Verifique a chave.
403	API Key inválida.	Confirme com o suporte.
409	`id` já utilizado.	Gere um `id` único.
500	Erro interno.	Notificação automática à nossa equipe.

Lista completa em Status HTTP.

Checklist de integração

POST /onboarding/legal_person com o payload mínimo retornando 200 no Sandbox.
CNPJ com pontuação e CNAE no formato XX.XX-X-XX.
source.session_id preenchido na raiz (sem isso, o device não aparece na dashboard de PJ).
face e documentos de identidade dentro de legal_representatives[].
Na raiz de documents, apenas ie, company_statute, proof_of_address.
Valores monetários em centavos.
Webhook configurado para o resultado assíncrono.

Objeto Legal Person

Payload mínimo​

Enviar um cadastro​

Query parameters​

Campos do objeto​

Obrigatórios​

Dados da empresa​

Contato e localização​

Quadro societário​

Classificação e extras​

Formatos de campo​

document_number — CNPJ​

activity_code — CNAE​

registration_date​

Valores monetários​

Representantes, sócios e beneficiários​

Testando no Sandbox​

Erros​

Checklist de integração​