Introdução

Bem vindo à API de Onboarding da Zaig! Esta API dá acesso aos serviços de Prevenção a Fraudes, à lavagem de dinheiro e de KYC em um Cadastro da sua plataforma!

Esta API pode ser utilizada para a validação cadastral de clientes para:

• Abertura de Contas Digitais ou Wallets
• Emissão de Cartão
• Validação de Usuários de Aplicativos
• Cadastro para Concessão de Crédito
• Cadastro para Contratação de Seguros
• Validação de Dados Cadastrais

Você pode utilizar a nossa API para acessar os endpoints para avaliar os seguintes tipos de Cadastro:

• Natural Person - utilizado para validação cadastral de Pessoas Físicas
• Legal Person - utilizado para validação cadastral de Pessoas Jurídicas

Os diferentes tipos de Cadastro acima possuem objetos e endpoints específicos com o intuito de cobrir as particularidades de cada entidade.

Ao lado, você pode observar a implementação da API utilizando cUrl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já notou), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

• Produção - https://api.caas.qitech.app/onboarding/
• Sandbox - https://api.sandbox.caas.qitech.app/onboarding/

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com a seguinte regra baseada no primeiro dígito do documento - CPF para Pessoas Físicas e CNPJ para Pessoas Jurídicas:

Nos casos de CPF ou CNPJ com início nos dígitos 1 ou 2, deve-se entrar em contato com nosso suporte para que a tratativa manual seja feita corretamente.

Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da Zaig devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

Integrações

Nossas soluções mobile são compatíveis com as mais diversas tecnologias como Flutter, Ionic Cordova, Capacitor, React Native, Java, Swift entre outras. Caso tenha interesse em alguma dessas integrações, entre em contato com nosso suporte para liberarmos acesso aos nossos repositórios privados.

Autenticação

Para autenticar uma chamada, utilize o código seguinte:

# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"

Substitua a API Key 'EXAMPLE-OF-API-KEY' pela sua chave, que deve ser obtida através do nosso time de suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br.

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

Authorization: EXAMPLE-OF-API-KEY

Dinâmica dos Status

O processo de análise consiste em enviar um cadastro, tanto de Natural Person como de Legal Person no endpoint adequado e esperar a resposta.

Após a Zaig realizar a análise do cadastro, ela retornará uma resposta com um status referente a análise. Esse status tem o nome de analysis_status, que representa o resultado da analise de cadastro realizado pela Zaig.

Além do analysis_status a Zaig também possui o client_status que tem como objetivo representar o status que o cliente possui em cada momento de sua vida na sua plataforma.

analysis_status

Conforme descrito anteriormente, a Zaig possui sete analysis_status que indicam o status da decisão do motor de onboarding e possui uma máquina de estados bastante simples:

client_status

O client_status indica a situação cadastral do cliente, ou seja, o status do indivíduo ou empresa na sua plataforma. Os seguintes enumeradores existem para este status:

Objeto Natural Person

Ao final do cadastro de uma pessoa física em sua plataforma, é necessário executar a avaliação de fraude e de KYC deste cliente, o que deve ser realizado através do endpoint de Natural 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 se realizar uma alteração nos dados básicos de cadastro como CPF, Nome, Data de Nascimento e outros após este processo. 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 Natural Person

Exemplo

{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "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",
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
    }
  ],
  "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": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
    }
  ],
  "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"
  }
}

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.

Enviar um Natural Person

Exemplo de Request

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

Exemplo de Retorno

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

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

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

O parâmetro analyze existe para identificar se o cadastro enviado deve ou não ser analisado pelos algoritmos da Zaig. 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 Zaig 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.

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

Exemplo

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

Enviar um Legal Person

Exemplo de Request

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

Exemplo de Retorno

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

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 Zaig. 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 Zaig 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.

Atualizar um Cadastro

Corpo da requisição - No bloqueio de um cadastro por fraude ou suspeita de fraude

{
  "client_status": "fraud_blocked",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Corpo da requisição - No bloqueio de um cadastro por inadimplência

{
  "client_status": "default_blocked",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Corpo da requisição - No cancelamento de um cadastro por solicitação do cliente

{
  "client_status": "cancelled",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Para garantir a retroalimentação das regras e do modelo de inteligência artificial, é necessário informar ao sistema quando os Cadastros sofrem alterações, como por exemplo quando são bloqueados, ou quando são cancelados. O status utilizado para essas alterações é o client_status, que deve ser alterado sempre que houver alterações no ciclo de vida do cliente. Para isso, requisições com o método PUT, autenticadas normalmente, devem ser utilizadas e os status devem seguir o padrão detalhado anteriomente:

• Natural Person:

PUT https://api.caas.qitech.app/onboarding/natural_person/123456

• Legal Person:

PUT https://api.caas.qitech.app/onboarding/legal_person/123456

Recuperar um Cadastro

Buscar Cadastro específico

A fim de recuperar um Cadastro específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do Cadastro em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

• Natural Person:

GET https://api.caas.qitech.app/onboarding/natural_person/12345678

• Legal Person:

GET https://api.caas.qitech.app/onboarding/legal_person/12345678

curl "https://api.caas.qitech.app/onboarding/natural_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"

O comando acima retorna o JSON que representa um objeto de Natural Person.

curl "https://api.caas.qitech.app/onboarding/legal_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"

O comando acima retorna o JSON que representa um objeto de Legal Person.

Buscar PDF

A fim de recuperar um PDF de um cadastro, basta realizar uma requisição GET. O resultado retornado é o arquivo PDF resultante da análise. Caso seja desejado, basta adicionar uma query string denominada base64 com o valor true para que o arquivo PDF seja retornado em base64.

• Natural Person:

GET https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf

GET https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf&base64=true

• Legal Person:

GET https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf

GET https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf&base64=true

curl "https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"

O comando acima retorna o arquivo PDF gerado pela consulta.

curl "https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"

O comando acima retorna o arquivo PDF gerado pela consulta.

Objetos Compartilhados

Boa parte dos dados são compartilhados entre várias APIs. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada.

Objeto email

Exemplo

{
  "email": "johnsample@test.com",
  "validation_type":"zaig_api",
  "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
}

O objeto email é utilizado para representar os e-mails em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

Existem os seguintes enumeradores para validation_type: zaig_api, company_email.

Objeto cnh

Exemplo

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

O objeto cnh é utilizado para representar as CNHs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

Existem os seguintes enumeradores para validation_type: zaig_api e zaig_sdk.

Objeto rg

Exemplo

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

O objeto rg é utilizado para representar os RGs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

Existem os seguintes enumeradores para validation_type: zaig_api e zaig_sdk.

Objeto ie

Exemplo

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

O objeto ie é utilizado para representar as Inscrições Estaduais dentro do objeto de documents no endpoint de legal_person, bem como se foi utilizado algum meio de validação do mesmo. Ele é representado da seguinte maneira:

Existem os seguintes enumeradores para validation_type: zaig_api.

Objeto company_statute

Exemplo

{
  "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
}

O objeto company_statute é utilizado para representar documentos de constituição de empresas, como por exemplo um Contrato Social dentro do objeto de documents no endpoint de legal_person. Ele é representado da seguinte maneira:

Objeto letter_attorney

Exemplo

{
  "ocr_key": "13571175-b1d9-4507-82e0-d266516fc5ae"
}

O objeto letter_attorney é utilizado para representar procurações que instituem poderes a representantes legais dentro do objeto de documents no endpoint de legal_person. Ele é representado da seguinte maneira:

Objeto address

Exemplo

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

O objeto address é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.

Existem os seguintes enumeradores para validation_type: visit, zaig_ocr.

Objeto phone

Exemplo

{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile",
  "validation_type": "zaig_sms",
  "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
}

Um objeto phone representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:

Existem os seguintes enumeradores para tipo de telefone: residential, commercial e mobile

Existem os seguintes enumeradores para as validações de telefone: zaig_sms, zaig_call, company_sms, company_call.

Objeto source

Exemplo

  {
    "channel": "app",
    "platform": "android",
    "ip":"211.7.142.62",
    "session_id": "733adf2c-a994-4113-aa59-beb646091fea",
  }

Um objeto source representa o conjunto de informações da plataforma utilizada pelo cliente para seu cadastramento. Para isso, os campos são:

Objeto face

Exemplo

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

Um objeto face representa uma validação de reconhecimento facial feita através das APIs ou SDKs da Zaig por você para verificar a autenticidade do cliente prévio ao envio do cadastro. Para isso, os campos são:

Existem os seguintes enumeradores para as validações de face: zaig_api e zaig_sdk.

Objeto partner

Exemplo

  {
    "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": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
      }
    ],
    "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",
    },
    "phones": [
      {
        "international_dial_code": "1",
        "area_code": "11",
        "number": "999999999",
        "type": "mobile",
        "validation_type": "zaig_sms",
        "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
      }
    ],
    "source": {
      "channel": "app",
      "platform": "android",
      "ip":"255.321.321.1",
      "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
    },
    "face":
    {
      "type":"zaig_sdk",
      "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
    }
  }

Um objeto partner representa os dados de um sócio da empresa que está sendo cadastrada, bem como informações referentes às validações que o sócio foi submetido durante seu processo de cadastro. Para isso, os campos são:

Objeto legal_representative

Exemplo

  {
    "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":"proof_of_address",
      "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"
    }
  }

Um objeto legal_representative representa os dados de um representante legal da empresa que está sendo cadastrada, bem como informações referentes às validações que o representante legal foi submetido durante seu processo de cadastro. Para isso, os campos são:

Webhook

Atualizações no status de fraude (Para cadastros que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do suporte, configurar um endereço do endpoint por onde vamos notificar as atualizações e também um secret_token que será utilizado para assinar a requisição.

O cliente pode, apesar de não recomendável, também utilizar a técnica de polling. Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de cadastro para proceder com o polling.

Assinatura

Exemplo de cálculo de assinatura em Python

    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()

Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, semelhante ao processo de autenticação.

Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.

Requisição

Exemplo de requisição

    {
        "natural_person_id": "123456",
        "analysis_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }

A requisição possui o formato ao lado e notifica a mudança no status de fraude. É importante ressaltar que a requisição utiliza o verbo HTTP POST e o corpo da requisição é enviado como texto codificado em UTF-8.

Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

• 30 segundos
• 60 segundos
• 120 segundos
• 240 segundos
• 360 segundos

Padrões

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

Valores Monetários

Exemplos:

10000
12345
98741
1223
1
0

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

Data e Hora com Fuso Horário

Alguns exemplos:

2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido.

A máscara utilizada para validação é a seguinte:

YYYY-MM-ddThh:mm:ss.sss±hh:mm

Data e Hora sem Fuso Horario

Alguns exemplos:

2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

YYYY-MM-ddThh:mm:ss.sssZ

Data

Alguns exemplos

2019-10-15
2019-01-01
2017-03-20

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

YYYY-MM-dd

Documentos

Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

CPF

Exemplos de CPFs válidos contra a máscara definida:

123.456.789-12
321.987.543-23
111.283.333-00

Exemplos de CPFs inválidos contra a máscara definida:

8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01

O CPF é sempre definido como uma string e será validado contra a máscara:

###.###.###-##

CNPJ

Exemplos de CNPJs válidos contra a máscara definida:

08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35

Exemplos de CNPJs inválidos contra a máscara definida:

8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3

O CNPJ é sempre definido como uma string e será validado contra a máscara:

##.###.###/####-##

IP

Exemplos de IPs válidos contra a máscara definida:

201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1

Exemplos de IPs inválidos:

201.81..86
358.81.161.86
201.81.161

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

###.###.###.###

Status HTTP

Todas as APIs da Zaig utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231: