Guides

Início

Ambientes

AmbienteURL Base
Sandboxhttps://api-bnpl.sandbox.geru.com.br/
Produçãohttps://***

Autenticação

Todas as requisições à API exigem autenticação via Bearer Token ou API Key:

# Bearer Token
Authorization: Bearer <your-token>

# OU API Key
X-API-Key: <your-api-key>

Máquina de Estados da Aplicação

Uma aplicação passa pelos seguintes estados durante seu ciclo de vida:

#StatusDescrição
1APPLICATION_CREATEDEstado inicial após a criação da aplicação
2APPLICATION_APPROVEDModelo de crédito aprovou a aplicação (possui ofertas e limite disponível)
3APPLICATION_DECLINEDModelo de crédito recusou a aplicação (sem ofertas ou limite disponível)
4APPLICATION_COMPLETEDCliente selecionou uma oferta e a aplicação foi atualizada
5CONTRACT_SIGNEDCliente assinou o contrato com OTP
6APPROVEDAnálise antifraude aprovou a aplicação
7DECLINEDAnálise antifraude recusou a aplicação
8SUBMITTED_TO_FIAplicação enviada para a instituição financeira
9FUNDEDEmpréstimo desembolsado com sucesso
10CANCELLEDAplicação foi cancelada
11FUNDING_FAILEDProcesso de desembolso falhou

Passo 1: Verificar Elegibilidade do Cliente

Antes de iniciar a aplicação, verifique se o cliente é elegível para o BNPL:

POST /fastqualify
{
  "cpf": "78011189603"
}

Resposta:

{
  "status": "Eligible",
  "person_id": "19474477-dc20-4b0a-9dfa-b3d3012c5401"
}
📘

Observação

Se o cliente for Not Eligible, ele não poderá prosseguir com a aplicação BNPL. Salve o person_id - você precisará dele nas chamadas subsequentes da API.


Passo 2: Criar a Aplicação

Crie uma aplicação de crédito para executar a política de crédito e obter as ofertas disponíveis:

POST /application/create

Requisição:

{
  "cpf": "111.111.111-11",
  "order_reference": "order_reference_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 }
  ],
  "shipping": {
    "value": 15.00,
    "zip": "01310100"
  }
}
📝

Observação: Os campos order_reference, cart e shipping são opcionais nesta etapa, mas recomendados para um cálculo de oferta mais preciso.

Resposta:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "max_total_value": 4726.28,
  "available_limit": 4726.28,
  "max_installment_value": 1500.0,
  "min_installment_value": 20.00,
  "offer_parameters_list": [
    {
      "term": 3,
      "monthly_interest_rate": 0.0445,
      "amount": 25.50,
      "upfront_installment": 10.50,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 52.17,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 25.50,
          "due_principal": 36.14,
          "due_interest": 18.07,
          "tax_amount": 0.05,
          "principal_amortization_amount": 7.38
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 25.50,
          "due_principal": 36.14,
          "due_interest": 17.02,
          "tax_amount": 0.05,
          "principal_amortization_amount": 8.43
        }
      ]
    },
    {
      "term": 4,
      "monthly_interest_rate": 0.0449,
      "amount": 19.50,
      "upfront_installment": 10.50,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 45.83,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 15.85,
          "tax_amount": 0.05,
          "principal_amortization_amount": 3.60
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 14.99,
          "tax_amount": 0.03,
          "principal_amortization_amount": 4.48
        },
        {
          "installment_number": 4,
          "due_date": "2024-12-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 14.99,
          "tax_amount": 0.02,
          "principal_amortization_amount": 4.49
        }
      ]
    },
    {
      "term": 5,
      "monthly_interest_rate": 0.0449,
      "amount": 10.50,
      "upfront_installment": 0.00,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 39.45,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.87,
          "tax_amount": 0.05,
          "principal_amortization_amount": 0.58
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.85,
          "tax_amount": 0.03,
          "principal_amortization_amount": 0.62
        },
        {
          "installment_number": 4,
          "due_date": "2024-12-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.83,
          "tax_amount": 0.01,
          "principal_amortization_amount": 0.66
        },
        {
          "installment_number": 5,
          "due_date": "2025-01-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.90,
          "tax_amount": 0.01,
          "principal_amortization_amount": 0.59
        }
      ]
    }
  ],
  "expires_at": "2026-01-21T00:00:00-03:00"
}
📘

Limite Disponível

O campo available_limit mostra o limite de crédito atual do cliente. Você também pode consultar isso em tempo real usando o endpoint /person/{person_id}/available-limit.

🔄

Simulação de Oferta

Descrição dos Campos:

CampoDescrição
termNúmero de parcelas
amountValor da parcela regular em BRL
upfront_installmentValor da primeira parcela (pode diferir das parcelas regulares)
cetCET (Custo Efetivo Total) mensal em percentual
annual_cetCET anual em percentual
total_iofValor total do IOF (Imposto sobre Operações Financeiras)
total_interestValor total de juros do empréstimo
first_due_dateData de vencimento da primeira parcela
disbursement_dateData prevista de desembolso
feesLista de taxas aplicadas ao empréstimo
installmentsDetalhamento de cada parcela
⚠️

Importante: Atualizações do Carrinho

Toda vez que o carrinho de compras for atualizado (itens adicionados/removidos, quantidades alteradas, frete modificado, cupom adicionado - basicamente tudo que altere o valor), você deve chamar o endpoint createApplication novamente para recalcular as ofertas com o novo valor. Isso garante simulações financeiras precisas e conformidade com as regulamentações.

Exemplo: Fluxo de Atualização do Carrinho

Cenário: Cliente adiciona mais itens ao carrinho após a aplicação inicial

  1. Aplicação Inicial (Total do Carrinho: R$ 515,00)
POST /application/create
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "order_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 }
  ],
  "shipping": { "value": 15.00, "zip": "01310100" }
}

A resposta inclui ofertas para R$ 515,00

  1. Cliente Adiciona Item (Novo Total do Carrinho: R$ 715,00)
POST /application/create
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "order_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 },
    { "item": "Product C", "value": 200.00 }
  ],
  "shipping": { "value": 15.00, "zip": "01310100" }
}

A resposta inclui ofertas recalculadas para R$ 715,00 com valores de parcelas, IOF e CET atualizados

📌

Importante: Sempre utilize o application_id mais recente da última chamada ao createApplication ao prosseguir para as etapas de atualização/assinatura.

Passo 3: Atualizar com a Oferta Selecionada

Após o cliente selecionar uma oferta, atualize a aplicação com os detalhes da compra:

PUT /application/{application_id}/update

Cabeçalhos:

Ip-Address: <client-ip-address>
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "amount": 500.00,
  "currency": "BRL",
  "term": 4,
  "order_reference": "order_reference",
  "cart": [
    { "item": "Product Name", "value": 500.00 }
  ],
  "shipping": {
    "value": 0,
    "zip": "01310100"
  }
}

A resposta inclui:

  • installment_amount: Valor da parcela mensal
  • total_interest_amount: Juros totais
  • contract_string: Contrato em PDF codificado em Base64
  • person_phone_number: Telefone para o qual o OTP foi enviado
⚠️

Importante

Um código OTP será enviado para o telefone do cliente para assinatura do contrato.

Passo 4: Assinar o Contrato

Assine o contrato usando o OTP enviado ao cliente:

POST /application/{application_id}/sign

Cabeçalhos:

Ip-Address: <client-ip-address>
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "otp": "265117"
}

Resposta:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "CONTRACT_SIGNED",
  "signed_at": "2026-01-20T10:40:00Z"
}
💡

Nota sobre Integração Antifraude

Se você não integrar o Passo 6 (validação de liveness por selfie), as regras antifraude serão executadas automaticamente nesta etapa. Nesse caso, a resposta incluirá os campos approved_at ou declined_at:

Exemplo de Aprovação:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "APPROVED",
  "signed_at": "2026-01-20T10:40:00Z",
  "approved_at": "2026-01-20T10:40:00Z"
}

Exemplo de Recusa:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "DECLINED",
  "signed_at": "2026-01-20T10:40:00Z",
  "declined_at": "2026-01-20T10:40:00Z"
}

Reenviar OTP (se necessário)

Se o cliente não recebeu o OTP ou se ele expirou:

POST /application/{application_id}/resend
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62"
}

Resposta:

{
  "person_phone_number": 83991116537,
  "sent_at": "2026-01-20T10:42:00Z",
  "expires_at": "2026-01-20T10:47:00Z"
}

Passo 5: Aprovação Antifraude (Validação de Liveness por Selfie) - OPCIONAL

⚠️

Este passo é OPCIONAL

Se você integrar a validação de liveness por selfie, este endpoint acionará o processo de desembolso. Se você não integrar este passo, as regras antifraude serão executadas automaticamente durante o Passo 4 (Assinar Contrato), e o desembolso será acionado a partir de lá.

Envie a aplicação para análise antifraude com validação de liveness por selfie:

🔐

Requisito de Integração com o SDK da QI Tech

O parceiro precisa integrar o SDK da QI Tech no front-end para captura de liveness por selfie.

Documentação do SDK: QI Tech Face Recognition - Android Liveness

Fluxo de Integração:

  1. Chame a função de liveness do SDK da QI Tech com o CPF do cliente (parâmetro obrigatório)
  2. O SDK captura a selfie do cliente e realiza a detecção de liveness
  3. O SDK retorna uma registration_key para a validação de liveness facial
  4. Salve esta registration key - você precisará dela para chamar o endpoint de aprovação
POST /application/{application_id}/approval

Cabeçalhos:

Ip-Address: <client-ip-address>

Requisição:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "face": {
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  },
  "selfie": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

Observação: O campo selfie é opcional e aceita uma imagem codificada em base64 para verificação adicional.

📝

Processo de Validação no Backend

No backend, validamos o liveness usando a API da QI Tech: Onboarding de Pessoa Física

A registration key é utilizada para validar o liveness com base em regras antifraude pré-estabelecidas. Isso inclui a verificação de:

  • Correspondência facial com o CPF
  • Detecção de liveness (pessoa real vs foto/vídeo)
  • Sinais de prevenção à fraude
  • Verificação de identidade

Resposta (Aprovado):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "approved_at": "2026-01-20T10:40:00Z"
}

Resposta (Recusado):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "declined_at": "2026-01-20T10:40:00Z"
}

Passo 6: Cobrar a Aplicação e Monitorar o Desembolso

Após a validação antifraude ser aprovada (via Passo 6 ou automaticamente durante a assinatura), faça a cobrança da aplicação para verificar o desembolso:

POST /application/{application_id}/charge

Requisição:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "testCredit1"
}

Exemplos de Resposta:

1. Enviado para a IF (Pendente):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "SUBMITTED_TO_FI",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}

2. Desembolsado (Sucesso):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "FUNDED",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}

3. Falha no Desembolso:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "FUNDING_FAILED",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}
💰

Atualização do Limite de Crédito

Quando o status é SUBMITTED_TO_FI, o limite de crédito do cliente é atualizado:

  • Limite inicial do cliente: R$ 1.000,00
  • Valor financiado: R$ 500,00
  • Novo limite disponível: R$ 500,00

Significado dos Status:

StatusAção Necessária
SUBMITTED_TO_FI⏳ PENDENTE - Desembolso em andamento, chame novamente para verificar o status
FUNDED✅ CONFIRMAR PEDIDO - Desembolso realizado com sucesso, prossiga com o envio
FUNDING_FAILED❌ CANCELAR PEDIDO - Desembolso falhou, o limite do cliente é restaurado
🔄

Restauração do Limite em Caso de Falha

Se o status for FUNDING_FAILED, o limite de crédito do cliente é automaticamente restaurado ao valor original (o valor financiado é creditado de volta).

Fluxo Recomendado:

  1. Chame o endpoint /charge → Obtenha o status inicial
  2. Se SUBMITTED_TO_FI → Aguarde alguns segundos e chame /charge novamente para verificar o status atualizado
  3. Se FUNDED → ✅ Confirme e envie o pedido
  4. Se FUNDING_FAILED → ❌ Cancele o pedido e notifique o cliente
🎉

Sucesso!

Quando o status for FUNDED, o empréstimo está ativo e o cliente receberá seu plano de pagamento. Agora você pode prosseguir com o envio do pedido.

Endpoints Adicionais

Consultar Limite Disponível em Tempo Real

Verifique o limite de crédito disponível atual do cliente:

GET /person/{person_id}/available-limit

Resposta:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "available_limit": 4726.28,
  "currency": "BRL",
  "updated_at": "2026-01-20T10:30:00Z"
}

***## Ambientes

AmbienteURL Base
Sandboxhttps://api-bnpl.sandbox.geru.com.br/
Produçãohttps://***

Autenticação

Todas as requisições à API exigem autenticação via Bearer Token ou API Key:

# Bearer Token
Authorization: Bearer <your-token>

# OU API Key
X-API-Key: <your-api-key>

Máquina de Estados da Aplicação

Uma aplicação passa pelos seguintes estados durante seu ciclo de vida:

#StatusDescrição
1APPLICATION_CREATEDEstado inicial após a criação da aplicação
2APPLICATION_APPROVEDModelo de crédito aprovou a aplicação (possui ofertas e limite disponível)
3APPLICATION_DECLINEDModelo de crédito recusou a aplicação (sem ofertas ou limite disponível)
4APPLICATION_COMPLETEDCliente selecionou uma oferta e a aplicação foi atualizada
5CONTRACT_SIGNEDCliente assinou o contrato com OTP
6APPROVEDAnálise antifraude aprovou a aplicação
7DECLINEDAnálise antifraude recusou a aplicação
8SUBMITTED_TO_FIAplicação enviada para a instituição financeira
9FUNDEDEmpréstimo desembolsado com sucesso
10CANCELLEDAplicação foi cancelada
11FUNDING_FAILEDProcesso de desembolso falhou

Passo 1: Verificar Elegibilidade do Cliente

Antes de iniciar a aplicação, verifique se o cliente é elegível para o BNPL:

POST /fastqualify
{
  "cpf": "78011189603"
}

Resposta:

{
  "status": "Eligible",
  "person_id": "19474477-dc20-4b0a-9dfa-b3d3012c5401"
}
📘

Observação

Se o cliente for Not Eligible, ele não poderá prosseguir com a aplicação BNPL. Salve o person_id - você precisará dele nas chamadas subsequentes da API.


Passo 2: Criar a Aplicação

Crie uma aplicação de crédito para executar a política de crédito e obter as ofertas disponíveis:

POST /application/create

Requisição:

{
  "cpf": "111.111.111-11",
  "order_reference": "order_reference_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 }
  ],
  "shipping": {
    "value": 15.00,
    "zip": "01310100"
  }
}
📝

Observação: Os campos order_reference, cart e shipping são opcionais nesta etapa, mas recomendados para um cálculo de oferta mais preciso.

Resposta:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "max_total_value": 4726.28,
  "available_limit": 4726.28,
  "max_installment_value": 1500.0,
  "min_installment_value": 20.00,
  "offer_parameters_list": [
    {
      "term": 3,
      "monthly_interest_rate": 0.0445,
      "amount": 25.50,
      "upfront_installment": 10.50,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 52.17,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 25.50,
          "due_principal": 36.14,
          "due_interest": 18.07,
          "tax_amount": 0.05,
          "principal_amortization_amount": 7.38
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 25.50,
          "due_principal": 36.14,
          "due_interest": 17.02,
          "tax_amount": 0.05,
          "principal_amortization_amount": 8.43
        }
      ]
    },
    {
      "term": 4,
      "monthly_interest_rate": 0.0449,
      "amount": 19.50,
      "upfront_installment": 10.50,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 45.83,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 15.85,
          "tax_amount": 0.05,
          "principal_amortization_amount": 3.60
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 14.99,
          "tax_amount": 0.03,
          "principal_amortization_amount": 4.48
        },
        {
          "installment_number": 4,
          "due_date": "2024-12-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 14.99,
          "tax_amount": 0.02,
          "principal_amortization_amount": 4.49
        }
      ]
    },
    {
      "term": 5,
      "monthly_interest_rate": 0.0449,
      "amount": 10.50,
      "upfront_installment": 0.00,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 39.45,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.87,
          "tax_amount": 0.05,
          "principal_amortization_amount": 0.58
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.85,
          "tax_amount": 0.03,
          "principal_amortization_amount": 0.62
        },
        {
          "installment_number": 4,
          "due_date": "2024-12-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.83,
          "tax_amount": 0.01,
          "principal_amortization_amount": 0.66
        },
        {
          "installment_number": 5,
          "due_date": "2025-01-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.90,
          "tax_amount": 0.01,
          "principal_amortization_amount": 0.59
        }
      ]
    }
  ],
  "expires_at": "2026-01-21T00:00:00-03:00"
}
📘

Limite Disponível

O campo available_limit mostra o limite de crédito atual do cliente. Você também pode consultar isso em tempo real usando o endpoint /person/{person_id}/available-limit.

🔄

Simulação de Oferta

Descrição dos Campos:

CampoDescrição
termNúmero de parcelas
amountValor da parcela regular em BRL
upfront_installmentValor da primeira parcela (pode diferir das parcelas regulares)
cetCET (Custo Efetivo Total) mensal em percentual
annual_cetCET anual em percentual
total_iofValor total do IOF (Imposto sobre Operações Financeiras)
total_interestValor total de juros do empréstimo
first_due_dateData de vencimento da primeira parcela
disbursement_dateData prevista de desembolso
feesLista de taxas aplicadas ao empréstimo
installmentsDetalhamento de cada parcela
⚠️

Importante: Atualizações do Carrinho

Toda vez que o carrinho de compras for atualizado (itens adicionados/removidos, quantidades alteradas, frete modificado, cupom adicionado - basicamente tudo que altere o valor), você deve chamar o endpoint createApplication novamente para recalcular as ofertas com o novo valor. Isso garante simulações financeiras precisas e conformidade com as regulamentações.

Exemplo: Fluxo de Atualização do Carrinho

Cenário: Cliente adiciona mais itens ao carrinho após a aplicação inicial

  1. Aplicação Inicial (Total do Carrinho: R$ 515,00)
POST /application/create
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "order_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 }
  ],
  "shipping": { "value": 15.00, "zip": "01310100" }
}

A resposta inclui ofertas para R$ 515,00

  1. Cliente Adiciona Item (Novo Total do Carrinho: R$ 715,00)
POST /application/create
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "order_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 },
    { "item": "Product C", "value": 200.00 }
  ],
  "shipping": { "value": 15.00, "zip": "01310100" }
}

A resposta inclui ofertas recalculadas para R$ 715,00 com valores de parcelas, IOF e CET atualizados

📌

Importante: Sempre utilize o application_id mais recente da última chamada ao createApplication ao prosseguir para as etapas de atualização/assinatura.

Passo 3: Atualizar com a Oferta Selecionada

Após o cliente selecionar uma oferta, atualize a aplicação com os detalhes da compra:

PUT /application/{application_id}/update

Cabeçalhos:

Ip-Address: <client-ip-address>
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "amount": 500.00,
  "currency": "BRL",
  "term": 4,
  "order_reference": "order_reference",
  "cart": [
    { "item": "Product Name", "value": 500.00 }
  ],
  "shipping": {
    "value": 0,
    "zip": "01310100"
  }
}

A resposta inclui:

  • installment_amount: Valor da parcela mensal
  • total_interest_amount: Juros totais
  • contract_string: Contrato em PDF codificado em Base64
  • person_phone_number: Telefone para o qual o OTP foi enviado
⚠️

Importante

Um código OTP será enviado para o telefone do cliente para assinatura do contrato.

Passo 4: Assinar o Contrato

Assine o contrato usando o OTP enviado ao cliente:

POST /application/{application_id}/sign

Cabeçalhos:

Ip-Address: <client-ip-address>
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "otp": "265117"
}

Resposta:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "CONTRACT_SIGNED",
  "signed_at": "2026-01-20T10:40:00Z"
}
💡

Nota sobre Integração Antifraude

Se você não integrar o Passo 6 (validação de liveness por selfie), as regras antifraude serão executadas automaticamente nesta etapa. Nesse caso, a resposta incluirá os campos approved_at ou declined_at:

Exemplo de Aprovação:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "APPROVED",
  "signed_at": "2026-01-20T10:40:00Z",
  "approved_at": "2026-01-20T10:40:00Z"
}

Exemplo de Recusa:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "DECLINED",
  "signed_at": "2026-01-20T10:40:00Z",
  "declined_at": "2026-01-20T10:40:00Z"
}

Reenviar OTP (se necessário)

Se o cliente não recebeu o OTP ou se ele expirou:

POST /application/{application_id}/resend
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62"
}

Resposta:

{
  "person_phone_number": 83991116537,
  "sent_at": "2026-01-20T10:42:00Z",
  "expires_at": "2026-01-20T10:47:00Z"
}

Passo 5: Aprovação Antifraude (Validação de Liveness por Selfie) - OPCIONAL

⚠️

Este passo é OPCIONAL

Se você integrar a validação de liveness por selfie, este endpoint acionará o processo de desembolso. Se você não integrar este passo, as regras antifraude serão executadas automaticamente durante o Passo 4 (Assinar Contrato), e o desembolso será acionado a partir de lá.

Envie a aplicação para análise antifraude com validação de liveness por selfie:

🔐

Requisito de Integração com o SDK da QI Tech

O parceiro precisa integrar o SDK da QI Tech no front-end para captura de liveness por selfie.

Documentação do SDK: QI Tech Face Recognition - Android Liveness

Fluxo de Integração:

  1. Chame a função de liveness do SDK da QI Tech com o CPF do cliente (parâmetro obrigatório)
  2. O SDK captura a selfie do cliente e realiza a detecção de liveness
  3. O SDK retorna uma registration_key para a validação de liveness facial
  4. Salve esta registration key - você precisará dela para chamar o endpoint de aprovação
POST /application/{application_id}/approval

Cabeçalhos:

Ip-Address: <client-ip-address>

Requisição:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "face": {
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  },
  "selfie": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

Observação: O campo selfie é opcional e aceita uma imagem codificada em base64 para verificação adicional.

📝

Processo de Validação no Backend

No backend, validamos o liveness usando a API da QI Tech: Onboarding de Pessoa Física

A registration key é utilizada para validar o liveness com base em regras antifraude pré-estabelecidas. Isso inclui a verificação de:

  • Correspondência facial com o CPF
  • Detecção de liveness (pessoa real vs foto/vídeo)
  • Sinais de prevenção à fraude
  • Verificação de identidade

Resposta (Aprovado):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "approved_at": "2026-01-20T10:40:00Z"
}

Resposta (Recusado):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "declined_at": "2026-01-20T10:40:00Z"
}

Passo 6: Cobrar a Aplicação e Monitorar o Desembolso

Após a validação antifraude ser aprovada (via Passo 6 ou automaticamente durante a assinatura), faça a cobrança da aplicação para verificar o desembolso:

POST /application/{application_id}/charge

Requisição:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "testCredit1"
}

Exemplos de Resposta:

1. Enviado para a IF (Pendente):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "SUBMITTED_TO_FI",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}

2. Desembolsado (Sucesso):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "FUNDED",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}

3. Falha no Desembolso:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "FUNDING_FAILED",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}
💰

Atualização do Limite de Crédito

Quando o status é SUBMITTED_TO_FI, o limite de crédito do cliente é atualizado:

  • Limite inicial do cliente: R$ 1.000,00
  • Valor financiado: R$ 500,00
  • Novo limite disponível: R$ 500,00

Significado dos Status:

StatusAção Necessária
SUBMITTED_TO_FI⏳ PENDENTE - Desembolso em andamento, chame novamente para verificar o status
FUNDED✅ CONFIRMAR PEDIDO - Desembolso realizado com sucesso, prossiga com o envio
FUNDING_FAILED❌ CANCELAR PEDIDO - Desembolso falhou, o limite do cliente é restaurado
🔄

Restauração do Limite em Caso de Falha

Se o status for FUNDING_FAILED, o limite de crédito do cliente é automaticamente restaurado ao valor original (o valor financiado é creditado de volta).

Fluxo Recomendado:

  1. Chame o endpoint /charge → Obtenha o status inicial
  2. Se SUBMITTED_TO_FI → Aguarde alguns segundos e chame /charge novamente para verificar o status atualizado
  3. Se FUNDED → ✅ Confirme e envie o pedido
  4. Se FUNDING_FAILED → ❌ Cancele o pedido e notifique o cliente
🎉

Sucesso!

Quando o status for FUNDED, o empréstimo está ativo e o cliente receberá seu plano de pagamento. Agora você pode prosseguir com o envio do pedido.

Endpoints Adicionais

Consultar Limite Disponível em Tempo Real

Verifique o limite de crédito disponível atual do cliente:

GET /person/{person_id}/available-limit

Resposta:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "available_limit": 4726.28,
  "currency": "BRL",
  "updated_at": "2026-01-20T10:30:00Z"
}

Precisa de Ajuda?

Precisa de Ajuda?

Updated 3 months ago