Skip to content

Catálogo Completo da API REST & Schemas Zod

Catálogo Completo da API REST & Schemas Zod

Section titled “Catálogo Completo da API REST & Schemas Zod”

Todos os endpoints sob /api/atomic/ seguem o padrão de mutação atômica atemporal, validando entradas via Zod schemas antes de interagir com o Cloudflare D1.


📡 1. Matriz de Endpoints Atômicos (/api/atomic/*)

Section titled “📡 1. Matriz de Endpoints Atômicos (/api/atomic/*)”
graph LR
    subgraph Client ["Client Services (EntitiesApiClient)"]
        Req["syncAtomic() / EntitiesApiClient"]
    end

    subgraph API ["Pages Functions Handlers"]
        C["/api/atomic/clients"]
        E["/api/atomic/employees"]
        R["/api/atomic/requests"]
        I["/api/atomic/invoices"]
        P["/api/atomic/payroll-runs"]
    end

    subgraph DB ["Cloudflare D1 (SQLite)"]
        D1[("Tables: clients, employees, service_requests...")]
    end

    Req --> C
    Req --> E
    Req --> R
    Req --> I
    Req --> P

    C --> D1
    E --> D1
    R --> D1
    I --> D1
    P --> D1

📋 2. Detalhamento dos Principais Endpoints

Section titled “📋 2. Detalhamento dos Principais Endpoints”
  • GET /api/atomic/clients: Retorna a lista completa de clientes cadastrados.
  • POST /api/atomic/clients: Cria ou atualiza um cliente.
  • Schema Zod:
    const clientSchema = z.object({
    id: z.string().optional(),
    name: z.string().min(2, "Nome é obrigatório"),
    email: z.string().email("E-mail inválido"),
    phone: z.string().min(8, "Telefone é obrigatório"),
    address: z.string().min(5, "Endereço é obrigatório"),
    preferredLanguage: z.enum(["pt-BR", "en-GB", "es-ES"]).default("en-GB"),
    });

B. Solicitações de Serviço (/api/atomic/requests)

Section titled “B. Solicitações de Serviço (/api/atomic/requests)”
  • GET /api/atomic/requests: Retorna os agendamentos.
  • POST /api/atomic/requests: Insere ou atualiza o status de um serviço.
  • POST /api/atomic/payrollEntries: Cria exclusivamente um holerite DRAFT; ID existente retorna 409 sem sobrescrever dados financeiros.
  • PUT /api/atomic/payrollEntries: Executa somente DRAFT → APPROVED ou APPROVED → PAID, com expectedStatus obrigatório e compare-and-set no D1. Conflito retorna 409 com currentStatus e advancesAmount. A liquidação vencedora usa um único batch D1 tokenizado para mudar o status, liquidar adiantamentos pendentes e reconciliar o total descontado antes da resposta.
  • POST /api/atomic/payrollRuns: Cria um ciclo OPEN sem permitir overwrite; generatedAt e generatedBy são derivados no servidor. ID existente retorna 409, inclusive se o ciclo já estiver fechado.
  • PUT /api/atomic/payrollRuns: Fecha exclusivamente um ciclo OPEN com expectedStatus: "OPEN". O mesmo statement recusa tarefas abertas no intervalo e decisões concorrentes; closedAt e closedBy são autoritativos e retornam ao cliente. Os horários de criação, geração e fechamento retornados por essas rotas são ISO 8601 UTC (Z) para parsing idêntico nas quatro plataformas. Ciclo inexistente retorna 404; tarefa aberta ou ciclo já fechado retorna 409.
  • POST /api/atomic/payrollGenerate: Gera atomicamente um ciclo, seus holerites obrigatoriamente DRAFT e o depósito opcional da reserva. Um token interno limita dependentes ao batch que venceu a criação do ciclo; colisão reverte o conjunto. Retry equivalente retorna 200 com idempotent: true, enquanto conteúdo divergente sob o mesmo run.id retorna 409 sem anexar linhas. Saldo, autoria e horários são derivados no servidor e retornados ao cliente.
  • Contrato temporal de /api/boot: campos de instante no formato SQLite (YYYY-MM-DD HH:mm:ss) são normalizados para ISO 8601 UTC antes da resposta. O contrato inclui registros principais e objetos aninhados montados a partir das tabelas normalizadas: incidentes, check-in/out, edições, carteira, pagamentos, adiantamentos e último sync de calendário. Datas civis sem horário, rótulos e valores já zonados permanecem inalterados, evitando mudança de hora/dia entre Safari e Chromium.
  • Contrato temporal incremental: CloudClient e toda chamada direta às APIs próprias aplicam parseApiJson às respostas JSON, incluindo autenticação, portais públicos, uploads, IA, WhatsApp e ações operacionais. O parser percorre objetos/arrays recém-criados e converte apenas campos de instante camelCase ou snake_case com a forma SQLite exata; datas civis, texto comum, valores já zonados e respostas primitivas não mudam. Um teste de contrato impede novos parsings diretos fora do parser compartilhado e de integrações externas explicitamente permitidas. Assim uma mutação não reintroduz divergência até o próximo /api/boot.
  • Fronteira de sessão do cliente HTTP: cada operação autenticada no CloudClient captura a geração da sessão corrente. Login confirmado, logout, revogação remota, magic link, biometria e impersonação avançam essa geração; respostas e replays de refresh pertencentes à identidade anterior são descartados como cancelados. O refresh compartilhado continua evitando tempestade de requests, sem permitir que um 401 lento repita uma leitura sob o cookie do usuário que acabou de entrar.
  • Ordem de mutações versionadas: syncAtomic serializa operações do mesmo endpoint:id dentro da geração de sessão que as criou. Edições rápidas de uma tarefa carregam versões consecutivas e chegam ao Worker nessa ordem; se a predecessora falhar, as posteriores não são enviadas e a query correspondente é revalidada. Login, logout ou revogação cancelam sucessores ainda enfileirados e impedem invalidação tardia do cache da nova conta. Recursos distintos continuam em paralelo. Os endpoints de cliente, profissional e tarefa aceitam somente a versão persistida ou a sua sucessora imediata, para manter compatibilidade com helpers legados já incrementados sem permitir que uma tela antiga salte o lock com uma versão arbitrária.
  • POST /api/atomic/cashReserve: Registra uma retirada manual de reserva para ADMIN. O saldo e o autor são derivados no servidor; saldo insuficiente ou reutilização conflitante do ID retorna 409. Retry idêntico devolve a linha já aceita.
  • Schema Zod:
    const requestSchema = z.object({
    id: z.string().optional(),
    clientId: z.string(),
    serviceId: z.string(),
    status: z.enum(["REQUESTED", "PENDING", "CONFIRMED", "IN_PROGRESS", "COMPLETED", "CANCELLED"]),
    scheduledDate: z.string(),
    totalPrice: z.number().positive(),
    });
  • POST /api/atomic/invoices: Grava faturas conforme as validações de estado e vínculo. A emissão pelo escritório usa invoice-operation com ação DISPATCH.
  • POST /api/billing/invoice-operation: executa VOID ou DISPATCH para ADMIN/MANAGER (tirar uma visita de uma fatura não existe: descarta-se o rascunho, e as visitas voltam à fila). O corpo inclui invoiceId e status/IDs esperados. O Worker revalida a transição e os vínculos persistidos; um único batch D1 atualiza payment status/versão das visitas e a fatura. Snapshot concorrente retorna 409 sem alteração parcial.

D. Telemetria do cliente (/api/atomic/system-logs)

Section titled “D. Telemetria do cliente (/api/atomic/system-logs)”
  • POST: disponível a usuários autenticados exceto CLIENT; aceita IDs/ação/entidade limitados por Zod e até 100 kB brutos em details, que são sanitizados e reduzidos a no máximo 8.000 caracteres antes do D1. user_id e timestamp são sempre derivados da sessão e do Worker. O orçamento é 20 relatórios por conta em 5 minutos; excesso retorna 429 e Retry-After: 300.
  • GET: disponível apenas a ADMIN e MANAGER; limit é normalizado entre 1 e 500 (default 200) e entityId aceita no máximo 256 caracteres.
  • Credenciais em URLs, mensagens, stacks ou contexto são redigidas novamente no servidor, independentemente da versão do aplicativo cliente. Erros internos retornam mensagem estável sem detalhes do D1.

E. Pausa de férias (POST /api/scheduling/holiday-suspension)

Section titled “E. Pausa de férias (POST /api/scheduling/holiday-suspension)”
  • Disponível somente para ADMIN e MANAGER autenticados.
  • Recebe operationId UUID, clientId, startDate e endDate em YYYY-MM-DD; o intervalo máximo é 366 dias.
  • Cancela em um único statement somente visitas PENDING, PENDING_REVIEW e SCHEDULED, com motivo CLIENT_HOLIDAY, atualização financeira e incremento de versão.
  • Repetir o mesmo UUID e payload devolve o conjunto original sem reaplicar a mutação. Reutilizar o UUID com cliente ou datas diferentes retorna 409.

E2. Cancelar ou remarcar a própria visita (POST /api/scheduling/client-change)

Section titled “E2. Cancelar ou remarcar a própria visita (POST /api/scheduling/client-change)”
  • Somente CLIENT, e só visitas do próprio cliente (outra → 404). Staff edita por /atomic/requests, que recusa qualquer update de CLIENT.
  • { action: 'CANCEL', requestId, version, reason, applyToSeries? } → CANCELLATION_REVIEW; visita PENDING/SCHEDULED.
  • { action: 'RESCHEDULE', requestId, version, newStartDateTime, applyToSeries? } → SCHEDULED vira PENDING_REVIEW (PENDING só muda a data); PENDING_REVIEW pode ser remarcada de novo. Data no passado → 400.
  • A taxa vem da política gravada (calculatePolicyFee), nunca do navegador; um crédito de fidelidade é gasto com decremento condicional (bonus_cancellations > 0) e devolvido se a visita mudou no meio (409).
  • applyToSeries aplica a mesma mudança às próximas visitas do mesmo groupId, sem segunda taxa; visitas passadas ou finalizadas ficam intactas.
  • Responde { success, fee, usedBonus, requests: [{ id, status, startDateTime, financials, cancellationReason, originalDateTime, version }] }.

E3. Suprimentos informados pela equipe (POST /api/field/shopping-list)

Section titled “E3. Suprimentos informados pela equipe (POST /api/field/shopping-list)”
  • { requestId, items: [{ label, ... }] (1–50) }. EMPLOYEE só na visita em que está escalado; ADMIN/MANAGER em qualquer uma; CLIENT → 403.
  • Mescla na lista do cliente por label (item repetido substitui o antigo) e grava condicionada à versão do cliente (409 se mudou no meio). Responde { success, clientId, shoppingList, version }.

E4. Campos visíveis por papel (common/roleRedaction.ts)

Section titled “E4. Campos visíveis por papel (common/roleRedaction.ts)”
  • /api/boot, GET /api/atomic/requests e GET /api/atomic/clients passam cada linha pela redação por papel, além do escopo de linhas de common/scoping.ts. O funcionário recebe os clientes das visitas atribuídas a ele com os endereços (tabela addresses), no boot como no GET /atomic/clients: o postcode do trajeto (a taxa de 15 min entre distritos de estimateTravel) e as notas de acesso vêm dali. Até 2026-09-24 o boot não os mandava e a rota do funcionário saía 15 min mais curta que a do gerente.
  • EMPLOYEE: financials.cost/profit = 0, sem marginPercent; manualLaborCosts só com a própria linha. Clientes vistos pela funcionária vêm sem carteira (walletBalance 0, walletHistory vazio), sem customRates, pontos de fidelidade e ids do GoCardless.
  • CLIENT: financials.cost/profit = 0 e manualLaborCosts vazio; o próprio registro de cliente vem completo.
  • ADMIN/MANAGER: sem redação.
  • POST /api/auth/phone/start recebe pendingToken e phone. O token pendente prova que senha/Google/Apple já validou a primeira etapa; o endpoint aplica rate limit D1, grava o pedido em whatsapp_access_requests e devolve o código PC-xxxx para o rascunho do WhatsApp do visitante.
  • A conta só nasce quando esse número escreve no WhatsApp. O inbound completa o cadastro e responde com o mesmo magic login link do resto do sistema. Não existe POST /api/auth/phone/verify nem código de seis dígitos.
  • Telefone que já autentica outra conta recebe o magic link dessa conta; o número nunca é transferido.
  • POST /api/atomic/client-quotes cria ou atualiza a cotação OPEN do cliente ou lead da sessão (mesmo formulário no app). O dono vem da sessão; o endereço é um que a pessoa já deu (address) ou um novo (newAddress), guardado na quote e criado no cadastro na confirmação.
  • GET /api/atomic/leadQuotes fornece a fila administrativa autenticada para ADMIN/MANAGER; decisões usam as rotas específicas abaixo.
  • POST /api/atomic/leadQuotes/:id/confirm exige ADMIN/MANAGER, entidade fiscal e preço; cria/reutiliza cliente, cria atendimento, aplica VAT e reponta a conta ligada ao lead.
  • POST /api/atomic/leadQuotes/:id/decline mantém o contato como lead, preserva a cotação como histórico, registra a decisão no chat e cancela follow-ups pendentes.
  • As rotas públicas antigas de conversão direta não existem mais. Cliente e atendimento só nascem na confirmação administrativa.

H. Pagamentos (/api/payments/*) e webhooks de gateway

Section titled “H. Pagamentos (/api/payments/*) e webhooks de gateway”
  • POST /api/payments/checkout — { invoiceIds (1–10), method: 'STRIPE' | 'GOCARDLESS' | 'CREZCO', returnPath? }. ADMIN/MANAGER qualquer fatura; CLIENT só as próprias; sem sessão só uma fatura (link /pay, rate limit 10/10 min). Faturas precisam estar SENT, do mesmo cliente e entidade, e o gateway pronto (chave e segredo de webhook). Valor e taxa calculados no servidor; grava payment_checkouts e devolve { checkoutId, url } (ou { status: 'SUBMITTED' } quando cobra o mandato GoCardless). Erro do gateway: 502, checkout FAILED.
  • POST /api/payments/wallet — { invoiceIds }. ADMIN/MANAGER ou o próprio CLIENT. DEBIT em wallet_transactions + liquidação na mesma transação; saldo insuficiente ou fatura mudada: 409 sem efeito.
  • POST /api/payments/transfer-claim — { invoiceIds, reference? }. Mesmos papéis do checkout (sem sessão: uma fatura, 5/10 min). SENT → PENDING_REVIEW, transação PENDING, visitas PENDING_CONFIRMATION; tudo ou nada (409).
  • POST /api/webhooks/stripe?entity=<fiscalEntityId> — assinatura Stripe-Signature (tolerância 5 min) com o segredo da entidade; eventos checkout.session.completed, …async_payment_succeeded, …async_payment_failed, …expired. Sem assinatura válida: 401.
  • POST /api/webhooks/gocardless?entity=<fiscalEntityId> — Webhook-Signature (HMAC do corpo) com o segredo da entidade; eventos payments (confirmed, paid_out, failed, cancelled, charged_back). O pagamento é relido na API do GoCardless. Sem assinatura válida: 498.
  • GET /api/billing/xero?action=status — ADMIN/MANAGER. { configured, connections: [{ fiscalEntityId, tenantName, bankAccountName, connectedAt, lastSyncAt, lastError, vatReady, failedCount }] }; nunca um token.
  • GET /api/billing/xero?action=auth-url&fiscalEntityId= — somente ADMIN; 501 sem XERO_CLIENT_ID/XERO_CLIENT_SECRET; 404 para entidade não salva; 409 se a entidade usa o QuickBooks.
  • GET /api/billing/xero-callback?code&state — retorno do Xero; sem sessão (o state assinado identifica entidade e admin, que é conferido de novo). Volta a Settings com ?xero=connected|denied|expired|forbidden|several|error|unavailable.
  • POST /api/billing/xero — { action: 'retry', fiscalEntityId } (ADMIN/MANAGER) reenvia até 10 falhas e devolve { sentCount, failedCount, remaining }; { action: 'disconnect', fiscalEntityId } só ADMIN (revoga o token e apaga a conexão).
  • /api/billing/quickbooks (por entidade fiscal) — as mesmas ações do Xero: ?action=status, ?action=auth-url (409 se a entidade usa o Xero), POST { action: 'retry' | 'disconnect', fiscalEntityId }; retorno do Intuit em /api/billing/quickbooks-callback?code&realmId&state (?qb=…).
  • POST /api/atomic/requests (inserção por CLIENT) — preço, VAT e entidade fiscal recalculados no servidor por clientBookingFields; campos de pagamento e da equipe zerados.