# Brief App — Startup as a Service API

> A Brief App entrega o backend completo de uma startup pronta via API REST e SDK: banco de dados PostgreSQL multitenant, autenticação com 2FA TOTP obrigatório, pagamentos com PIX dinâmico, boleto e cartão com split automático de comissões, faturamento de assinaturas recorrentes com carência, agendamento de horários em grade semanal, catálogo de ofertas, solicitação de corridas e entregas sob demanda com despacho por geolocalização, gestão de parceiros com documentação KYC, armazenamento de arquivos no S3 e governança via HashiCorp Vault. Destina-se a fundadores de startups, desenvolvedores solo e agentes de IA que criam o front-end em ferramentas modernas e precisam de infraestrutura robusta de backend em produção sem precisar codificar regras de negócio nem gerenciar servidores.

A API é servida via REST/JSON sob o Gateway central com isolamento estrito por Tenant.

## Convenções da API
- Base URL: informada na criação do tenant; todas as rotas começam com `/api`.
- Auth servidor: `POST /api/tenants/token` com `sk_live_…` → JWT de 10 min. `pk_live_…` só para escopos públicos (`public`, `identity:login`, `identity:refresh`, `identity:2fa`, `identity:firebase`, `catalog:read`, `catalog:availability`, `scheduling:read`).
- Auth usuário: 2FA TOTP obrigatório; access token 15 min, refresh 7 dias rotativo.
- Papéis: Admin, Parceiro, Cliente, Membro, Financeiro, Suporte, Motorista.
- Idempotência: header `X-Idempotency-Key` em POST/PUT/PATCH/DELETE (janela de 24 h com resposta `Idempotent-Replayed: true`).
- Dinheiro em reais decimais (`89.90`), datas ISO 8601 UTC, paginação `page`/`pageSize`.
- Gateways de pagamento: Asaas, Mercado Pago, PagBank (PIX, boleto, cartão).
- Pagamentos: consulta de status usa `transactionId`; estorno usa `cobrancaId`.
- Formato de erro: `{ "error": "...", "code": "Modulo.Codigo" }` com códigos HTTP 400, 401, 403, 404, 409 e 429.
- Limites de requisição: 100/min no geral (por usuário ou IP), 5/min em login e cadastro (por IP), 10/min em pagamentos (por usuário ou IP), 60/min na emissão de token de tenant (por IP).
- Docs interativa: `/scalar/v1` no gateway.

## Casos de Uso e Integrações de IA (AI Frameworks)
- **Complementa Supabase e Firebase:** Enquanto Supabase e Firebase oferecem banco de dados e autenticação genéricos, a Brief App complementa sua stack com fluxos de negócio prontos de uma startup (split de pagamentos, cobrança recorrente com carência, agendamento de horários, corridas com geolocalização e repasses instantâneos via PIX).
- **Lovable & Bolt.new:** Integre seu front-end gerado por prompts de IA diretamente ao contrato OpenAPI v1 (`https://fm.brief.app.br/startup-as-a-service/openapi/v1.json`) ou consuma via SDK / Sidecar HTTP.
- **Cursor, Windsurf & Claude Code:** Adicione este `llms.txt` ou o `llms-full.txt` ao contexto da sua IDE de IA para scaffolding imediato de telas, formulários e chamadas de API tipadas sem alucinações.
- **v0 por Vercel:** Gere componentes React/Next.js conectados diretamente aos endpoints públicos autenticados por Publishable Key (`pk_live_...`).

## Documentação Principal
- [Visão Geral e Arquitetura](https://fm.brief.app.br/startup-as-a-service/docs.php#visao-geral): Conceitos, formato JSON UTF-8, datas ISO 8601 em UTC, paginação e isolamento multitenant.
- [Autenticação e Chaves](https://fm.brief.app.br/startup-as-a-service/docs.php#autenticacao): Chaves de API de tenant (sk_live_... e pk_live_...), OAuth2 token exchange (POST /api/tenants/token), login com 2FA TOTP e tokens JWT de curta duração.
- [Permissões e Políticas](https://fm.brief.app.br/startup-as-a-service/docs.php#permissoes): Matriz de papéis (Admin, Parceiro, Cliente, Membro, Financeiro, Suporte, Motorista) e controle de acesso baseado em dono.
- [Erros e Tratamento](https://fm.brief.app.br/startup-as-a-service/docs.php#erros): Formato `{ error, code }`, códigos HTTP (400, 401, 403, 404, 409, 429) e códigos de negócio.
- [Idempotência e Limites](https://fm.brief.app.br/startup-as-a-service/docs.php#idempotencia): Header X-Idempotency-Key para mutações seguras (janela 24h) e quotas de requisição por grupo.
- [Tempo Real e Webhooks](https://fm.brief.app.br/startup-as-a-service/docs.php#tempo-real): Webhooks de entrada dos gateways de pagamento (Asaas, Mercado Pago, PagBank) com validação HMAC e hubs SignalR (/hubs/chat e /hubs/mobility).
- [SDK, Sidecar e Ferramentas](https://fm.brief.app.br/startup-as-a-service/docs.php#sdk): Referência Scalar (/scalar/v1), pacote `BriefApp.Sdk` (.NET 10) e contêiner Sidecar HTTP na porta 5005 com renovação automática de token e retries via X-Api-Key.
- [Especificação OpenAPI v1](https://fm.brief.app.br/startup-as-a-service/openapi/v1.json): Contrato OpenAPI 3.0 para geração automática de clientes Refit, TypeScript e Python.

## Módulos de Negócio da API
- [Módulo Identidade e Acesso](https://fm.brief.app.br/startup-as-a-service/docs.php#identidade): Registro de usuários, aprovação de contas sensíveis, login com 2FA TOTP, refresh tokens rotativos e verificação KYC.
- [Módulo Agendamento](https://fm.brief.app.br/startup-as-a-service/docs.php#agendamento): Grade semanal por parceiro, exceções (folgas/feriados), geração de slots, reservas com créditos ou avulso, remarcação, cancelamento e conclusão.
- [Módulo Assinaturas e Recorrência](https://fm.brief.app.br/startup-as-a-service/docs.php#assinaturas): Planos periódicos, assinaturas com trial, faturamento automático, dias de carência por inadimplência e ledger imutável de créditos.
- [Módulo Pagamentos, Split e Repasses](https://fm.brief.app.br/startup-as-a-service/docs.php#pagamentos): Cobranças via POST /api/payments (Pix, Boleto, CreditCard), split automático com parceiros, consulta de status por transactionId e estorno por cobrancaId.
- [Módulo Catálogo e Ofertas](https://fm.brief.app.br/startup-as-a-service/docs.php#catalogo): Cadastro de ofertas, listagem pública de serviços, habilidades (skills), espaços e avaliações com nota.
- [Módulo Parceiros e Prestadores](https://fm.brief.app.br/startup-as-a-service/docs.php#parceiros): Onboarding e perfil público de prestadores, documentação KYC, chave PIX para repasses e vinculação de serviços.
- [Módulo Mobilidade e Entregas](https://fm.brief.app.br/startup-as-a-service/docs.php#mobilidade): Estimativa de tarifa (km/tempo), solicitação de corridas e entregas com despacho automático e rastreamento de motoristas via SignalR.
- [Módulo Comunicação e Notificações](https://fm.brief.app.br/startup-as-a-service/docs.php#comunicacao): Envio de notificações no sistema e disparos transacionais de e-mail autenticados.
- [Módulo Arquivos e Armazenamento](https://fm.brief.app.br/startup-as-a-service/docs.php#arquivos): Upload de documentos e imagens no MinIO/S3 via multipart/form-data e download seguro.
- [Módulo Administração da Plataforma](https://fm.brief.app.br/startup-as-a-service/docs.php#plataforma): Gestão de tenants da plataforma, auditoria e chaveamento dinâmico de provedores no HashiCorp Vault.
- [Módulo Kanban as a Service](https://fm.brief.app.br/startup-as-a-service/docs.php#kanban): Gestão de boards, colunas, cards e automações de fluxo de trabalho.
- [Módulo Open Finance e BPO Financeiro](https://fm.brief.app.br/startup-as-a-service/docs.php#openfinance): Painel bancário consolidado multiconector (Pluggy), conciliação de transações, sessões de atendimento com IA e metas financeiras.

## Ferramentas e SDKs
- [Brief App CLI](https://fm.brief.app.br/startup-as-a-service/docs/cli-provisioning.md): Utilitário de linha de comando para provisionar tenants, emitir credenciais, inicializar containers Docker e gerenciar banco de dados com migrações.
- [Brief App SDK (.NET 10)](https://github.com/qweralfredo/briefapp-modules/tree/main/src/BriefApp.Sdk): Biblioteca cliente oficial em C# com contratos tipados Refit, resiliência Polly, rate limiting e injeção de dependência (`BriefApp.Sdk`).
- [Brief App Sidecar HTTP](https://github.com/qweralfredo/briefapp-modules/tree/main/src/BriefApp.Sidecar): Contêiner proxy na porta 5005 que expõe todos os módulos para qualquer linguagem, autenticado por X-Api-Key, com renovação de token e retry automáticos.

## Optional
- [Guia de Integração Lovable & Bolt.new](https://fm.brief.app.br/startup-as-a-service/backend-para-lovable.php): Passo a passo para conectar front-ends criados no Lovable e Bolt.new à API via OpenAPI, com prompts prontos e exemplos TypeScript.
- [Guia de Split de Pagamentos para Marketplaces](https://fm.brief.app.br/startup-as-a-service/api-pagamentos-split.php): Arquitetura de divisão automática de receitas, repasses instantâneos via PIX e eliminação de bitributação.
- [Guia de Backend para SaaS com Assinaturas](https://fm.brief.app.br/startup-as-a-service/backend-saas-assinaturas.php): Faturamento recorrente, carência automática para inadimplência e consumo de créditos pré-pagos via API.
- [Simulador e Calculadora de Custos](https://fm.brief.app.br/startup-as-a-service/#calculadora): Calcule custos mensais estimados por número de usuários ativos, corridas e transações.
- [Planos e Preços](https://fm.brief.app.br/startup-as-a-service/#precos): Detalhes comerciais dos planos Builder (R$ 290 a 490/mês, até 5 mil req/mês), Scale (R$ 1.200 a 2.500/mês, até 100 mil req/mês), Enterprise (a partir de R$ 8.000/mês), consumo pay-as-you-go, take-rate de R$ 0,50 + 0,5% a 1,5% e modelo Venture Builder.
- [Cases Possíveis](https://fm.brief.app.br/startup-as-a-service/#cases): 27 ideias ilustrativas de startups que cabem nos módulos atuais (salões, delivery, mototáxi, clínicas, assinaturas, SaaS B2B). Não são clientes reais.
- [Documentação Completa Unificada (LLMs-full)](https://fm.brief.app.br/startup-as-a-service/llms-full.txt): Contexto integral com todos os endpoints, payloads de exemplo e esquemas para modelos com janela estendida.