Objeto Legal Person

Ao final do cadastro de uma empresa em sua plataforma, é necessário executar a avaliação de fraude e de KYC desta companhia, o que deve ser realizado através do endpoint de Legal Person. Os dados enviados deverão ser os dados finais, que não serão alterados em hipótese alguma, isto é, não deverá existir a possibilidade de após este processo se realizar uma alteração nos dados básicos de cadastro como CNPJ, Razão Social, Data de Constituição e outros. Isto é muito importante para garantir dois pontos:

Consistência dos dados na base de dados do Antifraude
Avaliação realista do risco, evitando fraudes em momentos posteriores da operação

Definição do Objeto Legal Person

Request Body

{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "client_category" : "Premium Account",
  "legal_name": "John's Company",
  "trading_name": "John's Barbershop",
  "document_number": "11.111.111/0001-11",
  "foundation_date": "1992-09-15",
  "website": "www.johnsbarbershop.com.br",
  "activity": "Barber Shops",
  "activity_code": "96.02-5-01",
  "merchant_category_code": "0742",
  "tier" : "epp",
  "annual_revenues": 72000000,
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "ccc4b4b4-f91c-4475-8290-07152550aefc"
    }
  ],
  "documents": {
    "ie": {
      "number": "388.108.598.269",
      "issuer": "JUCESP",
      "issuer_state": "SP",
      "issuance_date":"2002-01-12",
      "validation_type": "zaig_api",
      "ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
    },
    "company_statute": {
      "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
    }
  },
  "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",
    "validation_type": "visit",
    "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
  },
  "phones": [
    {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile",
      "validation_type": "zaig_sms",
      "validation_key": "82473dec-8e14-4570-997a-59652818c908"
    }
  ],
  "source": {
    "channel": "app",
    "platform": "android",
    "ip":"201.6.142.66",
    "session_id": "c90ad2df-7307-4f82-8938-1da81dff2be6"
  },
  "legal_representatives": [
    {
      "name": "Frederic Attorney",
      "document_number": "111.111.111-11",
      "birthdate": "1987-06-12",
      "gender": "male",
      "nationality": "BRA",
      "mother_name": "Jackie Attorney Mother",
      "occupation": "Accountant",
      "emails":[
        {
          "email": "frederic@attorney.com",
          "validation_type":"zaig_api",
          "validation_key": "d174d522-6003-4b05-adb2-e92e92632c67"
        }
      ],
      "documents": {
        "letter_of_attorney": {
          "ocr_key": "6972894d-d2ef-4b5f-b54f-10f178bf3e5d"
        },
        "cnh": {
          "register_number": "05163811694",
          "issuer_state": "PR",
          "first_issuance_date":"2011-03-21",
          "issuance_date":"2016-06-29",
          "expiration_date":"2021-06-25",
          "category": "AB",
          "validation_type":"zaig_sdk",
          "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
        }
      },
      "address": {
        "street": "Avenida de Exemplo",
        "number": "99",
        "neighborhood": "Vila do Exemplo",
        "city": "Jundiaí",
        "uf": "SP",
        "complement": "Ap 82",
        "postal_code": "00000-000",
        "country": "BRA",
        "validation_type":"visit",
        "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "999998877",
          "type": "mobile",
          "validation_type": "zaig_sms",
          "validation_key": "e390d2b3-cb71-4991-9d94-1b7f8b43a04e"
        }
      ],
      "source": {
        "channel": "app",
        "platform": "ios",
        "ip":"175.92.122.2",
        "session_id": "93c68588-7a41-472f-95b3-835ea6ee1ede"
      },
      "face":
      {
        "type":"zaig_sdk",
        "registration_key":"d2677a8c-d575-44e1-a54d-ec00f9310f34"
      }
    }
  ],
  "partners": [
    {
      "name": "John Partner",
      "document_number": "111.111.111-11",
      "birthdate": "1992-09-15",
      "gender": "male",
      "nationality": "BRA",
      "mother_name": "Maria Partner's Mother",
      "occupation": "Teacher",
      "emails":[
        {
          "email": "johnsample@test.com",
          "validation_type":"zaig_api",
          "validation_key": "1fac6f8c-1a16-4a12-9afc-9a2d9ae0a31e"
        }
      ],
      "documents": {
        "rg": {
          "number": "4.366.477-8",
          "issuer": "II",
          "issuer_state": "PR",
          "issuance_date":"2002-01-12",
          "validation_type":"zaig_sdk",
          "ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
          "ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
        },
        "cnh": {
          "register_number": "05163811694",
          "issuer_state": "PR",
          "first_issuance_date":"2011-03-21",
          "issuance_date":"2016-06-29",
          "expiration_date":"2021-06-25",
          "category": "AB",
          "validation_type":"zaig_sdk",
          "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
        }
      },
      "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",
        "validation_type":"visit",
        "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
      },
      "phones": [
        {
          "international_dial_code": "1",
          "area_code": "11",
          "number": "999999999",
          "type": "mobile",
          "validation_type": "zaig_sms",
          "validation_key": "d1713959-4ae4-4180-befc-6931c658e908"
        }
      ],
      "source": {
        "channel": "app",
        "platform": "android",
        "ip":"255.201.26.1",
        "session_id": "79d5e442-2cb7-4a9e-82c5-7fa3717d7ada"
      },
      "face":
      {
        "type":"zaig_sdk",
        "registration_key":"a2b6ae92-1394-4f9b-b8ee-5be188f93609"
      }
    }
  ]
}

Todas as trocas de informação de um cadastro utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome	tipo	restrições	descrição
id	string	1–50 caracteres	Identificador da análise. É essencial que este número seja único para cada requisição (obrigatório)
registration_id	string	1–50 caracteres	Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro, utilize o mesmo registration_id nas diferentes análises. Terá o mesmo valor do id quando não enviado.
registration_date	datetime	ISO 8601 com fuso horário	Data e hora do cadastro. Formato: `YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM` ou `...Z`. Exemplo: `2019-12-11T11:37:15.12-03:00` (obrigatório)
client_category	string	1–100 caracteres	Categoria do cliente de acordo com a classificação da sua plataforma ou programa de fidelidade
legal_name	string	1–1000 caracteres	Razão Social da empresa sendo cadastrada
trading_name	string	1–1000 caracteres	Nome fantasia da empresa sendo cadastrada
document_number	string	Formato `XX.XXX.XXX/XXXX-XX`	CNPJ da empresa. Deve conter exatamente 18 caracteres, incluindo pontos, barra e hífen (obrigatório)
foundation_date	date	Formato `YYYY-MM-DD`	Data de fundação da empresa
website	string	até 10.000 caracteres	Website da empresa sendo cadastrada
activity	string	1–1000 caracteres	Ramo de atividade da empresa sendo cadastrada
activity_code	string	Formato `XX.XX-X-XX`	Código CNAE da atividade da empresa. Deve conter exatamente 10 caracteres. Exemplo: `96.02-5-01`
merchant_category_code	string	enum (ver lista abaixo)	Código MCC (Merchant Category Code) para o ramo de atividade, conforme padrão das bandeiras de cartões
tier	string	1–10 caracteres	Porte da empresa (ex.: `mei`, `epp`, `me`, `medio`, `grande`)
annual_revenues	integer	0 a 10.000.000.000.000	Receita bruta anual da empresa em centavos de reais
monthly_revenues	integer	0 a 10.000.000.000.000	Receita bruta mensal da empresa em centavos de reais
emails	Lista de Email	—	Lista de objetos do tipo Email com os endereços de e-mail da empresa
documents	Document	—	Objetos dos tipos Inscrição Estadual (`ie`) e Contrato Social (`company_statute`)
address	Address	—	Objeto do tipo Address com o endereço da empresa
phones	Lista de Phone	—	Lista de objetos do tipo Phone com os telefones da empresa
source	Source	—	Objeto do tipo Source com informações da aplicação utilizada para envio do cadastro
partners	Lista de Partner	—	Lista de objetos do tipo Partner com informações de cada sócio da empresa
legal_representatives	Lista de LegalRepresentative	—	Lista de objetos do tipo LegalRepresentative com informações de cada representante legal da empresa

Formatos de Campo

`registration_date`

Deve seguir o formato ISO 8601 com fuso horário obrigatório. Exemplos de valores aceitos:

2019-12-11T11:37:15-03:00        (sem fração de segundos, offset)
2019-12-11T11:37:15.123456-03:00 (com fração de segundos, até 6 dígitos)
2019-12-11T14:37:15Z             (UTC)

O campo não aceita datas sem o componente de fuso horário (ex.: 2019-12-11T11:37:15 é inválido).

`document_number` — CNPJ

O CNPJ deve ser enviado com pontuação, no formato XX.XXX.XXX/XXXX-XX, onde cada X é um dígito numérico. O campo possui exatamente 18 caracteres.

Exemplo válido: 11.222.333/0001-81

`foundation_date`

Data no formato YYYY-MM-DD (ano-mês-dia), conforme ISO 8601.

Exemplo válido: 1992-09-15

`activity_code` — CNAE

O código CNAE deve ser enviado no formato XX.XX-X-XX, com exatamente 10 caracteres incluindo os separadores.

Exemplo válido: 96.02-5-01

`annual_revenues` e `monthly_revenues`

Ambos os campos são inteiros que representam valores monetários em centavos de reais. Para converter de reais para o formato esperado, multiplique por 100.

Exemplo: R$ 720.000,00 → 72000000

Enviar um Legal Person

Request Body

  {
    "id": "12345",
    ...
  }

Response Body

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

Para realizar a avaliação de um Cadastro, basta enviar um objeto do tipo Legal Person ao seguinte endpoint com a flag setada adequadamente:

POST https://api.caas.qitech.app/onboarding/legal_person?analyze=true

O parâmetro analyze existe para identificar se o cadastro enviado deve ou não ser analisado pelos algoritmos da QI Tech. Caso um cadastro seja enviado com o parâmetro com o valor false, ele não será analisado nem cobrando, mas seus dados serão considerados pelos algoritmos da QI Tech para uma análise futura. O valor padrão deste parâmetro é true, de maneira que somente cadastros que forem explicitamente enviados com a flag false não serão analisados.

Definição do Objeto Legal Person​

Formatos de Campo​

registration_date​

document_number — CNPJ​

foundation_date​

activity_code — CNAE​

annual_revenues e monthly_revenues​

Enviar um Legal Person​