Introdução

Bem vindo à API de análise de crédito da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de executar uma análise de crédito, além de utilizar para atualizar a situação de um crédito concedido.

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á entendeu), 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/credit_analysis/
• Sandbox - https://api.sandbox.caas.qitech.app/credit_analysis/

No ambiente de Sandbox, as análises enviadas não são cobradas, são respondidas de acordo com regras pré estabelecidas e retornam dados fictícios, com o intuito exclusivo simular o ambiente de produção parap auxiliar o cliente no momento da integração.

Para a análise de uma operação de crédito, no ambiente de Sandbox, a decisão é aplicada sobre o valor total do crédito (financial.amount) a ser concedido, de acordo com a tabela abaixo:

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.

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' com a sua chave adquirida com o nosso 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 de crédito consiste em enviar uma requisição, tanto de NaturalPerson como de LegalPerson no respectivo endpoint e esperar a resposta.

Após a QI Tech realizar a análise de crédito, 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 crédito realizado pela QI Tech.

Além do analysis_status a QI Tech também possui o credit_proposal_status que tem como objetivo representar o status do crédito analisado em cada momento de sua vida na sua plataforma.

analysis_status

Conforme descrito anteriormente, a QI Tech possui sete analysis_status que indicam o status da decisão da análise de crédito e possui uma máquina de estados bastante simples:

credit_proposal_status

O credit_proposal_status indica o status da operação do cliente, ou seja, o status da proposta de crédito na sua empresa ou plataforma. Os seguintes enumeradores existem para este status:

Análise de Crédito - Pessoa Física

Para realizar a análise de crédito de uma pessoa física, utilize o endpoint de NaturalPerson.

No momento em que uma análise de crédito de pessoa física for realizada, os seguintes dados abaixo devem ser enviados para o nosso servidor.

Definição do Objeto Natural Person

Exemplo Pessoa Física

{
  "id": "678",
  "registration_id":"444",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "student_loan",
  "name": "Victor Silva Barbosa",
  "document_number": "199.208.915-92",
  "birthdate": "1990-01-01",
  "email": "exemplo@sample.com",
  "nationality": "BRA",
  "gender": "male",
  "mother_name": "Ana Barbosa",
  "father_name": "João Silva",
  "monthly_income": 30000,
  "declared_assets": 7500000,
  "occupation": "pedagogy",
  "address": {
    "country": "BRA",
    "street": "Rua Curitiba",
    "number": "150",
    "complement": "Bl 3 apt 122",
    "neighborhood": "Paraíso",
    "city": "São Paulo",
    "uf": "SP",
    "postal_code": "04005-030"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "32234611",
      "type": "residential"
    }
  ],
  "guarantors": [
    {
      "name": "Melissa Lima Melo",
      "document_number": "677.498.846-61",
      "birthdate": "1960-11-21",
      "email": "exemplo2@sample.com",
      "nationality": "BRA",
      "mother_name": "Raíssa Lima",
      "father_name": "Ronaldo Melo",
      "monthly_income": 800000,
      "declared_assets": 18600000,
      "occupation": "law",
      "gender": "female",
      "address": {
        "country": "BRA",
        "street": "Rua Castro Alves",
        "number": "100",
        "complement": "Ap 202",
        "neighborhood": "Parque Estrela Dalva I",
        "city": "Luziânia",
        "uf": "GO",
        "postal_code": "72804-050"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "21158745",
          "type": "residential"
        }
      ]
    }
  ],
  "financial": {
    "amount": 100000,
    "currency": "BRL",
    "interest_type": "cdi_plus",
    "annual_interest_rate": 2.32,
    "cdi_percentage": 100,
    "number_of_installments": 4
  },
  "warrants": [
    {
      "warrant_type": "real_estate",
      "address": {
        "country": "BRA",
        "street": "Rua Curitiba",
        "number": "150",
        "complement": "Bl 3 apt 122",
        "neighborhood": "Paraíso",
        "city": "São Paulo",
        "uf": "SP",
        "postal_code": "04005-030"
      },
      "property_type": "house",
      "estimated_value": 100000000,
      "forced_selling_value": 60000000
    }
  ],
  "source": {
    "channel": "website",
    "ip": "145.25.145.32",
    "session_id": "bec256b3-5265-4dcb-bc55-2e4fb43983e0"
  },
  "scr_parameters" : {
    ...
  }
}

Uma análise de crédito deve ser enviada para a API antes do desembolso e pode ser utilizada para se tomar a decisão de conceder ou não o crédito. Os dados enviados também podem, mediante acordo com o cliente, ser utilizados para a prevenção a fraudes.

Os objetos utilizados na composição do objeto CreditProposal e não definidos nesta seção estão disponíveis na seção Objetos Compartilhados.

Enviar uma Proposta de Crédito - Pessoa Física

Exemplo de Request

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

Exemplo de Retorno

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

Para realizar a avaliação de uma proposta de crédito, basta enviar um objeto do tipo NaturalPerson ao seguinte endpoint:

POST https://api.caas.qitech.app/credit_analysis/natural_person

Análise de Crédito - Pessoa Jurídica

Para realizar a análise de crédito de uma pessoa jurídica, utilize o endpoint de Legal Person.

No momento em que uma análise de crédito de pessoa jurídica for realizada, os seguintes dados deverão ser enviados para o nosso servidor.

Definição do Objeto Legal Person

Exemplo Pessoa Jurídica

{
  "id": "855",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "student_loan",
  "legal_name": "Zaig Tecnologia LTDA",
  "trading_name": "Zaig",
  "document_number": "35.472.523/0001-15",
  "constitution_date": "2019-11-11",
  "constitution_type": "llc",
  "email": "suporte.caas@qitech.com.br",
  "monthly_revenue": 50000000,
  "client_category": "Premium User",
  "client_since": "2021-02-11",
  "address": {
    "country": "BRA",
    "street": "Av. Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardim Paulistano",
    "city": "São Paulo",
    "uf": "SP",
    "postal_code": "01452-905"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "32234611",
      "type": "residential"
    }
  ],
  "shareholders": [
    {
      "name": "Anna Pinto Azevedo",
      "document_number": "261.026.462-31",
      "birthdate": "1972-08-22",
      "email": "annapintoazevedo@sample.com",
      "nationality": "BRA",
      "mother_name": "Beatrice Rodrigues Pinto",
      "father_name": "Luís Azevedo",
      "monthly_income": 800000,
      "declared_assets": 18600000,
      "occupation": "law",
      "gender": "female",
      "address": {
        "country": "BRA",
        "street": "Rua Derviche Djouki",
        "number": "598",
        "complement": "Ap 857",
        "neighborhood": "Chora Menino",
        "city": "São Paulo",
        "uf": "SP",
        "postal_code": "02463-080"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "55988644",
          "type": "mobile"
        }
      ]
    }
  ],
  "guarantors": [
    {
      "name": "Melissa Lima Melo",
      "document_number": "677.498.846-61",
      "birthdate": "1960-11-21",
      "email": "exemplo2@sample.com",
      "nationality": "BRA",
      "mother_name": "Raíssa Lima",
      "father_name": "Ronaldo Melo",
      "monthly_income": 800000,
      "declared_assets": 18600000,
      "occupation": "law",
      "gender": "female",
      "address": {
        "country": "BRA",
        "street": "Rua Castro Alves",
        "number": "100",
        "complement": "Ap 202",
        "neighborhood": "Parque Estrela Dalva I",
        "city": "Luziânia",
        "uf": "GO",
        "postal_code": "72804-050"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "21158745",
          "type": "residential"
        }
      ]
    }
  ],
  "financial": {
    "amount": 100000,
    "currency": "BRL",
    "interest_type": "cdi_plus",
    "annual_interest_rate": 2.32,
    "cdi_percentage": 100,
    "number_of_installments": 4
  },
  "warrants": [
    {
      "warrant_type": "real_estate",
      "address": {
        "country": "BRA",
        "street": "Rua Curitiba",
        "number": "150",
        "complement": "Bl 3 apt 122",
        "neighborhood": "Paraíso",
        "city": "São Paulo",
        "uf": "SP",
        "postal_code": "04005-030"
      },
      "property_type": "house",
      "estimated_value": 100000000,
      "forced_selling_value": 60000000
    }
  ],
  "source": {
    "channel": "website",
    "ip": "132.23.161.75",
    "session_id": "2bb684f9-6c00-4993-bcd7-18b9eccd7c9d"
  },
  "scr_parameters" : {
    ...
  }
}

Uma análise de crédito deve ser enviada para a API antes do desembolso e pode ser utilizada para se tomar a decisão de conceder ou não o crédito. Os dados enviados também podem, mediante acordo com o cliente, ser utilizados para a prevenção a fraudes.

Os objetos utilizados na composição do objeto CreditProposal e não definidos nesta seção estão disponíveis na seção Objetos Compartilhados.

Enviar uma Proposta de Crédito - Pessoa Jurídica

Exemplo de Request

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

Exemplo de Retorno

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

Para realizar a avaliação de uma proposta de crédito, basta enviar um objeto do tipo LegalPerson ao seguinte endpoint:

POST https://api.caas.qitech.app/credit_analysis/legal_person

Dados Sistema de Informações de Créditos (SCR - BACEN)

Caso o cliente contrate, temos a opção da utilização dos dados disponíveis no SCR da pessoa física ou jurídica no momento da análise de crédito. Para utilização dos dados do SCR, é primordial que o consentimento do consultado seja coletado. Esse consentimento pode ser coletado pela QI Tech ou pelo próprio cliente e isso influencia no fluxo de consentimento, bem como nos dados que devem ser enviados para a API, conforme abaixo:

1. Coleta de consentimento via QITech - Caso opte pela coleta do consentimento via QI Tech, um link para assinatura eletrônica é enviado diretamente, via e-mail, da QI Tech para o usuário consultado e, quando o usuário assina o link e finaliza o processo, a informação do SCR automaticamente torna-se disponível para uso. Para utilização deste fluxo, é necessário que, na integração, sejam enviados os dados do usuário final que irá assinar o termo de consentimento.

2. Coleta do consentimento pelo próprio cliente - É possível coletar a assinatura do termo de consentimento em seu próprio ambiente ou esteira de crédito (pode ser feito por documento assinado ou opt-in box do termo). Para que isso seja possível, o termo de consentimento utilizado deve ser validado pelo time jurídico da QI Tech e se faz necessário o envio de informações que comprovem de maneira auditável que o consentimento para acesso à informação de SCR foi coletado através do objeto scr_parameters.

Coleta do Consentimento via QITech - Pessoa Física

No caso de uma pessoa física, para que a QI Tech envie o pedido de consentimento, basta o preenchimento dos dados pessoais do consultado no objeto de CreditProposal. Com isso, a QI Tech irá enviar o pedido de consentimento ao consultado via e-mail e, automaticamente, realizar a consulta (após autorizaçao), disponibilizando os resultados para análise de crédito.

Coleta do Consentimento via QITech - Pessoa Jurídica

  {
    "id": "32199d0s",
    "legal_name": "QI CAAS LTDA",
    "trading_name": "QI Tech",
    ...
    "scr_parameters": {
      "signers": [
        {
          "document_number": "372.989.950-30",
          "name": "Felipe Marques da Silva",
          "email": "felipe.silva@qitech.com.br",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        },
        {
          "document_number": "440.896.050-08",
          "name": "Claudio Mattos",
          "email": "claudiomattos@sample.com",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        }
      ]
    }
  }

No caso de uma pessoa jurídica, para que a QI Tech envie o pedido de consentimento, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, será necessário adicionar a lista de responsáveis legais da empresa para os quais serão enviados os pedidos de assinatura eletrônica via e-mail. Essa lista deve ser enviada dentro da propriedade signers. Após a assinatura de todos os representantes legais, a QI Tech realizará a consulta, disponibilizando os resultados para análise de crédito. Ao lado temos um exemplo do objeto scr_parameters para o caso descrito.

Coleta do Consentimento pelo Próprio Cliente - Pessoa Física

  {
    "id": "678",
    "credit_request_date": "2021-03-31T10:30:00-03:00",
    "credit_type": "student_loan",
    "name": "Victor Silva Barbosa",
    "document_number": "199.208.915-92",
    ...
    "scr_parameters": {
      "signature_evidence": {
        "ip_address": "179.104.42.245",
        "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
        "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
        "additional_data": {
          ...
        },
        "signed_term": {
          "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
        }
      }
    }
  }

No caso de uma pessoa física, quando a coleta do consentimento é realizada pelo cliente, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, é necessário adicionar informações para comprovar que a pessoa analisada autorizou a consulta. Essas informações devem ser enviadas dentro da propriedade signature_evidence. Ao lado temos um exemplo do objeto scr_parameters para o caso descrito.

Coleta do Consentimento pelo Próprio Cliente - Pessoa Jurídica

  {
    "id": "678",
    "credit_request_date": "2021-03-31T10:30:00-03:00",
    "credit_type": "student_loan",
    "name": "Victor Silva Barbosa",
    "document_number": "199.208.915-92",
    ...
    "scr_parameters": {
      "signers": [
        {
          "document_number": "372.989.950-30",
          "name": "Felipe Marques da Silva",
          "email": "felipe.silva@qitech.com.br",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        },
        {
          "document_number": "440.896.050-08",
          "name": "Claudio Mattos",
          "email": "claudiomattos@sample.com",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        }
      ],
      "signature_evidence": {
        "ip_address": "179.104.42.245",
        "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
        "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
        "additional_data": {
          ...
        },
        "signed_term": {
          "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
        }
      }
    }
  }

No caso de uma pessoa jurídica, quando a coleta do consentimento é realizada pelo cliente, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, é necessário adicionar informações para comprovar que a pessoa analisada autorizou a consulta, bem como adicionar a lista de responsáveis legais da empresa que autorizaram a consulta. As informações de autorização deverão ser enviadas dentro da propriedade signature_evidence e a lista de pssoas que autorizaram a consulta dentro da propriedade signers. Ao lado temos um exemplo do objeto scr_parameters para o caso descrito.

Atualizar o status de uma CreditProposal

Corpo da requisição - Para marcar o crédito como concedido

{
  "credit_proposal_status": "disbursed",
  "event_date": "2021-11-05T13:34:12-03:00"
}

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as operações são efetivadas. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:

• Natural Person:

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

• Legal Person:

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

Fluxo de Desafio

É possível, após a execução da análise, ter como decisão desafiar o usuário para realizar uma nova ação em sua plataforma. Esse fluxo pode ser utilizado para, por exemplo, solicitar um comprovante de renda para um usuário que ainda não se tem certeza que deve ser aprovado ou reprovado na análise de crédito.

Há duas possibilidades de utilização deste fluxo, um deles de maneira automática, e outra fruto da decisão manual de um analista. Para o primeiro, o analysis_status retornado será automatically_challenged e para o segundo será manually_challenged. Abaixo temos a descrição do fluxo.

Passo-a-passo da execução do fluxo

1. Proposta é submetida para análise (ver seção Análise de Crédito - Pessoa Física ou Análise de Crédito - Pessoa Jurídica), e retornará o status automatically_challenge ou in_manual_analysis.

Exemplo de Payload de Envio:

{
  "id": "12345",
  "registration_id":"12345",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "clean",
  "name": "Victor Silva Barbosa",
  "document_number": "199.208.915-92",
  ...
}

Exemplo de Payload de Resposta

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

Caso a requisição retorne na resposta o status de in_manual_analysis, o analista poderá, através da dashboard, desafiar o usuário. Neste caso o status que será enviado na requisição de webhook é manually_challenged.

Exemplo de Payload de Resposta

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

2. Após a primeira requisição de análise ter retornado um dos dois analysis_status de desafio, uma nova requisição deverá ser enviada com as informações adicionais coletadas do cliente, como por exemplo, uma novo imagem de documento enviada. Esta requisição deve conter o mesmo registration_id da requisição anterior, uma vez que este campo será utilizado para que a plataforma identifique que ambas as requsições se referem ao mesmo usuário, bem como vincular as informações adicionais coletadas do cliente.

Exemplo de Payload de Envio com informações adicionais

{
  "id": "67890",
  "registration_id":"12345",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "clean",
  "name": "Victor Silva Barbosa",
  "document_number": "199.208.915-92",
  "documents": {    
    "cnh": {
      "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
    }
  }
  ...
}

Exemplo de Payload de Resposta

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

Objetos Compartilhados

Abaixo as definições de outros objetos utilizados ao longo da documentação.

Objeto Address

Exemplo

{
  "street": "Rua do Exemplo",
  "number": "111" ,
  "neighborhood": "Bairro do Teste",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "Apt 903",
  "postal_code": "00000-000"
}

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.

Objeto Phone

Exemplo

{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile"
}

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

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 NaturalPerson

Exemplo

{
  "name": "Melissa Lima Melo",
  "document_number": "677.498.846-61",
  "birthdate": "1960-11-21",
  "email": "exemplo2@sample.com",
  "nationality": "BRA",
  "gender": "female",
  "mother_name": "Raíssa Lima",
  "father_name": "Ronaldo Melo",
  "monthly_income": 800000,
  "declared_assets": 18600000,
  "occupation": "law",
  "address": {
    "country": "BRA",
    "street": "Rua Castro Alves",
    "number": "100",
    "complement": "Ap 202",
    "neighborhood": "Parque Estrela Dalva I",
    "city": "Luziânia",
    "state": "GO",
    "postal_code": "72804-050"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "21158745",
      "type": "residential"
    }
  ]
}

O objeto NaturalPerson representa os dados de uma pessoa que pode ser o próprio tomador, um garantidor ou um sócio de uma empresa tomadora. Ele é composto por:

Enumeradores de gênero:

• male
• female
• undefined

Objeto LegalPerson

Exemplo

{
  "legal_name": "Zaig Tecnologia LTDA",
  "trading_name": "Zaig",
  "document_number": "35.472.523/0001-15",
  "constitution_date": "1990-01-01",
  "constitution_type": "llc",
  "email": "exemplo@sample.com",
  "address": { ... },
  "phones": [ { ... } ],
  "shareholders": [ { ... }]
}

O objeto LegalPerson representa os dados de uma empresa que está tomando crédito ou garantindo o crédito (Fiador). Ele é composto por:

Objeto Source

Para pedidos de crédito realizados por meio do site próprio, utilizar o seguinte objeto:

{
  "channel": "website",
  "ip": "201.81.161.86",
  "session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}

Para pedidos de crédito realizados por meio de aplicativo próprio, utilizar o seguinte objeto:

{
  "channel": "app",
  "platform": "android",
  "ip": "201.81.161.86",
  "session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}

O objeto source representa o local onde o pedido de crédito foi realizado.

Objeto Warrant

Para análises de crédito que possuam algum tipo de garantia, o objeto warrant pode ser utilizado para informá-lo à nossa API. No momento, somente garantias de imóvel são aceitas e caso seja necessário outro tipo de garantia, basta entrar em contato com o nosso suporte

  {
    "warrant_type": "real_estate",
    "address": { ... },
    "property_type": "house",
    "estimated_value": 100000000,
    "forced_selling_value": 60000000
  }

Para a garantia do tipo real_estate, o objeto é formado pelos seguintes campos:

Objeto ScrParameters

  {
    "scr_parameters": {
      "signers": [
        {
          "document_number": "111.222.333-44",
          "name": "Felipe Marques da Silva",
          "email": "felipe.silva@qitech.com.br",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        }
      ],
      "signature_evidence": {
        "ip_address": "179.104.42.245",
        "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
        "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
        "additional_data": {
          ...
        },
        "signed_term": {
          "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque 
            et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
        }
      }
    }
  }

Objeto Signer

  {
    "document_number": "111.222.333-44",
    "name": "Felipe Marques da Silva",
    "email": "felipe.silva@qitech.com.br",
    "phone": {
      "number": "991722315",
      "area_code": "16",
      "international_dial_code": "55"
    }
  }

Objeto Signature_Evidence

  {
    "signature_evidence": {
      "ip_address": "179.104.42.245",
      "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
      "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
      "additional_data": {
        ...
      },
      "signed_term": {
        "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque 
          et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
      }
    }
  }

Objeto SignedTerm

  {
    "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
  }

Webhook

Atualizações no status (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 signature_key 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

Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, deve ser realizado o cálculo do hash HMAC da requisição, considerando os parâmetros definidos abaixo, e então, comparar este hash calculado com o enviado no header de assinatura (http header signature) da requisição. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.

Cálculo do Hash HMAC

Para o cálculo do hash HMAC os seguintes parâmetros devem ser considerados:

Exemplo de cálculo de assinatura em Python

    import hmac
    import hashlib

    SIGNATURE_KEY='SIGNATURE_KEY'
    WEBHOOK_URL='https://webhook_url.com'
    WEBHOOK_METHOD='PUT'

    PAYLOAD_EXAMPLE='{\"natural_person_id\": \"teste_webhook_1\", \"analysis_status\": \"automatically_reproved\", \"event_date\": \"2023-06-14T14:38:36Z\"}'

    def validate_hmac(payload):
            hmac_calculated = (hmac
                                    .new(SIGNATURE_KEY.encode('utf-8'), (WEBHOOK_URL + WEBHOOK_METHOD + payload).encode('utf-8'), hashlib.sha1)
                                    .hexdigest())
            return hmac_calculated

Requisição

Exemplo de requisição

    {
        "credit_proposal_natural_person_id": "123456",
        "analysis_status": "manually_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. É importante ressaltar que a requisição utiliza o verbo HTTP PUT 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-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+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. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

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

YYYY-MM-ddThh:mm:ss±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:ssZ

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 conta 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 conta 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: