Funcional Health Tech — Banking APIs (v1)

APIs REST para cadastro e operações bancárias (clientes, contas, transferências, cobranças, compliance, auditorias etc.)
Documentação OpenAPI 3.0 com Swagger UI.

Swagger UI: https://localhost:62879/swagger  •  Spec: /swagger/v1/swagger.json

---

Índice

1. Visão Geral
2. Autenticação & Segurança
3. Rate Limit & Cabeçalhos
4. Quickstart
5. Módulos & Endpoints
6. Auditoria
7. Erros & Convenções
8. Execução Local
9. Banco de Dados & Migrações

---

Visão Geral

• Objetivo: expor endpoints claros e seguros para gestão bancária:
  • Core: Cliente, Conta, Transferências, Cobrança, Comprovantes
  • Governança: Compliance, Auditoria
  • Dados do cliente: Contatos, Dados Pessoais (isolados p/ LGPD), Documentos e Endereços Fiscais, Societário
• Auditoria completa de eventos (migrações, criação/alteração de registros, movimentação de saldo, transferências).
• Stack: ASP.NET Core • EF Core (SQL Server) • AutoMapper • MediatR • JWT • CORS • Kestrel • Swagger.

Nota: Em Debug, o Swagger funciona sem Basic Gate. Em Release, além do JWT, é exigido cabeçalho Basic (detalhes abaixo).

Autenticação & Segurança

JWT (login) — POST /api/seguranca/login

Body:

{ "usuario": "FHT", "senha": "FHT" }

Resposta:

{ "access_token": "<jwt>", "token_type": "Bearer", "expires_in": 216000 }

Use nas chamadas:

Authorization: Bearer <jwt>

Basic Gate (somente em Release)

Além do Bearer, envie Authorization: Basic base64("Auth:yyyyMMdd:FHT")

# Exemplo bash
BASIC=$(printf "Auth:%(date +%Y%m%d):FHT")
curl ... -H "Authorization: Basic $(echo -n "$BASIC" | base64)" -H "Authorization: Bearer <jwt>"

No Swagger em Release, utilize um cliente (curl/Postman) que permita setar o Basic.

Rate Limit & Cabeçalhos

• Limite: 150 req/min
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
• Correlação: envie opcional X-Correlation-Id; se ausente, a API gera e retorna.
• Headers de segurança: CSP, HSTS, Referrer-Policy, Permissions-Policy, X-Content-Type-Options, X-Frame-Options, etc.

Quickstart

1) Login → JWT

curl -X POST "https://localhost:62879/api/seguranca/login" \
  -H "Content-Type: application/json" \
  -d '{ "usuario":"FHT", "senha":"FHT" }'

2) Criar cliente

curl -X POST "https://localhost:62879/api/clientes" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "nome":"Rafael Antunes dos Santos Silva", "tipo":"PessoaFisica", "status":"Ativo" }'

3) Criar conta (não envie contaId)

curl -X POST "https://localhost:62879/api/contas" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "clienteId":1, "tipo":"Corrente", "status":"Ativa",
        "agencia":"1", "numero":"1", "digito":"1", "saldo":100 }'

4) Listar contas (filtro opcional clienteId)

curl -X GET "https://localhost:62879/api/contas?clienteId=1" \
  -H "Authorization: Bearer <jwt>" \
  -H "accept: application/json"

5) Criar transferência (debita saldo automaticamente)

curl -X POST "https://localhost:62879/api/transferencias" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "clienteId":1, "contaId":1, "tipo":"Pix", "status":"Pendente",
    "valor":100, "descricao":"teste", "identificadorTransacao":"teste",
    "pixChave":"1", "bancoDestino":"1", "agenciaDestino":"1",
    "contaDestino":"1", "documentoTitularDestino":"1",
    "nomeTitularDestino":"1", "codigoBarras":"1", "linhaDigitavel":"1"
  }'

Erro esperado quando não há saldo suficiente:

{ "error": "Saldo insuficiente." }

6) Consultar transferência

curl -X GET "https://localhost:62879/api/transferencias/1" \
  -H "Authorization: Bearer <jwt>"

Módulos & Endpoints

Módulo	Endpoints	Notas
Segurança	POST /api/seguranca/login	Retorna JWT
Auditoria	GET /api/auditorias • GET /api/auditorias/{id}	Trilha de eventos
Cliente	GET/POST /api/clientes • GET/PUT/DELETE /api/clientes/{id}	CRUD clientes
Conta	GET/POST /api/contas • GET/PUT/DELETE /api/contas/{id}	POST: não enviar contaId
Transferências	POST /api/transferencias • GET /api/transferencias/{id}	Debita saldo automático
Cobrança	GET/POST /api/cobrancas • GET /api/cobrancas/{id} • POST /{id}/pagar • POST /{id}/cancelar • GET /{id}/comprovante	Gestão de cobranças
Compliance	GET/POST /api/compliances • GET/PUT/DELETE /api/compliances/{id}	Registros de compliance
Comprovantes	GET /api/comprovantes/{id} • GET /api/comprovantes/por-cobranca/{cobrancaId}	Consulta de comprovantes
Contato	GET/POST /api/contatos • GET/PUT/DELETE /api/contatos/{id}	Contatos de clientes
Dados Pessoais	GET/POST /api/dados-pessoais • GET /api/dados-pessoais/{id} • GET /api/dados-pessoais/por-cliente/{clienteId} • PUT/DELETE /api/dados-pessoais/{id}	Isolado p/ LGPD
Docs/Endereços Fiscais	/api/documentos-fiscais • /api/enderecos-fiscais	CRUDs completos
Societário	/api/societarios	Dados societários

Auditoria

Exemplo (resumido)

[
  {
    "auditoriaId": 1,
    "entidade": "__MIGRATIONS__",
    "entidadeId": "20250829203407_Criacao_Bd",
    "motivo": "Migrations aplicadas automaticamente na inicialização da API.",
    "usuarioLogin": "master",
    "correlacaoId": "36bcd617b2604d79aa008b48da0180c6",
    "sucesso": true
  },
  {
    "auditoriaId": 4,
    "entidade": "TransferenciaBancaria",
    "entidadeId": "1",
    "acao": "Outra",
    "sucesso": true
  }
]

Erros & Convenções

• 200 OK • 201 Created • 400 Bad Request • 401 Unauthorized • 404 Not Found • 422 Unprocessable Entity • 429 Too Many Requests • 500 Internal Server Error

Padrão de erro (ProblemDetails)

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Erros comuns

• 401 em Release: faltou o token Auth
• 500 na transferência: saldo insuficiente.
• 422: payload JSON malformado ou enum inválido.

Execução Local

Rodando

dotnet restore
dotnet build
dotnet run --project src/FHT.Api

Acesse: https://localhost:62879/swagger

Ambiente

ASPNETCORE_ENVIRONMENT=Development  # Swagger sem Basic Gate em Dev
# ConnectionStrings__DefaultConnection="Server=(localdb)\MSSQLLocalDB;AttachDbFilename=<repo>/App_Data/FHT.mdf;Trusted_Connection=True;"

Banco de Dados & Migrações

• BD em App_Data (SQL Server LocalDB/Express).
• Migrações aplicadas automaticamente na inicialização (auditoria de __MIGRATIONS__).

EF Core (opcional)

dotnet tool install --global dotnet-ef
dotnet ef migrations add Criacao_Bd --project src/FHT.Infra.Data --startup-project src/FHT.Api
dotnet ef database update --project src/FHT.Infra.Data --startup-project src/FHT.Api

---