ZapOrca: caso técnico de um MVP de orçamento com Pix

O ZapOrca é um MVP de orçamento para prestadores de serviço autônomos: eletricista, pintor, encanador, montador de móveis. O prestador monta a proposta no celular em três passos, define o sinal que quer receber e manda tudo pelo WhatsApp, com o código Pix do sinal no próprio texto. É uma aplicação web escrita em TypeScript, sem servidor: os dados ficam no navegador do aparelho de quem usa.

Este caso técnico mostra o que o código faz, como o Pix é montado sem intermediário, os erros que viraram regra e o que um MVP sem usuários ainda não prova. Os números foram conferidos no repositório na versão de 30/10/2026, a mais recente.

Transparência: o ZapOrca foi concebido e desenvolvido por Jeremias Cardoso, autor deste blog. O texto não cita empresa, pessoas nem cidade, e deixa de fora credenciais e detalhes de segurança.

Nota de atualização (30/10/2026): este post foi reescrito como caso técnico. A versão de 21/09/2026, já corrigida em 29/10 sobre o QR Code dinâmico, também dizia que os orçamentos eram sincronizados com um servidor quando a conexão voltava, que os dados ficavam num banco PostgreSQL com controle de acesso por linha e que a validação usava a biblioteca Zod. Conferido no código, o produto publicado não tem servidor desde 09/10/2026, a validação é própria e a proposta em PDF sai da impressão do navegador. O link da proposta, que a versão anterior apresentava como o caminho do cliente, só abre no aparelho de quem a criou; desde 30/10/2026 o código Pix vai no texto da mensagem. Este texto descreve o que o código faz.

O problema: o orçamento que vira conversa solta

O cliente pede um orçamento, e o prestador responde com uma mensagem de texto corrida ou com uma foto de papel. Faltam o número da proposta, a validade, o valor do sinal e a forma de pagar. Quando o cliente aceita, alguém ainda precisa passar a chave Pix, e o valor do sinal é digitado à mão, com chance de erro dos dois lados.

O ZapOrca ataca esse trecho, e só ele: transformar o que o prestador sabe sobre o serviço numa proposta com itens, total, sinal, saldo e prazo, e entregar ao cliente uma mensagem que já traz o código Pix do sinal com o valor certo. O resto da relação continua humano. É a mesma linha de outros casos do blog, como o catálogo que fecha pedidos no WhatsApp: automatizar o artefato, não a conversa.

O MVP em números

Números do repositório em 30/10/2026, data do último commit.

O repositório não registra nenhum prestador usando o produto. A tarefa de convidar os primeiros dez prestadores conhecidos pelo WhatsApp, sem mídia paga, consta como não iniciada.

Três passos no celular

A proposta nasce num assistente de três passos: o cliente, os itens e o fechamento. No primeiro, entram o nome e o WhatsApp do cliente e o título do serviço, que são obrigatórios, e, se o prestador quiser, o endereço da obra e o prazo. No segundo, cada item tem descrição, quantidade, unidade e valor unitário, e o subtotal é calculado na hora. Para não digitar tudo do zero, há um catálogo com 43 itens prontos em 8 nichos: elétrica, pintura, hidráulica, ar-condicionado, montagem de móveis, pequenos reparos, obras e gesso, e limpeza.

No terceiro passo ficam o desconto, em valor fixo ou em porcentagem, o sinal (sem sinal, 30%, 50% ou 100%) e um texto livre de termos, prazos e garantia. Sete cláusulas prontas podem entrar nesse texto com um toque: garantia, retenção do sinal em caso de cancelamento, escopo e retrabalho, quitação na entrega, materiais fornecidos pelo cliente, limpeza do entulho e uso de fotos do serviço.

A conta é simples e fica numa função própria, coberta por testes. O desconto nunca passa do subtotal, o sinal é uma porcentagem do total entre 0 e 100, e o saldo é o que sobra. Todo valor é arredondado em centavos a cada etapa.

Desde 30/10/2026, o último passo tem uma trava: sem uma chave Pix válida do próprio prestador no perfil, o orçamento não é criado. O app avisa e abre o perfil. O motivo está num comentário do código: sem essa chave, o Pix iria para outra pessoa ou para lugar nenhum.

O Pix montado no próprio aparelho

O código Pix que o cliente cola no banco é um texto no padrão BR Code, definido pelo Banco Central. O ZapOrca monta esse texto no navegador, sem chamar nenhum serviço de pagamento. A montagem segue o formato TLV, em que cada campo leva um identificador de dois dígitos, o tamanho e o valor:

• o indicador de formato;
• a marca de código de uso único, um por orçamento;
• a conta do recebedor: o identificador do Pix e a chave do prestador;
• a moeda, com o código 986, do real;
• o valor do sinal, ou o total quando a proposta é sem sinal;
• o país, o nome e a cidade do recebedor, sem acento e em maiúsculas, com 25 e 15 caracteres no máximo;
• o identificador da transação, tirado do número do orçamento.

No fim vem o CRC16, uma soma de verificação de 16 bits que o app do banco confere antes de aceitar o código. O cálculo usa o polinômio 0x1021 com valor inicial 0xFFFF, e os testes conferem o resultado contra o valor de referência desse algoritmo.

Antes de entrar no código, a chave passa por duas etapas. A validação aceita os cinco tipos do Pix: CPF e CNPJ com os dígitos verificadores conferidos, telefone, e-mail com até 77 caracteres e chave aleatória. A normalização põe a chave no formato em que ela é registrada: CPF e CNPJ só com dígitos, telefone com +55 e DDD, e-mail e chave aleatória em minúsculas. Uma chave com pontuação ou sem o código do país é o tipo de erro que o banco do cliente recusa, e a venda esfria no meio.

Esse é um Pix estático: o código carrega a chave e o valor, e não aponta para uma cobrança hospedada. Por isso o ZapOrca não sabe se o cliente pagou. Quem marca “recebi o sinal” é o prestador, depois de olhar o app do banco, e a própria mensagem avisa o cliente de que o ZapOrca não confirma o pagamento.

O QR Code também é desenhado no aparelho. Ele usa o modo byte com correção de erro de nível M, numa implementação própria que substituiu a biblioteca usada antes. A troca foi feita com uma rede de segurança: as matrizes geradas pela biblioteca antiga para dois textos, um curto e um com o tamanho de um código Pix, ficaram congeladas em arquivos, e dois testes exigem que a implementação nova reproduza cada uma, módulo a módulo.

O que vai para o WhatsApp

A mensagem é montada pelo app e aberta no WhatsApp do prestador, já com o número do cliente. Ela usa o negrito do próprio WhatsApp e põe um fato por linha: serviço, número, até seis itens, total, sinal, saldo na conclusão, prazo, validade e condição. Se houver mais de seis itens, uma linha avisa quantos ficaram de fora. A condição de pagamento é um texto fixo, que fala em 30% de sinal, e vai na mensagem e na proposta mesmo quando o prestador escolhe outro percentual.

O código Pix só entra no texto quando a chave é do próprio prestador. Logo depois vêm duas frases: o valor cai na chave Pix do prestador, e o ZapOrca não confirma o pagamento do banco.

Há duas versões do texto. A primeira usa emojis para marcar cada linha. A segunda existe por causa de um problema do WhatsApp no computador, que trocava parte dos emojis por um ponto de interrogação. O código chama essa versão de modo “Anti-’?’”: as mesmas informações, com marcadores simples. O prestador escolhe a versão antes de enviar, e pode copiar o texto em vez de abrir o link.

A proposta em PDF é a impressão do navegador

A proposta formal é uma página HTML em formato A4, com o logotipo do prestador, os itens e os totais. O botão “PDF” abre essa página numa janela e chama a impressão do navegador, em que a pessoa escolhe salvar em PDF. Também dá para baixar a mesma proposta como um arquivo HTML.

Nada disso vai sozinho para o WhatsApp. O que segue pela conversa é o texto da mensagem; o PDF, quando o prestador quiser mandá-lo, é um arquivo que ele anexa à mão. O logotipo é reduzido no próprio aparelho para no máximo 360 por 180 pixels antes de ser guardado, para a proposta abrir rápido e caber no armazenamento do navegador.

Os dados ficam no aparelho

O perfil, os orçamentos e a fila de ações ficam no armazenamento do navegador. O perfil e os orçamentos também têm cópia no IndexedDB, um banco do próprio navegador com mais espaço. A conta é opcional e local: o cadastro pede o consentimento da LGPD e grava a conta só naquele navegador. A primeira proposta não exige conta.

A exclusão da conta apaga, naquele aparelho, o perfil, os orçamentos, a fila, as transações e a conta. A confirmação exige digitar o e-mail da conta, e o botão fica bloqueado até o texto bater.

O tema claro ou escuro e o idioma da casca e da página inicial (português, inglês e espanhol) usam as mesmas chaves do portal de ferramentas do autor, onde o projeto registra o ZapOrca como uma porta separada das ferramentas grátis. O assistente e a proposta são só em português.

Plano grátis e ZapOrca Pro

O plano grátis permite até cinco propostas. O Pro libera propostas sem limite, muda o rodapé da proposta e permite exportar a lista para uma planilha CSV, com ponto e vírgula e acentos preservados para abrir direto no Excel. Ele custa R$ 29,90 por ano, sem renovação automática.

A compra é manual: o comprador faz um Pix, envia o comprovante por e-mail ou WhatsApp e recebe um código de licença, que digita no app. A licença pode ser desativada naquele aparelho. Não há cobrança recorrente.

Incidentes que viraram regra

1. A nuvem que saiu (08 e 09/10/2026). A primeira versão tinha conta na nuvem, sincronização com um banco remoto e regras de acesso por linha. Na publicação no portal, a decisão foi tirar tudo isso, para o prestador usar o primeiro orçamento sem depender de um serviço externo. Saíram o cliente do banco remoto, a biblioteca de validação e a de QR Code, e o produto ficou sem nenhuma dependência em tempo de execução. A regra que ficou na memória do projeto: tabela remota só volta se o dono decidir ter servidor de novo.
2. O teto de 5 MB (15/10/2026). Com logotipo e histórico, o armazenamento simples do navegador, de cerca de 5 MB, ficaria curto. Os orçamentos e o perfil passaram a ter cópia no IndexedDB, e o logotipo passou a ser reduzido antes de ser guardado.
3. O ponto de interrogação no lugar do emoji (15/10/2026). No WhatsApp do computador, parte dos emojis da mensagem chegava como ”?”. Nasceu a segunda versão do texto, sem esses símbolos, com uma dica na tela explicando quando usá-la.
4. Dois defeitos de tela que nenhum teste pegou. O tema escuro mostrou fundo claro com letra clara, porque o tema do aparelho e o tema escolhido no portal são coisas diferentes, e só a letra seguia o segundo. A folha do Pix abria sozinha, porque uma regra de exibição empatava com a regra que a escondia. Os dois foram corrigidos no estilo e ficaram registrados nas lições do projeto. Teste automático de regra não pega esse tipo de defeito.
5. O exemplo que cobrava para o autor (até 30/10/2026). Quem abria o app pela primeira vez recebia um perfil de exemplo com a chave Pix real do autor. Um prestador que fizesse um orçamento sem editar o perfil mandaria ao cliente um Pix que pagava o autor. Hoje o app começa sem chave, os orçamentos de exemplo usam a chave aleatória nula, que não pertence a ninguém, e o orçamento só é criado com a chave do prestador. Quem já tinha o perfil antigo guardado no aparelho tem a chave e os códigos Pix apagados na abertura seguinte. A lição vale para qualquer produto: dado de exemplo é dado de produção.
6. O link que só abria no aparelho de quem criou (até 30/10/2026). A mensagem levava um link para a proposta. Só que a proposta mora no navegador do prestador, e o link busca nesse armazenamento: no celular do cliente, a tela dizia “Proposta não encontrada ou expirada”, e o código Pix só existia ali. A correção foi pôr o Pix copia e cola no texto da mensagem e tirar o link, e o botão da tela de detalhes passou a copiar o código Pix. Em produto sem servidor, o que precisa chegar ao cliente vai dentro da mensagem.

Testes: muitos na regra, nenhum no navegador versionado

Os 131 testes rodam com o Vitest e cobrem a montagem do Pix e o CRC, a validação de chaves e de CPF e CNPJ, o QR Code contra as matrizes congeladas, o cálculo de totais e a máquina de estados do orçamento, a mensagem do WhatsApp, o perfil de exemplo, as cláusulas, o catálogo, a conta local, a exclusão de dados e a licença Pro. Nesta revisão, a suíte rodou inteira: 131 de 131, em 15 arquivos, e o build de produção terminou sem erro.

Dois cuidados na leitura desse número. Primeiro, ao menos 22 testes conferem peças da fase com servidor: 16 testam um modelo em memória do antigo banco remoto, 4 testam a reconciliação com a nuvem, que o app não chama mais, e outros 2 cobrem o esvaziamento da fila e um aviso de pagamento simulado. Eles ainda passam, mas não provam nada sobre o app atual. Segundo, não há teste de interface no repositório. A memória do projeto registra uma rodada de testes no navegador em 15/10, mas ela não está versionada, e foi na tela que nasceram os defeitos de tema e da folha do Pix.

O que ainda não está resolvido

Os itens abaixo vêm da leitura do código. A suíte foi rodada, mas o app não foi usado num navegador para esta revisão.

• Nenhum usuário ainda. O MVP não tem registro de uso. Preço, plano grátis e mensagem são hipóteses até os primeiros prestadores usarem.
• Os exemplos contam para o teto do plano grátis. O app guarda três orçamentos de exemplo na primeira abertura, e a verificação do teto conta todos os orçamentos guardados. Quem não apaga os exemplos faz duas propostas próprias antes de ver o convite para o Pro.
• A numeração pode repetir. O número é “ORC-2026-” seguido da quantidade de orçamentos guardados mais um. O ano está fixo no código, e apagar um orçamento faz o próximo número repetir um que já existe.
• Um aparelho só. Limpar os dados do navegador ou trocar de celular leva os orçamentos junto. A cópia possível é baixar cada proposta em HTML ou, no Pro, exportar a lista em CSV.
• A fila sem destino. A fila de ações foi desenhada para um servidor. Sem ele, esvaziar a fila marca cada item como enviado sem enviar nada. O código de reconciliação com a nuvem também continua no repositório.
• Pagamento não confirmado. O app não fala com banco nenhum; o “recebi o sinal” depende do prestador.
• Condição de pagamento fixa. O texto da condição fala em 30% de sinal mesmo quando o prestador escolhe sem sinal, 50% ou 100%.
• O link que ficou nos textos. O link da proposta saiu da mensagem em 30/10/2026, mas a página inicial do app ainda promete “o link da proposta”, a mensagem com mais de seis itens ainda manda ver o resto “no link” e o README ainda descreve o link.
• Publicação manual. Este texto descreve o código do repositório. A publicação no portal é um passo à parte, feito pelo dono.

Lições que valem fora do orçamento

1. Dado de exemplo é dado de produção. Chave, e-mail ou telefone de verdade num exemplo vai parar na mão de quem não editou nada.
2. Sem servidor, o que o cliente precisa vai dentro da mensagem. Link que aponta para o armazenamento de outro aparelho não abre.
3. Tirar o servidor é decisão de produto. Ganha-se custo zero e começo sem cadastro; perde-se backup, segundo aparelho e confirmação de pagamento.
4. Ao trocar uma biblioteca, congele a saída dela antes. A matriz antiga virou o teste da implementação nova.
5. Teste de arquitetura aposentada engana. Ele passa e infla o total sem provar nada sobre o produto atual.
6. Contagem não é identificador. Número de documento que depende de quantos existem se repete quando algo é apagado.
7. MVP sem usuário é hipótese. O código pronto não responde se alguém vai usar; só os primeiros prestadores respondem. O VE Facilites, um piloto ainda sem cliente contratado, e o Embalo, ainda em implementação, estão no mesmo ponto.

Fontes

• Código, documentação, histórico de commits e testes: repositório do ZapOrca na versão de 30/10/2026, lido pelo autor, com a suíte de testes e o build rodados localmente em 30/10/2026; extrato com os trechos, o método da contagem e os limites da verificação, verificado em 2026-10-30.
• Manual de Padrões para Iniciação do Pix e especificações técnicas de QR Code e Pix Copia e Cola — Banco Central do Brasil (BACEN) (regulamentação oficial), verificado em 2026-09-21.