Solicitar e Consultar Simulação Assertiva

1. Contexto

A Simulação Assertiva é um dos endpoints disponibilizados pela Creditas para integração dos parceiros ao fluxo de aquisição de leads de crédito com garantia de veículo (Auto Equity). Atualmente, o conjunto de endpoints oferecidos foi estruturado para atender as diferentes etapas do processo de oferta, criação da proposta e acompanhamento de propostas.

A imagem abaixo ilustra o fluxo recomendado de integração, que orienta a sequência ideal das chamadas entre os endpoints.

Nessa sequência, a Simulação Assertiva (etapa destacada na régua acima) corresponde ao momento em que executamos políticas internas de qualificação e realizamos cálculos para retorno de uma oferta quente, com informações assertivas sobre as condições de crédito disponíveis.

Este documento descreve em detalhe o funcionamento dos endpoints /offers e /offers/[id], seu papel dentro desse fluxo, e as orientações técnicas para sua correta implementação.

2. Objetivo da Simulação Assertiva

O endpoint de Simulação Assertiva tem como objetivo retornar uma oferta quente ao cliente final, ou seja, uma oferta qualificada e assertiva em termos de condições de crédito.

De forma mais detalhada, podemos falar que essa simulação cumpre dois papéis complementares dentro do fluxo:

• Realizar a pré-qualificação do lead, aplicando, antes mesmo do cálculo dos valores, um conjunto de políticas internas de elegibilidade e risco.
• Garantir a assertividade da oferta, proporcionando ao cliente uma prévia fiel das condições finais de crédito — taxas, prazos e valores — que ele encontrará ao prosseguir para a criação de proposta.

Com isso, o endpoint de Simulação Assertiva assegura que apenas leads qualificados recebam ofertas viáveis, contribuindo para uma jornada mais fluida e confiável tanto para o parceiro quanto para o cliente final.

3. Funcionamento Geral

A seguir, trazemos o fluxo completo de aplicação dos nossos endpoints sendo aplicados de uma perspectiva prática, dentro da jornada do ambiente do parceiro, e também técnica, com as chamadas que precisam ser realizadas.

3.1. Descrição do Processo de Aplicação

1. Início do processo
   • O cliente ou sistema parceiro inicia o fluxo solicitando uma simulação de crédito.
   
   
2. Criação de oferta — POST /offers
   • É enviada uma requisição para criação de uma oferta.
   • Nesta etapa, são informados apenas os dados mínimos necessários para calcular condições de crédito iniciais.
   • O retorno contém o identificador da oferta (offerId), que servirá como referência para próximos passos.
   
   
3. Consulta de oferta — GET /offers/[id]
   • Decisão do motor: oferta aprovada?
     • Aqui ocorre a validação da oferta.
     • Se a análise indicar que a oferta não está aprovada, o fluxo é encerrado.
     • Caso a oferta esteja aprovada, o processo pode avançar para formalização.
   • Após criada, a oferta pode ser consultada a qualquer momento para verificar suas condições e status.
   • O endpoint retorna os detalhes da simulação (ex.: taxa de juros, prazo, valor financiado).
   • Existe também a opção de receber o retorno da oferta pelo Webhook.
   
   
4. Criação da proposta — POST /proposals
   • Com uma oferta aprovada em mãos, o cliente pode prosseguir para criar a proposta de crédito.
   • Nesta etapa, além do offerId, devem ser enviados dados adicionais (como informações de tomador, garantia e condições específicas).
   • O sistema executa análises mais profundas (internas e externas, como consultas ao Bacen).
   • O retorno é o identificador da proposta (proposalId), que formaliza a solicitação de empréstimo.
   
   

🚧

Durante a execução das políticas internas para análise de viabilidade de crédito e liberação de uma oferta, são executadas consultas externas que podem gerar atrasos e maior tempo de resposta. Quando isso ocorre é necessário termos um processo de redundância onde mantemos uma resposta de análise sem a assertividade das políticas, desta forma, utilizamos a simulação fria.

O tempo de atraso (timeout) aceito é de 10 segundos, ou seja, quando executamos as políticas internas e as respostas não são retornadas até 10 segundos, fazemos o processo de simulação fria.

4. API Reference

Como já falado anteriormente, o recurso da Simulação Assertiva, disponibilizado nos endpoints /offers (para criação da oferta e acionamento das políticas) e /offers/id (para retorno das condições da oferta), realiza a qualificação do cliente e calcula, de forma assertiva, as taxas de crédito para um cliente.

❗️

Importante: este endpoint não cria uma solicitação de empréstimo na Creditas, apenas qualifica e calcula as taxas e valores para geração de uma oferta. Para solicitação de empréstimo, utilize o endpoint de criação da proposta (/proposals).

4.1. Solicitar a Simulação Assertiva — [POST] /offers

Este endpoint dá início ao processo de consulta das políticas (que é realizado de forma assíncrona) e gera o ID da oferta.

4.1.1. Request HTTP

4.1.2. Request Header

4.1.3. Request Params

4.1.4. Request Response

4.1.5. Exemplo de Request

Os exemplos são com e sem todos os dados do objeto Collateral. Ambos exemplos são funcionais e não afetam os valores da simulação de oferta.

curl --location --request POST '{{url_base}}/offers' \
--header 'Accept: application/vnd.creditas.v1+json' \
--header 'Content-Type: application/json;charset=UTF-8' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "purpose": "DEBTS_PAYMENT",
    "metadata": {"version": "V2024"},
    "intendedCredit": {
        "currency": "BRL",
        "amount": 50000
    },
    "borrower": {
        "email": "[email protected]",
        "birthDate": "1996-06-03",
        "cellphone": "965984565",
        "cellphoneCode": "11",
        "monthlyIncome": 5500,
        "professionalStatus": "CLT",
        "postalCode": "09181000",
        "cpf": "65498745698",
        "timeOfEmployment": "LESS_THAN_SIX_MONTHS",
        "bacenAuthorization": {
            "authorizationTerms": "O cliente autorizou a consulta de informações a seu respeito mantidas no Sistema de Informações (SCR) organizado pelo Banco Central do Brasil.",
            "bacenAuthorizedAt": "2023-06-02",
            "userAgent": "userAgent",
            "userIp": "191.17.110.30"
        }
    },
    "collateral": {
        "value": 15000,
        "brand": "CHEVROLET",
        "model": "PRISMA",
        "modelYear": "2014",
        "modelVersion": "LT 1.0 8V SPE/4",
        "manufacturingYear": "2014",
        "borrowerVehicleOwner": true,
        "licensePlate": "DPX1O73",
        "ownerKinshipDegree": "SPOUSE"
    }
}'

curl --location --request POST '{{url_base}}/offers' \
--header 'Accept: application/vnd.creditas.v1+json' \
--header 'Content-Type: application/json;charset=UTF-8' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "purpose": "DEBTS_PAYMENT",
    "intendedCredit": {
        "currency": "BRL",
        "amount": 50000
    },
    "borrower": {
        "email": "[email protected]",
        "birthDate": "1996-06-03",
        "cellphone": "965984565",
        "cellphoneCode": "11",
        "monthlyIncome": 5500,
        "professionalStatus": "CLT",
        "postalCode": "09181000",
        "cpf": "65498745698",
        "timeOfEmployment": "LESS_THAN_SIX_MONTHS",
        "bacenAuthorization": {
            "authorizationTerms": "O cliente autorizou a consulta de informações a seu respeito mantidas no Sistema de Informações (SCR) organizado pelo Banco Central do Brasil.",
            "bacenAuthorizedAt": "2023-06-02",
            "userAgent": "userAgent",
            "userIp": "191.17.110.30"
        }
    },
    "collateral": {
        "value": 15000,
        "debt": 5000,
        "borrowerVehicleOwner": true,
        "licensePlate": "DPX1O73",
        "pricingDetail": {
            "type": "MOLICAR",
            "code": "teste"
        }
    }
}'

4.1.6. Exemplo de Response

{
    "id": "OFR-DBC79D7F-E5D7-45B9-B9DD-A60C2561EA06"
}

4.2. Consultar Simulação Assertiva — [GET]/offers/[id]

Este endpoint é responsável por levar ao parceiro as condições da oferta (limite de crédito, taxa, IOF, parcelas etc) e os status da Simulação Assertiva.

4.2.1. Request HTTP

4.2.2. Request Header

4.1.3. Request Params

4.2.3. Request Response

4.2.4. Exemplos de Request e Response

curl --location --request GET '{{url_base}}/offers/{{id}}' \
--header 'Accept: application/vnd.creditas.v1+json' \
--header 'Content-Type: application/json;charset=UTF-8' \
--header 'Authorization: Bearer {{access_token}}'

{
    "id": "OFR-DBC79D7F-E5D7-45B9-B9DD-A60C2561EA06",
    "scoreFixed": false,
    "approvedStatus": "ANALYSIS_CREATED",
    "offers": [
        {
            "loanTerm": 60,
            "monthlyInterestRate": 0.05,
            "totalEffectiveCost": 0.0359,
            "installmentAmount": 3000.17,
            "loanAmount": 27833.46,
            "iof": 27833.46
        }
    ]
}