Objeto Natural Person

Envia o cadastro de uma pessoa física 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 e depois adicione o que fizer sentido para o seu caso.

Envie dados finais

Os dados enviados devem ser os definitivos. CPF, nome e data de nascimento não devem mudar depois desta chamada — isso garante consistência da base antifraude e uma avaliação realista de risco.

Usa os SDKs de biometria, OCR ou Device Scan?

As chaves devolvidas pelos SDKs entram nos blocos face, documents e source deste payload. Onde cada uma vai — e o que muda em relação a Pessoa Jurídica — está em Dados do SDK (face, documentos e device).

Payload mínimo

Este é o menor corpo aceito pelo POST /onboarding/natural_person.

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

Resposta:

{
  "id": "12345678",
  "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/natural_person

MÉTODO

POST

Query parameters

analyze boolean opcional — padrão true Com true, a sua árvore de decisão é executada e a resposta traz o resultado. Com false, o cadastro é apenas registrado (sem cobrança) e passa a compor o histórico usado em análises futuras — a resposta retorna not_analysed.

Exemplos de requisição

import requests

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

payload = {
    "id": "12345678",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "111.111.111-11"
}

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

response.raise_for_status()
result = response.json()
print(result["analysis_status"])  # automatically_approved

<?php

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

$payload = [
    'id'                => '12345678',
    'registration_date' => '2026-08-07T11:37:15-03:00',
    'document_number'   => '111.111.111-11'
];

$ch = curl_init($baseUrl . '/onboarding/natural_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}");
}

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

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

const payload = {
  id: "12345678",
  registration_date: "2026-08-07T11:37:15-03:00",
  document_number: "111.111.111-11"
};

async function createRegistration() {
  const response = await fetch(
    `${BASE_URL}/onboarding/natural_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;
}

createRegistration();

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 CreateNaturalPerson {

    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": "12345678",
              "registration_date": "2026-08-07T11:37:15-03:00",
              "document_number": "111.111.111-11"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/onboarding/natural_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 CreateNaturalPerson
{
    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 = "12345678",
            registration_date = "2026-08-07T11:37:15-03:00",
            document_number = "111.111.111-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/natural_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/natural_person?analyze=true' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "id": "12345678",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "111.111.111-11"
  }'

Resposta

idstringO mesmo id enviado na requisição.analysis_statusenumResultado da execução da sua árvore de decisão. Veja Dinâmica dos status.reasonstringMotivo da decisão, quando disponível.

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

Resposta assíncrona

Quando a análise demora mais que o esperado, a resposta vem como in_queue ou pending e o resultado final chega por Webhook. Trate esses dois status como "aguardando" — não como recusa.

Campos do objeto

Obrigatórios

idstringobrigatórioIdentificador da análise no seu sistema. 1 a 50 caracteres. Deve ser único por requisição — um id repetido retorna HTTP 409.registration_datedatetimeobrigatórioData e hora do cadastro, com fuso horário. Veja o formato aceito.document_numberstringobrigatórioCPF com pontuação, no formato XXX.XXX.XXX-XX. Exatamente 14 caracteres.

Identificação

registration_idstringopcionalIdentificador do cadastro no seu sistema. Use o mesmo valor em análises diferentes do mesmo cadastro para agrupá-las. Quando omitido, assume o valor de id.namestringopcionalNome completo. 1 a 500 caracteres.birthdatedateopcionalData de nascimento no formato YYYY-MM-DD.genderenumopcionalmale ou female.nationalitystringopcionalPaís em ISO 3166-1 alpha-3, 3 letras maiúsculas. Ex.: BRA.mother_namestringopcionalNome completo da mãe. 1 a 500 caracteres. Sinal relevante para validação em bureaus.father_namestringopcionalNome completo do pai. 1 a 500 caracteres.

Perfil financeiro

monthly_incomeintegeropcionalRenda mensal bruta em centavos. R$ 5.000,00 → 500000.declared_assetsintegeropcionalPatrimônio declarado em centavos.occupationstringopcionalProfissão. 1 a 100 caracteres.is_us_personbooleanopcionalIndica se a pessoa tem obrigações fiscais nos EUA (relevante para FATCA).pleaded_pepbooleanopcionalIndica se a pessoa se declarou politicamente exposta (PEP).

Contato e localização

emailsarrayopcionalLista de objetos Email. Dentro de cada item, apenas email é obrigatório.phonesarrayopcionalLista de objetos Phone. Se enviado, cada item exige international_dial_code, area_code e number.addressobjectopcionalObjeto Address. Se enviado, apenas postal_code é obrigatório dentro dele.documentsobjectopcionalDocumentos de identificação (RG, CNH, passaporte e outros). As chaves de OCR entram aqui — veja Dados do SDK e Objetos compartilhados.faceobjectopcionalDados de validação facial. A chave devolvida pelo SDK de biometria entra aqui — veja Dados do SDK.sourceobjectopcionalOrigem da requisição (canal, plataforma, IP, sessão). É aqui que entra o session_id do Device Scan — veja Dados do SDK.

Classificação e extras

analysis_typestringopcionalTipo de análise a aplicar, quando sua conta tem mais de um fluxo configurado. Combine com o suporte antes de usar.client_categorystringopcionalCategoria do cliente na sua plataforma ou programa de fidelidade. 1 a 100 caracteres.partnership_keystringopcionalIdentificador da parceria associada ao cadastro. 1 a 500 caracteres.related_account_typestringopcionalTipo de conta relacionada ao cadastro. 1 a 50 caracteres.vehicle_platestringopcionalPlaca de veículo associada ao cadastro. 1 a 50 caracteres.custom_dataobjectopcionalCampos personalizados da sua conta. Requer um schema previamente cadastrado pela QI Tech — veja o aviso abaixo.

Payload completo
{
  "id": "12345678",
  "registration_id": "cad-98765",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "analysis_type": "default",
  "client_category": "Premium User",
  "name": "John Sample",
  "document_number": "111.111.111-11",
  "birthdate": "1992-09-15",
  "gender": "male",
  "nationality": "BRA",
  "mother_name": "Maria Sample",
  "father_name": "John Sample",
  "monthly_income": 500000,
  "declared_assets": 7500000,
  "occupation": "Teacher",
  "is_us_person": false,
  "pleaded_pep": false,
  "emails": [
    {
      "email": "johnsample@test.com"
    }
  ],
  "documents": {
    "rg": {
      "number": "4.366.477-8",
      "issuer": "II",
      "issuer_state": "PR",
      "issuance_date": "2002-01-12"
    },
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "first_issuance_date": "2011-03-21",
      "issuance_date": "2016-06-29",
      "expiration_date": "2031-06-25",
      "category": "AB"
    }
  },
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Bairro do Exemplo",
    "city": "Aparecida de Goiânia",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000",
    "country": "BRA"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile"
    }
  ],
  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
    "os_version": "14"
  },
  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
}

Campos não previstos são rejeitados

O schema usa additionalProperties: false. Qualquer campo fora dos listados acima faz a requisição retornar HTTP 400, mesmo que o resto do payload esteja correto.

custom_data exige schema próprio

custom_data é validado contra um schema específico da sua empresa, registrado pela QI Tech. Se você enviar esse campo sem ter o schema cadastrado, a resposta é HTTP 400 com a mensagem "Custom data not available for you account". Fale com o suporte antes de usar.

Formatos de campo

Formato de `registration_date`

Formato ISO 8601 com fuso horário obrigatório. O validador aceita offsets terminados em :00 ou :30, ou o sufixo Z:

2026-08-07T11:37:15-03:00          ✅
2026-08-07T11:37:15.123456-03:00   ✅  fração de 1 a 6 dígitos
2026-08-07T14:37:15Z               ✅  UTC
2026-08-07T11:37:15                ❌  sem fuso horário
2026-08-07T11:37:15-03:15          ❌  offset não permitido

`document_number` — CPF

Deve ir com pontuação: XXX.XXX.XXX-XX, exatamente 14 caracteres. Enviar apenas dígitos (11111111111) retorna HTTP 400.

`postal_code` — CEP

Dentro de address, o CEP exige o formato XXXXX-XXX (com hífen). 00000000 é rejeitado.

Valores monetários

monthly_income e declared_assets são inteiros em centavos de reais. Multiplique por 100: R$ 5.000,00 → 500000.

Enumeradores

`gender`

Valor	Significado
`male`	Masculino
`female`	Feminino

`phones[].type`

Valor	Significado
`mobile`	Celular
`residential`	Residencial
`commercial`	Comercial

`face.type`

Valor	Significado
`zaig_sdk`	Captura via SDK da QI Tech (use `registration_key`)
`base_64`	Imagem enviada diretamente no campo `image`

Para analysis_status, client_status e risk_level, veja Dinâmica dos status.

Testando no Sandbox

No Sandbox a decisão é determinística, definida pelo primeiro dígito do CPF:

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 físicas no ambiente de Sandbox.

Erros

Status	Situação	Como resolver
400	Campo obrigatório ausente, formato inválido, enum fora da lista ou campo não previsto.	Veja a `description` da resposta, que aponta o campo.
400	`custom_data` sem schema cadastrado.	Solicite o cadastro do schema ao suporte.
401	Header `Authorization` ausente ou API Key desativada.	Verifique a chave.
403	API Key inválida.	Confirme a chave com o suporte.
409	`id` já utilizado.	Gere um `id` único por requisição.
500	Erro interno.	Nossos especialistas são notificados automaticamente.

Lista completa em Status HTTP.

Checklist de integração

POST /onboarding/natural_person com o payload mínimo retornando 200 no Sandbox.
id único por requisição (teste o 409 reenviando o mesmo id).
registration_id estável para agrupar análises do mesmo cadastro.
CPF com pontuação e CEP com hífen.
Valores monetários em centavos.
in_queue e pending tratados como "aguardando", não como recusa.
Webhook configurado para receber o resultado assíncrono.

Objeto Natural Person

Payload mínimo​

Enviar um cadastro​

Query parameters​

Exemplos de requisição​

Resposta​

Campos do objeto​

Obrigatórios​

Identificação​

Perfil financeiro​

Contato e localização​

Classificação e extras​

Formatos de campo​

Formato de registration_date​

document_number — CPF​

postal_code — CEP​

Valores monetários​

Enumeradores​

gender​

phones[].type​

face.type​

Testando no Sandbox​

Erros​

Checklist de integração​