Sobre a API

A FortunCred API permite que parceiros embutam o crédito imobiliário da FortunCred no próprio sistema: cadastro de lead, simulação de financiamento, análise de crédito (aprovação real nos bancos) e acompanhamento do resultado — tudo por HTTPS, com respostas em JSON.

Você opera sempre no contexto da sua unidade (definida na sua API Key). Não é preciso acessar o sistema interno da FortunCred: a API é a ponte.

Primeiros passos

Todo o fluxo em 4 chamadas:

Autenticação

Toda requisição em /v1 exige a sua API Key no header X-API-Key (ou Authorization: Bearer). A chave tem o formato fortuncred_… e é gerada pelo gestor no painel /admin.

curl https://developers.fortuncred.com.br/v1/me \
  -H "X-API-Key: fortuncred_sua_chave"

Guarde a chave como segredo (variável de ambiente). Nunca a exponha em app/front-end. Se vazar, o gestor rotaciona no painel e a antiga para de valer na hora.

Ambientes

Limites & idempotência

Rate limit: por padrão 120 requisições/minuto por parceiro. Ao estourar, a API responde 429 rate_limited com o header Retry-After (aguarde e tente de novo).

Idempotência: em POST /v1/analises o header Idempotency-Key é obrigatório. Reenvio com a mesma chave e mesmo corpo devolve a resposta original (Idempotent-Replay: true); a mesma chave com corpo diferente devolve 422 idempotency_conflito. Isso evita disparar a análise duas vezes num retry.

1 · Lead

Cadastra o cliente na sua unidade. Se o CPF já existir, a API reaproveita o lead (simulações e análises ficam salvas dentro dele) e retorna reaproveitado: true.

curl -X POST https://developers.fortuncred.com.br/v1/leads \
  -H "X-API-Key: fortuncred_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria Silva","cpf":"529.982.247-25","renda":8500}'

# 201 -> { "ok": true, "lead_id": 34077, "reaproveitado": false }

const r = await fetch("https://developers.fortuncred.com.br/v1/leads", {
  method: "POST",
  headers: { "X-API-Key": "fortuncred_sua_chave", "Content-Type": "application/json" },
  body: JSON.stringify({ nome: "Maria Silva", cpf: "529.982.247-25", renda: 8500 }),
});
const lead = await r.json(); // { ok: true, lead_id: 34077, reaproveitado: false }

import requests

r = requests.post(
    "https://developers.fortuncred.com.br/v1/leads",
    headers={"X-API-Key": "fortuncred_sua_chave"},
    json={"nome": "Maria Silva", "cpf": "529.982.247-25", "renda": 8500},
)
lead = r.json()  # {'ok': True, 'lead_id': 34077, 'reaproveitado': False}

$ch = curl_init("https://developers.fortuncred.com.br/v1/leads");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: fortuncred_sua_chave", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["nome" => "Maria Silva", "cpf" => "529.982.247-25", "renda" => 8500]),
]);
$lead = json_decode(curl_exec($ch), true); // ["ok" => true, "lead_id" => 34077]

Os demais endpoints seguem o mesmo padrão — só muda o caminho e o corpo. Coleção pronta em Postman/Insomnia e todos os detalhes na Referência.

2 · Simulação

Simula o financiamento em um ou mais bancos. Retorna taxas, parcelas e CET em JSON — você monta o layout como quiser.

curl -X POST https://developers.fortuncred.com.br/v1/simulacoes \
  -H "X-API-Key: fortuncred_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": 34077,
    "valor_imovel": 500000,
    "valor_financiado": 250000,
    "prazo": 360,
    "tipo_amortizacao": "SAC",
    "bancos": ["bradesco", "itau", "santander"]
  }'

3 · Análise de crédito

Envia a ficha completa do titular para aprovação real no banco (uma análise por banco). Exige Idempotency-Key e o consentimento do titular (veja abaixo). O resultado é assíncrono.

curl -X POST https://developers.fortuncred.com.br/v1/analises \
  -H "X-API-Key: fortuncred_sua_chave" \
  -H "Idempotency-Key: 8f14e45f-cea1-4a12-9b33-000000000001" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": 34077,
    "bancos": ["bradesco"],
    "consentimento": true,
    "consentimento_timestamp": "2026-07-10T14:32:00-03:00",
    "consentimento_ip": "200.145.32.10",
    "consentimento_canal": "web",
    "nome": "Maria Silva", "cpf": "529.982.247-25",
    "data_nascimento": "1990-05-01", "renda": 8500, "sexo": "F",
    "estado_civil": "solteiro", "nome_mae": "Ana Silva",
    "email": "maria@exemplo.com", "profissao": "Analista", "empresa": "ACME",
    "rg": "MG1234567", "rg_orgao": "SSP", "rg_uf": "MG", "rg_emissao": "2010-02-01",
    "cep": "38400-000", "logradouro": "Rua das Flores", "numero": "120",
    "bairro": "Centro", "municipio": "Uberlândia", "uf": "MG",
    "valor_imovel": 500000, "valor_financiado": 250000, "prazo": 360
  }'

// 202 — em processamento
{ "ok": true, "analises": [
  { "banco_id": 1, "sucesso": true, "analise_id": 27603, "status": "Análise Crédito" }
] }

4 · Acompanhamento

Consulte o status de uma análise. Faça polling (ex.: a cada 30 s por ~15 min) até pendente: false — ou receba por webhook.

curl https://developers.fortuncred.com.br/v1/analises/27603/status \
  -H "X-API-Key: fortuncred_sua_chave"

{ "ok": true, "analise": {
    "analise_id": 27603, "banco": "Bradesco",
    "status_original": "Crédito Aprovado",
    "situacao": "aprovado", "pendente": false } }

O campo situacao é um enum estável (programe por ele, não pelo texto):

Consentimento (LGPD)

A consulta de crédito só é aceita com o consentimento do titular. A coleta e o registro do consentimento são responsabilidade do parceiro — você envia os quatro campos abaixo em POST /v1/analises, e eles ficam gravados de forma auditável (consulte em GET /v1/leads/:id/consentimentos).

Faltando qualquer um → 422 consentimento_ausente.

Webhooks

Em vez de ficar consultando o status, você recebe um POST assinado na sua URL quando a análise resolve. A URL e o secret de assinatura são configurados pelo gestor no painel; você consulta a sua config em GET /v1/webhooks (somente leitura).

Cada entrega vem assinada em HMAC-SHA256 (header X-FortunCred-Signature: sha256=…). Valide a assinatura com o seu secret antes de confiar no payload. Reenvios automáticos em caso de falha (backoff).

Erros

Todo erro traz um codigo estável (você ramifica por ele, não pela mensagem) e, quando aplicável, a lista de campos. Veja a tabela completa em Erros & Status.

{
  "erro": "Campos obrigatorios ausentes",
  "codigo": "campo_obrigatorio",
  "campos": [ { "campo": "cpf", "motivo": "obrigatorio" } ],
  "request_id": "4a0ee7e3-…"
}

Postman / Insomnia

Duas formas de importar a API na sua ferramenta favorita e testar em segundos: