Pular para o conteúdo principal

4.1.1. Contrato Novo

Na modalidade Contrato Novo – Consignado Privado, é realizada a formalização de uma nova operação de crédito destinada a colaboradores com vínculo empregatício ativo (CLT ou Pessoa Jurídica), sem vínculo com contratos anteriores na instituição. A concessão está condicionada à margem consignável disponível junto ao empregador e à aprovação na análise de crédito realizada pelo provedor.

Códigos dos Provedores​

Os Códigos dos Provedores são utilizados para identificar e rotear as suas operações para a instituição financeira correta.

Você deve informar o código correspondente ao banco desejado no momento de realizar simulações ou cadastrar propostas. Isso garante que a transação seja processada exatamente com as regras, políticas de crédito e taxas daquele provedor específico.

ProvedorCódigo
QITech950002
321 Bank950703

Autenticação​

Para realizar requisições aos nossos endpoints, é necessário utilizar uma API Key válida. Esta chave é o identificador que garante a segurança e o controle de acesso às operações da plataforma.

KeyValue
apikey{{apikey}}
aviso

Importante: Mantenha sua API Key em segurança. Ela é pessoal, intransferível e dá acesso direto às operações de crédito e dados de clientes da sua conta.

Fluxo Principal​

Passos obrigatórios para qualquer conta, independentemente de o fluxo incluir ou não uma etapa de análise de crédito. Ao final do passo Confirmar Operação, verifique a resposta: se ela indicar que a proposta foi enviada para análise, siga para a seção Fluxo Opcional: Análise de Crédito logo abaixo.

POST Criar Termo de Autorização​

/v3/authorization-terms

Cria o termo de autorização para consulta dos dados do vínculo empregatício e do saldo devedor do tomador junto ao empregador. O termo precisa ser assinado antes que a simulação possa prosseguir.

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
type.codestringSimUse sempre "auth_loan_private_payroll_term"
type.namestringSimUse sempre "Termo de Autorização para Empréstimo de Consignado Privado"
identitystringSimCPF do tomador
signer.type.codestringSimUse sempre "person"
signer.type.namestringSimUse sempre "Pessoa"
signer.namestringSimNome completo do tomador
signer.identitystringSimCPF do tomador
signer.phonestringSimTelefone com DDD do tomador

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "type": {
    "code": "auth_loan_private_payroll_term",
    "name": "Termo de Autorização para Empréstimo de Consignado Privado"
  },
  "identity": "00000000000",
  "signer": {
    "type": {
      "code": "person",
      "name": "Pessoa"
    },
    "name": "João Silva",
    "identity": "00000000000",
    "phone": "11999999999"
  }
}

PUT Assinar Termo de Autorização​

/v3/signer/{{signer_key}}/accept

Realiza a assinatura do termo de autorização criado no passo anterior, a partir da chave (key) retornada no response.

Parâmetros de Rota (Path)​

VariávelDescrição
{{signer_key}}Chave (key) do termo retornada na criação do termo de autorização

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
position.latitudestringSimLatitude da localização do tomador no momento da assinatura
position.longitudestringSimLongitude da localização do tomador no momento da assinatura

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "position": {
    "latitude": "-23.4943",
    "longitude": "-46.8517"
  }
}

POST Criar Simulação​

/v3/loan-private-payroll-simulations/providers/{{provider_code}}

Cria a simulação e realiza a consulta do vínculo empregatício do tomador junto ao provedor informado. Caso o tomador não possua termo autorizado, é necessário executar os endpoints de criação e assinatura do termo antes de prosseguir.

Cálculo já disponível na criação

Diferente de outras modalidades, nesta simulação o provedor já retorna, no array items, as combinações de prazo e taxa pré-calculadas disponíveis para o tomador. Caso alguma delas atenda o tomador, não é necessário chamar a calculadora — basta seguir direto para a seleção do item. Se o tomador quiser simular uma condição diferente (outro prazo, taxa ou valor de parcela/desembolso), utilize os passos opcionais Calculadora e Aplicar a Condição Calculada na Simulação antes de prosseguir.

Parâmetros de Rota (Path)​

VariávelDescrição
{{provider_code}}Código do provedor responsável pela operação. Veja Códigos dos Provedores

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
borrower.namestringSimNome completo do tomador
borrower.identitystringSimCPF do tomador
borrower.phonestringSimTelefone com DDD do tomador
step.codenumberSimUse sempre 1
step.namestringSimUse sempre "Simulação de Proposta"
originCodenumberSimCódigo de origem da operação

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "borrower": {
    "name": "João Silva",
    "identity": "00000000000",
    "phone": "11999999999"
  },
  "step": {
    "code": 1,
    "name": "Simulação de Proposta"
  },
  "originCode": 3
}

POST Calculadora (Simular Outra Condição)​

/v3/loan-private-payroll-simulations/{{simulation_id}}/calculation

Passo opcional, usado apenas quando nenhuma das condições retornadas na criação da simulação atende o tomador. Calcula uma condição própria de prazo, taxa ou valor de parcela/desembolso. Este endpoint não grava nada na simulação — apenas devolve o item calculado, que deve ser aplicado através do endpoint Aplicar a Condição Calculada na Simulação.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação criada anteriormente

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
typenumberSimTipo de cálculo. 1 = pelo valor da parcela (usa installmentValue) | 2 = pelo valor de desembolso (usa disbursementValue)
identitystringSimCPF do tomador
ruleIdstring (UUID)SimID da tabela de produto. Use o campo rule.id retornado nos itens da simulação
termnumberSimPrazo em meses
ratenumberSimTaxa de juros mensal
installmentValuenumberCondicionalValor da parcela desejada. Obrigatório quando type = 1
disbursementValuenumberCondicionalValor líquido desejado. Obrigatório quando type = 2
registrationNumberstringNãoMatrícula do tomador junto ao empregador
employerDocumentstringNãoCNPJ do empregador
employerNamestringNãoNome do empregador
hasInsurancebooleanNãoIndica se o cálculo deve considerar seguro
isInitialCalculationbooleanSimUse sempre true
selectedbooleanSimUse sempre true
Envie apenas um dos dois valores

Envie apenas um dos campos installmentValue ou disbursementValue, de acordo com o type informado. Não envie o campo que não se aplica.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "type": 1,
  "identity": "00000000000",
  "ruleId": "61754934-8f52-4323-b63c-4d8f07860a81",
  "term": 84,
  "rate": 2,
  "installmentValue": 750,
  "registrationNumber": "0014641",
  "employerDocument": "00000000000000",
  "employerName": "Empregador Massa Extra 00000000000000",
  "hasInsurance": false,
  "isInitialCalculation": true,
  "selected": true
}

PUT Aplicar a Condição Calculada na Simulação​

/v3/loan-private-payroll-simulations/{{simulation_id}}

Passo opcional, complementar ao anterior. Aplica na simulação a condição obtida na Calculadora, usando exatamente os valores retornados por ela. Após este passo, o item calculado passa a ser o item selecionado da simulação — o mesmo efeito de selecionar um dos itens já retornados na criação da simulação.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
items[].idstring (UUID)Simid do item retornado pela calculadora
items[].ruleIdstring (UUID)SimID da tabela de produto
items[].termnumberSimPrazo em meses
items[].ratenumberSimTaxa de juros mensal
items[].loanValuenumberSimValor total do empréstimo
items[].installmentValuenumberSimValor da parcela
items[].netValuenumberSimValor líquido (troco)
items[].hasInsurancebooleanSimIndica se há seguro
items[].registrationNumberstringNãoMatrícula do tomador junto ao empregador
items[].employerDocumentstringNãoCNPJ do empregador
items[].employerNamestringNãoNome do empregador
items[].firstDueDatestringSimData do primeiro vencimento
items[].lastDueDatestringSimData do último vencimento
items[].totalEffectiveCostnumberSimCusto Efetivo Total (CET)
items[].selectedbooleanSimUse sempre true
items[].isInitialCalculationbooleanSimUse sempre true
items[].baseValuenumberSimValor base da operação
items[].additionalValuenumberSimValor adicional (0 se não houver)

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "items": [
    {
      "id": "a17c4f2e-3b6d-4e8a-9c1f-7d2b5e9a0c3d",
      "ruleId": "61754934-8f52-4323-b63c-4d8f07860a81",
      "term": 84,
      "rate": 2,
      "loanValue": 29516.91,
      "installmentValue": 750,
      "netValue": 28524.97,
      "hasInsurance": false,
      "registrationNumber": "0014641",
      "employerDocument": "00000000000000",
      "employerName": "Empregador Massa Extra 00000000000000",
      "firstDueDate": "2026-07-28",
      "lastDueDate": "2033-06-28",
      "totalEffectiveCost": 2.11,
      "selected": true,
      "isInitialCalculation": true,
      "baseValue": 28524.97,
      "additionalValue": 0
    }
  ]
}

GET Consultar Simulação​

/v3/loan-private-payroll-simulations/{{simulation_id}}

Consulta os dados atuais da simulação, incluindo o array items com as condições disponíveis e o objeto employmentRelationships com os dados do vínculo empregatício retornados pelo provedor.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação gerada anteriormente

Exemplo de Requisição e Resposta​

Visualizar cURL
curl --location 'https://integration.ajin.io/v3/loan-private-payroll-simulations/{{simulation_id}}' \
--header 'apikey: {{apikey}}'

PUT Definir Item da Simulação e Atualizar Dados Cadastrais​

/v3/loan-private-payroll-simulations/{{simulation_id}}

Seleciona a condição (item) escolhida pelo tomador dentre as retornadas na criação da simulação e complementa o cadastro com os dados pessoais, endereço e a forma de recebimento do crédito.

Forma de recebimento

Envie apenas um dos objetos creditBankAccount ou creditPix, de acordo com o valor informado em creditMethod. Não envie o objeto que não se aplica.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
itemIdstring (UUID)SimID do item da simulação a ser selecionado
borrower.namestringSimNome completo do tomador
borrower.birthDatestring (ISO 8601)SimData de nascimento
borrower.identitystringSimCPF do tomador
borrower.phonestringSimTelefone com DDD
borrower.sexstringSimSexo. Masculino | Feminino
borrower.document.type.codestringSimrg ou cnh
borrower.document.type.namestringSimRG ou CNH
borrower.document.numberstringSimNúmero do documento
borrower.document.issuingDatestringSimData de emissão do documento
borrower.document.issuingEntitystringSimÓrgão expedidor
borrower.document.issuingStatestringSimUF de expedição
borrower.maritalStatusstringSimEstado civil. Solteiro | Casado | Divorciado | Viúvo
borrower.emailstringSimE-mail do tomador
borrower.motherNamestringSimNome da mãe
borrower.address.streetstringSimRua
borrower.address.numberstringSimNúmero
borrower.address.complementstringNãoComplemento
borrower.address.districtstringSimBairro
borrower.address.citystringSimCidade
borrower.address.statestringSimEstado (UF)
borrower.address.zipCodestringSimCEP
creditMethodnumberSimForma de recebimento do crédito. 1 = Conta Bancária | 2 = PIX
creditBankAccount.typenumberCondicionalTipo da conta. 1 = Conta corrente | 2 = Conta poupança. Obrigatório quando creditMethod = 1
creditBankAccount.bankstringCondicionalCódigo do banco. Obrigatório quando creditMethod = 1
creditBankAccount.branchstringCondicionalAgência. Obrigatório quando creditMethod = 1
creditBankAccount.numberstringCondicionalNúmero da conta. Obrigatório quando creditMethod = 1
creditBankAccount.digitstringCondicionalDígito da conta. Obrigatório quando creditMethod = 1
creditPix.typestringCondicionalTipo da chave PIX. email | identity (CPF) | phone | random_key. Obrigatório quando creditMethod = 2
creditPix.keystringCondicionalChave PIX. Obrigatório quando creditMethod = 2

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "itemId": "c5e5a810-96e8-4655-8119-559edde8f00c",
  "borrower": {
    "name": "João Silva",
    "birthDate": "1998-02-11T02:00:00.000Z",
    "identity": "00000000000",
    "phone": "11999999999",
    "sex": "Masculino",
    "document": {
      "type": {
        "code": "rg",
        "name": "RG"
      },
      "number": "000000000",
      "issuingDate": "2009-01-23",
      "issuingEntity": "SSP",
      "issuingState": "SP"
    },
    "maritalStatus": "Solteiro",
    "email": "[email protected]",
    "motherName": "Maria da Silva",
    "address": {
      "street": "Rua",
      "number": "60",
      "complement": "",
      "district": "Vila",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "00000-000"
    }
  },
  "creditMethod": 1,
  "creditBankAccount": {
    "type": 1,
    "bank": "1",
    "branch": "3448",
    "number": "989898",
    "digit": "9"
  },
  "creditPix": {
    "type": "identity",
    "key": "00000000000"
  }
}

POST Confirmar Operação​

/v3/loan-private-payroll-simulations/{{simulation_id}}/actions

Confirma a operação. Deve ser chamado logo após a definição do item e dos dados cadastrais. É neste passo que o fluxo se divide, dependendo de a conta utilizar ou não análise de crédito:

Outros retornos possíveis (HTTP 400)
  • 1136002 — "Nenhum item para essa simulação": a análise já foi concluída, mas o item pós-análise ainda não foi selecionado. Vá direto para Consultar Simulação (Pós-Análise).
  • 1136046, 1136069 ou 1136078 — a operação foi reprovada na análise de crédito. O fluxo é encerrado sem emissão de contrato.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
commandstringSimComando a ser executado. Use "create_loans" para confirmar a operação

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "command": "create_loans"
}

Fluxo Opcional: Análise de Crédito​

Os endpoints desta seção só se aplicam a contas cujo fluxo de contratação inclui uma etapa de análise de crédito. Eles só devem ser utilizados quando o passo Confirmar Operação do Fluxo Principal retornar 400 com o código 1136074 ou 1136059 ("Análise em andamento"). Se ele retornar 200, o contrato já foi emitido e nada abaixo precisa ser executado.

Quando a análise de crédito estiver presente, siga esta ordem:

  1. Consultar Status da Análise de Crédito — repita esta chamada (polling) até que todas as análises retornadas estejam aprovadas.
  2. Consultar Simulação (Pós-Análise) — obtenha o id do item recalculado pelo provedor.
  3. Selecionar Item Final da Simulação — selecione esse item na simulação.
  4. Confirmar Operação e Emitir Contrato — finalize a operação e emita o contrato.

GET Consultar Status da Análise de Crédito​

/v3/credit-analysis/{{simulation_id}}

Consulta o status das análises realizadas pelo provedor para a simulação (onboarding, análise de pessoa física e/ou pessoa jurídica, conforme o caso). Utilize este endpoint para acompanhar a evolução da análise disparada na confirmação da operação.

Status possíveis por análise
  • pending, in_queue, in_manual_analysis — em andamento
  • automatically_approved, manually_approved — aprovada
  • automatically_reproved, manually_reproved — reprovada

A análise é considerada concluída quando todas as análises retornadas estiverem aprovadas. Se qualquer uma delas estiver reprovada, o fluxo é encerrado sem emissão de contrato.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Exemplo de Requisição e Resposta​

Visualizar cURL
curl --location 'https://integration.ajin.io/v3/credit-analysis/{{simulation_id}}' \
--header 'apikey: {{apikey}}'

GET Consultar Simulação (Pós-Análise)​

/v3/loan-private-payroll-simulations/{{simulation_id}}

Após a análise de crédito ser concluída com aprovação, o provedor recalcula as condições finais da operação e inclui um novo item no array items, com isInitialCalculation: false e selected: false. Utilize este endpoint para obter o id desse item antes de selecioná-lo.

Analise ainda não concluída

Caso o item com isInitialCalculation: false ainda não esteja presente, a análise de crédito ainda está em andamento. Volte para Consultar Status da Análise de Crédito e aguarde a conclusão antes de repetir esta consulta.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Exemplo de Requisição e Resposta​

Visualizar cURL
curl --location 'https://integration.ajin.io/v3/loan-private-payroll-simulations/{{simulation_id}}' \
--header 'apikey: {{apikey}}'

PUT Selecionar Item Final da Simulação (Pós Análise de Crédito)​

/v3/loan-private-payroll-simulations/{{simulation_id}}

Após a conclusão da análise de crédito, o provedor recalcula as condições finais da operação e inclui um novo item no array items. Este endpoint seleciona esse item final antes da confirmação definitiva da operação.

Identificando o item correto

Selecione, na lista de items retornada pela Consulta da Simulação (Pós-Análise), o item cujo campo isInitialCalculation esteja como false. Ele representa as condições já validadas pela análise de crédito.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
itemIdstring (UUID)SimID do item com isInitialCalculation: false retornado após a análise de crédito

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "itemId": "0e5576a0-54ec-4c3d-9180-6015b34421ac"
}

POST Confirmar Operação e Emitir Contrato​

/v3/loan-private-payroll-simulations/{{simulation_id}}/actions

Executa a etapa final de confirmação, agora com o item pós-análise já selecionado. São realizadas as validações das regras operacionais e, em caso de sucesso, ocorre a emissão da proposta e a atualização definitiva do status da operação.

Parâmetros de Rota (Path)​

VariávelDescrição
{{simulation_id}}UUID da simulação

Parâmetros do Body​

Visualizar Parâmetros
CampoTipoObrigatórioDescrição
commandstringSimComando a ser executado. Use "create_loans" para confirmar a operação

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "command": "create_loans"
}