Contratos do backend da aplicação

Esta página descreve contratos sugeridos entre o navegador e o backend da aplicação. Ela não é uma implementação obrigatória de rotas e não reproduz a API FortCard. O objetivo é mostrar o formato de troca esperado pela interface para que o backend possa adaptar a operação real com segurança.

Regra base

O navegador fala somente com o backend da aplicação. O backend valida host, sessão, origem comercial, produto e regras antes de chamar FortCard ou qualquer provedor. Campos operacionais como strLojista, strLoja, strProduto, strPlano, usuário, senha, token e credenciais não devem aparecer nos exemplos de request do browser.

Configuração pública por host

GET /api/public-config

Entrada esperada:

host observado pelo servidor ou proxy confiável;
headers de origem suficientes para auditoria;
nenhum campo operacional enviado pelo browser.

Resposta sugerida:

{
  "tenantId": "solarcred",
  "partnerId": "solarcred",
  "sourceDomain": "credito.solarcred.com.br",
  "displayName": "SolarCred",
  "enabledProducts": ["personal-loan", "salary-advance"],
  "publicBrand": {
    "colors": {
      "primary": "#075e54",
      "secondary": "#ffb020",
      "action": "#ffb020"
    },
    "logos": {
      "lightSurface": "/assets/clientes/solarcred/logo-azul.svg",
      "darkSurface": "/assets/clientes/solarcred/logo-branca.svg"
    },
    "favicon": "/assets/clientes/solarcred/favicon.svg",
    "banners": []
  }
}

Se o host não estiver permitido, o backend deve retornar uma configuração segura de fallback ou erro seguro, conforme a estratégia operacional definida.

Início de jornada

POST /api/jornadas

Request do navegador:

{
  "tenantId": "solarcred",
  "partnerId": "solarcred",
  "sourceDomain": "credito.solarcred.com.br",
  "selectedProductId": "personal-loan",
  "formValues": {
    "cpf": "12345678909",
    "requestedAmount": "2500.00"
  }
}

Resposta sugerida:

{
  "journeyId": "jor_01HZXK4R",
  "proposalId": null,
  "selectedProductId": "personal-loan",
  "nextPath": "/emprestimo/dados-pessoais",
  "status": "started"
}

O backend deve comparar sourceDomain com o host observado, validar a allowlist e resolver no servidor lojista, loja, produto operacional, condição comercial e demais parâmetros.

Simulação e oferta

POST /api/jornadas/{journeyId}/simulacao

Request do navegador:

{
  "cpf": "12345678909",
  "selectedProductId": "personal-loan",
  "requestedAmount": "2500.00",
  "installments": 12,
  "firstDueDate": "2026-08-20"
}

Resposta sugerida:

{
  "offerId": "off_01HZXM8A",
  "status": "approved",
  "amount": "2500.00",
  "netAmount": "2384.70",
  "installments": 12,
  "installmentAmount": "248.90",
  "cetMonthly": "2.10",
  "cetYearly": "28.35",
  "validUntil": "2026-07-24T23:59:59-03:00"
}

Valores monetários devem chegar ao front já normalizados para exibição e cálculo visual. A precisão operacional permanece no backend.

OTP e sessão

POST /api/auth/otp
POST /api/auth/otp/verify

Request de envio:

{
  "cpf": "12345678909",
  "channel": "sms"
}

Resposta de envio:

{
  "challengeId": "otp_01HZXN2K",
  "maskedTarget": "(61) *****-0909",
  "expiresInSeconds": 120
}

Request de validação:

{
  "challengeId": "otp_01HZXN2K",
  "code": "1234"
}

Resposta de validação:

{
  "authenticated": true,
  "sessionState": "active",
  "nextPath": "/arealogada/log-home"
}

OTP bruto não deve ser persistido como dado de negócio nem registrado em log.

Proposta, status e pendências

GET /api/propostas/{proposalId}
GET /api/propostas/{proposalId}/pendencias

Resposta de proposta:

{
  "proposalId": "prop_01HZXP3V",
  "displayCode": "FORT-2026-0001",
  "selectedProductId": "personal-loan",
  "status": "in_analysis",
  "currentStep": "analise",
  "updatedAt": "2026-07-24T10:30:00-03:00",
  "summary": {
    "amount": "2500.00",
    "installments": 12,
    "installmentAmount": "248.90"
  }
}

Resposta de pendências:

{
  "items": [
    {
      "id": "doc-selfie",
      "type": "document",
      "title": "Enviar selfie",
      "description": "Precisamos de uma nova imagem para validar sua identidade.",
      "actionPath": "/emprestimo/assinar-contrato"
    }
  ]
}

Erro normalizado

Erros técnicos e erros de negócio devem virar um contrato seguro para tela.

{
  "error": {
    "code": "business_rule_denied",
    "title": "Não conseguimos seguir com esta proposta",
    "message": "Revise os dados informados ou tente novamente mais tarde.",
    "field": null,
    "retryable": false
  }
}

O backend pode guardar diagnóstico técnico sanitizado, mas o front recebe apenas mensagem segura, campo relacionado quando houver e ação possível.

Lacunas que precisam de decisão

Tema	Decisão pendente
Consignado CLT	Formato da resposta de margem, vínculo, conveniada, parcela máxima e motivo de recusa.
Antecipação salarial	Provedor de Open Finance, retorno de salário elegível, expiração de consentimento e dados de quitação.
Assinatura e documentos	Ordem entre assinatura, biometria, documentos obrigatórios, link externo e status final.
Ranges de produto	Origem autoritativa de mínimo, máximo, prazo, carência, seguro e condição comercial.

Consulte campos operacionais FortCard para separar o que é público do que deve permanecer no backend.

Começando

Arquitetura

Site e white label

Fluxos de Empréstimos

Integração backend

Qualidade e componentes

Regra base

Configuração pública por host

Início de jornada

Simulação e oferta

OTP e sessão

Proposta, status e pendências

Erro normalizado

Lacunas que precisam de decisão

​Regra base

​Configuração pública por host

​Início de jornada

​Simulação e oferta

​OTP e sessão

​Proposta, status e pendências

​Erro normalizado

​Lacunas que precisam de decisão

Regra base

Configuração pública por host

Início de jornada

Simulação e oferta

OTP e sessão

Proposta, status e pendências

Erro normalizado

Lacunas que precisam de decisão