Integrando os dados do SDK

Os SDKs da QI Tech (biometria facial, OCR de documentos e Device Scan) não enviam dados direto para a análise cadastral. Cada um devolve uma chave para o seu backend, e é você que anexa essas chaves ao payload de onboarding.

Esta página trata de onde cada chave entra — que é diferente entre Pessoa Física e Pessoa Jurídica.

Bloco	O que carrega	Origem da chave
`face`	Biometria facial	SDK de biometria
`documents`	OCR de documentos	SDK/API de OCR
`source`	Dados de dispositivo e sessão	SDK de Device Scan

A diferença que mais causa retrabalho

Em Pessoa Física, os três blocos ficam na raiz do payload.

Em Pessoa Jurídica, face e documents de identidade ficam dentro de legal_representatives[] — mas o source continua na raiz. Detalhes em Pessoa Jurídica.

Onde cada bloco entra

Bloco	Pessoa Física	Pessoa Jurídica
`source` (`session_id`)	Raiz	Raiz — obrigatório para aparecer na dashboard
`face`	Raiz	Dentro de `legal_representatives[]`
`documents` (RG, CNH, passaporte)	Raiz	Dentro de `legal_representatives[]`
`documents` (`ie`, `company_statute`, `proof_of_address`)	—	Raiz

`source` — Device Scan e `session_id`

O session_id é a chave devolvida pelo SDK de Device Scan. É ele que conecta a análise cadastral aos dados de dispositivo, geolocalização e comportamento coletados no app ou no site.

session_idstringopcional — mas veja o avisoIdentificador da sessão gerado pelo SDK de Device Scan. 1 a 500 caracteres.channelstringopcionalCanal de origem do cadastro. Ex.: app, web, backoffice. 1 a 100 caracteres.platformstringopcionalPlataforma. Ex.: android, ios, web. 1 a 100 caracteres.ipstringopcionalIP de origem. Aceita IPv4 e IPv6. Um valor mal formatado retorna HTTP 400.os_versionstringopcionalVersão do sistema operacional. 1 a 100 caracteres.gps_dataobjectopcionalCoordenadas da captura.

Campos de gps_data:

latnumberopcionalLatitude, entre -90 e 90.lonnumberopcionalLongitude, entre -180 e 180.

source — sempre na raiz, PF e PJ
{
  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
    "os_version": "14",
    "gps_data": {
      "lat": -23.5613,
      "lon": -46.6565
    }
  }
}

Pessoa Jurídica: session_id precisa estar na raiz

Em Legal Person, o source.session_id deve estar no objeto source da raiz do payload — não dentro de legal_representatives[].

Se esse campo não estiver preenchido na raiz, os dados de device não aparecem na dashboard de análise cadastral de PJ. O schema aceita source dentro de legal_representatives[], mas não é de lá que a dashboard de PJ lê a sessão — colocar apenas ali faz o dado ser silenciosamente ignorado na análise.

`face` — biometria facial

typeenumopcionalComo a biometria foi capturada. Define qual dos campos abaixo você deve preencher.registration_keystringopcionalChave devolvida pelo SDK de biometria. Use com type: "zaig_sdk". Formato UUID.imagestringopcionalImagem em Base64. Use com type: "base_64" quando não houver SDK envolvido.

Valores de `type`

Valor	Campo a preencher
`zaig_sdk`	`registration_key`
`base_64`	`image`

face via SDK
{
  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
}

face via Base64
{
  "face": {
    "type": "base_64",
    "image": "iVBORw0KGgoAAAANSUhEUg..."
  }
}

`documents` — OCR

As chaves de OCR (ocr_key, ocr_front_key, ocr_back_key) vêm do SDK/API de OCR e entram dentro do documento correspondente.

Documentos aceitos em Pessoa Física

Na raiz do payload de Natural Person, documents aceita:

Campo	O que é	Chaves aceitas
`rg`	Registro Geral	`ocr_front_key`, `ocr_back_key`, `ocr_key`
`cnh`	Carteira Nacional de Habilitação	`ocr_key`, `ocr_front_key`, `ocr_back_key`
`passport`	Passaporte	`ocr_key` (obrigatório)
`ctps`	Carteira de Trabalho	`ocr_front_key` e `ocr_back_key` (ambos obrigatórios)
`cin_digital`	Carteira de Identidade Nacional digital	`ocr_key`
`national_registry_of_foreigners`	RNE — Registro Nacional de Estrangeiros	`ocr_key`, `ocr_front_key`, `ocr_back_key`
`national_migration_registry`	RNM — Registro Nacional Migratório	`ocr_key`, `ocr_front_key`, `ocr_back_key`
`class_entity_registry`	Carteira de entidade de classe (OAB, CRM…)	`ocr_key` (obrigatório)
`military_registry`	Documento militar	`ocr_key` (obrigatório)
`letter_of_emancipation`	Carta de emancipação	`ocr_key` (obrigatório)
`company_statute`	Contrato social / estatuto	`ocr_key`, `document_analysis_id`
`proof_of_address`	Comprovante de endereço	`document_analysis_id`
`others`	Outros documentos	`ocr_front_key` e `ocr_back_key` (ambos obrigatórios)

Documentos aceitos em Pessoa Jurídica

Na raiz do payload de Legal Person, documents aceita apenas documentos da empresa:

Campo	O que é	Chaves aceitas
`ie`	Inscrição estadual	`ocr_key` — exige o campo `number`
`company_statute`	Contrato social / estatuto	`ocr_key`, `document_analysis_id`
`proof_of_address`	Comprovante de endereço	`document_analysis_id`

RG e CNH não existem na raiz de Legal Person

Documentos de identidade (rg, cnh, passport…) não são aceitos na raiz do payload de PJ — o schema usa additionalProperties: false e a requisição retorna HTTP 400.

Eles pertencem ao representante legal, dentro de legal_representatives[].

Chaves de OCR por documento

As chaves aceitas por documento estão nas tabelas acima. Vale destacar:

Frente e verso: em documentos com dois lados (rg, ctps, others), o padrão é enviar ocr_front_key e ocr_back_key. Em ctps e others os dois são obrigatórios.
Chave única: quando o OCR devolve uma única chave para o documento inteiro, use ocr_key.
document_analysis_id: usado em company_statute e proof_of_address, que passam pela Análise de Documentos e não por OCR de identidade.

Em rg e cnh, o campo issuer_state aceita as siglas de UF em maiúsculas ou minúsculas.

documents com chaves de OCR (PF)
{
  "documents": {
    "rg": {
      "number": "4.366.477-8",
      "issuer": "SSP",
      "issuer_state": "PR",
      "issuance_date": "2002-01-12",
      "ocr_front_key": "a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
      "ocr_back_key": "b6df0d9e-3f77-45a1-b8ec-9b6cd81d2c87"
    },
    "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",
      "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
    }
  }
}

Pessoa Física (Natural Person)

Os três blocos ficam na raiz:

POST /onboarding/natural_person
{
  "id": "12345678",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "111.111.111-11",
  "name": "John Sample",

  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },

  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  },

  "documents": {
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
    }
  }
}

Pessoa Jurídica (Legal Person)

source na raiz; face e documentos de identidade dentro de legal_representatives[]:

POST /onboarding/legal_person
{
  "id": "87654321",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "11.111.111/1111-11",
  "legal_name": "Empresa Exemplo LTDA",

  "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",

      "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"
        }
      }
    }
  ]
}

Por que a biometria fica no representante

A biometria e o documento de identidade pertencem a uma pessoa, não à empresa. Em PJ, quem passa pela validação biométrica é o representante legal — por isso face e documents de identidade vivem dentro de legal_representatives[].

Já os dados de device pertencem à sessão em que o cadastro foi feito, que é única para toda a requisição — por isso source fica na raiz.

Erros comuns

Sintoma	Causa	Correção
Dados de device não aparecem na dashboard de PJ	`session_id` ausente na raiz, ou enviado apenas dentro de `legal_representatives[]`	Preencha `source.session_id` na raiz do payload
HTTP 400 ao enviar `rg`/`cnh` em PJ	Documento de identidade na raiz do Legal Person	Mova para `legal_representatives[].documents`
HTTP 400 no `passport`	Objeto enviado sem `ocr_key`	`ocr_key` é obrigatório em `passport`
HTTP 400 em `source.ip`	IP mal formatado	Envie IPv4 ou IPv6 válido
HTTP 400 sem campo aparente	Campo fora do schema (`additionalProperties: false`)	Confira a `description` da resposta

Checklist

source.session_id na raiz, tanto em PF quanto em PJ.
Em PJ, confirmado que os dados de device aparecem na dashboard de análise cadastral.
Em PJ, face e documentos de identidade dentro de legal_representatives[].
Em PJ, apenas ie, company_statute e proof_of_address na raiz de documents.
passport, quando enviado, com ocr_key.

Integrando os dados do SDK

Onde cada bloco entra​

source — Device Scan e session_id​

face — biometria facial​

Valores de type​

documents — OCR​

Documentos aceitos em Pessoa Física​

Documentos aceitos em Pessoa Jurídica​

Chaves de OCR por documento​

Pessoa Física (Natural Person)​

Pessoa Jurídica (Legal Person)​

Erros comuns​

Checklist​