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”A. Clientes (/api/atomic/clients)
Section titled “A. Clientes (/api/atomic/clients)”- 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 holeriteDRAFT; ID existente retorna409sem sobrescrever dados financeiros. - PUT
/api/atomic/payrollEntries: Executa somenteDRAFT → APPROVEDouAPPROVED → PAID, comexpectedStatusobrigatório e compare-and-set no D1. Conflito retorna409comcurrentStatuseadvancesAmount. 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 cicloOPENsem permitir overwrite;generatedAtegeneratedBysão derivados no servidor. ID existente retorna409, inclusive se o ciclo já estiver fechado. - PUT
/api/atomic/payrollRuns: Fecha exclusivamente um cicloOPENcomexpectedStatus: "OPEN". O mesmo statement recusa tarefas abertas no intervalo e decisões concorrentes;closedAteclosedBysã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 retorna404; tarefa aberta ou ciclo já fechado retorna409. - POST
/api/atomic/payrollGenerate: Gera atomicamente um ciclo, seus holerites obrigatoriamenteDRAFTe 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 retorna200comidempotent: true, enquanto conteúdo divergente sob o mesmorun.idretorna409sem 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:
CloudCliente toda chamada direta às APIs próprias aplicamparseApiJsonà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
CloudClientcaptura 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 um401lento repita uma leitura sob o cookie do usuário que acabou de entrar. - Ordem de mutações versionadas:
syncAtomicserializa operações do mesmoendpoint:iddentro 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 retorna409. 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(),});
C. Faturas (/api/atomic/invoices)
Section titled “C. Faturas (/api/atomic/invoices)”- POST
/api/atomic/invoices: Grava faturas conforme as validações de estado e vínculo. A emissão pelo escritório usainvoice-operationcom açãoDISPATCH. - POST
/api/billing/invoice-operation: executaVOIDouDISPATCHpara ADMIN/MANAGER (tirar uma visita de uma fatura não existe: descarta-se o rascunho, e as visitas voltam à fila). O corpo incluiinvoiceIde 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 retorna409sem 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 emdetails, que são sanitizados e reduzidos a no máximo 8.000 caracteres antes do D1.user_idetimestampsão sempre derivados da sessão e do Worker. O orçamento é 20 relatórios por conta em 5 minutos; excesso retorna429eRetry-After: 300. - GET: disponível apenas a
ADMINeMANAGER;limité normalizado entre 1 e 500 (default 200) eentityIdaceita 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
ADMINeMANAGERautenticados. - Recebe
operationIdUUID,clientId,startDateeendDateemYYYY-MM-DD; o intervalo máximo é 366 dias. - Cancela em um único statement somente visitas
PENDING,PENDING_REVIEWeSCHEDULED, com motivoCLIENT_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; visitaPENDING/SCHEDULED.{ action: 'RESCHEDULE', requestId, version, newStartDateTime, applyToSeries? }→SCHEDULEDviraPENDING_REVIEW(PENDINGsó muda a data);PENDING_REVIEWpode 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). applyToSeriesaplica a mesma mudança às próximas visitas do mesmogroupId, 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 (409se 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/requestseGET /api/atomic/clientspassam cada linha pela redação por papel, além do escopo de linhas decommon/scoping.ts. O funcionário recebe os clientes das visitas atribuídas a ele com os endereços (tabelaaddresses), no boot como noGET /atomic/clients: o postcode do trajeto (a taxa de 15 min entre distritos deestimateTravel) 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, semmarginPercent;manualLaborCostssó com a própria linha. Clientes vistos pela funcionária vêm sem carteira (walletBalance0,walletHistoryvazio), semcustomRates, pontos de fidelidade e ids do GoCardless. - CLIENT:
financials.cost/profit= 0 emanualLaborCostsvazio; o próprio registro de cliente vem completo. - ADMIN/MANAGER: sem redação.
F. Cadastro verificado por telefone
Section titled “F. Cadastro verificado por telefone”POST /api/auth/phone/startrecebependingTokenephone. O token pendente prova que senha/Google/Apple já validou a primeira etapa; o endpoint aplica rate limit D1, grava o pedido emwhatsapp_access_requestse devolve o códigoPC-xxxxpara 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/verifynem código de seis dígitos. - Telefone que já autentica outra conta recebe o magic link dessa conta; o número nunca é transferido.
G. Cotações de leads
Section titled “G. Cotações de leads”POST /api/atomic/client-quotescria ou atualiza a cotaçãoOPENdo 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/leadQuotesfornece a fila administrativa autenticada para ADMIN/MANAGER; decisões usam as rotas específicas abaixo.POST /api/atomic/leadQuotes/:id/confirmexige 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/declinemanté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 estarSENT, do mesmo cliente e entidade, e o gateway pronto (chave e segredo de webhook). Valor e taxa calculados no servidor; gravapayment_checkoutse devolve{ checkoutId, url }(ou{ status: 'SUBMITTED' }quando cobra o mandato GoCardless). Erro do gateway:502, checkoutFAILED.POST /api/payments/wallet—{ invoiceIds }. ADMIN/MANAGER ou o próprio CLIENT. DEBIT emwallet_transactions+ liquidação na mesma transação; saldo insuficiente ou fatura mudada:409sem 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çãoPENDING, visitasPENDING_CONFIRMATION; tudo ou nada (409).POST /api/webhooks/stripe?entity=<fiscalEntityId>— assinaturaStripe-Signature(tolerância 5 min) com o segredo da entidade; eventoscheckout.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; eventospayments(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;501semXERO_CLIENT_ID/XERO_CLIENT_SECRET;404para entidade não salva;409se a entidade usa o QuickBooks.GET /api/billing/xero-callback?code&state— retorno do Xero; sem sessão (ostateassinado 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 porclientBookingFields; campos de pagamento e da equipe zerados.