Documentação da API REST

Visão geral

A API Brief App expõe, por HTTP, os módulos que operam uma startup inteira: identidade, agendamento, assinaturas, pagamentos, catálogo, parceiros, mobilidade, comunicação e arquivos. Tudo roda num único Gateway, e cada cliente seu vive num tenant com dados isolados.

Formato: JSON em UTF-8 em todas as requisições e respostas (exceto uploads, que usam multipart/form-data).
Base URL: o endereço do seu ambiente, informado ao criar o tenant. Todas as rotas começam com /api.
Contrato OpenAPI: GET /openapi/v1.json. Entregue esse arquivo à sua IA (Lovable, Cursor, Claude Code…) para ela gerar as chamadas.
Saúde: GET /health (o processo está vivo) e GET /ready (dependências prontas).
Datas: ISO 8601 em UTC (2026-10-15T13:00:00Z). Datas sem hora usam AAAA-MM-DD.
Dinheiro: valores decimais em reais (89.90), nunca em centavos.
Paginação: listas aceitam page (começa em 1) e pageSize (padrão 20).

O banco de dados é nosso: o PostgreSQL é a fonte da verdade para dinheiro, contratos e agendas, e uma camada de leitura em tempo real sincroniza o seu front-end. Você não modela tabelas nem cuida de backup.

Autenticação

Todo endpoint exige um token Authorization: Bearer <token>, exceto os marcados como Público. Há duas formas de obter o token.

1. Token do tenant (servidor para servidor)

Ao criar o seu tenant você recebe chaves de API:

sk_live_… Secret key: só no seu backend. Pode receber qualquer escopo.
pk_live_… Publishable key: pode ir para o app ou navegador, limitada aos escopos públicos (public, identity:login, identity:refresh, identity:2fa, identity:firebase, catalog:read, catalog:availability, scheduling:read) e às origens/bundle IDs cadastrados.

POST /api/tenants/token
Content-Type: application/json

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

→ 200 { "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 600,
        "scope": "financial partners", "tenant_id": "…", "tenant_slug": "minha-startup" }

O token vale 10 minutos. Peça só os escopos de que precisa: se omitir scope, recebe todos os da chave. Para agir em nome de um usuário, envie on_behalf_of com o id dele (ou o header X-On-Behalf-Of). A chave também pode vir no header X-Api-Key.

2. Login do usuário final

Para os usuários do seu app (clientes, parceiros, motoristas), o 2FA por aplicativo autenticador (TOTP) é obrigatório:

POST /api/auth/register cria a conta. Os papéis Admin e Parceiro ficam aguardando aprovação.
POST /api/auth/login com e-mail e senha. Na primeira vez a resposta traz requiresTwoFactorSetup: true, o userId e um twoFactorSetupToken de curta duração, mas nenhum token de sessão.
POST /api/auth/2fa/setup devolve a chave e o QR Code para o app autenticador.
POST /api/auth/2fa/verify confirma o código de 6 dígitos, ativa o 2FA e já devolve os tokens de sessão.
Nos próximos logins, envie twoFactorCode junto com e-mail e senha.

O access token dura 15 minutos. O refresh token dura 7 dias e é trocado a cada uso: POST /api/auth/refresh devolve um par novo e invalida o anterior. Também é possível entrar com Firebase (POST /api/auth/firebase-login).

Papéis e permissões

A API é segura por padrão: qualquer rota exige usuário autenticado, a não ser que esteja marcada como pública. Algumas rotas exigem um papel; para tokens de tenant, o escopo equivalente também libera.

Exigência	Papéis aceitos	Escopo do token de tenant
Admin	Admin	`admin`
Financeiro	Admin, Financeiro	`financial`
Parceiro	Admin, Parceiro	`partners`
Motorista	Admin, Motorista	`mobility`
Envio de e-mail	Admin, Suporte	`email`

Papéis disponíveis: Admin, Parceiro, Cliente, Membro, Financeiro, Suporte e Motorista.

Rotas que levam o id de um usuário, cliente ou parceiro também conferem o Dono: só o próprio dono do recurso (ou um Admin) passa. Um cliente nunca lê a agenda de outro, por exemplo.

Erros e status HTTP

Erros de negócio voltam sempre no mesmo formato, com uma mensagem legível e um código estável para o seu código tratar:

{ "error": "Horário não encontrado.", "code": "Scheduling.NotFound" }

Status	Quando acontece
`400`	Dados inválidos ou regra de negócio violada (ex.: faixas de horário sobrepostas).
`401`	Sem token, token expirado ou inválido.
`403`	Autenticado, mas sem o papel exigido ou sem ser dono do recurso.
`404`	Recurso inexistente.
`409`	Conflito de estado: horário já reservado, corrida já aceita, cadastro duplicado.
`429`	Limite de requisições atingido. Espere e tente de novo.

Idempotência e limites

Idempotência

Em criações e mutações (POST, PUT, PATCH, DELETE), envie o header X-Idempotency-Key com um valor único por operação (um UUID, por exemplo). Se a mesma chave chegar de novo em até 24 horas, a API devolve a resposta original sem repetir a operação, com o header Idempotent-Replayed: true. Isso torna seguro repetir uma cobrança ou um agendamento após uma queda de rede.

Limites de requisição

Grupo	Limite padrão	Por
Geral	100 por minuto	usuário (ou IP)
Login e cadastro	5 por minuto	IP
Pagamentos	10 por minuto	usuário (ou IP)
Emissão de token de tenant	60 por minuto	IP

O plano Enterprise pode ter limites próprios por tenant.

Tempo real e webhooks

Hubs em tempo real (SignalR)

/hubs/chat: mensagens de chat entre cliente e parceiro.
/hubs/mobility: posição do motorista e mudanças de status de corridas e entregas. O motorista envia a posição pelo método AtualizarLocalizacao, que é mais leve que o PATCH de localização.

Conecte com o mesmo Bearer token da API.

Webhooks dos gateways de pagamento

Asaas, Mercado Pago e PagBank avisam a Brief App quando um pagamento é confirmado, estornado ou contestado. A Brief App valida a assinatura HMAC de cada aviso (Asaas e Mercado Pago em hexadecimal, PagBank em Base64), atualiza a cobrança e libera ou bloqueia o repasse ao parceiro. Você não precisa implementar nada disso: basta consultar o status da cobrança ou reagir às notificações.

SDK, Sidecar e Ferramentas

Scalar API Reference: documentação interativa e exploratória acessível em /scalar/v1 tanto no Gateway quanto no Sidecar, com suporte completo a autenticação Bearer JWT e API Key (X-Api-Key).
Coleção Bruno: conjunto com mais de 30 requisições prontas na pasta api/bruno/, com ambientes configurados (local, staging e prod) e automação de token exchange no pós-resposta.
Qualquer linguagem: HTTP puro seguindo o contrato OpenAPI (/openapi/v1.json) ou gerando clientes em TypeScript, Python e C# com nossos scripts de codegen.
.NET: o pacote BriefApp.Sdk traz um cliente tipado, com renovação automática do token, retry seguro com X-Idempotency-Key e três modos de autenticação: conta de serviço, repasse do token do usuário ou híbrido.
Sidecar: um contêiner HTTP que envolve o SDK e expõe todos os módulos para qualquer linguagem na porta 5005, autenticado por X-Api-Key. Útil quando o seu backend não é .NET e você quer a renovação de token e os retries prontos.

Módulo

Identidade e acesso

Usuários, login, 2FA, papéis, aprovação de contas e verificação de documentos.

O módulo de identidade é o controle de usuários da sua startup. Ele guarda as contas, autentica com senha e 2FA obrigatório, emite os tokens de sessão e define quem pode fazer o quê por meio de papéis. Cadastros sensíveis (Admin e Parceiro) passam por aprovação, e contas podem ser suspensas ou bloqueadas a qualquer momento.

Conceitos

Usuário: Conta com e-mail único por tenant, nome, telefone, papéis e status.
Papel: Admin, Parceiro, Cliente, Membro, Financeiro, Suporte ou Motorista. Um usuário pode ter mais de um.
Status da conta: PendingApproval (aguardando aprovação), Active, Suspended, Blocked ou Rejected.
2FA (TOTP): Código de 6 dígitos de um app autenticador. Obrigatório para todos; sem ele não há sessão.
Access / refresh token: Access de 15 minutos para chamar a API; refresh de 7 dias, trocado a cada renovação.
KYC: Consulta de CPF/CNPJ ou extração de dados de um PDF, usada para validar parceiros e motoristas.

Estados possíveis

Conta

PendingApproval
Active
Suspended
Blocked

Fluxo típico

Cadastre o usuário com POST /api/auth/register informando o papel desejado.
Se o papel for Admin ou Parceiro, um Admin aprova com PUT /api/auth/users/{id}/approve.
O usuário faz login e, na primeira vez, configura o 2FA (setup e verify).
Com o token de sessão, o app chama GET /api/auth/me para montar o perfil e as permissões na tela.
Quando o access token expirar, troque pelo refresh com POST /api/auth/refresh.

Exemplo: Login com 2FA já configurado

Requisição

POST /api/auth/login
{ "email": "julia@exemplo.com", "password": "••••••••", "twoFactorCode": "482913" }

Resposta

200 OK
{ "accessToken": "eyJ…", "refreshToken": "q3V…",
  "accessTokenExpiresAt": "2026-10-15T13:15:00Z", "refreshTokenExpiresAt": "2026-10-22T13:00:00Z",
  "requiresTwoFactor": false, "requiresTwoFactorSetup": false, "userId": "7b1c…", "roles": ["Cliente"] }

Regras importantes

O login aceita 5 tentativas por minuto por IP.
Suspender ou bloquear um usuário revoga todos os refresh tokens dele na hora.
Ao conceder um papel (ex.: Motorista), o usuário passa a tê-lo no próximo login ou refresh.
Consultas de KYC trazem dados pessoais (LGPD) e são cobradas pelo provedor, por isso são restritas a Admin.

Referência de endpoints

Endpoints de autenticação e gestão de usuários. Rate limit para auth: 5 tentativas/min por IP (proteção brute-force).

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

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.

Permissão: Não exige token.

Corpo (JSON) · `LoginRequest`

Campo	Tipo	Obrigatório
`email`	string	sim
`password`	string	sim
`twoFactorCode`	string	não

Resposta · `LoginResult`

Campo	Tipo	Descrição
`accessToken`	string
`refreshToken`	string
`accessTokenExpiresAt`	datetime
`refreshTokenExpiresAt`	datetime
`requiresTwoFactor`	boolean
`requiresTwoFactorSetup`	boolean
`userId`	uuid
`roles`	string[]
`twoFactorSetupToken`	string

Status possíveis

200 OK
401 Não autenticado
429 Limite de requisições

POST /api/auth/register Registra um novo usuário. Roles Admin/Parceiro requerem aprovação administrativa — ficam com status PendingApproval. Público

Registra um novo usuário. Roles Admin/Parceiro requerem aprovação administrativa — ficam com status PendingApproval.

Permissão: Não exige token.

Corpo (JSON) · `RegisterUserRequest`

Campo	Tipo	Obrigatório
`email`	string	sim
`password`	string	sim
`fullName`	string	sim
`phoneNumber`	string	não
`requestedRole`	string	não

Resposta · `UserRegistrationResult`

Campo	Tipo	Descrição
`id`	uuid
`email`	string
`fullName`	string
`status`	UserStatus
`role`	string

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

POST /api/auth/refresh Renova o access token usando um refresh token válido. Público

Renova o access token usando um refresh token válido.

Permissão: Não exige token.

Corpo (JSON) · `RefreshTokenRequest`

Campo	Tipo	Obrigatório	Descrição
`userId`	uuid	sim
`refreshToken`	string	sim

Resposta · `TokenResponse`

Campo	Tipo	Descrição
`accessToken`	string
`refreshToken`	string
`accessTokenExpiresAt`	datetime
`refreshTokenExpiresAt`	datetime

Status possíveis

200 OK
401 Não autenticado

GET /api/auth/me Retorna o perfil do usuário autenticado (lido do JWT). Autenticado

Retorna o perfil do usuário autenticado (lido do JWT).

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `UserProfileResponse`

Campo	Tipo	Descrição
`userId`	string
`email`	string
`fullName`	string
`roles`	string[]
`partnerId`	string

Status possíveis

200 OK
401 Não autenticado

POST /api/auth/2fa/setup Gera a chave secreta e o QR Code URI para configurar o autenticador TOTP. Público

Gera a chave secreta e o QR Code URI para configurar o autenticador TOTP.

Permissão: Não exige token.

Corpo (JSON) · `Setup2faRequest`

Campo	Tipo	Obrigatório	Descrição
`userId`	uuid	sim
`setupToken`	string	não

Resposta · `Enable2faResult`

Campo	Tipo	Descrição
`secretKey`	string
`qrCodeUri`	string

Status possíveis

200 OK
404 Não encontrado

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

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).

Permissão: Não exige token.

Corpo (JSON) · `Verify2faRequest`

Campo	Tipo	Obrigatório
`userId`	uuid	sim
`secretKey`	string	sim
`code`	string	sim
`setupToken`	string	não

Resposta · `Verify2faResult`

Campo	Tipo	Descrição
`accessToken`	string
`refreshToken`	string
`accessTokenExpiresAt`	datetime
`refreshTokenExpiresAt`	datetime

Status possíveis

200 OK
400 Dados inválidos

PUT /api/auth/users/{userId}/approve Aprova um usuário com status PendingApproval (apenas Admin). Admin

Aprova um usuário com status PendingApproval (apenas Admin).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid

Status possíveis

204 Sem conteúdo
403 Sem permissão
404 Não encontrado

PUT /api/auth/users/{userId}/reject Rejeita um cadastro com status PendingApproval (apenas Admin). Admin

Rejeita um cadastro com status PendingApproval (apenas Admin).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid

Corpo (JSON) · `RejectUserRequest`

Campo	Tipo	Obrigatório	Descrição
`reason`	string	sim

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

GET /api/auth/users Lista usuários com paginação e filtros opcionais de papel, status e busca (nome, e-mail, telefone). Admin

Lista usuários com paginação e filtros opcionais de papel, status e busca (nome, e-mail, telefone).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo
`role`	query	string
`status`	query	UserStatus
`search`	query	string
`page`	query	integer
`pageSize`	query	integer

Resposta · `UserPageDto`

Campo	Tipo	Descrição
`items`	UserSummaryDto[]
`page`	integer
`pageSize`	integer
`total`	integer

Status possíveis

200 OK
400 Dados inválidos

GET /api/auth/users/{userId} Detalhe de um usuário. O próprio usuário ou um Admin. Autenticado Dono

Detalhe de um usuário. O próprio usuário ou um Admin.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid

Resposta · `UserSummaryDto`

Campo	Tipo	Descrição
`id`	uuid
`email`	string
`fullName`	string
`phoneNumber`	string
`status`	string
`roles`	string[]
`isTwoFactorEnabled`	boolean
`createdAt`	datetime
`lastLoginAt`	datetime

Status possíveis

200 OK
403 Sem permissão
404 Não encontrado

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. Admin

Muda o status de um usuário já aprovado: Active, Suspended ou Blocked (apenas Admin). Suspender/bloquear revoga os refresh tokens.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid

Corpo (JSON) · `ChangeUserStatusRequest`

Campo	Tipo	Obrigatório	Descrição
`status`	string	sim
`reason`	string	não

Resposta · `UserSummaryDto`

Campo	Tipo	Descrição
`id`	uuid
`email`	string
`fullName`	string
`phoneNumber`	string
`status`	string
`roles`	string[]
`isTwoFactorEnabled`	boolean
`createdAt`	datetime
`lastLoginAt`	datetime

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

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. Admin

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.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid
`role`	rota	string

Resposta · `UserSummaryDto`

Campo	Tipo	Descrição
`id`	uuid
`email`	string
`fullName`	string
`phoneNumber`	string
`status`	string
`roles`	string[]
`isTwoFactorEnabled`	boolean
`createdAt`	datetime
`lastLoginAt`	datetime

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

DELETE /api/auth/users/{userId}/roles/{role} Remove um papel do usuário (Admin). Não é possível remover o próprio papel de Admin. Admin

Remove um papel do usuário (Admin). Não é possível remover o próprio papel de Admin.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid
`role`	rota	string

Resposta · `UserSummaryDto`

Campo	Tipo	Descrição
`id`	uuid
`email`	string
`fullName`	string
`phoneNumber`	string
`status`	string
`roles`	string[]
`isTwoFactorEnabled`	boolean
`createdAt`	datetime
`lastLoginAt`	datetime

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

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 Dono

Atualiza nome e/ou telefone. O próprio usuário ou um Admin; campos nulos ficam como estão.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid

Corpo (JSON) · `UpdateUserProfileRequest`

Campo	Tipo	Obrigatório	Descrição
`fullName`	string	não
`phoneNumber`	string	não

Resposta · `UserSummaryDto`

Campo	Tipo	Descrição
`id`	uuid
`email`	string
`fullName`	string
`phoneNumber`	string
`status`	string
`roles`	string[]
`isTwoFactorEnabled`	boolean
`createdAt`	datetime
`lastLoginAt`	datetime

Status possíveis

200 OK
400 Dados inválidos
403 Sem permissão
404 Não encontrado

POST /api/auth/firebase-login Verifica um Firebase ID token e sincroniza o usuário (cria no primeiro login). Público

Verifica um Firebase ID token e sincroniza o usuário (cria no primeiro login).

Permissão: Não exige token.

Corpo (JSON) · `FirebaseLoginRequest`

Campo	Tipo	Obrigatório	Descrição
`idToken`	string	sim

Endpoint OAuth2/OpenID Connect para emissão de tokens de Tenant (client credentials e on-behalf-of).

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

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.

Permissão: Não exige token.

Consulta KYC (CPF/CNPJ e PDF) com chaveamento dinâmico via HashiCorp Vault (ApiBrasil e PdfExtractor). Restrito a Admin: a resposta traz dados pessoais (LGPD) e cada consulta é cobrada pelo provedor.

POST /api/kyc/consulta Consulta um CPF ou CNPJ no provedor de KYC configurado no Vault para o tenant. Pontuação (., -, /) é aceita e removida. Admin

Consulta um CPF ou CNPJ no provedor de KYC configurado no Vault para o tenant. Pontuação (., -, /) é aceita e removida.

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `ConsultaKycRequest`

Campo	Tipo	Obrigatório	Descrição
`tipoDocumento`	string	sim
`documento`	string	sim

Resposta · `ConsultaKycResponse`

Campo	Tipo	Descrição
`sucesso`	boolean
`status`	string
`provedor`	string
`dados`	JsonElement
`mensagemErro`	string

Status possíveis

200 OK
400 Dados inválidos
503 Indisponível

POST /api/kyc/consulta/pdf Consulta e extração estruturada de dados KYC a partir de um documento PDF. Admin

Consulta e extração estruturada de dados KYC a partir de um documento PDF.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`file`	form	arquivo

Resposta · `ConsultaKycResponse`

Campo	Tipo	Descrição
`sucesso`	boolean
`status`	string
`provedor`	string
`dados`	JsonElement
`mensagemErro`	string

Status possíveis

200 OK
400 Dados inválidos
503 Indisponível

Módulo

Agendamento

Grade semanal, exceções, horários livres, reservas, remarcação, conclusão e no-show.

O agendamento resolve o calendário de qualquer negócio de serviço. O parceiro define uma grade semanal (ex.: segunda a sexta, das 9h às 18h, atendimentos de 60 minutos) e marca exceções como folgas e feriados. A API gera os horários das próximas semanas a partir dessa grade, e o cliente reserva um horário livre, pagando com créditos da assinatura ou de forma avulsa. Remarcação, cancelamento com política de estorno, conclusão e no-show fecham o ciclo.

Conceitos

Grade semanal: Faixas por dia da semana (Monday … Sunday) com hora de início, fim e duração do atendimento, no fuso do parceiro.
Exceção: Data indisponível (folga, feriado, férias). Bloqueia os horários livres daquela data; os já reservados continuam.
Horário (slot): Um intervalo concreto da agenda: Disponivel, Reservado, Bloqueado ou Cancelado.
Agendamento: A reserva de um horário por um cliente, ligada a uma oferta do catálogo.
Tipo de pagamento: Credito (debita créditos da assinatura ou pacote) ou Avulso (valor pago na hora).
Política de estorno: Total, Parcial ou SemEstorno, aplicada automaticamente ao cancelar.

Estados possíveis

Horário

Disponivel
Reservado
Bloqueado
Cancelado

Agendamento

PendentePagamento
Confirmado
EmAndamento
Concluido
Cancelado
NoShow

Fluxo típico

O parceiro define a grade com PUT /api/scheduling/partners/{partnerId}/availability/weekly.
Marca folgas e feriados com POST …/availability/exceptions.
Gera os horários das próximas 1 a 12 semanas com POST …/slots/generate. Pode repetir: horários já existentes não são duplicados.
O cliente vê os horários livres numa data com GET /api/scheduling/availability (público, cache de 30 s).
O cliente reserva com POST /api/scheduling/appointments, escolhendo pagar com créditos ou avulso.
Se precisar, remarca para outro horário livre (PUT …/reschedule) ou cancela (DELETE …/appointments/{id}), com estorno pela política.
Depois do atendimento, o parceiro conclui (…/complete) ou registra que o cliente faltou (…/no-show).

Exemplo: Definir a grade semanal do parceiro

Requisição

PUT /api/scheduling/partners/9f2e…/availability/weekly
{ "regras": [
  { "diaSemana": "Monday",  "horaInicio": "09:00", "horaFim": "18:00", "duracaoMinutos": 60 },
  { "diaSemana": "Saturday", "horaInicio": "09:00", "horaFim": "13:00", "duracaoMinutos": 30 }
] }

Resposta

200 OK
[ { "id": "…", "diaSemana": "Monday", "horaInicio": "09:00:00", "horaFim": "18:00:00", "duracaoMinutos": 60 }, … ]

Regras importantes

Faixas do mesmo dia não podem se sobrepor, e a duração precisa caber na faixa.
Enviar a grade substitui a anterior inteira; lista vazia limpa a grade.
Informe utcOffsetMinutes (ex.: -180 para Brasília) ao gerar horários e criar exceções.
O calendário do parceiro (GET …/slots) aceita no máximo 62 dias por consulta.
Só o próprio parceiro ou um Admin gerencia a agenda; o cliente só vê os próprios agendamentos.

Referência de endpoints

Endpoints de agendamento — disponibilidade, marcação, cancelamento e remarcação.

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

Consulta os slots de horário disponíveis para um parceiro em uma data. Cache de 30s, variado por partnerId + date.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	query	uuid
`date`	query	date

Resposta · `AvailabilityResponse`

Campo	Tipo	Descrição
`partnerId`	uuid
`date`	date
`slots`	SlotResponse[]

Status possíveis

200 OK

POST /api/scheduling/appointments Cria um agendamento consumindo um slot disponível. Pagamento pode ser via créditos ou avulso. Autenticado Dono

Cria um agendamento consumindo um slot disponível. Pagamento pode ser via créditos ou avulso.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `BookAppointmentRequest`

Campo	Tipo	Obrigatório	Descrição
`clienteId`	uuid	sim
`parceiroId`	uuid	sim
`ofertaId`	uuid	sim
`slotId`	uuid	sim
`tipoPagamento`	string	sim
`valorAvulso`	decimal	não	Padrão: 0.
`quantidadeCreditos`	integer	não	Padrão: 1.

Resposta · `AgendamentoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`parceiroId`	uuid
`dataHoraInicio`	datetime
`status`	string

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

GET /api/scheduling/appointments/{appointmentId} Retorna os detalhes de um agendamento pelo ID. Autenticado Dono

Retorna os detalhes de um agendamento pelo ID.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`appointmentId`	rota	uuid

Resposta · `AgendamentoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`parceiroId`	uuid
`dataHoraInicio`	datetime
`status`	string

Status possíveis

200 OK
404 Não encontrado

DELETE /api/scheduling/appointments/{appointmentId} Cancela um agendamento. Aplica política de estorno de créditos conforme configuração. Autenticado

Cancela um agendamento. Aplica política de estorno de créditos conforme configuração.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`appointmentId`	rota	uuid

Corpo (JSON) · `CancelAppointmentRequest`

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	sim

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

PUT /api/scheduling/appointments/{appointmentId}/reschedule Remarca um agendamento para outro slot disponível. Autenticado

Remarca um agendamento para outro slot disponível.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`appointmentId`	rota	uuid

Corpo (JSON) · `RescheduleRequest`

Campo	Tipo	Obrigatório	Descrição
`novoSlotId`	uuid	sim

Resposta · `AgendamentoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`parceiroId`	uuid
`dataHoraInicio`	datetime
`status`	string

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

Agenda do parceiro (grade semanal, exceções, geração e bloqueio de horários), listagens de agendamentos e conclusão. As operações de agenda são do próprio parceiro ou de um Admin.

GET /api/scheduling/partners/{partnerId}/availability/weekly Grade semanal de atendimento do parceiro (horários locais do parceiro). Parceiro Dono

Grade semanal de atendimento do parceiro (horários locais do parceiro).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<RegraSemanalResponse>`

Campo	Tipo	Descrição
`id`	uuid
`diaSemana`	string
`horaInicio`	time (HH:mm)
`horaFim`	time (HH:mm)
`duracaoMinutos`	integer

Status possíveis

200 OK

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. Parceiro Dono

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.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `SetWeeklyAvailabilityRequest`

Campo	Tipo	Obrigatório	Descrição
`regras`	RegraSemanalRequest[]	sim

Resposta · `IReadOnlyList<RegraSemanalResponse>`

Campo	Tipo	Descrição
`id`	uuid
`diaSemana`	string
`horaInicio`	time (HH:mm)
`horaFim`	time (HH:mm)
`duracaoMinutos`	integer

Status possíveis

200 OK
400 Dados inválidos

GET /api/scheduling/partners/{partnerId}/availability/exceptions Lista as exceções (folgas, feriados, férias) do parceiro. Parceiro Dono

Lista as exceções (folgas, feriados, férias) do parceiro.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<ExcecaoResponse>`

Campo	Tipo	Descrição
`id`	uuid
`data`	date
`motivo`	string

Status possíveis

200 OK

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). Parceiro Dono

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).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `AddExceptionRequest`

Campo	Tipo	Obrigatório	Descrição
`data`	date	sim
`motivo`	string	sim
`utcOffsetMinutes`	integer	não	Padrão: 0.

Resposta · `ExcecaoCriadaResponse`

Campo	Tipo	Descrição
`excecao`	ExcecaoResponse
`slotsBloqueados`	integer

Status possíveis

201 Criado
409 Conflito de estado

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. Parceiro Dono

Remove a exceção da data. Os horários que ela bloqueou continuam bloqueados até serem liberados.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid
`date`	rota	date

Status possíveis

204 Sem conteúdo
404 Não encontrado

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. Parceiro Dono

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.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `GenerateSlotsRequest`

Campo	Tipo	Obrigatório	Descrição
`dataInicio`	date	sim
`semanas`	integer	sim
`utcOffsetMinutes`	integer	não	Padrão: 0.

Resposta · `GeracaoSlotsResponse`

Campo	Tipo	Descrição
`gerados`	integer
`ignorados`	integer
`de`	date
`ate`	date

Status possíveis

200 OK
400 Dados inválidos

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. Parceiro Dono

Calendário do parceiro: todos os horários (livres, reservados e bloqueados) em [from, to). Máx. 62 dias.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo
`partnerId`	rota	uuid
`from`	query	datetime
`to`	query	datetime

Resposta · `IReadOnlyList<SlotDetalheResponse>`

Campo	Tipo	Descrição
`id`	uuid
`parceiroId`	uuid
`inicio`	datetime
`fim`	datetime
`status`	string
`motivoBloqueio`	string

Status possíveis

200 OK
400 Dados inválidos

POST /api/scheduling/slots/{slotId}/block Bloqueia um horário livre, com motivo (ex.: almoço, compromisso). Parceiro Dono

Bloqueia um horário livre, com motivo (ex.: almoço, compromisso).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`slotId`	rota	uuid

Corpo (JSON) · `BlockSlotRequest`

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	sim

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

POST /api/scheduling/slots/{slotId}/unblock Libera um horário bloqueado, que volta a ficar disponível para reserva. Parceiro Dono

Libera um horário bloqueado, que volta a ficar disponível para reserva.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`slotId`	rota	uuid

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

GET /api/scheduling/appointments/client/{clientId} Agendamentos de um cliente, do mais recente ao mais antigo. status: PendentePagamento, Confirmado, EmAndamento, Concluido, Cancelado, NoShow. Autenticado Dono

Agendamentos de um cliente, do mais recente ao mais antigo. status: PendentePagamento, Confirmado, EmAndamento, Concluido, Cancelado, NoShow.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo
`clientId`	rota	uuid
`status`	query	string
`page`	query	integer
`pageSize`	query	integer

Resposta · `AgendamentoPaginaResponse`

Campo	Tipo	Descrição
`itens`	AgendamentoDetalheResponse[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK
400 Dados inválidos

GET /api/scheduling/appointments/partner/{partnerId} Agendamentos de um parceiro no intervalo [from, to) (UTC), do mais cedo ao mais tarde. Parceiro Dono

Agendamentos de um parceiro no intervalo [from, to) (UTC), do mais cedo ao mais tarde.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo
`partnerId`	rota	uuid
`from`	query	datetime
`to`	query	datetime
`status`	query	string
`page`	query	integer
`pageSize`	query	integer

Resposta · `AgendamentoPaginaResponse`

Campo	Tipo	Descrição
`itens`	AgendamentoDetalheResponse[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK
400 Dados inválidos

POST /api/scheduling/appointments/{appointmentId}/complete O parceiro conclui o atendimento (agendamento confirmado ou em andamento). Parceiro Dono

O parceiro conclui o atendimento (agendamento confirmado ou em andamento).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`appointmentId`	rota	uuid

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

POST /api/scheduling/appointments/{appointmentId}/no-show O parceiro registra que o cliente não compareceu. Parceiro Dono

O parceiro registra que o cliente não compareceu.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`appointmentId`	rota	uuid

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

Módulo

Assinaturas e recorrência

Planos, assinaturas com trial, renovação, inadimplência, cancelamento e ledger de créditos.

O Billing transforma o seu produto em receita recorrente. Você cria planos com preço, periodicidade e quantidade de créditos por ciclo; o cliente assina, opcionalmente começando com trial; a cada renovação os créditos do ciclo entram no saldo dele. Se uma cobrança falhar, a assinatura fica inadimplente durante o prazo de carência do plano antes de ser cancelada. Os créditos vivem num ledger de dupla entrada: toda entrada, uso, estorno e expiração fica registrada, e o saldo nunca é editado à mão.

Conceitos

Plano: Nome, preço, periodicidade (Mensal, Trimestral, Semestral, Anual), créditos por ciclo, dias de carência e validade dos créditos.
Status do plano: Ativo (aceita novas assinaturas), Inativo ou Descontinuado.
Assinatura: O vínculo de um cliente com um plano. Guarda o valor contratado, a vigência e o ciclo atual.
Trial: Período de teste antes da primeira cobrança.
Carência: Dias que a assinatura inadimplente continua de pé esperando o pagamento.
Ledger de créditos: Extrato imutável: EntradaAssinatura, EntradaPacote, EntradaBonus, DebitoUso, Estorno e Expiracao.

Estados possíveis

Assinatura

Trial
Ativa
Inadimplente
Pausada
Cancelada

Fluxo típico

Crie os planos com POST /api/billing/plans (papel Financeiro).
O app lista os planos ativos com GET /api/billing/plans para a tela de preços.
O cliente assina com POST /api/billing/subscriptions, com ou sem trial.
A cada renovação a cobrança é gerada e, confirmada pelo gateway, os créditos do ciclo entram no saldo.
O consumo (ex.: um agendamento pago com créditos) debita do saldo; cancelamentos estornam.
O cliente cancela com POST …/subscriptions/{id}/cancel, na hora ou ao fim do ciclo pago.

Exemplo: Criar um plano mensal com créditos

Requisição

POST /api/billing/plans
{ "nome": "Pro", "preco": 89.90, "periodicidade": "Mensal", "creditosPorCiclo": 8,
  "descricao": "8 sessões por mês", "diasCarenciaInadimplencia": 7, "validadeDiasCreditos": 60 }

Resposta

201 Created
{ "id": "c41d…", "nome": "Pro", "descricao": "8 sessões por mês", "preco": 89.90,
  "periodicidade": "Mensal", "creditosPorCiclo": 8, "diasCarenciaInadimplencia": 7,
  "validadeDiasCreditos": 60, "status": "Ativo" }

Regras importantes

Alterar o preço de um plano vale só para novas assinaturas; quem já assina mantém o valor contratado.
Upgrade e downgrade trocam o plano com proporcionalidade sobre o ciclo vigente.
Quem não é Admin ou Financeiro só enxerga os planos ativos.
Adicionar, debitar e estornar créditos manualmente exige o papel Financeiro.

Referência de endpoints

Endpoints de billing — créditos e assinaturas.

GET /api/billing/credits/{clienteId} Consulta o saldo de créditos disponível de um cliente. Autenticado Dono

Consulta o saldo de créditos disponível de um cliente.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`clienteId`	rota	uuid

Resposta · `SaldoCreditosResponse`

Campo	Tipo	Descrição
`clienteId`	uuid
`saldo`	integer

Status possíveis

200 OK

POST /api/billing/credits/{clienteId}/add Adiciona créditos ao saldo de um cliente (ex: compra de pacote). Financeiro

Adiciona créditos ao saldo de um cliente (ex: compra de pacote).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`clienteId`	rota	uuid

Corpo (JSON) · `AddCreditsRequest`

Campo	Tipo	Obrigatório
`quantidade`	integer	sim
`descricao`	string	sim
`referenciaId`	uuid	não
`validadeDias`	integer	não

Resposta · `CreditoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`saldo`	integer

Status possíveis

200 OK
400 Dados inválidos

POST /api/billing/credits/{clienteId}/debit Debita créditos do saldo de um cliente (ex: consumo de agendamento). Financeiro

Debita créditos do saldo de um cliente (ex: consumo de agendamento).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`clienteId`	rota	uuid

Corpo (JSON) · `DebitCreditsRequest`

Campo	Tipo	Obrigatório
`quantidade`	integer	sim
`motivo`	string	sim
`referenciaId`	uuid	não

Resposta · `CreditoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`saldo`	integer

Status possíveis

200 OK
400 Dados inválidos

POST /api/billing/credits/{clienteId}/refund Estorna créditos debitados (ex: cancelamento de agendamento). Financeiro

Estorna créditos debitados (ex: cancelamento de agendamento).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`clienteId`	rota	uuid

Corpo (JSON) · `RefundCreditsRequest`

Campo	Tipo	Obrigatório
`quantidade`	integer	sim
`motivo`	string	sim
`referenciaId`	uuid	não

Resposta · `CreditoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`saldo`	integer

Status possíveis

200 OK
400 Dados inválidos

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

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.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`includeInactive`	query	boolean

Resposta · `IReadOnlyList<PlanoResponse>`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`preco`	decimal
`periodicidade`	string
`creditosPorCiclo`	integer
`diasCarenciaInadimplencia`	integer
`validadeDiasCreditos`	integer
`status`	string

Status possíveis

200 OK

GET /api/billing/plans/{planId} Detalhe de um plano. Autenticado

Detalhe de um plano.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`planId`	rota	uuid

Resposta · `PlanoResponse`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`preco`	decimal
`periodicidade`	string
`creditosPorCiclo`	integer
`diasCarenciaInadimplencia`	integer
`validadeDiasCreditos`	integer
`status`	string

Status possíveis

200 OK
404 Não encontrado

POST /api/billing/plans Cria um plano com preço, periodicidade, créditos por ciclo, carência de inadimplência e validade dos créditos. Financeiro

Cria um plano com preço, periodicidade, créditos por ciclo, carência de inadimplência e validade dos créditos.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Corpo (JSON) · `CreatePlanRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`preco`	decimal	sim
`periodicidade`	string	sim
`creditosPorCiclo`	integer	sim
`descricao`	string	não
`diasCarenciaInadimplencia`	integer	não	Padrão: 3.
`validadeDiasCreditos`	integer	não	Padrão: 365.

Resposta · `PlanoResponse`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`preco`	decimal
`periodicidade`	string
`creditosPorCiclo`	integer
`diasCarenciaInadimplencia`	integer
`validadeDiasCreditos`	integer
`status`	string

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

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. Financeiro

Atualiza nome, descrição, preço e créditos. Quem já assina mantém o valor contratado; a mudança vale para novas assinaturas.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`planId`	rota	uuid

Corpo (JSON) · `UpdatePlanRequest`

Campo	Tipo	Obrigatório
`nome`	string	sim
`preco`	decimal	sim
`creditosPorCiclo`	integer	sim
`descricao`	string	não

Resposta · `PlanoResponse`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`preco`	decimal
`periodicidade`	string
`creditosPorCiclo`	integer
`diasCarenciaInadimplencia`	integer
`validadeDiasCreditos`	integer
`status`	string

Status possíveis

200 OK
404 Não encontrado

PATCH /api/billing/plans/{planId}/status Muda o status do plano: Ativo, Inativo ou Descontinuado. Só planos ativos aceitam novas assinaturas. Financeiro

Muda o status do plano: Ativo, Inativo ou Descontinuado. Só planos ativos aceitam novas assinaturas.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`planId`	rota	uuid

Corpo (JSON) · `SetPlanStatusRequest`

Campo	Tipo	Obrigatório	Descrição
`status`	string	sim

Resposta · `PlanoResponse`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`preco`	decimal
`periodicidade`	string
`creditosPorCiclo`	integer
`diasCarenciaInadimplencia`	integer
`validadeDiasCreditos`	integer
`status`	string

Status possíveis

200 OK
404 Não encontrado

POST /api/billing/subscriptions Cria uma nova assinatura para um cliente. Autenticado Dono

Cria uma nova assinatura para um cliente.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreateSubscriptionRequest`

Campo	Tipo	Obrigatório	Descrição
`clienteId`	uuid	sim
`planoId`	uuid	sim
`iniciarComoTrial`	boolean	não	Padrão: false.

Resposta · `AssinaturaResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`status`	string
`dataInicio`	datetime
`dataRenovacao`	datetime

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

GET /api/billing/subscriptions/{clienteId} Consulta a assinatura ativa de um cliente. Autenticado Dono

Consulta a assinatura ativa de um cliente.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`clienteId`	rota	uuid

Resposta · `AssinaturaResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`status`	string
`dataInicio`	datetime
`dataRenovacao`	datetime

Status possíveis

200 OK
404 Não encontrado

GET /api/billing/subscriptions Lista todas as assinaturas da plataforma (Financeiro). Financeiro

Lista todas as assinaturas da plataforma (Financeiro).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo
`status`	query	string
`planId`	query	uuid
`page`	query	integer
`pageSize`	query	integer

Resposta · `AssinaturaPaginaResponse`

Campo	Tipo	Descrição
`itens`	AssinaturaDetalheResponse[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK
400 Dados inválidos

GET /api/billing/subscriptions/client/{clienteId} Histórico de assinaturas de um cliente, incluindo as canceladas. Autenticado Dono

Histórico de assinaturas de um cliente, incluindo as canceladas.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`clienteId`	rota	uuid

Resposta · `IReadOnlyList<AssinaturaDetalheResponse>`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`planoId`	uuid
`valorRecorrente`	decimal
`status`	string
`cicloAtual`	integer
`dataInicio`	datetime
`dataFimVigencia`	datetime
`proximaCobranca`	datetime
`dataCancelamento`	datetime
`motivoCancelamento`	string
`tentativasCobrancaFalhadas`	integer

Status possíveis

200 OK

POST /api/billing/subscriptions/{assinaturaId}/cancel Cancela uma assinatura (imediatamente ou ao fim do ciclo vigente). Autenticado Dono

Cancela uma assinatura (imediatamente ou ao fim do ciclo vigente).

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`assinaturaId`	rota	uuid

Corpo (JSON) · `CancelSubscriptionRequest`

Campo	Tipo	Obrigatório	Descrição
`clienteId`	uuid	sim
`motivo`	string	sim
`imediato`	boolean	não	Padrão: false.

Resposta · `AssinaturaResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`status`	string
`dataInicio`	datetime
`dataRenovacao`	datetime

Status possíveis

200 OK
400 Dados inválidos
403 Sem permissão
404 Não encontrado

Módulo

Pagamentos, split e repasses

Cobranças PIX, boleto e cartão, estornos, split com parceiros, saques e disputas.

O módulo de pagamentos cobra o cliente por PIX, boleto ou cartão em três gateways (Asaas, Mercado Pago e PagBank), escolhidos automaticamente ou por configuração. Cada cobrança pode ter split: a parte do parceiro fica registrada e é liberada quando o gateway confirma o pagamento. O parceiro acompanha o extrato e pede saques para a chave PIX. Disputas entre cliente e parceiro seguem um fluxo de reembolso com decisão do parceiro e mediação do Admin.

Conceitos

Cobrança: O registro do pagamento na Brief App. Tem o id interno (cobrancaId) e o id do gateway (transactionId).
Split: A divisão de uma cobrança: valor bruto, taxa da plataforma e valor líquido do parceiro.
Status do split: Pendente, Liquidado (repasse confirmado), Bloqueado (chargeback, fraude, disputa) ou Cancelado.
Saque: Pedido do parceiro para transferir o saldo a uma chave PIX, aprovado pelo Financeiro.
Reembolso: Solicitação do cliente sobre um agendamento: o parceiro aprova ou rejeita, e o cliente pode contestar para o Admin.

Estados possíveis

Split

Pendente
Liquidado
Bloqueado
Cancelado

Fluxo típico

Crie a cobrança com POST /api/payments, informando valor, pagador e o percentual de repasse ao parceiro.
Mostre ao cliente o QR Code PIX, o boleto ou o checkout do cartão devolvidos na resposta.
O gateway confirma pelo webhook; a cobrança muda de status e o split é liquidado.
Consulte o status quando quiser com GET /api/payments/{transactionId}/status, sem ir ao gateway.
O parceiro vê o extrato em GET /api/payments/parceiros/{id}/repasses e pede saque em POST /api/transfers.

Exemplo: Cobrança PIX com repasse de 80% ao parceiro

Requisição

POST /api/payments
X-Idempotency-Key: 5c0e2a5e-…
{ "pedidoId": "…", "clienteId": "…", "parceiroId": "…", "valorTotal": 120.00, "metodo": "Pix",
  "payerEmail": "julia@exemplo.com", "payerName": "Júlia Andrade", "payerCpfCnpj": "123.456.789-09",
  "percentualRepasseParceiro": 80, "taxaFixaPlataforma": 0.50 }

Resposta

200 OK
{ "success": true, "transactionId": "pay_8x2…", "status": "Pending", "provedor": "Asaas",
  "pixQrCode": "iVBORw0KGgo…", "pixQrCodeText": "000201…", "boletoUrl": null, "paymentUrl": null }

Regras importantes

Não confunda os ids: o status usa o transactionId do gateway; o estorno usa o cobrancaId da Brief App.
Pagamentos aceitam 10 requisições por minuto por usuário. Sempre envie X-Idempotency-Key.
Um chargeback bloqueia o split automaticamente, antes que o dinheiro chegue ao parceiro.
Estornos, liquidação e bloqueio manual de splits exigem o papel Financeiro.

Referência de endpoints

Endpoints de pagamento — suporta Asaas, Mercado Pago e PagBank. Rate limit: 10 req/min por token (anti-fraude).

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 Dono

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.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CriarPagamentoRequest`

Campo	Tipo	Obrigatório	Descrição
`pedidoId`	uuid	sim
`clienteId`	uuid	sim
`parceiroId`	uuid	sim
`valorTotal`	decimal	sim
`metodo`	string	sim	Pix \| Boleto \| CreditCard
`provedor`	string	não	Asaas \| MercadoPago \| PagBank (opcional: se omitido, resolvido via Vault)
`payerEmail`	string	não
`payerName`	string	não
`payerCpfCnpj`	string	não
`percentualRepasseParceiro`	decimal	não	Padrão: 85.
`taxaFixaPlataforma`	decimal	não	Padrão: 0.
`dataVencimento`	datetime	não

Resposta · `PaymentResultResponse`

Campo	Tipo	Descrição
`success`	boolean
`transactionId`	string
`status`	string
`provedor`	string
`pixQrCode`	string	Imagem Base64 do QR Code PIX (somente para Pix)
`pixQrCodeText`	string	Payload EMV do PIX para copiar e colar
`boletoUrl`	string	URL do PDF do Boleto (somente para Boleto)
`boletoBarcode`	string	Código de barras do Boleto
`paymentUrl`	string	URL de pagamento (somente para CreditCard)
`errorMessage`	string
`cobrancaId`	uuid	Id interno da cobrança — use este valor (não o TransactionId) para solicitar estorno.

Status possíveis

200 OK
400 Dados inválidos
429 Limite de requisições

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. Financeiro

Solicita estorno total ou parcial de um pagamento. O gateway correto é selecionado automaticamente com base no registro da cobrança.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`cobrancaId`	rota	uuid

Corpo (JSON) · `EstornarPagamentoRequest`

Campo	Tipo	Obrigatório	Descrição
`valor`	decimal	sim
`motivo`	string	sim

Resposta · `RefundResultResponse`

Campo	Tipo	Descrição
`success`	boolean
`refundId`	string
`status`	string

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

GET /api/payments/{transactionId}/status Consulta o status atual de uma cobrança pelo transactionId do gateway. Autenticado Dono

Consulta o status atual de uma cobrança pelo transactionId do gateway.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`transactionId`	rota	string

Resposta · `PaymentStatusResponse`

Campo	Tipo	Descrição
`transactionId`	string
`status`	string
`provedor`	string
`amount`	decimal
`paidAt`	datetime

Status possíveis

200 OK
404 Não encontrado

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). Financeiro

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).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`cobrancaId`	rota	uuid

Resposta · `IReadOnlyList<SplitResponse>`

Campo	Tipo	Descrição
`splitId`	uuid
`cobrancaId`	uuid
`parceiroId`	uuid
`percentualRepasse`	decimal
`valorBruto`	decimal
`taxaPlataforma`	decimal
`valorLiquidoParceiro`	decimal
`status`	string
`dataLiquidacao`	datetime

Status possíveis

200 OK

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. Financeiro

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.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`splitId`	rota	uuid

Resposta · `SplitResponse`

Campo	Tipo	Descrição
`splitId`	uuid
`cobrancaId`	uuid
`parceiroId`	uuid
`percentualRepasse`	decimal
`valorBruto`	decimal
`taxaPlataforma`	decimal
`valorLiquidoParceiro`	decimal
`status`	string
`dataLiquidacao`	datetime

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

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. Financeiro

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.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`splitId`	rota	uuid

Resposta · `SplitResponse`

Campo	Tipo	Descrição
`splitId`	uuid
`cobrancaId`	uuid
`parceiroId`	uuid
`percentualRepasse`	decimal
`valorBruto`	decimal
`taxaPlataforma`	decimal
`valorLiquidoParceiro`	decimal
`status`	string
`dataLiquidacao`	datetime

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

GET /api/payments/parceiros/{parceiroId}/repasses Retorna o extrato paginado de repasses de um parceiro. Suporta filtro por status: Pendente, Liquidado, Bloqueado, Cancelado. Autenticado Dono

Retorna o extrato paginado de repasses de um parceiro. Suporta filtro por status: Pendente, Liquidado, Bloqueado, Cancelado.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo
`parceiroId`	rota	uuid
`status`	query	string
`page`	query	integer
`pageSize`	query	integer

Resposta · `IReadOnlyList<SplitResponse>`

Campo	Tipo	Descrição
`splitId`	uuid
`cobrancaId`	uuid
`parceiroId`	uuid
`percentualRepasse`	decimal
`valorBruto`	decimal
`taxaPlataforma`	decimal
`valorLiquidoParceiro`	decimal
`status`	string
`dataLiquidacao`	datetime

Status possíveis

200 OK

Endpoints for managing balance withdrawals, transfer requests, and admin payout processing.

GET /api/transfers Lista todos os pedidos de saque da plataforma (Financeiro). Financeiro

Lista todos os pedidos de saque da plataforma (Financeiro).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Resposta · `IReadOnlyList<TransferResponse>`

Campo	Tipo	Descrição
`id`	uuid
`partnerId`	uuid
`amount`	decimal
`pixKey`	string
`pixKeyType`	string
`status`	string
`adminNote`	string
`processedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK

GET /api/transfers/partner/{partnerId} Saldo e histórico de saques de um parceiro. Autenticado Dono

Saldo e histórico de saques de um parceiro.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `TransferBalanceResponse`

Campo	Tipo	Descrição
`available`	decimal
`totalEarned`	decimal
`transferred`	decimal
`transfers`	TransferResponse[]

Status possíveis

200 OK

POST /api/transfers O parceiro pede o saque de um valor para a sua chave PIX. Parceiro Dono

O parceiro pede o saque de um valor para a sua chave PIX.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `RequestTransferRequest`

Campo	Tipo	Obrigatório	Descrição
`partnerId`	uuid	sim
`amount`	decimal	sim
`pixKey`	string	sim
`pixKeyType`	string	não	Padrão: "CPF".

Resposta · `TransferResponse`

Campo	Tipo	Descrição
`id`	uuid
`partnerId`	uuid
`amount`	decimal
`pixKey`	string
`pixKeyType`	string
`status`	string
`adminNote`	string
`processedAt`	datetime
`createdAt`	datetime

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

PATCH /api/transfers/{transferId}/status O Financeiro atualiza o status do saque, com observação. Financeiro

O Financeiro atualiza o status do saque, com observação.

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Parâmetros

Nome	Onde	Tipo	Descrição
`transferId`	rota	uuid

Corpo (JSON) · `UpdateTransferStatusRequest`

Campo	Tipo	Obrigatório	Descrição
`status`	string	sim
`adminNote`	string	não

Resposta · `TransferResponse`

Campo	Tipo	Descrição
`id`	uuid
`partnerId`	uuid
`amount`	decimal
`pixKey`	string
`pixKeyType`	string
`status`	string
`adminNote`	string
`processedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK
404 Não encontrado

Endpoints for handling dispute resolution and refund workflows between clients, partners, and administrators.

GET /api/refunds Lista todas as solicitações de reembolso da plataforma (Financeiro). Financeiro

Lista todas as solicitações de reembolso da plataforma (Financeiro).

Permissão: Exige Admin ou Financeiro (ou escopo financial).

Resposta · `IReadOnlyList<RefundResponse>`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK

GET /api/refunds/partner/{partnerId} Solicitações de reembolso que envolvem um parceiro. Autenticado Dono

Solicitações de reembolso que envolvem um parceiro.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<RefundResponse>`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK

GET /api/refunds/client/{clientId} Solicitações de reembolso feitas por um cliente. Autenticado Dono

Solicitações de reembolso feitas por um cliente.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`clientId`	rota	uuid

Resposta · `IReadOnlyList<RefundResponse>`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK

POST /api/refunds O cliente pede reembolso de um agendamento, com valor e motivo. Autenticado Dono

O cliente pede reembolso de um agendamento, com valor e motivo.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreateRefundRequest`

Campo	Tipo	Obrigatório
`appointmentId`	uuid	sim
`clientId`	uuid	sim
`partnerId`	uuid	sim
`amount`	decimal	sim
`reason`	string	sim

Resposta · `RefundResponse`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

PATCH /api/refunds/{refundId}/partner-decision O parceiro aprova ou rejeita o reembolso. Rejeitar exige uma justificativa. Parceiro Dono

O parceiro aprova ou rejeita o reembolso. Rejeitar exige uma justificativa.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`refundId`	rota	uuid

Corpo (JSON) · `PartnerDecisionRequest`

Campo	Tipo	Obrigatório	Descrição
`decision`	string	sim
`partnerNote`	string	não

Resposta · `RefundResponse`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

PATCH /api/refunds/{refundId}/admin-decision O Admin decide um reembolso contestado (mediação). Admin

O Admin decide um reembolso contestado (mediação).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`refundId`	rota	uuid

Corpo (JSON) · `AdminDecisionRequest`

Campo	Tipo	Obrigatório	Descrição
`decision`	string	sim
`adminNote`	string	não

Resposta · `RefundResponse`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK
404 Não encontrado

POST /api/refunds/{refundId}/contest O cliente contesta a rejeição do parceiro e leva o caso ao Admin. Autenticado Dono

O cliente contesta a rejeição do parceiro e leva o caso ao Admin.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`refundId`	rota	uuid

Corpo (JSON) · `ContestRefundRequest`

Campo	Tipo	Obrigatório	Descrição
`contestReason`	string	sim
`contestedBy`	string	sim

Resposta · `RefundResponse`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`amount`	decimal
`reason`	string
`appointmentId`	uuid
`clientId`	uuid
`partnerId`	uuid
`partnerNote`	string
`partnerDecidedAt`	datetime
`contestReason`	string
`contestedAt`	datetime
`contestedBy`	string
`adminNote`	string
`adminDecidedAt`	datetime
`createdAt`	datetime

Status possíveis

200 OK
404 Não encontrado

Recebe webhooks de gateways de pagamento (Asaas, Mercado Pago, PagBank). Valida a assinatura HMAC antes de processar qualquer evento.

POST /api/webhooks/asaas Webhook do Asaas. Valida assinatura via header "asaas-access-token" (HMAC-SHA256 Hex). Público

Webhook do Asaas. Valida assinatura via header "asaas-access-token" (HMAC-SHA256 Hex).

Permissão: Não exige token.

Status possíveis

200 OK
401 Não autenticado

POST /api/webhooks/mercadopago Webhook do Mercado Pago. Valida assinatura via header "x-signature" (HMAC-SHA256 Hex). Público

Webhook do Mercado Pago. Valida assinatura via header "x-signature" (HMAC-SHA256 Hex).

Permissão: Não exige token.

Status possíveis

200 OK
401 Não autenticado

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

Webhook do PagBank (PagSeguro). Valida assinatura via header "x-pagbank-signature" (HMAC-SHA256 Base64). Payload: { charges: [{ id, status, amount: { value (centavos) } }] }

Permissão: Não exige token.

Status possíveis

200 OK
401 Não autenticado

Módulo

Catálogo, avaliações e skills

Ofertas de serviços e pacotes, contratação avulsa, avaliações e especialidades.

O catálogo é a vitrine do seu marketplace. Parceiros publicam ofertas (serviço avulso, pacote de créditos ou assinatura) com título, preço e imagem; o cliente navega por categoria e parceiro e pode contratar direto, sem agendamento. As avaliações formam a reputação de cada profissional, e as skills descrevem as especialidades de cada um (ex.: “Coloração”, “Depilação a laser”).

Conceitos

Oferta: Item vendável de um parceiro: título, descrição, preço, tipo, créditos e periodicidade (quando for pacote ou assinatura).
Contratação avulsa: Compra imediata de uma oferta, sem horário marcado.
Avaliação: Nota e comentário de um cliente para um profissional; atualiza a média e o total de avaliações.
Skill: Especialidade do catálogo global, atribuída a parceiros.

Fluxo típico

O parceiro cria ofertas com POST /api/catalog/offers.
O app lista as ofertas com filtros em GET /api/catalog/offers (público, cache de 2 minutos).
O cliente contrata direto (…/offers/{id}/hire) ou agenda um horário no módulo de Agendamento.
Depois do atendimento, o cliente avalia com POST /api/reviews/professional.

Exemplo: Listar ofertas de uma categoria

Requisição

GET /api/catalog/offers?categoriaId=…&page=1&pageSize=20

Resposta

200 OK
{ "items": [ { "id": "…", "titulo": "Coloração completa", "descricao": "…", "preco": 180.00,
    "tipo": "Avulso", "parceiroId": "…" } ],
  "page": 1, "pageSize": 20, "total": 34 }

Regras importantes

Só o parceiro dono da oferta (ou um Admin) cria e edita ofertas.
Leituras públicas do catálogo ficam em cache por 2 minutos e são invalidadas quando uma oferta muda.
O catálogo global de skills é mantido por Admin; o parceiro escolhe quais skills tem.

Referência de endpoints

Endpoints do catálogo — ofertas, parceiros e contratação avulsa. Leitura usa OutputCache de 2 minutos (dado semi-estático).

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

Lista ofertas com paginação e filtros opcionais (categoria, parceiro, tipo). Cache de 2 minutos com invalidação por tag "catalog".

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo
`categoriaId`	query	uuid
`parceiroId`	query	uuid
`tipo`	query	string
`page`	query	integer
`pageSize`	query	integer

Resposta · `PagedResponse<OfertaResponse>`

Campo	Tipo	Descrição
`id`	uuid
`titulo`	string
`descricao`	string
`preco`	decimal
`tipo`	string
`parceiroId`	uuid

Status possíveis

200 OK

GET /api/catalog/offers/{offerId} Retorna os detalhes de uma oferta pelo ID. Público

Retorna os detalhes de uma oferta pelo ID.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`offerId`	rota	uuid

Resposta · `OfertaResponse`

Campo	Tipo	Descrição
`id`	uuid
`titulo`	string
`descricao`	string
`preco`	decimal
`tipo`	string
`parceiroId`	uuid

Status possíveis

200 OK
404 Não encontrado

POST /api/catalog/offers Cria uma nova oferta (apenas Parceiro/Admin). Parceiro Dono

Cria uma nova oferta (apenas Parceiro/Admin).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreateOfferRequest`

Campo	Tipo	Obrigatório	Descrição
`parceiroId`	uuid	sim
`categoriaId`	uuid	sim
`titulo`	string	sim
`descricao`	string	sim
`preco`	decimal	sim
`tipo`	string	não	Padrão: "Avulso".
`quantidadeCreditos`	integer	não
`periodicidadeMeses`	integer	não
`imagemUrl`	string	não

Resposta · `OfertaResponse`

Campo	Tipo	Descrição
`id`	uuid
`titulo`	string
`descricao`	string
`preco`	decimal
`tipo`	string
`parceiroId`	uuid

Status possíveis

201 Criado
400 Dados inválidos

PUT /api/catalog/offers/{offerId} Atualiza uma oferta existente (apenas Parceiro dono ou Admin). Parceiro

Atualiza uma oferta existente (apenas Parceiro dono ou Admin).

Permissão: Exige Admin ou Parceiro (ou escopo partners).

Parâmetros

Nome	Onde	Tipo	Descrição
`offerId`	rota	uuid

Corpo (JSON) · `UpdateOfferRequest`

Campo	Tipo	Obrigatório
`titulo`	string	não
`descricao`	string	não
`preco`	decimal	não
`imagemUrl`	string	não

Resposta · `OfertaResponse`

Campo	Tipo	Descrição
`id`	uuid
`titulo`	string
`descricao`	string
`preco`	decimal
`tipo`	string
`parceiroId`	uuid

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

POST /api/catalog/offers/{offerId}/hire Contratação direta sem agendamento (serviço avulso imediato). Autenticado Dono

Contratação direta sem agendamento (serviço avulso imediato).

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`offerId`	rota	uuid

Corpo (JSON) · `HireOfferRequest`

Campo	Tipo	Obrigatório	Descrição
`clienteId`	uuid	sim

Resposta · `ContratacaoResponse`

Campo	Tipo	Descrição
`id`	uuid
`clienteId`	uuid
`ofertaId`	uuid
`status`	string

Status possíveis

201 Criado
400 Dados inválidos

Endpoints for customer feedback and partner reviews. Supports both directions: clients rating professionals, and professionals rating clients.

GET /api/reviews/professionals/{partnerId} Avaliações públicas recebidas por um profissional. Público

Avaliações públicas recebidas por um profissional.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<BriefApp.Partners.Queries.ReviewDto>`

Status possíveis

200 OK

POST /api/reviews/professional Registra a nota e o comentário de um cliente para um profissional e atualiza a média. Autenticado Dono

Registra a nota e o comentário de um cliente para um profissional e atualiza a média.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreateProfessionalReviewRequest`

Campo	Tipo	Obrigatório
`partnerId`	uuid	sim
`customerId`	uuid	sim
`rating`	integer	sim
`comment`	string	não

Status possíveis

400 Dados inválidos

Skill catalogue management and partner skill assignments. Skills represent professional specialties (e.g. "Corte Feminino", "Coloração", "Depilação a Laser").

GET /api/skills Lista skills com filtros por categoria, nome e status, paginado. Público

Lista skills com filtros por categoria, nome e status, paginado.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo
`categoria`	query	string
`nome`	query	string
`apenasAtivas`	query	boolean
`page`	query	integer
`pageSize`	query	integer

GET /api/skills/{skillId} Detalhe de uma skill. Público

Detalhe de uma skill.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`skillId`	rota	uuid

Status possíveis

404 Não encontrado

POST /api/skills Cria uma skill no catálogo global (Admin). Admin

Cria uma skill no catálogo global (Admin).

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `CreateSkillRequest`

Campo	Tipo	Obrigatório
`nome`	string	sim
`categoria`	string	sim
`descricao`	string	não

Status possíveis

400 Dados inválidos
409 Conflito de estado

PATCH /api/skills/{skillId}/status Ativa ou desativa uma skill (Admin). Admin

Ativa ou desativa uma skill (Admin).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`skillId`	rota	uuid
`ativa`	query	boolean

Status possíveis

404 Não encontrado

GET /api/skills/partners/{partnerId} Skills atribuídas a um parceiro. Público

Skills atribuídas a um parceiro.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<BriefApp.Partners.Queries.PartnerSkillDto>`

Status possíveis

200 OK

POST /api/skills/partners/{partnerId} Atribui uma skill do catálogo ao parceiro (o próprio parceiro ou Admin). Parceiro Dono

Atribui uma skill do catálogo ao parceiro (o próprio parceiro ou Admin).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `AssignSkillRequest`

Campo	Tipo	Obrigatório	Descrição
`skillId`	uuid	sim

Status possíveis

400 Dados inválidos
409 Conflito de estado

DELETE /api/skills/partners/{partnerId}/{skillId} Remove uma skill do parceiro (o próprio parceiro ou Admin). Parceiro Dono

Remove uma skill do parceiro (o próprio parceiro ou Admin).

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid
`skillId`	rota	uuid

Status possíveis

204 Sem conteúdo
404 Não encontrado

Módulo

Parceiros e prestadores

Perfil profissional, dados bancários, serviços, galeria, espaços físicos e busca por proximidade.

Parceiros são os prestadores do seu marketplace: profissionais, lojas, estúdios. Qualquer usuário logado pode abrir um perfil de parceiro (onboarding) com especialidade, endereço, dados bancários e chave PIX para receber repasses. O parceiro cadastra os serviços que oferece, monta uma galeria de portfólio e registra os espaços físicos onde atende. O diretório permite buscar parceiros ativos, inclusive por distância.

Conceitos

Perfil do parceiro: Dados profissionais, endereço com latitude e longitude, banco e chave PIX.
Aceite automático: Quando ligado, novas reservas entram confirmadas sem o parceiro aprovar uma a uma.
Serviço: Item do cardápio do parceiro, com nome, preço e duração.
Galeria: Fotos e destaques do portfólio, com legenda e ordem.
Espaço: Local físico de atendimento (salão, sala), com endereço e fotos.

Fluxo típico

O usuário cria o perfil com POST /api/partner/profile.
Completa endereço e dados bancários com PUT /api/partner/profile/{id}.
Um Admin ativa o parceiro (PATCH …/status) e concede o papel Parceiro.
O parceiro cadastra serviços, galeria e espaços; o app mostra tudo no perfil público.
Clientes encontram parceiros pelo diretório (GET /api/partner/profiles), com busca por proximidade.

Exemplo: Buscar parceiros num raio de 5 km

Requisição

GET /api/partner/profiles?lat=-23.5614&lon=-46.6559&radiusKm=5

Resposta

200 OK
{ "items": [ { "id": "…", "nome": "Ana Souza", "specialty": "Cabeleireira", "rating": 4.9,
    "reviewCount": 128, "autoAccept": true, "city": "São Paulo", "state": "SP", "isActive": true, "distanceKm": 1.2 } ],
  "page": 1, "pageSize": 20, "total": 7 }

Regras importantes

O diretório mostra só parceiros ativos e só campos públicos, a menos que um Admin peça os inativos.
Um serviço com agendamentos ativos não pode ser apagado (409).
Dados bancários e documentos só são visíveis ao próprio parceiro e ao Admin.

Referência de endpoints

Endpoints for partner professional profile management, including address, KYC documents, payout/banking settings, and automatic booking acceptance toggling.

POST /api/partner/profile Cria o perfil de parceiro do usuário logado (onboarding). Um Admin pode criar em nome de outro usuário. Autenticado Dono

Cria o perfil de parceiro do usuário logado (onboarding). Um Admin pode criar em nome de outro usuário.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreatePartnerRequest`

Campo	Tipo	Obrigatório
`nome`	string	sim
`specialty`	string	sim
`professionalId`	uuid	não

Status possíveis

400 Dados inválidos
409 Conflito de estado

PATCH /api/partner/profile/{partnerId}/status Ativa ou desativa um parceiro (Admin). Admin

Ativa ou desativa um parceiro (Admin).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `SetPartnerStatusRequest`

Campo	Tipo	Obrigatório	Descrição
`isActive`	boolean	sim

Status possíveis

404 Não encontrado

GET /api/partner/profile/{partnerId} Perfil completo do parceiro, com endereço e dados bancários. Autenticado Dono

Perfil completo do parceiro, com endereço e dados bancários.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Status possíveis

404 Não encontrado

PUT /api/partner/profile/{partnerId} Atualiza dados pessoais, endereço e dados bancários e PIX do parceiro. Autenticado Dono

Atualiza dados pessoais, endereço e dados bancários e PIX do parceiro.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `UpdatePartnerProfileRequest`

Campo	Tipo	Obrigatório
`cpf`	string	não
`birthDate`	datetime	não
`phone`	string	não
`instagramUrl`	string	não
`bio`	string	não
`workingHours`	string	não
`zipCode`	string	não
`street`	string	não
`number`	string	não
`complement`	string	não
`neighborhood`	string	não
`city`	string	não
`state`	string	não
`lat`	number	não
`lon`	number	não
`bankName`	string	não
`bankBranch`	string	não
`bankAccount`	string	não
`bankAccountType`	string	não
`pixKeyType`	string	não
`pixKey`	string	não

Status possíveis

400 Dados inválidos
404 Não encontrado

PATCH /api/partner/profile/{partnerId}/auto-accept Liga ou desliga o aceite automático de novas reservas. Autenticado Dono

Liga ou desliga o aceite automático de novas reservas.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Corpo (JSON) · `SetAutoAcceptRequest`

Campo	Tipo	Obrigatório	Descrição
`autoAccept`	boolean	sim

Status possíveis

404 Não encontrado

Vitrine de parceiros: listagem pública (para usuários logados) só com campos não sensíveis.

GET /api/partner/profiles Lista parceiros. Mostra só ativos e campos públicos, a menos que um Admin peça includeInactive=true. Busca por proximidade com lat, lon e raio. Autenticado

Lista parceiros. Mostra só ativos e campos públicos, a menos que um Admin peça includeInactive=true. Busca por proximidade com lat, lon e raio.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`search`	query	string
`specialty`	query	string
`city`	query	string
`state`	query	string
`lat`	query	number
`lon`	query	number
`radiusKm`	query	number
`includeInactive`	query	boolean
`page`	query	integer
`pageSize`	query	integer

Resposta · `PartnerPageDto`

Campo	Tipo	Descrição
`items`	PartnerSummaryDto[]
`page`	integer
`pageSize`	integer
`total`	integer

Status possíveis

200 OK
400 Dados inválidos

Endpoints for managing customized services offered by partners.

GET /api/partner/services/{partnerId} Lista os serviços de um parceiro. Público. Público

Lista os serviços de um parceiro. Público.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<BriefApp.Partners.Queries.PartnerServiceDto>`

Status possíveis

200 OK

POST /api/partner/services Cadastra um serviço do parceiro com nome, descrição, preço e duração. Parceiro Dono

Cadastra um serviço do parceiro com nome, descrição, preço e duração.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreatePartnerServiceRequest`

Campo	Tipo	Obrigatório	Descrição
`partnerId`	uuid	sim
`nome`	string	sim
`description`	string	não
`price`	decimal	sim
`duration`	string	não	Padrão: "60 min".

Status possíveis

400 Dados inválidos
409 Conflito de estado

PUT /api/partner/services/{serviceId} Atualiza nome, descrição, preço ou duração de um serviço. Parceiro Dono

Atualiza nome, descrição, preço ou duração de um serviço.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`serviceId`	rota	uuid

Corpo (JSON) · `UpdatePartnerServiceRequest`

Campo	Tipo	Obrigatório
`nome`	string	não
`description`	string	não
`price`	decimal	não
`duration`	string	não

Status possíveis

404 Não encontrado

DELETE /api/partner/services/{serviceId} Remove um serviço. Falha com 409 se houver agendamentos ativos para ele. Parceiro Dono

Remove um serviço. Falha com 409 se houver agendamentos ativos para ele.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`serviceId`	rota	uuid

Status possíveis

204 Sem conteúdo
404 Não encontrado
409 Conflito de estado

Endpoints for managing partner portfolio gallery media items (photos and showcases).

GET /api/partner/gallery/{partnerId} Lista a galeria de portfólio de um parceiro. Público. Público

Lista a galeria de portfólio de um parceiro. Público.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<BriefApp.Partners.Queries.GalleryImageDto>`

Status possíveis

200 OK

POST /api/partner/gallery Adiciona uma foto ou destaque à galeria do parceiro. Parceiro Dono

Adiciona uma foto ou destaque à galeria do parceiro.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `AddGalleryItemRequest`

Campo	Tipo	Obrigatório	Descrição
`partnerId`	uuid	sim
`url`	string	sim
`type`	string	não	Padrão: "photo".
`caption`	string	não
`order`	integer	não	Padrão: 0.

Status possíveis

400 Dados inválidos

PUT /api/partner/gallery/{itemId} Atualiza legenda, tipo, URL ou ordem de um item da galeria. Parceiro Dono

Atualiza legenda, tipo, URL ou ordem de um item da galeria.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`itemId`	rota	uuid

Corpo (JSON) · `UpdateGalleryItemRequest`

Campo	Tipo	Obrigatório
`url`	string	não
`type`	string	não
`caption`	string	não
`order`	integer	não

Status possíveis

404 Não encontrado

DELETE /api/partner/gallery/{itemId} Remove um item da galeria. Parceiro Dono

Remove um item da galeria.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`itemId`	rota	uuid

Status possíveis

204 Sem conteúdo
404 Não encontrado

Endpoints for managing provider workspaces and physical salon locations.

GET /api/spaces/partner/{partnerId} Lista os espaços físicos de um parceiro. Público. Público

Lista os espaços físicos de um parceiro. Público.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`partnerId`	rota	uuid

Resposta · `IReadOnlyList<BriefApp.Partners.Queries.SpaceDto>`

Status possíveis

200 OK

POST /api/spaces Cadastra um espaço físico de atendimento, com endereço, descrição e fotos. Parceiro Dono

Cadastra um espaço físico de atendimento, com endereço, descrição e fotos.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `CreateSpaceRequest`

Campo	Tipo	Obrigatório	Descrição
`partnerId`	uuid	sim
`nome`	string	sim
`address`	string	sim
`about`	string	não	Padrão: "".
`photos`	string[]	não
`isActive`	boolean	não	Padrão: false.

Status possíveis

400 Dados inválidos

PUT /api/spaces/{spaceId} Atualiza dados, endereço ou fotos de um espaço. Parceiro Dono

Atualiza dados, endereço ou fotos de um espaço.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`spaceId`	rota	uuid

Corpo (JSON) · `UpdateSpaceRequest`

Campo	Tipo	Obrigatório
`nome`	string	não
`address`	string	não
`about`	string	não
`photos`	string[]	não
`isActive`	boolean	não

Status possíveis

404 Não encontrado

PATCH /api/spaces/{spaceId}/toggle-active Ativa ou desativa um espaço. Parceiro Dono

Ativa ou desativa um espaço.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`spaceId`	rota	uuid
`isActive`	query	boolean

Status possíveis

404 Não encontrado

DELETE /api/spaces/{spaceId} Remove um espaço. Parceiro Dono

Remove um espaço.

Permissão: Exige Admin ou Parceiro (ou escopo partners). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`spaceId`	rota	uuid

Status possíveis

204 Sem conteúdo
404 Não encontrado

Módulo

Mobilidade e entregas

Corridas e entregas: motoristas, preço por região, matching, despacho, rastreio e back-office.

O módulo de mobilidade opera dois produtos com o mesmo motor. Corridas: o cliente estima o preço, pede a corrida e acompanha o motorista; o motorista aceita, informa a chegada, inicia e conclui. Entregas: um pedido de outro sistema (restaurante, farmácia, loja, o seu catálogo) pede a logística, que fica ligada ao pedido de origem pelo par (tipo, id). Motoristas se cadastram com documentos e veículo e só operam depois da aprovação. O preço vem de categorias (tarifa base, preço por km e por minuto) e de regras por região.

Conceitos

Categoria: Tipo de serviço (ex.: Moto, Carro Econômico): veículo, tarifa base, preço por km e minuto, máximo de passageiros.
Regra de preço: Ajuste por região: distância mínima, tarifa mínima, preço por km, taxa da plataforma e imposto municipal.
Motorista: Perfil com CNH, veículo, documentos e chave PIX. Precisa ser aprovado e receber o papel Motorista.
Corrida: Viagem pedida por um cliente, com origem, destino, categoria e forma de pagamento.
Entrega: Logística de um pedido externo: coleta, destino, destinatário e frete. Idempotente pelo par (tipo, id).
Reclamação: Problema aberto pelo cliente sobre uma corrida, tratado pelo Admin.

Estados possíveis

Corrida

ProcurandoMotorista
Aceita
MotoristaChegou
EmAndamento
Concluida

Entrega

AguardandoEntregador
Atribuida
Coletada
Entregue

Motorista

PendenteAprovacao
Ativo
Suspenso
Bloqueado

Fluxo típico

O Admin cria categorias e regras de preço por região.
O motorista se cadastra (POST /api/mobility/drivers/register); o Admin aprova e concede o papel Motorista.
O motorista fica online (PUT …/drivers/me/availability) e envia a posição pelo hub /hubs/mobility.
O cliente estima o preço (POST /api/mobility/pricing/estimate) e pede a corrida (POST /api/mobility/rides).
O motorista aceita, informa a chegada, inicia e conclui; o cliente acompanha em tempo real.
A cobrança do Payments é vinculada à corrida e, no fim, cliente e motorista se avaliam.

Exemplo: Pedir a entrega de um pedido do seu catálogo

Requisição

POST /api/mobility/delivery
{ "clienteId": "…", "referenciaTipo": "pedido-loja", "referenciaId": "…",
  "coleta": { "endereco": "Rua Augusta, 500", "latitude": -23.553, "longitude": -46.657 },
  "destino": { "endereco": "Av. Paulista, 1000", "latitude": -23.565, "longitude": -46.652 },
  "destinatarioNome": "Júlia", "tipoVeiculoExigido": "Moto", "valorFrete": 12.90 }

Resposta

201 Created
{ "id": "…", "status": "AguardandoEntregador", "referenciaTipo": "pedido-loja", "referenciaId": "…",
  "distanciaKm": 1.6, "valorFrete": 12.90, "entregadorId": null, "solicitadaEm": "2026-10-15T13:02:11Z", … }

Regras importantes

Sem motorista por perto, a corrida volta com status SemMotorista.
Corrida em andamento não pode ser cancelada; antes disso, cliente ou motorista podem cancelar.
Pedir a mesma entrega duas vezes (mesmo tipo e id) devolve a entrega existente.
Um Parceiro pode pedir entregas em nome de um cliente e fica registrado como emissor.
A posição do motorista a cada ~5 s deve ir pelo hub; o PATCH de localização é a alternativa.

Referência de endpoints

Consultas públicas (sem login) para a tela de pedir corrida: categorias e estimativa de preço.

GET /api/mobility/pricing/categories Categorias de corrida ativas. Público

Categorias de corrida ativas.

Permissão: Não exige token.

Resposta · `IReadOnlyList<CategoriaDto>`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`iconeUrl`	string
`tipoVeiculo`	string
`tarifaBase`	decimal
`precoKm`	decimal
`precoMinuto`	decimal
`maxPassageiros`	integer
`ordem`	integer
`ativa`	boolean

Status possíveis

200 OK

POST /api/mobility/pricing/estimate Distância, tempo e tarifa estimada de cada categoria para o trajeto. Público

Distância, tempo e tarifa estimada de cada categoria para o trajeto.

Permissão: Não exige token.

Corpo (JSON) · `EstimateRideRequest`

Campo	Tipo	Obrigatório
`origemLat`	number	sim
`origemLng`	number	sim
`destinoLat`	number	sim
`destinoLng`	number	sim
`origemEndereco`	string	não

Resposta · `EstimativaViagemDto`

Campo	Tipo	Descrição
`distanciaKm`	number
`duracaoMinutos`	integer
`categorias`	EstimativaCategoriaDto[]

Status possíveis

200 OK

Corridas: o cliente pede e acompanha; o motorista aceita e conduz.

GET /api/mobility/rides/nearby-drivers Motoristas disponíveis por perto (só posição e distância — sem identificação). Autenticado

Motoristas disponíveis por perto (só posição e distância — sem identificação).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`lat`	query	number
`lng`	query	number
`type`	query	TipoVeiculo

Resposta · `IReadOnlyList<MotoristaProximoDto>`

Campo	Tipo	Descrição
`motoristaId`	uuid
`latitude`	number
`longitude`	number
`distanciaKm`	number
`veiculoTipo`	string
`avaliacaoMedia`	decimal

Status possíveis

200 OK

POST /api/mobility/rides Pede uma corrida. Sem motorista por perto, a corrida volta com status SemMotorista. Autenticado

Pede uma corrida. Sem motorista por perto, a corrida volta com status SemMotorista.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `RequestRideRequest`

Campo	Tipo	Obrigatório
`categoriaId`	uuid	sim
`origem`	LocalDto	sim
`destino`	LocalDto	sim
`metodoPagamento`	string	não
`agendamentoId`	uuid	não
`clienteTelefone`	string	não

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

201 Criado
409 Conflito de estado

GET /api/mobility/rides/{id} Detalhe de uma corrida (cliente, motorista ou equipe da plataforma). Autenticado

Detalhe de uma corrida (cliente, motorista ou equipe da plataforma).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK

GET /api/mobility/rides/active Corrida em curso do usuário (como cliente ou motorista). 204 quando não há. Autenticado

Corrida em curso do usuário (como cliente ou motorista). 204 quando não há.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK
204 Sem conteúdo

GET /api/mobility/rides/history Histórico de corridas do usuário, paginado. Autenticado

Histórico de corridas do usuário, paginado.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`page`	query	integer
`pageSize`	query	integer

Resposta · `ViagemPaginaDto`

Campo	Tipo	Descrição
`itens`	ViagemDto[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK

POST /api/mobility/rides/{id}/cancelar Cancela (cliente ou motorista da corrida). Corrida em andamento não pode ser cancelada. Autenticado

Cancela (cliente ou motorista da corrida). Corrida em andamento não pode ser cancelada.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `CancelRideRequest`

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	não

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK

POST /api/mobility/rides/{id}/cobranca Vincula a cobrança (Payments) à corrida. Só o cliente da corrida (ou um administrador). Autenticado

Vincula a cobrança (Payments) à corrida. Só o cliente da corrida (ou um administrador).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `LinkChargeRequest`

Campo	Tipo	Obrigatório	Descrição
`cobrancaId`	uuid	sim
`metodoPagamento`	string	sim

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK

POST /api/mobility/rides/{id}/avaliar Avalia a corrida: o cliente avalia o motorista; o motorista avalia o cliente. Autenticado

Avalia a corrida: o cliente avalia o motorista; o motorista avalia o cliente.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `RateRequest`

Campo	Tipo	Obrigatório	Descrição
`nota`	integer	sim
`comentario`	string	não

Status possíveis

204 Sem conteúdo

GET /api/mobility/rides/{id}/messages Mensagens trocadas entre cliente e motorista na corrida. Autenticado

Mensagens trocadas entre cliente e motorista na corrida.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `IReadOnlyList<MensagemDto>`

Campo	Tipo	Descrição
`id`	uuid
`viagemId`	uuid
`remetenteId`	uuid
`conteudo`	string
`enviadaEm`	datetime

Status possíveis

200 OK

POST /api/mobility/rides/{id}/messages Envia uma mensagem no chat da corrida. Autenticado

Envia uma mensagem no chat da corrida.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `SendMessageRequest`

Campo	Tipo	Obrigatório	Descrição
`conteudo`	string	sim

Resposta · `MensagemDto`

Campo	Tipo	Descrição
`id`	uuid
`viagemId`	uuid
`remetenteId`	uuid
`conteudo`	string
`enviadaEm`	datetime

Status possíveis

200 OK

POST /api/mobility/rides/{id}/reclamacoes Abre uma reclamação sobre a corrida, com categoria e descrição. Autenticado

Abre uma reclamação sobre a corrida, com categoria e descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `OpenComplaintRequest`

Campo	Tipo	Obrigatório	Descrição
`categoria`	string	sim
`descricao`	string	sim

Resposta · `ReclamacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`viagemId`	uuid
`autorId`	uuid
`categoria`	string
`descricao`	string
`status`	string
`respostaAdmin`	string
`criadaEm`	datetime
`resolvidaEm`	datetime

Status possíveis

200 OK

POST /api/mobility/rides/{id}/aceitar O motorista aceita a corrida. 409 se outro já aceitou ou se ele está em outra corrida. Motorista

O motorista aceita a corrida. 409 se outro já aceitou ou se ele está em outra corrida.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK
409 Conflito de estado

POST /api/mobility/rides/{id}/recusar O motorista recusa a corrida oferecida. Motorista

O motorista recusa a corrida oferecida.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Status possíveis

204 Sem conteúdo

POST /api/mobility/rides/{id}/chegou O motorista informa que chegou ao ponto de embarque. Motorista

O motorista informa que chegou ao ponto de embarque.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK

POST /api/mobility/rides/{id}/iniciar O motorista inicia a viagem com o passageiro a bordo. Motorista

O motorista inicia a viagem com o passageiro a bordo.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK

POST /api/mobility/rides/{id}/concluir O motorista conclui a corrida no destino. Motorista

O motorista conclui a corrida no destino.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `ViagemDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`clienteId`	uuid
`clienteNome`	string
`clienteTelefone`	string
`motorista`	MotoristaResumoDto
`categoriaId`	uuid
`categoriaNome`	string
`origem`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`duracaoEstimadaMinutos`	integer
`polyline`	string
`tarifaEstimada`	decimal
`tarifaFinal`	decimal
`taxaPlataforma`	decimal
`ganhoMotorista`	decimal
`metodoPagamento`	string
`cobrancaId`	uuid
`agendamentoId`	uuid
`solicitadaEm`	datetime
`aceitaEm`	datetime
`iniciadaEm`	datetime
`concluidaEm`	datetime
`canceladaEm`	datetime
`motivoCancelamento`	string
`notaDoCliente`	integer
`notaDoMotorista`	integer

Status possíveis

200 OK

Entregas de pedidos de outros sistemas (restaurante, farmácia, loja, catálogo). O pedido continua no sistema de origem; aqui vive só a logística, ligada por (tipo, id) do pedido.

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 Dono

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.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Corpo (JSON) · `RequestDeliveryRequest`

Campo	Tipo	Obrigatório
`clienteId`	uuid	sim
`referenciaTipo`	string	sim
`referenciaId`	uuid	sim
`coleta`	LocalDto	sim
`destino`	LocalDto	sim
`parceiroId`	uuid	não
`descricao`	string	não
`destinatarioNome`	string	não
`destinatarioTelefone`	string	não
`tipoVeiculoExigido`	TipoVeiculo	não
`valorFrete`	decimal	não

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

201 Criado
403 Sem permissão

GET /api/mobility/delivery/{id} Detalhe de uma entrega (cliente, emissor, entregador ou Admin). Autenticado

Detalhe de uma entrega (cliente, emissor, entregador ou Admin).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK

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

Quem acompanha a logística do pedido: cliente, emissor, ou (sincronização entre sistemas) Admin/Financeiro/Suporte.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`tipo`	rota	string
`referenciaId`	rota	uuid

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK

GET /api/mobility/delivery/mine Entregas do usuário (como cliente ou parceiro emissor). Autenticado

Entregas do usuário (como cliente ou parceiro emissor).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`page`	query	integer
`pageSize`	query	integer

Resposta · `EntregaPaginaDto`

Campo	Tipo	Descrição
`itens`	EntregaDto[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK

POST /api/mobility/delivery/{id}/cancelar Cancela a entrega, com motivo opcional. Autenticado

Cancela a entrega, com motivo opcional.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `CancelRideRequest`

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	não

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK

POST /api/mobility/delivery/{id}/avaliar Avalia a entrega com nota e comentário. Autenticado

Avalia a entrega com nota e comentário.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `RateRequest`

Campo	Tipo	Obrigatório	Descrição
`nota`	integer	sim
`comentario`	string	não

Status possíveis

204 Sem conteúdo

GET /api/mobility/delivery/available Entregas aguardando entregador, compatíveis com o veículo, das mais próximas às mais distantes. Motorista

Entregas aguardando entregador, compatíveis com o veículo, das mais próximas às mais distantes.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`lat`	query	number
`lng`	query	number

Resposta · `IReadOnlyList<EntregaDisponivelDto>`

Campo	Tipo	Descrição
`id`	uuid
`referenciaTipo`	string
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEstimado`	decimal
`solicitadaEm`	datetime

Status possíveis

200 OK

POST /api/mobility/delivery/{id}/aceitar O entregador aceita a entrega. 409 se outro já aceitou ou se ele já está ocupado. Motorista

O entregador aceita a entrega. 409 se outro já aceitou ou se ele já está ocupado.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK
409 Conflito de estado

POST /api/mobility/delivery/{id}/coletar O entregador confirma a coleta no ponto de origem. Motorista

O entregador confirma a coleta no ponto de origem.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK

POST /api/mobility/delivery/{id}/concluir O entregador conclui a entrega, com URL opcional do comprovante (foto ou assinatura). Motorista

O entregador conclui a entrega, com URL opcional do comprovante (foto ou assinatura).

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `CompleteDeliveryRequest`

Campo	Tipo	Obrigatório	Descrição
`comprovanteUrl`	string	não

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK

POST /api/mobility/delivery/{id}/falha O entregador registra que não conseguiu entregar, com o motivo. Motorista

O entregador registra que não conseguiu entregar, com o motivo.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `FailDeliveryRequest`

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	sim

Resposta · `EntregaDto`

Campo	Tipo	Descrição
`id`	uuid
`status`	string
`referenciaTipo`	string
`referenciaId`	uuid
`parceiroId`	uuid
`clienteId`	uuid
`coleta`	LocalDto
`destino`	LocalDto
`distanciaKm`	number
`descricao`	string
`destinatarioNome`	string
`destinatarioTelefone`	string
`tipoVeiculoExigido`	string
`valorFrete`	decimal
`ganhoEntregador`	decimal
`taxaPlataforma`	decimal
`entregadorId`	uuid
`entregador`	MotoristaResumoDto
`solicitadaEm`	datetime
`atribuidaEm`	datetime
`coletadaEm`	datetime
`entregueEm`	datetime
`canceladaEm`	datetime
`comprovanteUrl`	string
`motivoFalhaOuCancelamento`	string
`notaDoCliente`	integer

Status possíveis

200 OK

Perfil operacional do motorista/entregador. Qualquer usuário logado pode se cadastrar e acompanhar a análise; depois que um Admin aprova o cadastro, o Admin também concede o papel Motorista no Identity, que libera ficar online, enviar posição e ver ganhos.

POST /api/mobility/drivers/register Cadastra documentos e veículo. O motorista só opera depois que um admin aprova. Autenticado

Cadastra documentos e veículo. O motorista só opera depois que um admin aprova.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `RegisterDriverRequest`

Campo	Tipo	Obrigatório
`nome`	string	sim
`cpf`	string	sim
`cnh`	string	sim
`categoriaCnh`	string	sim
`veiculo`	VeiculoInput	sim
`telefone`	string	não
`validadeCnh`	date	não
`documentoCnhUrl`	string	não
`documentoVeiculoUrl`	string	não
`selfieUrl`	string	não
`chavePix`	string	não
`tipoChavePix`	string	não
`fotoUrl`	string	não

Resposta · `MotoristaDto`

Campo	Tipo	Descrição
`id`	uuid
`usuarioId`	uuid
`nome`	string
`cpf`	string
`telefone`	string
`fotoUrl`	string
`cnh`	string
`categoriaCnh`	string
`validadeCnh`	date
`veiculoTipo`	string
`veiculoMarca`	string
`veiculoModelo`	string
`veiculoCor`	string
`veiculoAno`	integer
`placa`	string
`documentoCnhUrl`	string
`documentoVeiculoUrl`	string
`selfieUrl`	string
`chavePix`	string
`tipoChavePix`	string
`status`	string
`motivoStatus`	string
`avaliacaoMedia`	decimal
`totalAvaliacoes`	integer
`totalViagens`	integer
`totalEntregas`	integer
`online`	boolean
`ocupado`	boolean
`criadoEm`	datetime
`latitude`	number
`longitude`	number
`posicaoEm`	datetime

Status possíveis

201 Criado
409 Conflito de estado

GET /api/mobility/drivers/me Perfil de motorista do usuário logado e a situação da análise. Autenticado

Perfil de motorista do usuário logado e a situação da análise.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `MotoristaDto`

Campo	Tipo	Descrição
`id`	uuid
`usuarioId`	uuid
`nome`	string
`cpf`	string
`telefone`	string
`fotoUrl`	string
`cnh`	string
`categoriaCnh`	string
`validadeCnh`	date
`veiculoTipo`	string
`veiculoMarca`	string
`veiculoModelo`	string
`veiculoCor`	string
`veiculoAno`	integer
`placa`	string
`documentoCnhUrl`	string
`documentoVeiculoUrl`	string
`selfieUrl`	string
`chavePix`	string
`tipoChavePix`	string
`status`	string
`motivoStatus`	string
`avaliacaoMedia`	decimal
`totalAvaliacoes`	integer
`totalViagens`	integer
`totalEntregas`	integer
`online`	boolean
`ocupado`	boolean
`criadoEm`	datetime
`latitude`	number
`longitude`	number
`posicaoEm`	datetime

Status possíveis

200 OK

PUT /api/mobility/drivers/me Atualiza dados, CNH, veículo, documentos e chave PIX do motorista. Autenticado

Atualiza dados, CNH, veículo, documentos e chave PIX do motorista.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `UpdateDriverRequest`

Campo	Tipo	Obrigatório
`nome`	string	sim
`cnh`	string	sim
`categoriaCnh`	string	sim
`veiculo`	VeiculoInput	sim
`telefone`	string	não
`validadeCnh`	date	não
`chavePix`	string	não
`tipoChavePix`	string	não
`fotoUrl`	string	não
`documentoCnhUrl`	string	não
`documentoVeiculoUrl`	string	não
`selfieUrl`	string	não

Resposta · `MotoristaDto`

Campo	Tipo	Descrição
`id`	uuid
`usuarioId`	uuid
`nome`	string
`cpf`	string
`telefone`	string
`fotoUrl`	string
`cnh`	string
`categoriaCnh`	string
`validadeCnh`	date
`veiculoTipo`	string
`veiculoMarca`	string
`veiculoModelo`	string
`veiculoCor`	string
`veiculoAno`	integer
`placa`	string
`documentoCnhUrl`	string
`documentoVeiculoUrl`	string
`selfieUrl`	string
`chavePix`	string
`tipoChavePix`	string
`status`	string
`motivoStatus`	string
`avaliacaoMedia`	decimal
`totalAvaliacoes`	integer
`totalViagens`	integer
`totalEntregas`	integer
`online`	boolean
`ocupado`	boolean
`criadoEm`	datetime
`latitude`	number
`longitude`	number
`posicaoEm`	datetime

Status possíveis

200 OK

PUT /api/mobility/drivers/me/availability Fica online/offline. Ao ficar online sem posição gravada, informe latitude e longitude. Motorista

Fica online/offline. Ao ficar online sem posição gravada, informe latitude e longitude.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Corpo (JSON) · `SetAvailabilityRequest`

Campo	Tipo	Obrigatório
`online`	boolean	sim
`latitude`	number	não
`longitude`	number	não

Resposta · `MotoristaDto`

Campo	Tipo	Descrição
`id`	uuid
`usuarioId`	uuid
`nome`	string
`cpf`	string
`telefone`	string
`fotoUrl`	string
`cnh`	string
`categoriaCnh`	string
`validadeCnh`	date
`veiculoTipo`	string
`veiculoMarca`	string
`veiculoModelo`	string
`veiculoCor`	string
`veiculoAno`	integer
`placa`	string
`documentoCnhUrl`	string
`documentoVeiculoUrl`	string
`selfieUrl`	string
`chavePix`	string
`tipoChavePix`	string
`status`	string
`motivoStatus`	string
`avaliacaoMedia`	decimal
`totalAvaliacoes`	integer
`totalViagens`	integer
`totalEntregas`	integer
`online`	boolean
`ocupado`	boolean
`criadoEm`	datetime
`latitude`	number
`longitude`	number
`posicaoEm`	datetime

Status possíveis

200 OK

PATCH /api/mobility/drivers/me/location Atualiza a posição (a cada ~5 s). Prefira o hub /hubs/mobility (AtualizarLocalizacao). Motorista

Atualiza a posição (a cada ~5 s). Prefira o hub /hubs/mobility (AtualizarLocalizacao).

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Corpo (JSON) · `UpdateLocationRequest`

Campo	Tipo	Obrigatório	Descrição
`latitude`	number	sim
`longitude`	number	sim

Status possíveis

204 Sem conteúdo

GET /api/mobility/drivers/me/earnings Ganhos do motorista. Motorista

Ganhos do motorista.

Permissão: Exige Admin ou Motorista (ou escopo mobility).

Resposta · `GanhosDto`

Campo	Tipo	Descrição
`hoje`	decimal
`semana`	decimal
`mes`	decimal
`total`	decimal
`viagensHoje`	integer
`viagensMes`	integer
`entregasMes`	integer
`viagensSemana`	integer
`viagensTotal`	integer

Status possíveis

200 OK

Back-office do Mobility: aprovação de motoristas, tabela de preços, operação e reclamações.

GET /api/mobility/admin/drivers Lista motoristas com filtro por status e busca, paginado. Admin

Lista motoristas com filtro por status e busca, paginado.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo
`status`	query	StatusMotorista
`search`	query	string
`page`	query	integer
`pageSize`	query	integer

Resposta · `MotoristaPaginaDto`

Campo	Tipo	Descrição
`itens`	MotoristaDto[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK

GET /api/mobility/admin/drivers/{id} Detalhe completo de um motorista, com documentos e veículo. Admin

Detalhe completo de um motorista, com documentos e veículo.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `MotoristaDto`

Campo	Tipo	Descrição
`id`	uuid
`usuarioId`	uuid
`nome`	string
`cpf`	string
`telefone`	string
`fotoUrl`	string
`cnh`	string
`categoriaCnh`	string
`validadeCnh`	date
`veiculoTipo`	string
`veiculoMarca`	string
`veiculoModelo`	string
`veiculoCor`	string
`veiculoAno`	integer
`placa`	string
`documentoCnhUrl`	string
`documentoVeiculoUrl`	string
`selfieUrl`	string
`chavePix`	string
`tipoChavePix`	string
`status`	string
`motivoStatus`	string
`avaliacaoMedia`	decimal
`totalAvaliacoes`	integer
`totalViagens`	integer
`totalEntregas`	integer
`online`	boolean
`ocupado`	boolean
`criadoEm`	datetime
`latitude`	number
`longitude`	number
`posicaoEm`	datetime

Status possíveis

200 OK

PATCH /api/mobility/admin/drivers/{id}/decision Aprova/rejeita cadastros pendentes e ativa/suspende/bloqueia quem já foi aprovado. Admin

Aprova/rejeita cadastros pendentes e ativa/suspende/bloqueia quem já foi aprovado.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `DriverDecisionRequest`

Campo	Tipo	Obrigatório	Descrição
`decisao`	DecisaoMotorista	sim
`motivo`	string	não

Resposta · `MotoristaDto`

Campo	Tipo	Descrição
`id`	uuid
`usuarioId`	uuid
`nome`	string
`cpf`	string
`telefone`	string
`fotoUrl`	string
`cnh`	string
`categoriaCnh`	string
`validadeCnh`	date
`veiculoTipo`	string
`veiculoMarca`	string
`veiculoModelo`	string
`veiculoCor`	string
`veiculoAno`	integer
`placa`	string
`documentoCnhUrl`	string
`documentoVeiculoUrl`	string
`selfieUrl`	string
`chavePix`	string
`tipoChavePix`	string
`status`	string
`motivoStatus`	string
`avaliacaoMedia`	decimal
`totalAvaliacoes`	integer
`totalViagens`	integer
`totalEntregas`	integer
`online`	boolean
`ocupado`	boolean
`criadoEm`	datetime
`latitude`	number
`longitude`	number
`posicaoEm`	datetime

Status possíveis

200 OK

GET /api/mobility/admin/categories Lista todas as categorias de serviço, inclusive as inativas. Admin

Lista todas as categorias de serviço, inclusive as inativas.

Permissão: Exige o papel Admin (ou escopo admin).

Resposta · `IReadOnlyList<CategoriaDto>`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`iconeUrl`	string
`tipoVeiculo`	string
`tarifaBase`	decimal
`precoKm`	decimal
`precoMinuto`	decimal
`maxPassageiros`	integer
`ordem`	integer
`ativa`	boolean

Status possíveis

200 OK

POST /api/mobility/admin/categories Cria uma categoria: veículo, tarifa base, preço por km e por minuto, máximo de passageiros. Admin

Cria uma categoria: veículo, tarifa base, preço por km e por minuto, máximo de passageiros.

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `SaveCategoryRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`tipoVeiculo`	TipoVeiculo	sim
`tarifaBase`	decimal	sim
`precoKm`	decimal	sim
`precoMinuto`	decimal	sim
`maxPassageiros`	integer	sim
`descricao`	string	não
`iconeUrl`	string	não
`ordem`	integer	não	Padrão: 0.
`ativa`	boolean	não	Padrão: true.

Resposta · `CategoriaDto`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`iconeUrl`	string
`tipoVeiculo`	string
`tarifaBase`	decimal
`precoKm`	decimal
`precoMinuto`	decimal
`maxPassageiros`	integer
`ordem`	integer
`ativa`	boolean

Status possíveis

200 OK

PUT /api/mobility/admin/categories/{id} Atualiza uma categoria de serviço. Admin

Atualiza uma categoria de serviço.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `SaveCategoryRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`tipoVeiculo`	TipoVeiculo	sim
`tarifaBase`	decimal	sim
`precoKm`	decimal	sim
`precoMinuto`	decimal	sim
`maxPassageiros`	integer	sim
`descricao`	string	não
`iconeUrl`	string	não
`ordem`	integer	não	Padrão: 0.
`ativa`	boolean	não	Padrão: true.

Resposta · `CategoriaDto`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`descricao`	string
`iconeUrl`	string
`tipoVeiculo`	string
`tarifaBase`	decimal
`precoKm`	decimal
`precoMinuto`	decimal
`maxPassageiros`	integer
`ordem`	integer
`ativa`	boolean

Status possíveis

200 OK

GET /api/mobility/admin/price-rules Lista as regras de preço por região, opcionalmente de uma categoria. Admin

Lista as regras de preço por região, opcionalmente de uma categoria.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`categoryId`	query	uuid

Resposta · `IReadOnlyList<RegraPrecoDto>`

Campo	Tipo	Descrição
`id`	uuid
`categoriaId`	uuid
`regiao`	string
`distanciaMinimaKm`	number
`tarifaMinima`	decimal
`precoKm`	decimal
`percentualTaxaPlataforma`	decimal
`percentualImpostoMunicipal`	decimal
`ativa`	boolean

Status possíveis

200 OK

POST /api/mobility/admin/price-rules Cria uma regra de preço para uma região: distância e tarifa mínimas, preço por km, taxa da plataforma e imposto municipal. Admin

Cria uma regra de preço para uma região: distância e tarifa mínimas, preço por km, taxa da plataforma e imposto municipal.

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `SavePriceRuleRequest`

Campo	Tipo	Obrigatório	Descrição
`categoriaId`	uuid	sim
`regiao`	string	sim
`distanciaMinimaKm`	number	sim
`tarifaMinima`	decimal	sim
`precoKm`	decimal	sim
`percentualTaxaPlataforma`	decimal	sim
`percentualImpostoMunicipal`	decimal	sim
`ativa`	boolean	não	Padrão: true.

Resposta · `RegraPrecoDto`

Campo	Tipo	Descrição
`id`	uuid
`categoriaId`	uuid
`regiao`	string
`distanciaMinimaKm`	number
`tarifaMinima`	decimal
`precoKm`	decimal
`percentualTaxaPlataforma`	decimal
`percentualImpostoMunicipal`	decimal
`ativa`	boolean

Status possíveis

200 OK

PUT /api/mobility/admin/price-rules/{id} Atualiza uma regra de preço. Admin

Atualiza uma regra de preço.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `SavePriceRuleRequest`

Campo	Tipo	Obrigatório	Descrição
`categoriaId`	uuid	sim
`regiao`	string	sim
`distanciaMinimaKm`	number	sim
`tarifaMinima`	decimal	sim
`precoKm`	decimal	sim
`percentualTaxaPlataforma`	decimal	sim
`percentualImpostoMunicipal`	decimal	sim
`ativa`	boolean	não	Padrão: true.

Resposta · `RegraPrecoDto`

Campo	Tipo	Descrição
`id`	uuid
`categoriaId`	uuid
`regiao`	string
`distanciaMinimaKm`	number
`tarifaMinima`	decimal
`precoKm`	decimal
`percentualTaxaPlataforma`	decimal
`percentualImpostoMunicipal`	decimal
`ativa`	boolean

Status possíveis

200 OK

DELETE /api/mobility/admin/price-rules/{id} Remove uma regra de preço. Admin

Remove uma regra de preço.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Status possíveis

204 Sem conteúdo

GET /api/mobility/admin/rides Lista corridas para a operação, com filtros por status, cliente e motorista. Admin

Lista corridas para a operação, com filtros por status, cliente e motorista.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo
`status`	query	StatusViagem
`clientId`	query	uuid
`driverId`	query	uuid
`page`	query	integer
`pageSize`	query	integer

Resposta · `ViagemPaginaDto`

Campo	Tipo	Descrição
`itens`	ViagemDto[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK

GET /api/mobility/admin/deliveries Lista entregas para a operação, com filtro por status. Admin

Lista entregas para a operação, com filtro por status.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo
`status`	query	StatusEntrega
`page`	query	integer
`pageSize`	query	integer

Resposta · `EntregaPaginaDto`

Campo	Tipo	Descrição
`itens`	EntregaDto[]
`pagina`	integer
`tamanho`	integer
`total`	integer

Status possíveis

200 OK

GET /api/mobility/admin/metrics Indicadores da operação de mobilidade. Admin

Indicadores da operação de mobilidade.

Permissão: Exige o papel Admin (ou escopo admin).

Resposta · `MetricasDto`

Campo	Tipo	Descrição
`motoristasOnline`	integer
`viagensProcurando`	integer
`viagensEmAndamento`	integer
`viagensConcluidasHoje`	integer
`receitaHoje`	decimal
`taxaPlataformaHoje`	decimal
`viagensConcluidasMes`	integer
`receitaMes`	decimal
`taxaPlataformaMes`	decimal

Status possíveis

200 OK

GET /api/mobility/admin/complaints Lista reclamações, com filtro por status. Admin

Lista reclamações, com filtro por status.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo
`status`	query	StatusReclamacao
`page`	query	integer
`pageSize`	query	integer

Resposta · `IReadOnlyList<ReclamacaoDto>`

Campo	Tipo	Descrição
`id`	uuid
`viagemId`	uuid
`autorId`	uuid
`categoria`	string
`descricao`	string
`status`	string
`respostaAdmin`	string
`criadaEm`	datetime
`resolvidaEm`	datetime

Status possíveis

200 OK

PATCH /api/mobility/admin/complaints/{id} Trata uma reclamação: muda o status (EmAnalise, Resolvida, Descartada) e registra a resposta. Admin

Trata uma reclamação: muda o status (EmAnalise, Resolvida, Descartada) e registra a resposta.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `HandleComplaintRequest`

Campo	Tipo	Obrigatório	Descrição
`status`	StatusReclamacao	sim
`resposta`	string	não

Resposta · `ReclamacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`viagemId`	uuid
`autorId`	uuid
`categoria`	string
`descricao`	string
`status`	string
`respostaAdmin`	string
`criadaEm`	datetime
`resolvidaEm`	datetime

Status possíveis

200 OK

Módulo

Notificações e e-mail

Notificações no app, e-mail transacional e acompanhamento de entrega dos e-mails.

As notificações avisam o usuário dentro do app (reserva confirmada, corrida aceita, pagamento aprovado) e podem ser marcadas como lidas. O e-mail transacional envia confirmações, lembretes e recibos com HTML e texto, e os eventos de entrega (entregue, aberto, devolvido) voltam por webhook assinado.

Conceitos

Notificação: Aviso para um usuário, com status de lida ou não lida.
E-mail transacional: Mensagem disparada por um evento do sistema, com HTML, texto, cópias e uma tag para rastreio.

Fluxo típico

O app busca as notificações do usuário com GET /api/notifications/{userId}.
Ao abrir uma notificação, marca como lida com PATCH …/{id}/read.
O seu backend envia e-mails com POST /api/email/send usando uma conta de Suporte ou o escopo email.

Exemplo: Enviar um e-mail de confirmação

Requisição

POST /api/email/send
{ "to": ["julia@exemplo.com"], "subject": "Seu horário está confirmado",
  "htmlBody": "<p>Quinta, 15/10 às 11h com a Ana.</p>", "tag": "agendamento-confirmado" }

Resposta

200 OK
{ "success": true, "messageId": "…", "errorMessage": null, "provider": "Resend" }

Regras importantes

Enviar e-mail exige Admin, Suporte ou o escopo email: destinatários livres seriam um vetor de spam.
O webhook do provedor de e-mail valida a assinatura antes de processar qualquer evento.

Referência de endpoints

Endpoints for device registration and push notification token management.

GET /api/notifications/{userId} Lista as notificações de um usuário. Autenticado Dono

Lista as notificações de um usuário.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`userId`	rota	uuid
`unreadOnly`	query	boolean

Resposta · `IReadOnlyList<BriefApp.Partners.Queries.NotificationDto>`

Status possíveis

200 OK

PATCH /api/notifications/{notificationId}/read Marca uma notificação como lida. Autenticado Dono

Marca uma notificação como lida.

Permissão: Exige um token válido (usuário ou tenant). Também confere se quem chama é o dono do recurso (ou Admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`notificationId`	rota	uuid

Status possíveis

204 Sem conteúdo
404 Não encontrado

Envio de e-mail transacional (consumido por BriefApp.Sdk.IEmailApi). Restrito a Admin/Suporte: enviar para destinatários arbitrários é vetor de spam/phishing.

POST /api/email/send Envia um e-mail transacional com HTML e/ou texto, cópias, remetente opcional e uma tag para rastreio. Envio de e-mail

Envia um e-mail transacional com HTML e/ou texto, cópias, remetente opcional e uma tag para rastreio.

Permissão: Exige Admin ou Suporte (ou escopo email).

Corpo (JSON) · `SendEmailRequest`

Campo	Tipo	Obrigatório
`to`	string[]	sim
`subject`	string	sim
`htmlBody`	string	não
`textBody`	string	não
`from`	string	não
`cc`	string[]	não
`bcc`	string[]	não
`tag`	string	não
`provider`	string	não

Resposta · `SendEmailResponse`

Campo	Tipo	Descrição
`success`	boolean
`messageId`	string
`errorMessage`	string
`provider`	string

Status possíveis

200 OK
400 Dados inválidos
403 Sem permissão
502 Falha no provedor

Recebe webhooks do Resend (eventos de entrega de e-mail). Valida a assinatura HMAC-SHA256 via Svix antes de processar qualquer evento. Endpoint: POST /api/webhooks/email/resend Headers Svix obrigatórios: svix-id, svix-timestamp, svix-signature

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

Webhook do Resend. Valida assinatura via headers Svix (svix-id, svix-timestamp, svix-signature). Ref: https://resend.com/docs/dashboard/webhooks/introduction

Permissão: Não exige token.

Status possíveis

200 OK
400 Dados inválidos
401 Não autenticado

Módulo

Arquivos e imagens

Upload seguro, metadados, download e exclusão de fotos e documentos.

O módulo de arquivos guarda avatares, fotos de galeria, documentos de motoristas e comprovantes de entrega. O upload vai para o armazenamento configurado na plataforma, e cada arquivo ganha um id e uma URL estável para usar no app.

Conceitos

Arquivo: Conteúdo enviado com metadados: nome, tipo, tamanho e provedor de origem.
Exclusão lógica: Ao apagar, o registro é marcado como removido e o arquivo sai do armazenamento.

Fluxo típico

Envie o arquivo com POST /api/storage/upload (multipart/form-data, até 50 MB), opcionalmente ligando a uma entidade com entityType e entityId.
Guarde o id e use a publicUrl devolvida nas telas.
Remova com DELETE /api/storage/{id} quando não precisar mais.

Exemplo: Upload de uma foto

Requisição

POST /api/storage/upload
Content-Type: multipart/form-data

file=@corte.jpg
entityType=gallery
entityId=…

Resposta

201 Created
{ "id": "…", "originalName": "corte.jpg", "contentType": "image/jpeg", "sizeBytes": 284133,
  "storagePath": "…", "publicUrl": "https://…/corte.jpg", "createdAt": "2026-10-15T13:05:00Z" }

Regras importantes

O upload exige usuário autenticado; arquivos públicos podem ser lidos sem token.
Use a URL devolvida pela API em vez de montar caminhos à mão.

Referência de endpoints

Endpoints para upload seguro, consulta e streaming de arquivos/imagens (avatars, perfil, galeria). Integrado dinamicamente com HashiCorp Vault (S3, FileSystem, Firebase) via BriefApp.FileStorage.

POST /api/storage/upload Faz upload seguro de um arquivo (imagem, documento) para o storage configurado no Vault (S3, FileSystem ou Firebase). Autenticado

Faz upload seguro de um arquivo (imagem, documento) para o storage configurado no Vault (S3, FileSystem ou Firebase).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`file`	form	arquivo
`entityType`	form	string
`entityId`	form	uuid
`provider`	form	string

Resposta · `StoredFileResponse`

Campo	Tipo	Descrição
`id`	uuid
`originalName`	string
`contentType`	string
`sizeBytes`	integer
`storagePath`	string
`publicUrl`	string
`entityType`	string
`entityId`	uuid
`createdAt`	datetime
`provider`	string

Status possíveis

201 Criado
400 Dados inválidos
403 Sem permissão

GET /api/storage/{id} Retorna os metadados de um arquivo por ID. Público

Retorna os metadados de um arquivo por ID.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `StoredFileResponse`

Campo	Tipo	Descrição
`id`	uuid
`originalName`	string
`contentType`	string
`sizeBytes`	integer
`storagePath`	string
`publicUrl`	string
`entityType`	string
`entityId`	uuid
`createdAt`	datetime
`provider`	string

Status possíveis

200 OK
404 Não encontrado

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

Streaming direto e seguro de arquivos públicos com cabeçalhos de cache. Resolve automaticamente o provedor de origem gravado no banco de dados.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`storagePath`	query	string

Status possíveis

200 OK
404 Não encontrado

GET /api/storage/{id}/download Streaming de arquivo por ID com resolução garantida do provedor original. Público

Streaming de arquivo por ID com resolução garantida do provedor original.

Permissão: Não exige token.

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Status possíveis

200 OK
404 Não encontrado

DELETE /api/storage/{id} Exclusão lógica (soft delete) e remoção do arquivo do storage de origem. Autenticado

Exclusão lógica (soft delete) e remoção do arquivo do storage de origem.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Status possíveis

204 Sem conteúdo
404 Não encontrado

Módulo

Administração da plataforma

Tenants, chaves de API e provedores. Uso do time Brief App e do plano Enterprise.

Estes endpoints administram a própria plataforma: criar e suspender tenants, emitir, rotacionar e revogar chaves de API, e trocar o provedor de um componente (gateway de pagamento, armazenamento, KYC) sem deploy. No dia a dia quem usa é o time Brief App; clientes Enterprise podem receber acesso para gerir os próprios ambientes.

Conceitos

Tenant: Ambiente isolado de um cliente: slug, nome, plano, limites de requisição e origens permitidas.
Chave de API: Secret (sk_) ou Publishable (pk_), com escopos, validade e origens ou bundle IDs permitidos.
Rotação: Troca de chave com uma janela de sobreposição, para atualizar os sistemas sem queda.
Provedor: Implementação ativa de um componente. A troca passa por verificação prévia (preflight) obrigatória.

Estados possíveis

Tenant

Active
Suspended
Canceled

Fluxo típico

Crie o tenant com POST /api/admin/tenants.
Gere as chaves com POST /api/admin/tenants/{id}/keys e entregue ao cliente.
Rotacione periodicamente com …/keys/{keyId}/rotate, mantendo a chave antiga durante a janela.

Exemplo: Gerar uma chave secreta com escopos

Requisição

POST /api/admin/tenants/…/keys
{ "name": "backend-producao", "type": "Secret", "scopes": ["financial", "partners"] }

Resposta

201 Created
{ "keyId": "…", "tenantId": "…", "name": "backend-producao", "type": "Secret",
  "keyPrefix": "sk_live_8f3a", "plaintextKey": "sk_live_…", "scopes": ["financial", "partners"],
  "expiresAt": null, "createdAt": "2026-10-15T13:00:00Z" }

Regras importantes

Todos os endpoints exigem o papel Admin.
O valor completo da chave aparece uma única vez, na criação ou na rotação. Guarde em local seguro.

Referência de endpoints

POST /api/admin/tenants Cria um tenant com slug, nome, plano, limites de requisição e origens permitidas. Admin

Cria um tenant com slug, nome, plano, limites de requisição e origens permitidas.

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `CreateTenantRequest`

Campo	Tipo	Obrigatório	Descrição
`slug`	string	sim
`name`	string	sim
`plan`	TenantPlan	não	Padrão: TenantPlan.Standard.
`rateLimitRpm`	integer	não
`rateLimitBurst`	integer	não
`allowedOrigins`	string[]	não
`allowedBundleIds`	string[]	não

Resposta · `TenantDto`

Campo	Tipo	Descrição
`id`	uuid
`slug`	string
`name`	string
`status`	TenantStatus
`plan`	TenantPlan
`rateLimitRpm`	integer
`rateLimitBurst`	integer
`allowedOrigins`	string[]
`allowedBundleIds`	string[]
`createdAt`	datetime
`updatedAt`	datetime

Status possíveis

201 Criado
400 Dados inválidos
409 Conflito de estado

GET /api/admin/tenants Lista os tenants com paginação, opcionalmente filtrando por status. Admin

Lista os tenants com paginação, opcionalmente filtrando por status.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo
`page`	query	integer
`pageSize`	query	integer
`status`	query	TenantStatus

Resposta · `PagedResult<TenantDto>`

Campo	Tipo	Descrição
`id`	uuid
`slug`	string
`name`	string
`status`	TenantStatus
`plan`	TenantPlan
`rateLimitRpm`	integer
`rateLimitBurst`	integer
`allowedOrigins`	string[]
`allowedBundleIds`	string[]
`createdAt`	datetime
`updatedAt`	datetime

Status possíveis

200 OK

GET /api/admin/tenants/{id} Detalhe de um tenant. Admin

Detalhe de um tenant.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `TenantDto`

Campo	Tipo	Descrição
`id`	uuid
`slug`	string
`name`	string
`status`	TenantStatus
`plan`	TenantPlan
`rateLimitRpm`	integer
`rateLimitBurst`	integer
`allowedOrigins`	string[]
`allowedBundleIds`	string[]
`createdAt`	datetime
`updatedAt`	datetime

Status possíveis

200 OK
404 Não encontrado

PUT /api/admin/tenants/{id}/suspend Suspende o tenant, informando o motivo. As chamadas dele passam a ser recusadas. Admin

Suspende o tenant, informando o motivo. As chamadas dele passam a ser recusadas.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `SuspendTenantRequest`

Campo	Tipo	Obrigatório	Descrição
`reason`	string	sim

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

PUT /api/admin/tenants/{id}/activate Reativa um tenant suspenso. Admin

Reativa um tenant suspenso.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

PUT /api/admin/tenants/{id}/cancel Cancela o tenant definitivamente, informando o motivo. Admin

Cancela o tenant definitivamente, informando o motivo.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `SuspendTenantRequest`

Campo	Tipo	Obrigatório	Descrição
`reason`	string	sim

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

POST /api/admin/tenants/{id}/keys Gera uma chave de API (Secret ou Publishable) com escopos, validade e origens permitidas. O valor completo só aparece nesta resposta. Admin

Gera uma chave de API (Secret ou Publishable) com escopos, validade e origens permitidas. O valor completo só aparece nesta resposta.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Corpo (JSON) · `CreateApiKeyRequest`

Campo	Tipo	Obrigatório
`name`	string	sim
`type`	ApiKeyType	sim
`scopes`	string[]	sim
`expiresAt`	datetime	não
`allowedOrigins`	string[]	não
`allowedBundleIds`	string[]	não

Resposta · `GeneratedApiKeyDto`

Campo	Tipo	Descrição
`keyId`	uuid
`tenantId`	uuid
`name`	string
`type`	ApiKeyType
`keyPrefix`	string
`plaintextKey`	string
`scopes`	string[]
`expiresAt`	datetime
`createdAt`	datetime

Status possíveis

201 Criado
400 Dados inválidos
404 Não encontrado

GET /api/admin/tenants/{id}/keys Lista as chaves do tenant (sem o valor secreto). Admin

Lista as chaves do tenant (sem o valor secreto).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid

Resposta · `IReadOnlyList<TenantApiKeySummaryDto>`

Campo	Tipo	Descrição
`id`	uuid
`tenantId`	uuid
`name`	string
`type`	ApiKeyType
`keyPrefix`	string
`scopes`	string[]
`expiresAt`	datetime
`revokedAt`	datetime
`revocationReason`	string
`lastUsedAt`	datetime
`createdAt`	datetime
`isActive`	boolean

Status possíveis

200 OK

DELETE /api/admin/tenants/{id}/keys/{keyId} Revoga uma chave, informando o motivo. Tokens novos deixam de ser emitidos com ela. Admin

Revoga uma chave, informando o motivo. Tokens novos deixam de ser emitidos com ela.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid
`keyId`	rota	uuid

Corpo (JSON) · `RevokeApiKeyRequest`

Campo	Tipo	Obrigatório	Descrição
`reason`	string	sim

Status possíveis

204 Sem conteúdo
400 Dados inválidos
404 Não encontrado

POST /api/admin/tenants/{id}/keys/{keyId}/rotate Gera uma chave substituta e mantém a antiga válida durante a janela de sobreposição. Admin

Gera uma chave substituta e mantém a antiga válida durante a janela de sobreposição.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	uuid
`keyId`	rota	uuid

Corpo (JSON) · `RotateApiKeyRequest`

Campo	Tipo	Obrigatório	Descrição
`overlapWindow`	duração	não
`newName`	string	não

Resposta · `RotatedApiKeyResultDto`

Campo	Tipo	Descrição
`newKey`	GeneratedApiKeyDto
`previousKeyExpiresAt`	datetime
`previousKeyId`	uuid

Status possíveis

200 OK
400 Dados inválidos
404 Não encontrado

Endpoints administrativos para auditoria, visibilidade, validação prévia (preflight) e chaveamento dinâmico de provedores controlados via HashiCorp Vault.

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). Admin

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).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`tenantId`	query	uuid

Resposta · `ProvidersOverviewResponse`

Campo	Tipo	Descrição
`tenantId`	uuid
`effectiveProviders`	IReadOnlyDictionary<string, string>
`platformProviders`	IReadOnlyDictionary<string, string>
`tenantOverrides`	IReadOnlyDictionary<string, string>
`originBreakdown`	ProviderOriginItem[]
`supportedCatalog`	IReadOnlyDictionary<string, IReadOnlyList<string>>

Status possíveis

200 OK

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. Admin

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.

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `AdminPreflightRequest`

Campo	Tipo	Obrigatório
`component`	string	sim
`targetProvider`	string	sim
`tenantId`	uuid	não

Resposta · `PreflightValidationResult`

Campo	Tipo	Descrição
`passed`	boolean
`component`	string
`targetProvider`	string
`tenantId`	uuid
`isDryRun`	boolean
`errors`	string[]
`checkedCredentials`	IReadOnlyDictionary<string, string>

Status possíveis

200 OK
400 Dados inválidos

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. Admin

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.

Permissão: Exige o papel Admin (ou escopo admin).

Corpo (JSON) · `AdminSwitchProviderRequest`

Campo	Tipo	Obrigatório	Descrição
`component`	string	sim
`targetProvider`	string	sim
`tenantId`	uuid	não
`dryRun`	boolean	não	Padrão: false.

Status possíveis

200 OK
400 Dados inválidos

Módulo

Kanban as a Service

Quadros, colunas (WIP, transições), cartões dinâmicos tipados jsonb, automações e webhooks.

O Kanban as a Service resolve a gestão operacional e o fluxo de trabalho de qualquer negócio. Cada quadro define seu schema de campos tipados (12 tipos: Moeda, Usuário, Data, Seleção, etc.), colunas com limite WIP e regras de transição. Cartões recebem valores validados e posições fracionárias para ordenação rápida. Automações assíncronas "quando → se → então" disparam ações em outros módulos (FileStorage, Email, Notifications, OCR, KYC, Payments) e webhooks assinados notificam sistemas externos.

Conceitos

Quadro: Dono do schema de campos tipados e das colunas. Identificado por chave única por tenant.
Campo: Definição tipada no schema do quadro: chave, rótulo, tipo, obrigatório, mínimo, máximo e regex.
Coluna: Etapa do fluxo: ordem, limiteWip (com wipEstrito), final, cor hex e lista de transições permitidas.
Cartão: Item de trabalho com título, descrição, valores em campos jsonb, posição ordinal e versão para concorrência otimista.
Vínculo: Associação de um cartão a qualquer entidade de negócio (cobrança, agendamento, usuário ou id externo).
Automação: Gatilho de evento + condições declarativas + ações integradas aos serviços da plataforma.
Webhook: Disparo de eventos kanban.* para URLs externas com assinatura HMAC e retry automático.

Estados possíveis

Cartão

Ativo
Arquivado

Entrega de Webhook

Pendente
Entregue
Falhou

Fluxo típico

Crie um quadro com POST /api/kanban/boards definindo colunas e campos tipados.
Crie cartões na primeira coluna com POST /api/kanban/boards/{id}/cards.
Mova cartões entre colunas com POST /api/kanban/cards/{id}/move, validando WIP e transições.
Configure automações com POST /api/kanban/boards/{id}/automations para reagir a movimentos ou eventos externos.
Inscreva webhooks de saída com POST /api/kanban/webhooks para integrar seu front-end.

Exemplo: Criar cartão com campos personalizados

Requisição

POST /api/kanban/boards/meu-quadro/cards
{ "titulo": "Aprovação de Fornecedor", "colunaId": "…",
  "campos": { "valor": 4500.00, "prioridade": "Alta", "responsavel": "…" } }

Resposta

201 Created
{ "id": "…", "titulo": "Aprovação de Fornecedor", "colunaId": "…",
  "posicao": 1000.0, "versao": 1, "campos": { "valor": 4500.00, "prioridade": "Alta" }, … }

Regras importantes

Todas as rotas exigem scope:kanban (token de API key) ou role Parceiro/Admin.
Com wipEstrito ativado, mover um cartão para uma coluna cheia devolve 409.
Toda mutação de cartão valida concorrência otimista via versao (ou header If-Match).

Referência de endpoints

Kanban as a service: quadros, schema de campos dos cartões, colunas, cartões de um quadro e automações. Tudo é isolado pelo tenant do token; exige o escopo kanban (ou role Parceiro/Admin).

GET /api/kanban/boards Quadros do tenant. Autenticado

Quadros do tenant.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`includeArchived`	query	boolean

Resposta · `IReadOnlyList<QuadroResumoDto>`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

POST /api/kanban/boards Cria um quadro, opcionalmente já com campos e colunas. Autenticado

Cria um quadro, opcionalmente já com campos e colunas.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `CreateBoardRequest`

Campo	Tipo	Obrigatório
`nome`	string	sim
`chave`	string	não
`descricao`	string	não
`campos`	DefinicaoCampo[]	não
`colunas`	ColunaInput[]	não

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

201 Criado
409 Conflito de estado

GET /api/kanban/boards/{boardId} Quadro com campos, colunas (em ordem) e a contagem de cartões ativos por coluna. Autenticado

Quadro com campos, colunas (em ordem) e a contagem de cartões ativos por coluna.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

PUT /api/kanban/boards/{boardId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `UpdateBoardRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`descricao`	string	não

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

POST /api/kanban/boards/{boardId}/archive Arquiva o quadro: fica somente leitura e para de disparar automações. Autenticado

Arquiva o quadro: fica somente leitura e para de disparar automações.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Resposta · `QuadroResumoDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

POST /api/kanban/boards/{boardId}/restore Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Resposta · `QuadroResumoDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

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

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.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `BoardRestrictionsRequest`

Campo	Tipo	Obrigatório	Descrição
`eventosPermitidos`	string[]	não
`acoesPermitidas`	TipoAcao[]	não

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

GET /api/kanban/boards/{boardId}/fields Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Resposta · `IReadOnlyList<DefinicaoCampo>`

Campo	Tipo	Descrição
`chave`	string
`rotulo`	string
`tipo`	TipoCampo
`obrigatorio`	boolean
`opcoes`	string[]
`minimo`	decimal
`maximo`	decimal
`padrao`	string
`valorPadrao`	JsonElement
`descricao`	string

Status possíveis

200 OK

PUT /api/kanban/boards/{boardId}/fields Substitui todos os campos. Campos removidos têm os valores apagados de todos os cartões. Autenticado

Substitui todos os campos. Campos removidos têm os valores apagados de todos os cartões.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `IReadOnlyList<DefinicaoCampo>`

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

POST /api/kanban/boards/{boardId}/fields Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `DefinicaoCampo`

Campo	Tipo	Obrigatório	Descrição
`chave`	string	sim
`rotulo`	string	sim
`tipo`	TipoCampo	sim
`obrigatorio`	boolean	não	Padrão: false.
`opcoes`	string[]	não
`minimo`	decimal	não
`maximo`	decimal	não
`padrao`	string	não
`valorPadrao`	JsonElement	não
`descricao`	string	não

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

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

Atualiza um campo. O tipo não muda: para outro tipo, remova e crie com outra chave.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`key`	rota	string

Corpo (JSON) · `DefinicaoCampo`

Campo	Tipo	Obrigatório	Descrição
`chave`	string	sim
`rotulo`	string	sim
`tipo`	TipoCampo	sim
`obrigatorio`	boolean	não	Padrão: false.
`opcoes`	string[]	não
`minimo`	decimal	não
`maximo`	decimal	não
`padrao`	string	não
`valorPadrao`	JsonElement	não
`descricao`	string	não

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

DELETE /api/kanban/boards/{boardId}/fields/{key} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`key`	rota	string

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

POST /api/kanban/boards/{boardId}/columns Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `ColumnRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`posicao`	integer	não
`limiteWip`	integer	não
`wipEstrito`	boolean	não	Padrão: false.
`final`	boolean	não	Padrão: false.
`cor`	string	não
`transicoes`	uuid[]	não

Resposta · `ColunaDto`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`ordem`	integer
`limiteWip`	integer
`wipEstrito`	boolean
`final`	boolean
`cor`	string
`transicoesPermitidas`	uuid[]
`quantidadeCartoes`	integer

Status possíveis

200 OK

PUT /api/kanban/boards/{boardId}/columns/{columnId} Atualiza a coluna. transicoes: nulo mantém, lista vazia libera qualquer destino. Autenticado

Atualiza a coluna. transicoes: nulo mantém, lista vazia libera qualquer destino.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`columnId`	rota	uuid

Corpo (JSON) · `ColumnRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`posicao`	integer	não
`limiteWip`	integer	não
`wipEstrito`	boolean	não	Padrão: false.
`final`	boolean	não	Padrão: false.
`cor`	string	não
`transicoes`	uuid[]	não

Resposta · `ColunaDto`

Campo	Tipo	Descrição
`id`	uuid
`nome`	string
`ordem`	integer
`limiteWip`	integer
`wipEstrito`	boolean
`final`	boolean
`cor`	string
`transicoesPermitidas`	uuid[]
`quantidadeCartoes`	integer

Status possíveis

200 OK

DELETE /api/kanban/boards/{boardId}/columns/{columnId} Remove a coluna; se houver cartões, moveCardsTo indica para onde vão. Autenticado

Remove a coluna; se houver cartões, moveCardsTo indica para onde vão.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`boardId`	rota	uuid
`columnId`	rota	uuid
`moveCardsTo`	query	uuid

Status possíveis

204 Sem conteúdo
409 Conflito de estado

PUT /api/kanban/boards/{boardId}/columns/order Nova ordem das colunas (todas, cada uma uma vez). Autenticado

Nova ordem das colunas (todas, cada uma uma vez).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `ReorderColumnsRequest`

Campo	Tipo	Obrigatório	Descrição
`colunas`	uuid[]	sim

Resposta · `QuadroDto`

Campo	Tipo	Descrição
`id`	uuid
`chave`	string
`nome`	string
`descricao`	string
`arquivado`	boolean
`versaoSchema`	integer
`versao`	integer
`campos`	DefinicaoCampo[]
`colunas`	ColunaDto[]
`criadoEm`	datetime
`atualizadoEm`	datetime
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]

Status possíveis

200 OK

GET /api/kanban/boards/{boardId}/cards Cartões paginados, ordenados por coluna e posição. Filtros por campo customizado como ?field.prioridade=Alta&field.valor=150 (igualdade; em multisseleção, "contém"). archived: omitido = ativos, true = só arquivados, false = todos. Autenticado

Cartões paginados, ordenados por coluna e posição. Filtros por campo customizado como ?field.prioridade=Alta&field.valor=150 (igualdade; em multisseleção, "contém"). archived: omitido = ativos, true = só arquivados, false = todos.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`boardId`	rota	uuid
`columnId`	query	uuid
`search`	query	string
`archived`	query	boolean
`page`	query	integer
`pageSize`	query	integer

Resposta · `PaginaDto<CartaoDto>`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK

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

Cria um cartão. Sem coluna, entra na primeira; sem âncora, no fim. Campos validados pelo schema do quadro.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `CreateCardRequest`

Campo	Tipo	Obrigatório
`titulo`	string	sim
`descricao`	string	não
`colunaId`	uuid	não
`campos`	Dictionary<string, JsonElement>	não
`aposCartaoId`	uuid	não
`antesCartaoId`	uuid	não

Resposta · `CartaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

201 Criado

GET /api/kanban/boards/{boardId}/automations Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Resposta · `IReadOnlyList<AutomacaoDto>`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`nome`	string
`ativa`	boolean
`gatilho`	GatilhoAutomacao
`condicoes`	CondicaoAutomacao[]
`acoes`	AcaoAutomacao[]
`execucoes`	integer
`falhas`	integer
`ultimaExecucaoEm`	datetime
`ultimoErro`	string
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

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

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}}.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid

Corpo (JSON) · `AutomationRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`gatilho`	GatilhoAutomacao	sim
`acoes`	AcaoAutomacao[]	sim
`condicoes`	CondicaoAutomacao[]	não
`ativa`	boolean	não	Padrão: true.

Resposta · `AutomacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`nome`	string
`ativa`	boolean
`gatilho`	GatilhoAutomacao
`condicoes`	CondicaoAutomacao[]
`acoes`	AcaoAutomacao[]
`execucoes`	integer
`falhas`	integer
`ultimaExecucaoEm`	datetime
`ultimoErro`	string
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

201 Criado

GET /api/kanban/boards/{boardId}/automations/{automationId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`automationId`	rota	uuid

Resposta · `AutomacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`nome`	string
`ativa`	boolean
`gatilho`	GatilhoAutomacao
`condicoes`	CondicaoAutomacao[]
`acoes`	AcaoAutomacao[]
`execucoes`	integer
`falhas`	integer
`ultimaExecucaoEm`	datetime
`ultimoErro`	string
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

PUT /api/kanban/boards/{boardId}/automations/{automationId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`automationId`	rota	uuid

Corpo (JSON) · `AutomationRequest`

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim
`gatilho`	GatilhoAutomacao	sim
`acoes`	AcaoAutomacao[]	sim
`condicoes`	CondicaoAutomacao[]	não
`ativa`	boolean	não	Padrão: true.

Resposta · `AutomacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`nome`	string
`ativa`	boolean
`gatilho`	GatilhoAutomacao
`condicoes`	CondicaoAutomacao[]
`acoes`	AcaoAutomacao[]
`execucoes`	integer
`falhas`	integer
`ultimaExecucaoEm`	datetime
`ultimoErro`	string
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

POST /api/kanban/boards/{boardId}/automations/{automationId}/enable Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`automationId`	rota	uuid

Resposta · `AutomacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`nome`	string
`ativa`	boolean
`gatilho`	GatilhoAutomacao
`condicoes`	CondicaoAutomacao[]
`acoes`	AcaoAutomacao[]
`execucoes`	integer
`falhas`	integer
`ultimaExecucaoEm`	datetime
`ultimoErro`	string
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

POST /api/kanban/boards/{boardId}/automations/{automationId}/disable Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`automationId`	rota	uuid

Resposta · `AutomacaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`nome`	string
`ativa`	boolean
`gatilho`	GatilhoAutomacao
`condicoes`	CondicaoAutomacao[]
`acoes`	AcaoAutomacao[]
`execucoes`	integer
`falhas`	integer
`ultimaExecucaoEm`	datetime
`ultimoErro`	string
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

DELETE /api/kanban/boards/{boardId}/automations/{automationId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	rota	uuid
`automationId`	rota	uuid

Status possíveis

204 Sem conteúdo

GET /api/kanban/boards/{boardId}/automations/{automationId}/executions Histórico de execuções (ações executadas, saídas e erros). Autenticado

Histórico de execuções (ações executadas, saídas e erros).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`boardId`	rota	uuid
`automationId`	rota	uuid
`success`	query	boolean
`page`	query	integer
`pageSize`	query	integer

Resposta · `PaginaDto<ExecucaoAutomacaoDto>`

Campo	Tipo	Descrição
`id`	uuid
`automacaoId`	uuid
`eventoId`	uuid
`eventoTipo`	string
`cartaoId`	uuid
`sucesso`	boolean
`erro`	string
`resultados`	JsonElement
`duracaoMs`	integer
`ocorridaEm`	datetime

Status possíveis

200 OK

Cartões do Kanban: edição, movimento, histórico, comentários, anexos (FileStorage) e vínculos com entidades.

GET /api/kanban/cards/{cardId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Resposta · `CartaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK

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

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).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Corpo (JSON) · `UpdateCardRequest`

Campo	Tipo	Obrigatório
`titulo`	string	não
`descricao`	string	não
`campos`	Dictionary<string, JsonElement>	não
`versaoEsperada`	integer	não

Resposta · `CartaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK
409 Conflito de estado

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

Move para a coluna, depois de aposCartaoId e/ou antes de antesCartaoId (sem âncora: fim). Respeita WIP e transições.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Corpo (JSON) · `MoveCardRequest`

Campo	Tipo	Obrigatório
`colunaId`	uuid	sim
`aposCartaoId`	uuid	não
`antesCartaoId`	uuid	não
`versaoEsperada`	integer	não

Resposta · `CartaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK
409 Conflito de estado

POST /api/kanban/cards/{cardId}/archive Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Resposta · `CartaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK

POST /api/kanban/cards/{cardId}/restore Restaura ao fim da coluna de origem ou de colunaId. Autenticado

Restaura ao fim da coluna de origem ou de colunaId.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Corpo (JSON) · `RestoreCardRequest`

Campo	Tipo	Obrigatório	Descrição
`colunaId`	uuid	não

Resposta · `CartaoDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK

DELETE /api/kanban/cards/{cardId} Exclui definitivamente o cartão e o seu histórico. Autenticado

Exclui definitivamente o cartão e o seu histórico.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Status possíveis

204 Sem conteúdo

GET /api/kanban/cards/{cardId}/activity Histórico do cartão, mais recente primeiro. Autenticado

Histórico do cartão, mais recente primeiro.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`cardId`	rota	uuid
`page`	query	integer
`pageSize`	query	integer

Resposta · `PaginaDto<AtividadeDto>`

Campo	Tipo	Descrição
`id`	uuid
`cartaoId`	uuid
`tipo`	string
`autorId`	uuid
`automacaoId`	uuid
`dados`	JsonElement
`ocorridaEm`	datetime

Status possíveis

200 OK

POST /api/kanban/cards/{cardId}/comments Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Corpo (JSON) · `CommentRequest`

Campo	Tipo	Obrigatório	Descrição
`texto`	string	sim

Resposta · `AtividadeDto`

Campo	Tipo	Descrição
`id`	uuid
`cartaoId`	uuid
`tipo`	string
`autorId`	uuid
`automacaoId`	uuid
`dados`	JsonElement
`ocorridaEm`	datetime

Status possíveis

200 OK

GET /api/kanban/cards/{cardId}/attachments Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Resposta · `IReadOnlyList<AnexoDto>`

Campo	Tipo	Descrição
`id`	uuid
`cartaoId`	uuid
`nomeArquivo`	string
`contentType`	string
`tamanho`	integer
`provedor`	string
`urlPublica`	string
`enviadoPor`	uuid
`criadoEm`	datetime

Status possíveis

200 OK

POST /api/kanban/cards/{cardId}/attachments Envia um arquivo (multipart, campo file) para o provedor de storage ativo do tenant. Autenticado

Envia um arquivo (multipart, campo file) para o provedor de storage ativo do tenant.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid
`file`	form	arquivo

Resposta · `AnexoDto`

Campo	Tipo	Descrição
`id`	uuid
`cartaoId`	uuid
`nomeArquivo`	string
`contentType`	string
`tamanho`	integer
`provedor`	string
`urlPublica`	string
`enviadoPor`	uuid
`criadoEm`	datetime

Status possíveis

200 OK

GET /api/kanban/cards/{cardId}/attachments/{attachmentId}/content Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid
`attachmentId`	rota	uuid

Resposta · `FileStreamResult`

Status possíveis

200 OK

DELETE /api/kanban/cards/{cardId}/attachments/{attachmentId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid
`attachmentId`	rota	uuid

Status possíveis

204 Sem conteúdo

GET /api/kanban/cards/{cardId}/links Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Resposta · `IReadOnlyList<VinculoDto>`

Campo	Tipo	Descrição
`id`	uuid
`cartaoId`	uuid
`quadroId`	uuid
`entidade`	string
`entidadeId`	string
`rotulo`	string
`criadoPor`	uuid
`criadoEm`	datetime

Status possíveis

200 OK

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

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.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid

Corpo (JSON) · `LinkRequest`

Campo	Tipo	Obrigatório
`entidade`	string	sim
`entidadeId`	string	sim
`rotulo`	string	não

Resposta · `VinculoDto`

Campo	Tipo	Descrição
`id`	uuid
`cartaoId`	uuid
`quadroId`	uuid
`entidade`	string
`entidadeId`	string
`rotulo`	string
`criadoPor`	uuid
`criadoEm`	datetime

Status possíveis

200 OK
409 Conflito de estado

DELETE /api/kanban/cards/{cardId}/links/{linkId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`cardId`	rota	uuid
`linkId`	rota	uuid

Status possíveis

204 Sem conteúdo

Webhooks de saída do Kanban (assinados com HMAC-SHA256: X-BriefApp-Signature: sha256=hex(HMAC(segredo, "{timestamp}.{corpo}"))), catálogo de eventos e consulta de cartões por entidade de negócio.

GET /api/kanban/events Tipos de evento do Kanban (webhooks e gatilhos) e tipos de entidade com checagem de existência. Autenticado

Tipos de evento do Kanban (webhooks e gatilhos) e tipos de entidade com checagem de existência.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `KanbanCatalogResponse`

Campo	Tipo	Descrição
`eventos`	string[]
`entidades`	string[]

Status possíveis

200 OK

GET /api/kanban/policy Política efetiva do tenant: eventos e ações permitidos nas automações e limites (definida pelo Admin). Autenticado

Política efetiva do tenant: eventos e ações permitidos nas automações e limites (definida pelo Admin).

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `PoliticaDto`

Campo	Tipo	Descrição
`tenantId`	uuid
`habilitado`	boolean
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]
`maximoQuadros`	integer
`maximoAutomacoesPorQuadro`	integer
`maximoWebhooks`	integer
`maximoAnexoBytes`	integer
`maximoAnexosPorCartao`	integer
`intervalosRetrySegundos`	integer[]
`limiteFalhasParaDesativar`	integer
`personalizada`	boolean
`personalizacao`	PersonalizacaoPolitica
`atualizadaEm`	datetime
`atualizadoPor`	uuid

Status possíveis

200 OK

GET /api/kanban/entities Tipos de entidade conferidos ao vincular (os demais são aceitos como ids externos). Autenticado

Tipos de entidade conferidos ao vincular (os demais são aceitos como ids externos).

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `IReadOnlyList<string>`

Status possíveis

200 OK

GET /api/kanban/entities/{entity}/{entityId}/cards Cartões de todos os quadros vinculados à entidade (ex.: /entities/cobranca/{id}/cards). Autenticado

Cartões de todos os quadros vinculados à entidade (ex.: /entities/cobranca/{id}/cards).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`entity`	rota	string
`entityId`	rota	string
`includeArchived`	query	boolean

Resposta · `IReadOnlyList<CartaoDto>`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`colunaId`	uuid
`titulo`	string
`descricao`	string
`posicao`	string
`campos`	IReadOnlyDictionary<string, JsonElement>
`arquivado`	boolean
`versao`	integer
`criadoPor`	uuid
`atualizadoPor`	uuid
`criadoEm`	datetime
`atualizadoEm`	datetime
`entrouNaColunaEm`	datetime

Status possíveis

200 OK

GET /api/kanban/webhooks Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`boardId`	query	uuid

Resposta · `IReadOnlyList<WebhookDto>`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`url`	string
`descricao`	string
`eventos`	string[]
`ativa`	boolean
`falhasConsecutivas`	integer
`desativadaAutomaticamenteEm`	datetime
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

POST /api/kanban/webhooks Cria a assinatura. O segredo HMAC só aparece nesta resposta (e na rotação). Autenticado

Cria a assinatura. O segredo HMAC só aparece nesta resposta (e na rotação).

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `WebhookRequest`

Campo	Tipo	Obrigatório	Descrição
`url`	string	sim
`eventos`	string[]	não
`quadroId`	uuid	não
`descricao`	string	não
`ativa`	boolean	não	Padrão: true.

Resposta · `WebhookComSegredoDto`

Campo	Tipo	Descrição
`webhook`	WebhookDto
`segredo`	string

Status possíveis

201 Criado

GET /api/kanban/webhooks/{webhookId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`webhookId`	rota	uuid

Resposta · `WebhookDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`url`	string
`descricao`	string
`eventos`	string[]
`ativa`	boolean
`falhasConsecutivas`	integer
`desativadaAutomaticamenteEm`	datetime
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

PUT /api/kanban/webhooks/{webhookId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`webhookId`	rota	uuid

Corpo (JSON) · `WebhookRequest`

Campo	Tipo	Obrigatório	Descrição
`url`	string	sim
`eventos`	string[]	não
`quadroId`	uuid	não
`descricao`	string	não
`ativa`	boolean	não	Padrão: true.

Resposta · `WebhookDto`

Campo	Tipo	Descrição
`id`	uuid
`quadroId`	uuid
`url`	string
`descricao`	string
`eventos`	string[]
`ativa`	boolean
`falhasConsecutivas`	integer
`desativadaAutomaticamenteEm`	datetime
`criadoEm`	datetime
`atualizadoEm`	datetime

Status possíveis

200 OK

DELETE /api/kanban/webhooks/{webhookId} Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`webhookId`	rota	uuid

Status possíveis

204 Sem conteúdo

POST /api/kanban/webhooks/{webhookId}/rotate-secret Autenticado

Sem descrição.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`webhookId`	rota	uuid

Resposta · `WebhookComSegredoDto`

Campo	Tipo	Descrição
`webhook`	WebhookDto
`segredo`	string

Status possíveis

200 OK

POST /api/kanban/webhooks/{webhookId}/ping Enfileira um evento kanban.ping só para esta assinatura (teste de conectividade e assinatura). Autenticado

Enfileira um evento kanban.ping só para esta assinatura (teste de conectividade e assinatura).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`webhookId`	rota	uuid

Resposta · `EntregaWebhookDto`

Campo	Tipo	Descrição
`id`	uuid
`assinaturaId`	uuid
`eventoId`	uuid
`tipo`	string
`status`	string
`tentativas`	integer
`proximaTentativaEm`	datetime
`ultimoStatusHttp`	integer
`ultimoErro`	string
`ultimaResposta`	string
`ultimaDuracaoMs`	integer
`criadaEm`	datetime
`entregueEm`	datetime

Status possíveis

200 OK

GET /api/kanban/webhooks/{webhookId}/deliveries Entregas da assinatura (status, tentativas, último HTTP/erro). Autenticado

Entregas da assinatura (status, tentativas, último HTTP/erro).

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo
`webhookId`	rota	uuid
`status`	query	StatusEntregaWebhook
`page`	query	integer
`pageSize`	query	integer

Resposta · `PaginaDto<EntregaWebhookDto>`

Campo	Tipo	Descrição
`id`	uuid
`assinaturaId`	uuid
`eventoId`	uuid
`tipo`	string
`status`	string
`tentativas`	integer
`proximaTentativaEm`	datetime
`ultimoStatusHttp`	integer
`ultimoErro`	string
`ultimaResposta`	string
`ultimaDuracaoMs`	integer
`criadaEm`	datetime
`entregueEm`	datetime

Status possíveis

200 OK

POST /api/kanban/webhooks/deliveries/{deliveryId}/redeliver Reenfileira uma entrega já concluída ou falha. Autenticado

Reenfileira uma entrega já concluída ou falha.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`deliveryId`	rota	uuid

Resposta · `EntregaWebhookDto`

Campo	Tipo	Descrição
`id`	uuid
`assinaturaId`	uuid
`eventoId`	uuid
`tipo`	string
`status`	string
`tentativas`	integer
`proximaTentativaEm`	datetime
`ultimoStatusHttp`	integer
`ultimoErro`	string
`ultimaResposta`	string
`ultimaDuracaoMs`	integer
`criadaEm`	datetime
`entregueEm`	datetime

Status possíveis

200 OK

Admin da plataforma: política do Kanban por tenant — habilitação, eventos e ações permitidos nas automações e limites. Campos omitidos (nulos) herdam o padrão global Kanban:Politica.

GET /api/admin/kanban/policies Tenants com política personalizada. Admin

Tenants com política personalizada.

Permissão: Exige o papel Admin (ou escopo admin).

Resposta · `IReadOnlyList<PoliticaDto>`

Campo	Tipo	Descrição
`tenantId`	uuid
`habilitado`	boolean
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]
`maximoQuadros`	integer
`maximoAutomacoesPorQuadro`	integer
`maximoWebhooks`	integer
`maximoAnexoBytes`	integer
`maximoAnexosPorCartao`	integer
`intervalosRetrySegundos`	integer[]
`limiteFalhasParaDesativar`	integer
`personalizada`	boolean
`personalizacao`	PersonalizacaoPolitica
`atualizadaEm`	datetime
`atualizadoPor`	uuid

Status possíveis

200 OK

GET /api/admin/kanban/tenants/{tenantId}/policy Política efetiva do tenant (personalização + padrão global). Admin

Política efetiva do tenant (personalização + padrão global).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`tenantId`	rota	uuid

Resposta · `PoliticaDto`

Campo	Tipo	Descrição
`tenantId`	uuid
`habilitado`	boolean
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]
`maximoQuadros`	integer
`maximoAutomacoesPorQuadro`	integer
`maximoWebhooks`	integer
`maximoAnexoBytes`	integer
`maximoAnexosPorCartao`	integer
`intervalosRetrySegundos`	integer[]
`limiteFalhasParaDesativar`	integer
`personalizada`	boolean
`personalizacao`	PersonalizacaoPolitica
`atualizadaEm`	datetime
`atualizadoPor`	uuid

Status possíveis

200 OK

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). Admin

Substitui a personalização do tenant. Vale em até 30 s em todas as réplicas (na hora nesta).

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`tenantId`	rota	uuid

Corpo (JSON) · `PersonalizacaoPolitica`

Campo	Tipo	Obrigatório
`habilitado`	boolean	não
`eventosPermitidos`	string[]	não
`acoesPermitidas`	TipoAcao[]	não
`maximoQuadros`	integer	não
`maximoAutomacoesPorQuadro`	integer	não
`maximoWebhooks`	integer	não
`maximoAnexoBytes`	integer	não
`maximoAnexosPorCartao`	integer	não
`intervalosRetrySegundos`	integer[]	não
`limiteFalhasParaDesativar`	integer	não
`observacao`	string	não

Resposta · `PoliticaDto`

Campo	Tipo	Descrição
`tenantId`	uuid
`habilitado`	boolean
`eventosPermitidos`	string[]
`acoesPermitidas`	string[]
`maximoQuadros`	integer
`maximoAutomacoesPorQuadro`	integer
`maximoWebhooks`	integer
`maximoAnexoBytes`	integer
`maximoAnexosPorCartao`	integer
`intervalosRetrySegundos`	integer[]
`limiteFalhasParaDesativar`	integer
`personalizada`	boolean
`personalizacao`	PersonalizacaoPolitica
`atualizadaEm`	datetime
`atualizadoPor`	uuid

Status possíveis

200 OK

DELETE /api/admin/kanban/tenants/{tenantId}/policy Remove a personalização: o tenant volta ao padrão global. Admin

Remove a personalização: o tenant volta ao padrão global.

Permissão: Exige o papel Admin (ou escopo admin).

Parâmetros

Nome	Onde	Tipo	Descrição
`tenantId`	rota	uuid

Status possíveis

204 Sem conteúdo

Módulo

OpenFinance e Gestão Bancária

Painel bancário consolidado, conciliação de transações, sessões de atendimento e metas financeiras.

O módulo OpenFinance conecta a plataforma a agregadores bancários (Pluggy) para consolidação em tempo real de contas correntes, poupanças e investimentos. Oferece conciliação bancária automática e manual, painel de fluxo de caixa, registro de sessões de suporte com especialistas e acompanhamento de metas financeiras do cliente.

Conceitos

Conta Bancária: Conta agregada via OpenFinance com saldo atualizado, tipo e instituição financeira.
Transação Bancária: Débito ou crédito sincronizado com descrição, categoria, valor e status de conciliação.
Conciliação: Vinculação de uma transação bancária a um lançamento financeiro interno com carimbo do operador.
Sessão de Voz: Atendimento de especialista financeiro com transcrições, resumo e itens de ação gerados por IA.
Meta Financeira: Objetivo financeiro de redução de despesas ou reserva com prazo e valor alvo.

Estados possíveis

Transação

POSTED
PENDING

Status de Conciliação

Não Conciliado
Conciliado

Meta Financeira

in_progress
completed
canceled

Fluxo típico

Gere o link de conexão bancária com GET /api/openfinance/connect-url.
Sincronize as contas e extratos com POST /api/openfinance/sync.
Consulte o painel consolidado com GET /api/openfinance/summary.
Realize a conciliação de transações com POST /api/openfinance/transactions/{id}/conciliate.
Acompanhe metas e sessões de suporte financeiro com /api/openfinance/goals e /sessions.

Exemplo: Conciliar uma transação bancária

Requisição

POST /api/openfinance/transactions/tx-123/conciliate
{ "conciliatedBy": "operador@bpo.com.br" }

Resposta

200 OK
{ "id": "tx-123", "isConciliated": true, "conciliatedAt": "2026-10-15T14:30:00Z", "conciliatedBy": "operador@bpo.com.br" }

Regras importantes

Todas as rotas operam sob isolamento multitenant estrito via TenantAwareDbContext.
Transações conciliadas registram autor e carimbo de tempo para auditoria contábil.

Referência de endpoints

Módulo de Open Finance, conciliação bancária multiconector (Pluggy) e BPO Financeiro com IA. Permite sincronizar extratos em tempo real, gerenciar contas bancárias, metas e histórico de atendimentos.

GET /api/openfinance/summary Retorna o saldo acumulado e extrato sincronizado de todas as contas no PostgreSQL. Autenticado

Retorna o saldo acumulado e extrato sincronizado de todas as contas no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `OpenFinanceSummaryDto`

Campo	Tipo	Descrição
`totalBalance`	decimal
`accounts`	BankAccountDto[]
`recentTransactions`	BankTransactionDto[]
`connectUrl`	string
`status`	string
`toolkitUrl`	string

Status possíveis

200 OK

POST /api/openfinance/sync Executa a sincronização em tempo real das contas e transações via MCP e persiste no PostgreSQL. Autenticado

Executa a sincronização em tempo real das contas e transações via MCP e persiste no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `OpenFinanceSyncResultDto`

Campo	Tipo	Descrição
`success`	boolean
`status`	string
`message`	string
`syncedAccounts`	integer
`syncedTransactions`	integer
`bankName`	string
`checkoutUrls`	IReadOnlyDictionary<string, string>
`isBillingNotice`	boolean

Status possíveis

200 OK

GET /api/openfinance/accounts Lista as contas bancárias ativas persistidas no PostgreSQL. Autenticado

Lista as contas bancárias ativas persistidas no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `List<BankAccountDto>`

Campo	Tipo	Descrição
`id`	string
`accountId`	string
`bankName`	string
`connectorName`	string
`accountType`	string
`accountNumber`	string
`balance`	decimal
`currencyCode`	string
`taxNumber`	string
`updatedAt`	datetime

Status possíveis

200 OK

GET /api/openfinance/transactions Lista transações bancárias com paginação e filtro por conta no PostgreSQL. Autenticado

Lista transações bancárias com paginação e filtro por conta no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`accountId`	query	uuid	Identificador da conta bancária para filtragem.
`limit`	query	integer	Quantidade máxima de transações a retornar (padrão 50).

Resposta · `List<BankTransactionDto>`

Campo	Tipo	Descrição
`id`	string
`accountId`	string
`date`	string
`description`	string
`amount`	decimal
`currencyCode`	string
`type`	string
`status`	string
`category`	string
`operationType`	string
`receiverSender`	string
`rawJson`	string
`isConciliated`	boolean
`conciliatedAt`	datetime
`conciliatedBy`	string

Status possíveis

200 OK

POST /api/openfinance/transactions/{id}/conciliate Marca uma transação bancária como conciliada no PostgreSQL. Autenticado

Marca uma transação bancária como conciliada no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	rota	string	Identificador interno ou externo da transação.

Corpo (JSON) · `ConciliateTransactionRequest`

Campo	Tipo	Obrigatório	Descrição
`conciliatedBy`	string	não
`notes`	string	não

Status possíveis

200 OK
404 Não encontrado

GET /api/openfinance/sessions Lista o histórico de chamadas e atendimentos de diagnóstico BPO com IA. Autenticado

Lista o histórico de chamadas e atendimentos de diagnóstico BPO com IA.

Permissão: Exige um token válido (usuário ou tenant).

Parâmetros

Nome	Onde	Tipo	Descrição
`limit`	query	integer	Limite de sessões a retornar (padrão 20).

Resposta · `List<CallSessionDto>`

Campo	Tipo	Descrição
`id`	string
`callSid`	string
`callerName`	string
`callerPhone`	string
`status`	string
`durationSeconds`	integer
`summary`	string
`actionItems`	string
`sentiment`	string
`startedAt`	datetime
`transcriptions`	CallTranscriptionDto[]

Status possíveis

200 OK

POST /api/openfinance/sessions Persiste uma sessão de atendimento de voz e transcrições no PostgreSQL. Autenticado

Persiste uma sessão de atendimento de voz e transcrições no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `SaveCallSessionRequest`

Campo	Tipo	Obrigatório
`callSid`	string	não
`callerName`	string	sim
`callerPhone`	string	não
`durationSeconds`	integer	sim
`summary`	string	não
`actionItems`	string	não
`sentiment`	string	não
`transcriptions`	CallTranscriptionDto[]	não

Status possíveis

201 Criado

GET /api/openfinance/goals Lista as metas financeiras e planejamento orçamentário do cliente no PostgreSQL. Autenticado

Lista as metas financeiras e planejamento orçamentário do cliente no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `List<CallGoalDto>`

Campo	Tipo	Descrição
`id`	string
`title`	string
`targetAmount`	decimal
`currentAmount`	decimal
`deadline`	datetime
`status`	string
`category`	string

Status possíveis

200 OK

POST /api/openfinance/goals Cria ou atualiza uma meta financeira do cliente no PostgreSQL. Autenticado

Cria ou atualiza uma meta financeira do cliente no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `UpsertGoalRequest`

Campo	Tipo	Obrigatório
`id`	string	não
`title`	string	sim
`targetAmount`	decimal	sim
`currentAmount`	decimal	sim
`deadline`	datetime	não
`status`	string	não
`category`	string	não

Resposta · `CallGoalDto`

Campo	Tipo	Descrição
`id`	string
`title`	string
`targetAmount`	decimal
`currentAmount`	decimal
`deadline`	datetime
`status`	string
`category`	string

Status possíveis

200 OK

GET /api/openfinance/missions Lista as missões de rotina financeira e tarefas pendentes no PostgreSQL. Autenticado

Lista as missões de rotina financeira e tarefas pendentes no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `List<CallMissionDto>`

Campo	Tipo	Descrição
`id`	string
`title`	string
`description`	string
`status`	string
`dueDate`	datetime
`assignedTo`	string

Status possíveis

200 OK

POST /api/openfinance/missions Cria ou atualiza uma missão financeira de rotina no PostgreSQL. Autenticado

Cria ou atualiza uma missão financeira de rotina no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `UpsertMissionRequest`

Campo	Tipo	Obrigatório
`id`	string	não
`title`	string	sim
`description`	string	não
`status`	string	não
`dueDate`	datetime	não
`assignedTo`	string	não

Resposta · `CallMissionDto`

Campo	Tipo	Descrição
`id`	string
`title`	string
`description`	string
`status`	string
`dueDate`	datetime
`assignedTo`	string

Status possíveis

200 OK

GET /api/openfinance/connect-url Retorna a URL de conexão do widget Pluggy Connect para autenticação de novas contas bancárias. Autenticado

Retorna a URL de conexão do widget Pluggy Connect para autenticação de novas contas bancárias.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `ConnectUrlResponse`

Campo	Tipo	Descrição
`url`	string
`hint`	string

Status possíveis

200 OK

GET /api/openfinance/config Obtém a configuração ativa e endpoints do toolkit MCP Open Finance. Autenticado

Obtém a configuração ativa e endpoints do toolkit MCP Open Finance.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `McpConfigDto`

Campo	Tipo	Descrição
`toolkitUrl`	string
`connectUrl`	string
`authToken`	string
`status`	string
`isConfigured`	boolean

Status possíveis

200 OK

POST /api/openfinance/config Atualiza os endpoints e credenciais do MCP Open Finance no PostgreSQL. Autenticado

Atualiza os endpoints e credenciais do MCP Open Finance no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Corpo (JSON) · `UpdateMcpConfigRequest`

Campo	Tipo	Obrigatório
`toolkitUrl`	string	não
`connectUrl`	string	não
`authToken`	string	não

Resposta · `McpConfigDto`

Campo	Tipo	Descrição
`toolkitUrl`	string
`connectUrl`	string
`authToken`	string
`status`	string
`isConfigured`	boolean

Status possíveis

200 OK

POST /api/openfinance/test Testa a conectividade com o MCP Toolkit e serviços bancários. Autenticado

Testa a conectividade com o MCP Toolkit e serviços bancários.

Permissão: Exige um token válido (usuário ou tenant).

Resposta · `OpenFinanceSyncResultDto`

Campo	Tipo	Descrição
`success`	boolean
`status`	string
`message`	string
`syncedAccounts`	integer
`syncedTransactions`	integer
`bankName`	string
`checkoutUrls`	IReadOnlyDictionary<string, string>
`isBillingNotice`	boolean

Status possíveis

200 OK

POST /api/openfinance/clear-mock Desativa dados de mock e ativa operação 100% real no PostgreSQL. Autenticado

Desativa dados de mock e ativa operação 100% real no PostgreSQL.

Permissão: Exige um token válido (usuário ou tenant).

Status possíveis

200 OK

Tudo o que a sua IA precisa para construir sobre a Brief App.

Visão geral

Autenticação

1. Token do tenant (servidor para servidor)

2. Login do usuário final

Papéis e permissões

Erros e status HTTP

Idempotência e limites

Idempotência

Limites de requisição

Tempo real e webhooks

Hubs em tempo real (SignalR)

Webhooks dos gateways de pagamento

SDK, Sidecar e Ferramentas

Identidade e acesso

Conceitos

Estados possíveis

Fluxo típico

Exemplo: Login com 2FA já configurado

Regras importantes

Referência de endpoints

Corpo (JSON) · LoginRequest

Resposta · LoginResult

Status possíveis

Corpo (JSON) · RegisterUserRequest

Resposta · UserRegistrationResult

Status possíveis

Corpo (JSON) · RefreshTokenRequest

Resposta · TokenResponse

Status possíveis

Resposta · UserProfileResponse

Status possíveis

Corpo (JSON) · Setup2faRequest

Resposta · Enable2faResult

Status possíveis

Corpo (JSON) · Verify2faRequest

Resposta · Verify2faResult

Status possíveis

Parâmetros

Status possíveis

Parâmetros

Corpo (JSON) · RejectUserRequest

Status possíveis

Parâmetros

Resposta · UserPageDto

Status possíveis

Parâmetros

Resposta · UserSummaryDto

Status possíveis

Parâmetros

Corpo (JSON) · ChangeUserStatusRequest

Resposta · UserSummaryDto

Status possíveis

Parâmetros

Resposta · UserSummaryDto

Status possíveis

Parâmetros

Resposta · UserSummaryDto

Status possíveis

Parâmetros

Corpo (JSON) · UpdateUserProfileRequest

Resposta · UserSummaryDto

Status possíveis

Corpo (JSON) · FirebaseLoginRequest

Corpo (JSON) · ConsultaKycRequest

Resposta · ConsultaKycResponse

Status possíveis

Parâmetros

Resposta · ConsultaKycResponse

Status possíveis

Agendamento

Conceitos

Estados possíveis

Fluxo típico

Exemplo: Definir a grade semanal do parceiro

Regras importantes

Referência de endpoints

Parâmetros

Resposta · AvailabilityResponse

Status possíveis

Corpo (JSON) · `LoginRequest`

Resposta · `LoginResult`

Corpo (JSON) · `RegisterUserRequest`

Resposta · `UserRegistrationResult`

Corpo (JSON) · `RefreshTokenRequest`

Resposta · `TokenResponse`

Resposta · `UserProfileResponse`

Corpo (JSON) · `Setup2faRequest`

Resposta · `Enable2faResult`

Corpo (JSON) · `Verify2faRequest`

Resposta · `Verify2faResult`

Corpo (JSON) · `RejectUserRequest`

Resposta · `UserPageDto`

Resposta · `UserSummaryDto`

Corpo (JSON) · `ChangeUserStatusRequest`

Resposta · `UserSummaryDto`

Resposta · `UserSummaryDto`

Resposta · `UserSummaryDto`

Corpo (JSON) · `UpdateUserProfileRequest`

Resposta · `UserSummaryDto`

Corpo (JSON) · `FirebaseLoginRequest`

Corpo (JSON) · `ConsultaKycRequest`

Resposta · `ConsultaKycResponse`

Resposta · `ConsultaKycResponse`

Resposta · `AvailabilityResponse`

Corpo (JSON) · `BookAppointmentRequest`

Resposta · `AgendamentoResponse`

Resposta · `AgendamentoResponse`

Corpo (JSON) · `CancelAppointmentRequest`

Corpo (JSON) · `RescheduleRequest`

Resposta · `AgendamentoResponse`

Resposta · `IReadOnlyList<RegraSemanalResponse>`

Corpo (JSON) · `SetWeeklyAvailabilityRequest`

Resposta · `IReadOnlyList<RegraSemanalResponse>`

Resposta · `IReadOnlyList<ExcecaoResponse>`

Corpo (JSON) · `AddExceptionRequest`

Resposta · `ExcecaoCriadaResponse`

Corpo (JSON) · `GenerateSlotsRequest`

Resposta · `GeracaoSlotsResponse`

Resposta · `IReadOnlyList<SlotDetalheResponse>`

Corpo (JSON) · `BlockSlotRequest`

Resposta · `AgendamentoPaginaResponse`

Resposta · `AgendamentoPaginaResponse`

Resposta · `SaldoCreditosResponse`

Corpo (JSON) · `AddCreditsRequest`

Resposta · `CreditoResponse`

Corpo (JSON) · `DebitCreditsRequest`

Resposta · `CreditoResponse`