# Brief App — Especificação Técnica Integral da API REST (LLMs Full Context)

> Este documento é a referência técnica consolidada da plataforma Brief App (Startup as a Service). Destina-se a modelos de linguagem e agentes autônomos (Cursor, Lovable, Claude Code, Windsurf, v0) que operam com janelas de contexto estendidas e precisam integrar front-ends a um backend de startup em produção sem alucinações.

- **Base URL:** `https://fm.brief.app.br/startup-as-a-service` (ou a URL informada na criação do tenant; todas as rotas começam com `/api`)
- **Contrato OpenAPI v1:** `https://fm.brief.app.br/startup-as-a-service/openapi/v1.json`
- **Documentação Interativa (Scalar):** `/scalar/v1` no Gateway
- **SDK Oficial (.NET 10):** `BriefApp.Sdk` (Refit, Polly, Rate Limiting)
- **Sidecar HTTP:** Contêiner HTTP na porta `5005`, autenticado por `X-Api-Key`, com renovação automática de token e retries prontos para qualquer linguagem

---

## 1. Convenções Globais da API
- **Formato de Dados:** JSON em UTF-8 para requisições e respostas (uploads multipart/form-data).
- **Datas e Horários:** Padrão ISO 8601 em UTC (`2026-10-15T13:00:00Z`). Datas sem hora usam `AAAA-MM-DD`.
- **Valores Monetários:** Decimais em reais (`89.90`), nunca em centavos.
- **Paginação:** Parâmetros `page` (inicia em 1) e `pageSize` (padrão 20).
- **Idempotência Obrigatória:** Envie o cabeçalho `X-Idempotency-Key` (UUIDv4) em todas as mutações (`POST`, `PUT`, `PATCH`, `DELETE`). A chave é retida por 24 horas. Respostas reexecutadas devolvem `Idempotent-Replayed: true`.
- **Gateways de Pagamento:** Asaas, Mercado Pago e PagBank (PIX, boleto e cartão de crédito).
- **Formato de Erro Padronizado:**
```json
{ "error": "Mensagem descritiva da falha", "code": "Modulo.Codigo" }
```
Códigos HTTP de retorno: `400` (Dados inválidos ou regra de negócio violada), `401` (Não autenticado), `403` (Sem permissão ou papel insuficiente), `404` (Não encontrado), `409` (Conflito de estado), `429` (Limite de requisições excedido).

- **Limites de Requisição (Rate Limiting):**
  - Geral: 100 requisições por minuto por usuário ou IP.
  - Login e Cadastro: 5 requisições por minuto por IP.
  - Pagamentos: 10 requisições por minuto por usuário ou IP.
  - Emissão de Token de Tenant: 60 requisições por minuto por IP.
  - Plano Enterprise possui limites customizados por contrato.

---

## 2. Autenticação e Chaves de API
Todo endpoint exige `Authorization: Bearer <token>`, exceto os marcados como Públicos.

### 2.1 Token do Tenant (Servidor para Servidor)
Chaves emitidas na criação do tenant:
- `sk_live_...` (Secret key): Uso estrito em backend seguro. Pode solicitar qualquer escopo.
- `pk_live_...` (Publishable key): Uso em apps móveis e navegadores. Restrita a escopos públicos (`public`, `identity:login`, `identity:refresh`, `identity:2fa`, `identity:firebase`, `catalog:read`, `catalog:availability`, `scheduling:read`) e origens cadastradas.

Troca de chave por token de curta duração (10 minutos):
```http
POST /api/tenants/token
Content-Type: application/json

{ "grant_type": "client_credentials", "api_key": "sk_live_...", "scope": "financial partners" }
```

### 2.2 Sessão de Usuário
- **2FA Obrigatório (TOTP):** Código de 6 dígitos via app autenticador. Não há sessão ativa sem 2FA.
- **Access Token:** Duração de 15 minutos.
- **Refresh Token:** Duração de 7 dias, rotacionado a cada renovação via `POST /api/auth/refresh`.
- **Papéis (RBAC):** `Admin`, `Parceiro`, `Cliente`, `Membro`, `Financeiro`, `Suporte`, `Motorista`.

---

## 3. Webhooks e Tempo Real
- **Webhooks de Entrada:** Recebimento assíncrono dos gateways de pagamento (Asaas, Mercado Pago, PagBank) com verificação rigorosa de assinatura HMAC.
- **Hubs SignalR em Tempo Real:**
  - `/hubs/chat`: Mensageria entre cliente e prestador parceiro.
  - `/hubs/mobility`: Rastreamento de localização do motorista e atualizações de corridas/entregas via método `AtualizarLocalizacao`.
  - Conexão autenticada via Bearer JWT.

---

## 4. Endpoints Operacionais da API por Módulo

### Identidade e Acesso
- `POST /api/auth/2fa/setup` — Gera a chave secreta e o QR Code URI para configurar o autenticador TOTP. (Público)
- `POST /api/auth/2fa/verify` — Confirma o código TOTP, habilita o 2FA permanentemente na conta e autentica a sessão (retorna os mesmos tokens de um login bem-sucedido). (Público)
- `POST /api/auth/firebase-login` — Verifica um Firebase ID token e sincroniza o usuário (cria no primeiro login). (Público)
- `POST /api/auth/login` — Autentica um usuário com email e senha. Se a conta ainda não tem 2FA configurado, retorna requiresTwoFactorSetup=true (e o userId) para o cliente ir direto para a configuração — 2FA é obrigatório para todas as contas. Se já tem 2FA habilitado, retorna requiresTwoFactor=true e um segundo passo com o código TOTP é necessário. (Público)
- `GET /api/auth/me` — Retorna o perfil do usuário autenticado (lido do JWT). (Autenticado)
- `POST /api/auth/refresh` — Renova o access token usando um refresh token válido. (Público)
- `POST /api/auth/register` — Registra um novo usuário. Roles Admin/Parceiro requerem aprovação administrativa — ficam com status PendingApproval. (Público)
- `GET /api/auth/users` — Lista usuários com paginação e filtros opcionais de papel, status e busca (nome, e-mail, telefone). (Autenticado)
- `GET /api/auth/users/{userId}` — Detalhe de um usuário. O próprio usuário ou um Admin. (Autenticado)
- `PUT /api/auth/users/{userId}/approve` — Aprova um usuário com status PendingApproval (apenas Admin). (Autenticado)
- `PUT /api/auth/users/{userId}/profile` — Atualiza nome e/ou telefone. O próprio usuário ou um Admin; campos nulos ficam como estão. (Autenticado)
- `PUT /api/auth/users/{userId}/reject` — Rejeita um cadastro com status PendingApproval (apenas Admin). (Autenticado)
- `PUT /api/auth/users/{userId}/roles/{role}` — Concede um papel ao usuário (apenas Admin) — ex.: Motorista ou Parceiro depois que o cadastro operacional foi aprovado. O usuário recebe o papel no próximo refresh/login. Idempotente. (Autenticado)
- `DELETE /api/auth/users/{userId}/roles/{role}` — Remove um papel do usuário (apenas Admin). Não é possível remover o próprio papel de Admin. (Autenticado)
- `PUT /api/auth/users/{userId}/status` — Muda o status de um usuário já aprovado: Active, Suspended ou Blocked (apenas Admin). Suspender/bloquear revoga os refresh tokens. (Autenticado)
- `POST /api/kyc/consulta` — Consulta um CPF ou CNPJ no provedor de KYC configurado no Vault para o tenant. Pontuação (., -, /) é aceita e removida. (Autenticado)
- `POST /api/kyc/consulta/pdf` — Consulta e extração estruturada de dados KYC a partir de um documento PDF. (Autenticado)
- `POST /api/tenants/token` — Emite um token de acesso JWT (10 min) a partir de uma API Key válida do Tenant. Suporta formatos JSON e application/x-www-form-urlencoded. (Público)

### Agendamento
- `POST /api/scheduling/appointments` — Cria um agendamento consumindo um slot disponível. Pagamento pode ser via créditos ou avulso. (Autenticado)
- `GET /api/scheduling/appointments/client/{clientId}` — Agendamentos de um cliente, do mais recente ao mais antigo. status: PendentePagamento, Confirmado, EmAndamento, Concluido, Cancelado, NoShow. (Autenticado)
- `GET /api/scheduling/appointments/partner/{partnerId}` — Agendamentos de um parceiro no intervalo [from, to) (UTC), do mais cedo ao mais tarde. (Autenticado)
- `GET /api/scheduling/appointments/{appointmentId}` — Retorna os detalhes de um agendamento pelo ID. (Autenticado)
- `DELETE /api/scheduling/appointments/{appointmentId}` — Cancela um agendamento. Aplica política de estorno de créditos conforme configuração. (Autenticado)
- `POST /api/scheduling/appointments/{appointmentId}/complete` — O parceiro conclui o atendimento (agendamento confirmado ou em andamento). (Autenticado)
- `POST /api/scheduling/appointments/{appointmentId}/no-show` — O parceiro registra que o cliente não compareceu. (Autenticado)
- `PUT /api/scheduling/appointments/{appointmentId}/reschedule` — Remarca um agendamento para outro slot disponível. (Autenticado)
- `GET /api/scheduling/availability` — Consulta os slots de horário disponíveis para um parceiro em uma data. Cache de 30s, variado por partnerId + date. (Público)
- `GET /api/scheduling/partners/{partnerId}/availability/exceptions` — GetExceptions (Autenticado)
- `POST /api/scheduling/partners/{partnerId}/availability/exceptions` — Marca uma data como indisponível (folga, feriado, férias). Os horários livres dessa data que já existem são bloqueados; os já reservados permanecem. UtcOffsetMinutes: fuso do parceiro (ex.: -180). (Autenticado)
- `DELETE /api/scheduling/partners/{partnerId}/availability/exceptions/{date}` — Remove a exceção da data. Os horários que ela bloqueou continuam bloqueados até serem liberados. (Autenticado)
- `GET /api/scheduling/partners/{partnerId}/availability/weekly` — Grade semanal de atendimento do parceiro (horários locais do parceiro). (Autenticado)
- `PUT /api/scheduling/partners/{partnerId}/availability/weekly` — Substitui a grade semanal inteira. Faixas de um mesmo dia não podem se sobrepor e a duração precisa caber na faixa. Lista vazia limpa a grade. DiaSemana: Monday … Sunday. (Autenticado)
- `GET /api/scheduling/partners/{partnerId}/slots` — Calendário do parceiro: todos os horários (livres, reservados e bloqueados) em [from, to). Máx. 62 dias. (Autenticado)
- `POST /api/scheduling/partners/{partnerId}/slots/generate` — Gera os horários das próximas Semanas (1 a 12) a partir de DataInicio (data local do parceiro), pela grade semanal e respeitando as exceções. Idempotente: horários que já existem não são recriados. (Autenticado)
- `POST /api/scheduling/slots/{slotId}/block` — BlockSlot (Autenticado)
- `POST /api/scheduling/slots/{slotId}/unblock` — UnblockSlot (Autenticado)

### Assinaturas e Recorrência
- `GET /api/billing/credits/{clienteId}` — Consulta o saldo de créditos disponível de um cliente. (Autenticado)
- `POST /api/billing/credits/{clienteId}/add` — Adiciona créditos ao saldo de um cliente (ex: compra de pacote). (Autenticado)
- `POST /api/billing/credits/{clienteId}/debit` — Debita créditos do saldo de um cliente (ex: consumo de agendamento). (Autenticado)
- `POST /api/billing/credits/{clienteId}/refund` — Estorna créditos debitados (ex: cancelamento de agendamento). (Autenticado)
- `GET /api/billing/plans` — Lista os planos. Quem não é Admin/Financeiro só vê os ativos (os que aceitam novas assinaturas); staff pode pedir também os inativos e descontinuados com includeInactive=true. (Autenticado)
- `POST /api/billing/plans` — Cria um plano de assinatura (Admin/Financeiro). (Autenticado)
- `GET /api/billing/plans/{planId}` — GetPlan (Autenticado)
- `PUT /api/billing/plans/{planId}` — Atualiza nome, descrição, preço e créditos. Quem já assina mantém o valor contratado; a mudança vale para novas assinaturas. (Autenticado)
- `PATCH /api/billing/plans/{planId}/status` — Ativo ↔ Inativo é reversível; Descontinuado é definitivo. (Autenticado)
- `POST /api/billing/subscriptions` — Cria uma nova assinatura para um cliente. (Autenticado)
- `GET /api/billing/subscriptions` — Lista assinaturas, paginado, com filtro de status e plano (Admin/Financeiro). (Autenticado)
- `GET /api/billing/subscriptions/client/{clienteId}` — Histórico de assinaturas de um cliente (ativas e encerradas). (Autenticado)
- `POST /api/billing/subscriptions/{assinaturaId}/cancel` — Cancela uma assinatura (imediatamente ou ao fim do ciclo vigente). (Autenticado)
- `GET /api/billing/subscriptions/{clienteId}` — Consulta a assinatura ativa de um cliente. (Autenticado)

### Pagamentos, Split e Repasses
- `POST /api/payments` — Inicia um pagamento (PIX, Boleto ou Cartão de Crédito). Suporta os gateways: Asaas, MercadoPago e PagBank. Se omitido, o gateway é selecionado dinamicamente via Vault. (Autenticado)
- `GET /api/payments/parceiros/{parceiroId}/repasses` — Retorna o extrato paginado de repasses de um parceiro. Suporta filtro por status: Pendente, Liquidado, Bloqueado, Cancelado. (Autenticado)
- `POST /api/payments/splits/{splitId}/bloquear` — Bloqueia um split, impedindo o repasse ao parceiro. Usado em casos de chargeback, suspeita de fraude ou disputa. O webhook de chargeback bloqueia automaticamente; use este endpoint para bloqueio manual. (Autenticado)
- `POST /api/payments/splits/{splitId}/liquidar` — Liquida manualmente um split, confirmando o repasse ao parceiro. Normalmente a liquidação ocorre automaticamente via webhook de pagamento confirmado. Use este endpoint para liquidações administrativas ou fallback. (Autenticado)
- `POST /api/payments/{cobrancaId}/refund` — Solicita estorno total ou parcial de um pagamento. O gateway correto é selecionado automaticamente com base no registro da cobrança. (Autenticado)
- `GET /api/payments/{cobrancaId}/splits` — Lista todos os splits de repasse de uma cobrança. Retorna os detalhes do repasse ao parceiro: valor bruto, taxa da plataforma, valor líquido e status (Pendente / Liquidado / Bloqueado). (Autenticado)
- `GET /api/payments/{transactionId}/status` — Consulta o status atual de uma cobrança pelo transactionId do gateway. (Autenticado)
- `GET /api/refunds` — Lists all refund requests across the platform (Admin role). (Autenticado)
- `POST /api/refunds` — Submits a new refund request for an appointment. (Autenticado)
- `GET /api/refunds/client/{clientId}` — Lists all refund requests submitted by a specific client. (Autenticado)
- `GET /api/refunds/partner/{partnerId}` — Lists all refund requests involving a specific partner. (Autenticado)
- `PATCH /api/refunds/{refundId}/admin-decision` — Records the admin's mediation decision on a contested or escalated refund. (Autenticado)
- `POST /api/refunds/{refundId}/contest` — Contests a partner's rejected refund decision, escalating to platform administration. (Autenticado)
- `PATCH /api/refunds/{refundId}/partner-decision` — Records the partner's decision (Aprovado / Rejeitado) on a pending refund. Rejection requires a reason note. (Autenticado)
- `GET /api/transfers` — Lists all transfer requests across the platform (Admin role). (Autenticado)
- `POST /api/transfers` — Submits a new withdrawal/transfer request to a PIX key. (Autenticado)
- `GET /api/transfers/partner/{partnerId}` — Returns financial balance and transfer history for a specific partner. (Autenticado)
- `PATCH /api/transfers/{transferId}/status` — Updates the status of a transfer request (Admin role). (Autenticado)
- `POST /api/webhooks/asaas` — Webhook do Asaas. Valida assinatura via header "asaas-access-token" (HMAC-SHA256 Hex). (Público)
- `POST /api/webhooks/mercadopago` — Webhook do Mercado Pago. Valida assinatura via header "x-signature" (HMAC-SHA256 Hex). (Público)
- `POST /api/webhooks/pagbank` — Webhook do PagBank (PagSeguro). Valida assinatura via header "x-pagbank-signature" (HMAC-SHA256 Base64). Payload: { charges: [{ id, status, amount: { value (centavos) } }] } (Público)

### Catálogo e Ofertas
- `GET /api/catalog/offers` — Lista ofertas com paginação e filtros opcionais (categoria, parceiro, tipo). Cache de 2 minutos com invalidação por tag "catalog". (Público)
- `POST /api/catalog/offers` — Cria uma nova oferta (apenas Parceiro/Admin). (Autenticado)
- `GET /api/catalog/offers/{offerId}` — Retorna os detalhes de uma oferta pelo ID. (Público)
- `PUT /api/catalog/offers/{offerId}` — Atualiza uma oferta existente (apenas Parceiro dono ou Admin). (Autenticado)
- `POST /api/catalog/offers/{offerId}/hire` — Contratação direta sem agendamento (serviço avulso imediato). (Autenticado)
- `POST /api/partner/gallery` — Adds a new media item to a partner's portfolio. (Autenticado)
- `PUT /api/partner/gallery/{itemId}` — Updates an existing gallery item's caption, type, URL, or ordering. (Autenticado)
- `DELETE /api/partner/gallery/{itemId}` — Removes an item from the gallery portfolio. (Autenticado)
- `GET /api/partner/gallery/{partnerId}` — Lists all gallery portfolio media items for a specific partner. Publicly accessible. (Público)
- `POST /api/reviews/professional` — Submits a review and rating for a professional. Updates average rating & review count. (Autenticado)
- `GET /api/reviews/professionals/{partnerId}` — Lists public reviews received by a professional partner. (Público)
- `GET /api/skills` — List skills with optional filtering by category, name and active status. Results are paginated (default page size = 20). (Público)
- `POST /api/skills` — Create a new skill in the catalogue. Requires Admin role. (Autenticado)
- `GET /api/skills/partners/{partnerId}` — List all skills assigned to a specific partner. (Público)
- `POST /api/skills/partners/{partnerId}` — Assign an existing skill to a partner. Requires Admin role or the partner themselves. (Autenticado)
- `DELETE /api/skills/partners/{partnerId}/{skillId}` — Remove a skill assignment from a partner. Requires Admin role or the partner themselves. (Autenticado)
- `GET /api/skills/{skillId}` — Get a single skill by its ID. (Público)
- `PATCH /api/skills/{skillId}/status` — Activate or deactivate a skill (soft toggle). Requires Admin role. (Autenticado)
- `POST /api/spaces` — Registers a new workspace/physical space for a partner. (Autenticado)
- `GET /api/spaces/partner/{partnerId}` — Lists physical spaces registered by a partner. Publicly accessible. (Público)
- `PUT /api/spaces/{spaceId}` — Updates details, address, or photos of a registered space. (Autenticado)
- `DELETE /api/spaces/{spaceId}` — Deletes a registered workspace. (Autenticado)
- `PATCH /api/spaces/{spaceId}/toggle-active` — Toggles the active status of a workspace. (Autenticado)

### Parceiros e Prestadores
- `POST /api/partner/profile` — Creates the partner profile of a user (onboarding, open to any signed-in user). The user is the caller; an Admin may create it for another user by sending ProfessionalId. The profile starts pending (IsActive=false, hidden from public listings) until an Admin activates it; profiles created by an Admin start active. One profile per user: 409 when it already exists. (Autenticado)
- `GET /api/partner/profile/{partnerId}` — Returns the full profile of a partner professional by ID. (Autenticado)
- `PUT /api/partner/profile/{partnerId}` — Updates personal, address, and banking details of a partner. (Autenticado)
- `PATCH /api/partner/profile/{partnerId}/auto-accept` — Toggles the auto-acceptance configuration for new booking requests. (Autenticado)
- `PATCH /api/partner/profile/{partnerId}/status` — Activates/deactivates a partner (Admin). Inactive partners disappear from public listings. (Autenticado)
- `GET /api/partner/profiles` — Lists partners. Only active partners (and only public fields) unless an Admin asks for includeInactive=true. Proximity search needs lat, lon and radiusKm and sorts by distance; otherwise sorted by rating. (Autenticado)
- `POST /api/partner/services` — Creates a new service offering for a partner. (Autenticado)
- `GET /api/partner/services/{partnerId}` — Lists all services registered by a specific partner. (Público)
- `PUT /api/partner/services/{serviceId}` — Updates an existing service's details, name, or price. (Autenticado)
- `DELETE /api/partner/services/{serviceId}` — Deletes a service offered by a partner. Fails with conflict if there are active appointments booked for this service. (Autenticado)

### Mobilidade e Entregas
- `GET /api/mobility/admin/categories` — ListCategories (Autenticado)
- `POST /api/mobility/admin/categories` — CreateCategory (Autenticado)
- `PUT /api/mobility/admin/categories/{id}` — UpdateCategory (Autenticado)
- `GET /api/mobility/admin/complaints` — ListComplaints (Autenticado)
- `PATCH /api/mobility/admin/complaints/{id}` — HandleComplaint (Autenticado)
- `GET /api/mobility/admin/deliveries` — ListDeliveries (Autenticado)
- `GET /api/mobility/admin/drivers` — ListDrivers (Autenticado)
- `GET /api/mobility/admin/drivers/{id}` — GetDriver (Autenticado)
- `PATCH /api/mobility/admin/drivers/{id}/decision` — Aprova/rejeita cadastros pendentes e ativa/suspende/bloqueia quem já foi aprovado. (Autenticado)
- `GET /api/mobility/admin/metrics` — Metrics (Autenticado)
- `GET /api/mobility/admin/price-rules` — ListPriceRules (Autenticado)
- `POST /api/mobility/admin/price-rules` — CreatePriceRule (Autenticado)
- `PUT /api/mobility/admin/price-rules/{id}` — UpdatePriceRule (Autenticado)
- `DELETE /api/mobility/admin/price-rules/{id}` — DeletePriceRule (Autenticado)
- `GET /api/mobility/admin/rides` — ListRides (Autenticado)
- `POST /api/mobility/delivery` — Pede a entrega de um pedido. Idempotente por (referenciaTipo, referenciaId). O cliente pede para si; um Parceiro pede em nome de um cliente (fica como emissor); Admin/Financeiro/Suporte podem tudo. (Autenticado)
- `GET /api/mobility/delivery/available` — Entregas aguardando entregador, compatíveis com o veículo, das mais próximas às mais distantes. (Autenticado)
- `GET /api/mobility/delivery/by-reference/{tipo}/{referenciaId}` — Quem acompanha a logística do pedido: cliente, emissor, ou (sincronização entre sistemas) Admin/Financeiro/Suporte. (Autenticado)
- `GET /api/mobility/delivery/mine` — Entregas do usuário (como cliente ou parceiro emissor). (Autenticado)
- `GET /api/mobility/delivery/{id}` — GetDelivery (Autenticado)
- `POST /api/mobility/delivery/{id}/aceitar` — Accept (Autenticado)
- `POST /api/mobility/delivery/{id}/avaliar` — Rate (Autenticado)
- `POST /api/mobility/delivery/{id}/cancelar` — Cancel (Autenticado)
- `POST /api/mobility/delivery/{id}/coletar` — Pickup (Autenticado)
- `POST /api/mobility/delivery/{id}/concluir` — Complete (Autenticado)
- `POST /api/mobility/delivery/{id}/falha` — Fail (Autenticado)
- `GET /api/mobility/drivers/me` — GetMe (Autenticado)
- `PUT /api/mobility/drivers/me` — UpdateMe (Autenticado)
- `PUT /api/mobility/drivers/me/availability` — Fica online/offline. Ao ficar online sem posição gravada, informe latitude e longitude. (Autenticado)
- `GET /api/mobility/drivers/me/earnings` — Earnings (Autenticado)
- `PATCH /api/mobility/drivers/me/location` — Atualiza a posição (a cada ~5 s). Prefira o hub /hubs/mobility (AtualizarLocalizacao). (Autenticado)
- `POST /api/mobility/drivers/register` — Cadastra documentos e veículo. O motorista só opera depois que um admin aprova. (Autenticado)
- `GET /api/mobility/pricing/categories` — Categorias de corrida ativas. (Público)
- `POST /api/mobility/pricing/estimate` — Distância, tempo e tarifa estimada de cada categoria para o trajeto. (Público)
- `POST /api/mobility/rides` — Pede uma corrida. Sem motorista por perto, a corrida volta com status SemMotorista. (Autenticado)
- `GET /api/mobility/rides/active` — Corrida em curso do usuário (como cliente ou motorista). 204 quando não há. (Autenticado)
- `GET /api/mobility/rides/history` — History (Autenticado)
- `GET /api/mobility/rides/nearby-drivers` — Motoristas disponíveis por perto (só posição e distância — sem identificação). (Autenticado)
- `GET /api/mobility/rides/{id}` — GetRide (Autenticado)
- `POST /api/mobility/rides/{id}/aceitar` — Accept (Autenticado)
- `POST /api/mobility/rides/{id}/avaliar` — Avalia a corrida: o cliente avalia o motorista; o motorista avalia o cliente. (Autenticado)
- `POST /api/mobility/rides/{id}/cancelar` — Cancela (cliente ou motorista da corrida). Corrida em andamento não pode ser cancelada. (Autenticado)
- `POST /api/mobility/rides/{id}/chegou` — Arrived (Autenticado)
- `POST /api/mobility/rides/{id}/cobranca` — Vincula a cobrança (Payments) à corrida. Só o cliente da corrida (ou um administrador). (Autenticado)
- `POST /api/mobility/rides/{id}/concluir` — Complete (Autenticado)
- `POST /api/mobility/rides/{id}/iniciar` — Start (Autenticado)
- `GET /api/mobility/rides/{id}/messages` — GetMessages (Autenticado)
- `POST /api/mobility/rides/{id}/messages` — SendMessage (Autenticado)
- `POST /api/mobility/rides/{id}/reclamacoes` — OpenComplaint (Autenticado)
- `POST /api/mobility/rides/{id}/recusar` — Decline (Autenticado)

### Comunicação e Notificações
- `POST /api/email/send` — Envia um e-mail transacional pelo provedor configurado no Vault (com failover automático). (Autenticado)
- `PATCH /api/notifications/{notificationId}/read` — Marks a notification as read. (Autenticado)
- `GET /api/notifications/{userId}` — Gets all notifications for a user. (Autenticado)
- `POST /api/webhooks/email/resend` — Webhook do Resend. Valida assinatura via headers Svix (svix-id, svix-timestamp, svix-signature). Ref: https://resend.com/docs/dashboard/webhooks/introduction (Público)

### Arquivos e Armazenamento
- `GET /api/storage/files/{**storagePath}` — Streaming direto e seguro de arquivos públicos com cabeçalhos de cache. Resolve automaticamente o provedor de origem gravado no banco de dados. (Público)
- `POST /api/storage/upload` — Faz upload seguro de um arquivo (imagem, documento) para o storage configurado no Vault (S3, FileSystem ou Firebase). (Autenticado)
- `GET /api/storage/{id}` — Retorna os metadados de um arquivo por ID. (Público)
- `DELETE /api/storage/{id}` — Exclusão lógica (soft delete) e remoção do arquivo do storage de origem. (Autenticado)
- `GET /api/storage/{id}/download` — Streaming de arquivo por ID com resolução garantida do provedor original. (Público)

### Kanban as a Service
- `GET /api/admin/kanban/policies` — Tenants com política personalizada. (Autenticado)
- `GET /api/admin/kanban/tenants/{tenantId}/policy` — Política efetiva do tenant (personalização + padrão global). (Autenticado)
- `PUT /api/admin/kanban/tenants/{tenantId}/policy` — Substitui a personalização do tenant. Vale em até 30 s em todas as réplicas (na hora nesta). (Autenticado)
- `DELETE /api/admin/kanban/tenants/{tenantId}/policy` — Remove a personalização: o tenant volta ao padrão global. (Autenticado)
- `GET /api/kanban/boards` — Quadros do tenant. (Autenticado)
- `POST /api/kanban/boards` — Cria um quadro, opcionalmente já com campos e colunas. (Autenticado)
- `GET /api/kanban/boards/{boardId}` — Quadro com campos, colunas (em ordem) e a contagem de cartões ativos por coluna. (Autenticado)
- `PUT /api/kanban/boards/{boardId}` — UpdateBoard (Autenticado)
- `POST /api/kanban/boards/{boardId}/archive` — Arquiva o quadro: fica somente leitura e para de disparar automações. (Autenticado)
- `GET /api/kanban/boards/{boardId}/automations` — ListAutomations (Autenticado)
- `POST /api/kanban/boards/{boardId}/automations` — Cria uma regra "quando → se → então". Gatilho: evento do Kanban ("kanban.cartao.movido") ou de qualquer módulo ("payments.pagamento.confirmado", "scheduling.*"). Ações: mover, atualizar campos, comentar, arquivar, criar cartão, vincular entidade, e-mail, notificação, OCR, KYC, cobrança e webhook. Textos aceitam {{caminho}}. (Autenticado)
- `GET /api/kanban/boards/{boardId}/automations/{automationId}` — GetAutomation (Autenticado)
- `PUT /api/kanban/boards/{boardId}/automations/{automationId}` — UpdateAutomation (Autenticado)
- `DELETE /api/kanban/boards/{boardId}/automations/{automationId}` — DeleteAutomation (Autenticado)
- `POST /api/kanban/boards/{boardId}/automations/{automationId}/disable` — DisableAutomation (Autenticado)
- `POST /api/kanban/boards/{boardId}/automations/{automationId}/enable` — EnableAutomation (Autenticado)
- `GET /api/kanban/boards/{boardId}/automations/{automationId}/executions` — Histórico de execuções (ações executadas, saídas e erros). (Autenticado)
- `GET /api/kanban/boards/{boardId}/cards` — Cartões paginados, ordenados por coluna e posição. Filtros por campo customizado como ?field.prioridade=Alta&amp;field.valor=150 (igualdade; em multisseleção, "contém"). archived: omitido = ativos, true = só arquivados, false = todos. (Autenticado)
- `POST /api/kanban/boards/{boardId}/cards` — Cria um cartão. Sem coluna, entra na primeira; sem âncora, no fim. Campos validados pelo schema do quadro. (Autenticado)
- `POST /api/kanban/boards/{boardId}/columns` — CreateColumn (Autenticado)
- `PUT /api/kanban/boards/{boardId}/columns/order` — Nova ordem das colunas (todas, cada uma uma vez). (Autenticado)
- `PUT /api/kanban/boards/{boardId}/columns/{columnId}` — Atualiza a coluna. transicoes: nulo mantém, lista vazia libera qualquer destino. (Autenticado)
- `DELETE /api/kanban/boards/{boardId}/columns/{columnId}` — Remove a coluna; se houver cartões, moveCardsTo indica para onde vão. (Autenticado)
- `GET /api/kanban/boards/{boardId}/fields` — ListFields (Autenticado)
- `PUT /api/kanban/boards/{boardId}/fields` — Substitui todos os campos. Campos removidos têm os valores apagados de todos os cartões. (Autenticado)
- `POST /api/kanban/boards/{boardId}/fields` — AddField (Autenticado)
- `PUT /api/kanban/boards/{boardId}/fields/{key}` — Atualiza um campo. O tipo não muda: para outro tipo, remova e crie com outra chave. (Autenticado)
- `DELETE /api/kanban/boards/{boardId}/fields/{key}` — RemoveField (Autenticado)
- `PUT /api/kanban/boards/{boardId}/policy` — Estreita, neste quadro, os eventos e ações de automação que a política do tenant permite (nunca amplia). Nulo remove a restrição; automações já salvas que saírem da regra deixam de executar. (Autenticado)
- `POST /api/kanban/boards/{boardId}/restore` — RestoreBoard (Autenticado)
- `GET /api/kanban/cards/{cardId}` — GetCard (Autenticado)
- `PATCH /api/kanban/cards/{cardId}` — Atualização parcial. Em campos só as chaves enviadas mudam e null apaga o valor. Concorrência otimista por versaoEsperada ou cabeçalho If-Match (409 se o cartão mudou). (Autenticado)
- `DELETE /api/kanban/cards/{cardId}` — Exclui definitivamente o cartão e o seu histórico. (Autenticado)
- `GET /api/kanban/cards/{cardId}/activity` — Histórico do cartão, mais recente primeiro. (Autenticado)
- `POST /api/kanban/cards/{cardId}/archive` — ArchiveCard (Autenticado)
- `GET /api/kanban/cards/{cardId}/attachments` — ListAttachments (Autenticado)
- `POST /api/kanban/cards/{cardId}/attachments` — Envia um arquivo (multipart, campo file) para o provedor de storage ativo do tenant. (Autenticado)
- `DELETE /api/kanban/cards/{cardId}/attachments/{attachmentId}` — DeleteAttachment (Autenticado)
- `GET /api/kanban/cards/{cardId}/attachments/{attachmentId}/content` — DownloadAttachment (Autenticado)
- `POST /api/kanban/cards/{cardId}/comments` — Comment (Autenticado)
- `GET /api/kanban/cards/{cardId}/links` — ListLinks (Autenticado)
- `POST /api/kanban/cards/{cardId}/links` — Vincula o cartão a uma entidade (ex.: {"entidade":"cobranca","entidadeId":"…"}). Tipos conhecidos (GET /api/kanban/entities) são conferidos no tenant; outros são aceitos como ids externos. (Autenticado)
- `DELETE /api/kanban/cards/{cardId}/links/{linkId}` — RemoveLink (Autenticado)
- `POST /api/kanban/cards/{cardId}/move` — Move para a coluna, depois de aposCartaoId e/ou antes de antesCartaoId (sem âncora: fim). Respeita WIP e transições. (Autenticado)
- `POST /api/kanban/cards/{cardId}/restore` — Restaura ao fim da coluna de origem ou de colunaId. (Autenticado)
- `GET /api/kanban/entities` — Tipos de entidade conferidos ao vincular (os demais são aceitos como ids externos). (Autenticado)
- `GET /api/kanban/entities/{entity}/{entityId}/cards` — Cartões de todos os quadros vinculados à entidade (ex.: /entities/cobranca/{id}/cards). (Autenticado)
- `GET /api/kanban/events` — Tipos de evento do Kanban (webhooks e gatilhos) e tipos de entidade com checagem de existência. (Autenticado)
- `GET /api/kanban/policy` — Política efetiva do tenant: eventos e ações permitidos nas automações e limites (definida pelo Admin). (Autenticado)
- `GET /api/kanban/webhooks` — ListWebhooks (Autenticado)
- `POST /api/kanban/webhooks` — Cria a assinatura. O segredo HMAC só aparece nesta resposta (e na rotação). (Autenticado)
- `POST /api/kanban/webhooks/deliveries/{deliveryId}/redeliver` — Reenfileira uma entrega já concluída ou falha. (Autenticado)
- `GET /api/kanban/webhooks/{webhookId}` — GetWebhook (Autenticado)
- `PUT /api/kanban/webhooks/{webhookId}` — UpdateWebhook (Autenticado)
- `DELETE /api/kanban/webhooks/{webhookId}` — DeleteWebhook (Autenticado)
- `GET /api/kanban/webhooks/{webhookId}/deliveries` — Entregas da assinatura (status, tentativas, último HTTP/erro). (Autenticado)
- `POST /api/kanban/webhooks/{webhookId}/ping` — Enfileira um evento kanban.ping só para esta assinatura (teste de conectividade e assinatura). (Autenticado)
- `POST /api/kanban/webhooks/{webhookId}/rotate-secret` — RotateSecret (Autenticado)

### Open Finance e BPO Financeiro
- `GET /api/openfinance/accounts` — Lista as contas bancárias ativas persistidas no PostgreSQL. (Autenticado)
- `POST /api/openfinance/clear-mock` — Desativa dados de mock e ativa operação 100% real no PostgreSQL. (Autenticado)
- `GET /api/openfinance/config` — Obtém a configuração ativa e endpoints do toolkit MCP Open Finance. (Autenticado)
- `POST /api/openfinance/config` — Atualiza os endpoints e credenciais do MCP Open Finance no PostgreSQL. (Autenticado)
- `GET /api/openfinance/connect-url` — Retorna a URL de conexão do widget Pluggy Connect para autenticação de novas contas bancárias. (Autenticado)
- `GET /api/openfinance/goals` — Lista as metas financeiras e planejamento orçamentário do cliente no PostgreSQL. (Autenticado)
- `POST /api/openfinance/goals` — Cria ou atualiza uma meta financeira do cliente no PostgreSQL. (Autenticado)
- `GET /api/openfinance/missions` — Lista as missões de rotina financeira e tarefas pendentes no PostgreSQL. (Autenticado)
- `POST /api/openfinance/missions` — Cria ou atualiza uma missão financeira de rotina no PostgreSQL. (Autenticado)
- `GET /api/openfinance/sessions` — Lista o histórico de chamadas e atendimentos de diagnóstico BPO com IA. (Autenticado)
- `POST /api/openfinance/sessions` — Persiste uma sessão de atendimento de voz e transcrições no PostgreSQL. (Autenticado)
- `GET /api/openfinance/summary` — Retorna o saldo acumulado e extrato sincronizado de todas as contas no PostgreSQL. (Autenticado)
- `POST /api/openfinance/sync` — Executa a sincronização em tempo real das contas e transações via MCP e persiste no PostgreSQL. (Autenticado)
- `POST /api/openfinance/test` — Testa a conectividade com o MCP Toolkit e serviços bancários. (Autenticado)
- `GET /api/openfinance/transactions` — Lista transações bancárias com paginação e filtro por conta no PostgreSQL. (Autenticado)
- `POST /api/openfinance/transactions/{id}/conciliate` — Marca uma transação bancária como conciliada no PostgreSQL. (Autenticado)

### Administração da Plataforma
- `GET /api/admin/providers` — Retorna o estado completo de provedores: efetivos (por tenant ou plataforma), catálogo de provedores suportados e divisão de origem (padrão vs override por tenant). (Autenticado)
- `POST /api/admin/providers/preflight` — Executa verificação prévia (preflight) ativa antes de comutar um provedor. Valida chaves necessárias no Vault e executa health checks sem aplicar a troca. (Autenticado)
- `POST /api/admin/providers/switch` — Comuta o provedor ativo de um componente (plataforma ou tenant específico) no Vault. Executa preflight obrigatório antes de salvar e invalida o cache do seletor. Suporta modo dry-run para teste operacional sem persistência. (Autenticado)
- `POST /api/admin/tenants` — CreateTenant (Autenticado)
- `GET /api/admin/tenants` — ListTenants (Autenticado)
- `GET /api/admin/tenants/{id}` — GetTenant (Autenticado)
- `PUT /api/admin/tenants/{id}/activate` — ActivateTenant (Autenticado)
- `PUT /api/admin/tenants/{id}/cancel` — CancelTenant (Autenticado)
- `POST /api/admin/tenants/{id}/keys` — CreateApiKey (Autenticado)
- `GET /api/admin/tenants/{id}/keys` — ListApiKeys (Autenticado)
- `DELETE /api/admin/tenants/{id}/keys/{keyId}` — RevokeApiKey (Autenticado)
- `POST /api/admin/tenants/{id}/keys/{keyId}/rotate` — RotateApiKey (Autenticado)
- `PUT /api/admin/tenants/{id}/suspend` — SuspendTenant (Autenticado)

---

## 5. Ferramenta CLI de Provisionamento (BriefApp CLI)
O BriefApp CLI (`cli/`) automatiza o ciclo de vida operacional:
- `briefapp provision`: Cria novo tenant, define quotas, emite chaves `sk_live_...` e `pk_live_...` e gera `.env`.
- `briefapp validate --env <caminho>`: Valida conectividade, expiração e faz token exchange no Gateway.
- `briefapp keys generate|rotate`: Emite ou rotaciona credenciais com segurança.
- `briefapp db status|migrate`: Aplica migrações DDL e checa histórico no PostgreSQL.
- `briefapp deploy up|down`: Gerencia containers Docker locais e em produção.

---

## 6. Modelos Comerciais e Preços
- **Plano Builder:** R$ 290 a 490/mês, até 5 mil requisições/mês. Ideal para validar MVPs com front-end de IA.
- **Plano Scale:** R$ 1.200 a 2.500/mês, até 100 mil requisições/mês. Para operações ativas com faturamento e split.
- **Plano Enterprise:** A partir de R$ 8.000/mês. SLAs garantidos, limites dedicados e infraestrutura isolada.
- **Consumo Adicional:** Modelo pay-as-you-go transparente para excedentes.
- **Take-rate de Transações:** R$ 0,50 fixo + 0,5% a 1,5% sobre o volume transacionado via split.
- **Modelo Venture Builder:** Parceria tecnológica com participação societária em startups selecionadas.

---

## 7. Cases Possíveis (Ideias Ilustrativas)
Exemplos de 27 modelos de negócios digitais que utilizam a arquitetura modular da Brief App:
- **Marketplace de Serviços e Salões:** Catálogo, agendamento de horários e split automático com profissionais.
- **Delivery Local e Farmácias:** Catálogo multi-categoria, pedidos e despacho com motoristas parceiros.
- **App de Mobilidade Urbana:** Cálculo dinâmico de tarifa por km/min, despacho por geolocalização e repasse instantâneo via PIX.
- **Plataforma de Clínicas e Consultas:** Agendamento com slots de atendimento, prontuários no storage S3 e cobrança recorrente.
- **Clube de Assinaturas (SaaS):** Planos mensais com trial e gestão automática de inadimplência.
*(Nota: Casos conceituais e ilustrativos para orientação de arquitetura; não representam clientes comerciais específicos).*

---

## 8. Links Úteis e Suporte
- **Website Oficial:** https://fm.brief.app.br/startup-as-a-service/
- **Documentação Técnica:** https://fm.brief.app.br/startup-as-a-service/docs.php
- **Contrato OpenAPI v1:** https://fm.brief.app.br/startup-as-a-service/openapi/v1.json
- **Guia do CLI:** https://fm.brief.app.br/startup-as-a-service/docs/cli-provisioning.md
- **Repositório GitHub:** https://github.com/qweralfredo/briefapp-modules