Pular para o conteúdo principal

Fluxos de Integração

Esta página descreve o passo a passo dos principais fluxos de negócio que podem ser realizados através da API de Middleware da CredAluga. Entender estes fluxos é essencial para uma integração bem-sucedida.

Fluxo Principal: Da Simulação à Ativação​

Este é o fluxo mais comum, cobrindo o caminho completo desde a simulação de uma fiança até a sua ativação.

Passo 1: Onboarding (Cadastro Inicial)​

Antes de iniciar as operações de fiança, seu sistema precisa cadastrar as entidades básicas. Este passo geralmente é feito apenas uma vez.

  1. Cadastre o Parceiro: Utilize o endpoint POST /api/v1/partner para registrar sua empresa como um parceiro.
  2. Cadastre a Imobiliária: Utilize POST /api/v1/real-estate para registrar a imobiliária que fará a locação.
  3. Vincule a Imobiliária ao Parceiro: Use POST /api/v1/real-estate/link para associar a imobiliária ao seu cadastro de parceiro.
informação

Guarde os IDs retornados nestes cadastros, pois eles serão necessários nos passos seguintes.

Passo 2: Simulação de Fiança​

Com os cadastros feitos, você pode iniciar uma simulação para um potencial inquilino.

  1. Envie os dados da simulação: Chame o endpoint POST /api/v1/simulations/single (para o fluxo simplificado) ou POST /api/v1/simulations (para o fluxo completo) com as informações do imóvel e do inquilino.
  2. Receba o ID da Simulação: A API retornará um simulationId, que identifica unicamente esta simulação.

Passo 3: Consulta de Planos​

Após a simulação ser criada e processada, você deve consultar os planos de fiança disponíveis para o perfil analisado.

  1. Consulte os planos: Faça uma chamada GET /api/v1/simulations/{simulationId}/plans.
  2. Apresente ao usuário: A API retornará uma lista de planos (com valores, taxas, etc.) que podem ser apresentados ao cliente.

Passo 4: Criação da Proposta​

Quando o cliente escolhe um dos planos, você pode formalizar a operação criando uma proposta.

  1. Envie a proposta: Utilize o endpoint POST /api/v1/proposal, enviando o simulationId, o planId escolhido e os dados completos do inquilino e do imóvel.
  2. Receba o ID da Proposta: A API retornará um proposalId.

Passo 5: Acompanhamento com Webhooks​

A análise e aprovação de uma proposta é um processo assíncrono. A melhor forma de acompanhar as mudanças de status é através de Webhooks.

  1. Cadastre seu Webhook: Se ainda não o fez, utilize o endpoint POST /api/v1/webhook para registrar uma URL do seu sistema que receberá as notificações.
  2. Receba as atualizações: Sempre que o status da proposta mudar (ex: de Em Análise para Aprovada), a CredAluga enviará uma notificação para a sua URL de webhook. O payload conterá o proposalId e o novo status.

Exemplo de Payload de Webhook:

{
  "proposalId": "12345",
  "status": "APPROVED",
  "description": "Proposta aprovada com sucesso.",
  "updatedAt": "2026-04-13T22:00:00Z"
}

Passo 6: Consulta Manual (Opcional)​

Além dos webhooks, você pode consultar o status de uma proposta a qualquer momento.

  1. Consulte a proposta: Faça uma chamada GET /api/v1/proposal/{proposalId} para obter o estado atual completo da proposta.

Compreender este fluxo é o primeiro grande passo para uma integração robusta e eficiente. Navegue pelos endpoints na barra lateral para ver os detalhes de cada requisição e resposta.