DEV Community: Felipe Ricarte

Multitenancy de verdade num SaaS de PDV: as decisões que você não pode errar

Felipe Ricarte — Wed, 17 Jun 2026 16:46:01 +0000

Quem decide construir um SaaS para o varejo costuma subestimar a mesma coisa: não é a tela do PDV que dá trabalho. É tudo o que sustenta vários comércios rodando no mesmo sistema sem um ver os dados do outro, sem uma cobrança vazar, sem uma nota fiscal travar a venda.

Essas decisões de fundação, se erradas no início, custam uma reescrita lá na frente. Vamos às que mais importam.

1. Isolamento de tenant: a decisão que atravessa tudo

Há três caminhos para multitenancy: um banco por cliente, um schema por cliente, ou uma coluna tenant_id compartilhada. Para um SaaS de PMEs com muitos clientes pequenos, coluna compartilhada é o equilíbrio certo entre custo e simplicidade — mas só funciona se o isolamento for inescapável.

O erro clássico é confiar que cada query vai lembrar de filtrar por tenant. Uma esquecida e um comércio vê a venda do outro. A defesa é tornar o tenant parte do contexto da requisição, resolvido num filtro HTTP antes de qualquer lógica:

// Filtro resolve o tenant uma vez; o resto do código nunca "esquece"
String tenantId = header("X-Tenant-Id"); // ou claim tenant_id do JWT em produção
TenantContext.set(tenantId);

{data-source-line="832"}

A partir daí, todo acesso a dados parte do contexto — não de um parâmetro que alguém pode omitir.

2. Fiscal não pode derrubar a venda

Emissão de NFC-e/NF-e depende da SEFAZ, e a SEFAZ cai. Se a emissão for síncrona dentro da venda, o dia em que a SEFAZ ficar lenta, seu PDV trava e o caixa para.

A venda e a emissão fiscal são responsabilidades diferentes. Use o padrão outbox: registre a venda e a intenção de emitir na mesma transação; um processo separado emite contra o provedor fiscal com retry.

BEGIN;
  INSERT INTO venda (...) VALUES (...);
  INSERT INTO outbox (tipo, payload, status) VALUES ('EmitirNFCe', ?, 'PENDENTE');
COMMIT;

{data-source-line="847"}

A venda fecha na hora; a nota é emitida de forma resiliente. SEFAZ instável vira "nota pendente", não "loja parada".

3. Cobrar a mensalidade — e cortar o inadimplente — sem trabalho manual

Um SaaS vive da recorrência. Mas controlar quem pagou, quem atrasou e quem deve perder acesso vira um pesadelo manual rápido. A resposta é ligar o estado da assinatura ao próprio acesso da API: o tenant inadimplente recebe HTTP 402 (Payment Required) até regularizar.

if (assinatura.inadimplente()) {
    throw new PaymentRequiredException(); // 402: bloqueia o tenant, reativa sozinho ao pagar
}

{data-source-line="859"}

Suspensão e reativação automáticas, sem ninguém ligando ou desligando cliente na mão.

4. Onboarding self-service: o cliente entra sozinho

Se cada novo comércio exige você criar tenant, loja e admin manualmente, o SaaS não escala. O cadastro precisa ser uma chamada que provisiona tudo — tenant, loja, usuário admin, assinatura (com trial) e até dados de demonstração para o cliente ver valor no primeiro minuto.

POST /api/v1/public/onboarding
→ cria tenant + loja + admin + assinatura (trial) + dados demo

Onboarding automático é o que separa um sistema que você "instala para cada cliente" de um SaaS que cresce sozinho.

O custo real é a soma

Nenhuma dessas decisões é exótica. O problema é que são meses somando isolamento multitenant, autenticação com RBAC, fiscal resiliente, billing recorrente, onboarding, observabilidade — antes de vender a primeira licença. E qualquer uma mal resolvida no começo vira dívida cara.

Atalho

Eu construí exatamente essa fundação como um boilerplate completo: PDV + retaguarda multitenant em Java 21/Quarkus e Next.js, com fiscal (outbox), cobrança recorrente com suspensão automática, onboarding self-service e observabilidade — tudo documentado e rodando via Docker Compose.

É o ComercialCloud. Se você vai entrar no mercado de PDV/varejo, ele te poupa meses e te entrega uma base que já nasceu pensando nos erros caros.

👉 [Conheça o ComercialCloud(https://pay.kiwify.com.br/XOuVLZc)

Quer trocar ideia sobre alguma dessas decisões de arquitetura? Comenta aí.

RAG sobre o seu próprio código: o encanamento que separa o protótipo do produto

Felipe Ricarte — Wed, 17 Jun 2026 16:42:37 +0000

"Vamos colocar uma IA pra responder perguntas sobre o nosso código." A frase parece simples, e um protótipo sai numa tarde: joga uns arquivos num embedding, guarda num índice, faz a busca. Funciona na demo.

O problema aparece quando isso vira produto: respostas inconsistentes, vetores que não batem com o banco, cada cliente vendo dados do outro, e um acoplamento total a um provedor de LLM. O que separa o protótipo do produto é o encanamento — e ele é mais chato do que parece.

1. A dimensão do vetor é um contrato (e quase ninguém trata)

O erro de RAG mais silencioso: você indexa com um modelo de embeddings de 1536 dimensões, depois troca para um de 768, e o banco continua esperando vector(1536). Nada explode na cara — as buscas só ficam sutilmente erradas.

A coluna do banco e o modelo são um contrato. Trate como tal: valide no arranque.

# Probe de arranque: materializa um embedding e falha cedo se a dimensão divergir {#probe-de-arranque-materializa-um-embedding-e-falha-cedo-se-a-dimensão-divergir  data-source-line="528"}
vetor = embedding_provider.embed("amostra")
assert len(vetor) == EMBEDDING_DIMENSION, "Dimensão do modelo != vector(N) no banco"

{data-source-line="531"}

Falhar no boot é infinitamente melhor que descobrir semanas depois que a busca semântica está degradada.

2. O provedor de LLM não pode estar grudado no domínio

No protótipo, a chamada à OpenAI fica no meio da regra. Aí você quer rodar local para testar sem custo, ou trocar para um modelo self-hosted, e percebe que o provedor está espalhado por toda parte.

A saída é uma porta (hexagonal): o domínio fala com uma interface; os adaptadores implementam cada provedor.

public interface LlmGateway {
    String complete(String prompt);
}
// local (determinístico, sem custo) | openai | ollama — escolhidos por configuração

{data-source-line="546"}

Com isso, provider=local roda em dev sem chave nem rede, e produção troca para openai ou ollama sem tocar no núcleo. Testes ficam determinísticos; custo de dev vai a zero.

3. Multitenancy desde o primeiro embedding

Se a ferramenta vai servir mais de um time ou cliente, o isolamento precisa existir desde a ingestão — não dá para "adicionar depois". Cada chunk, cada vetor, cada consulta carrega o tenant_id. Uma busca vetorial sem filtro de tenant é um vazamento de dados esperando para acontecer.

4. RAG sozinho não basta: combine com análise estática

Embeddings respondem "o que o código diz". Mas um diagnóstico de arquitetura útil também precisa de fatos determinísticos: este endpoint do OpenAPI não tem schema de erro, esta migration não tem rollback, este Dockerfile roda como root, este pipeline não trava em vulnerabilidade.

Isso é análise estática de artefatos — código, OpenAPI, migrations, Docker, CI — e ela dá ao relatório evidências rastreáveis, não só texto plausível de LLM. A combinação (RAG contextual + análise factual) é o que torna o diagnóstico confiável.

O encanamento é o produto

Chunking, embeddings, pgvector, probe de dimensão, porta de LLM, multitenancy, analisadores de artefatos, geração de ADR com evidência — nada disso é a "feature de IA" que aparece na demo, mas é tudo que faz ela virar produto. São semanas de fundação antes da primeira resposta confiável.

Atalho

Empacotei essa fundação inteira como um boilerplate: backend Java 21/Quarkus + worker Python/FastAPI, com pipeline de RAG (chunking, embeddings, pgvector com probe de dimensão), análise estática de artefatos, geração de ADRs com evidências, troca de LLM por configuração (local/openai/ollama) e multitenancy — rodando via Docker Compose.

É o ArchLens. Se você vai construir uma ferramenta de IA sobre código, ele te entrega o encanamento pronto e uma arquitetura limpa para estender.

👉 Conheça o ArchLens

Já apanhou de algum desses pontos montando RAG? Conta nos comentários.

Cobrança recorrente em produção: o que ninguém te conta antes da primeira cobrança duplicada

Felipe Ricarte — Wed, 17 Jun 2026 16:33:22 +0000

Implementar cobrança recorrente parece um problema resolvido. Você integra um gateway, agenda um job pra rodar todo dia e cobra quem vence hoje. Em uma tarde está "funcionando".

Aí o sistema vai pra produção, você escala pra duas instâncias, e numa madrugada o mesmo cliente é cobrado duas vezes. Ou pior: o pagamento confirma, mas o módulo que libera o acesso nunca fica sabendo — e o cliente paga sem receber.

A cobrança em si é a parte fácil. O que separa um protótipo de um billing de produção são quatro detalhes que quase ninguém trata no começo.

1. Concorrência: o job que roda duas vezes

O cenário clássico: um @Scheduled que busca assinaturas vencidas e cobra cada uma. Com uma instância, funciona. Com duas (deploy sem downtime, autoscaling), as duas leem a mesma assinatura no mesmo segundo e cobram em dobro.

A solução não é "garantir uma instância" — é tornar a leitura segura sob concorrência. No PostgreSQL:

SELECT * FROM assinatura
WHERE proxima_cobranca <= now() AND status = 'ATIVA'
FOR UPDATE SKIP LOCKED
LIMIT 50;

{data-source-line="212"}

FOR UPDATE SKIP LOCKED faz cada instância travar e processar um lote disjunto: ninguém espera, ninguém duplica. Escala horizontalmente sem coordenação externa.

2. Retry determinístico: falhar não pode ser improviso

Cartão recusado acontece o tempo todo. A pergunta é: quantas vezes tentar, com qual intervalo, e quando desistir? Se isso for "ad hoc", você terá clientes suspensos cedo demais e outros cobrados pra sempre.

Trate a falha como uma máquina de estados explícita:

1ª falha → reagenda +15 min
2ª falha → +60 min
3ª falha → suspende a assinatura e desliga a renovação

Cada tentativa fica registrada e auditável. O comportamento é previsível — para você e para o cliente.

3. Outbox: o evento que não pode se perder

O erro mais caro: cobrar com sucesso e, na sequência, publicar o evento PagamentoConfirmado num broker. Se a aplicação morre entre as duas operações, o pagamento aconteceu mas o resto do sistema nunca soube. Dinheiro entrou, acesso não foi liberado.

O padrão Outbox resolve: grave o evento na mesma transação da cobrança, numa tabela outbox. Um publicador lê essa tabela e entrega ao broker com retry/backoff, marcando como DEAD ao estourar o limite.

BEGIN;
  UPDATE assinatura SET status = 'ATIVA', proxima_cobranca = ... WHERE id = ?;
  INSERT INTO outbox (tipo, payload, status) VALUES ('PagamentoConfirmado', ?, 'PENDENTE');
COMMIT;

{data-source-line="239"}

Ou a cobrança e o evento são persistidos, ou nenhum dos dois. Sem estado inconsistente.

4. Idempotência no consumidor

O outbox garante entrega pelo menos uma vez — então o mesmo evento pode chegar duas vezes. O consumidor precisa ser idempotente. A forma mais simples e robusta é uma constraint única na chave do evento:

ALTER TABLE evento_processado ADD CONSTRAINT uq_evento UNIQUE (evento_id);

{data-source-line="249"}

Processou de novo? A inserção viola a constraint e você ignora com segurança. Sem efeito colateral duplicado.

O encanamento toma mais tempo que o produto

Nada disso é "difícil" isoladamente. O problema é que são semanas de encanamento — concorrência, retry, outbox, idempotência, métricas, testes com containers — antes de escrever uma linha da regra de negócio que importa pro seu SaaS. E é justamente a parte onde um bug custa cliente e reputação.

Atalho

Empacotei exatamente essa camada num starter kit em Java 21 + Spring Boot 3: renovação automática, retry determinístico, outbox com idempotência, suspensão por inadimplência, métricas Prometheus e testes com Testcontainers — tudo documentado e rodando via Docker Compose.

É o AssinaFlow. Se você vai construir cobrança recorrente, ele economiza as semanas chatas e te dá uma base que já nasce pronta pra produção.

👉 Conheça o AssinaFlow

Dúvidas sobre alguma das decisões acima? Comenta aí — respondo todas.

Idempotência em ingestão de pedidos no Spring Boot: o que separa o protótipo da produção

Felipe Ricarte — Wed, 17 Jun 2026 13:10:56 +0000

Integrar dois sistemas via pedidos parece a tarefa mais banal do mundo: recebe um JSON, salva no banco, devolve 201. Você faz isso antes do café.

O problema nunca é esse. O problema aparece três semanas depois, em produção, quando o sistema que te envia os pedidos sofre um timeout, reenvia a mesma requisição, e você descobre que o pedido A-123456 agora existe duas vezes no seu banco — com cobrança dobrada, estoque furado e um cliente irritado.

Este artigo é sobre como receber pedidos de forma idempotente, mesmo sob concorrência, em Java + Spring Boot. É a diferença entre um endpoint que funciona na demo e um que aguenta produção.

O cenário

Um Sistema A envia pedidos para o seu serviço. Cada pedido tem um identificador de origem — vou chamar de externalOrderId. Seu serviço precisa:

Receber o pedido (POST /orders).
Calcular os totais.
Persistir.
Disponibilizar para consulta de um Sistema B.

A regra de ouro: o mesmo externalOrderId nunca pode virar dois pedidos, não importa quantas vezes o Sistema A reenvie, nem quantas instâncias do seu serviço estejam rodando.

A tentativa ingênua (que falha)

A primeira versão que todo mundo escreve é mais ou menos esta:

public Order receber(OrderRequest req) {
    Optional<Order> existente = repo.findByExternalOrderId(req.externalOrderId());
    if (existente.isPresent()) {
        return existente.get(); // já existe, retorna
    }
    Order novo = calcular(req);
    return repo.save(novo); // cria
}

Parece correto. E funciona — até duas requisições com o mesmo externalOrderId chegarem ao mesmo tempo (duas instâncias, ou duas threads). As duas executam o findBy..., as duas não encontram nada, as duas chamam save. Resultado: pedido duplicado.

Esse é um race condition clássico. O check-then-act (verifico e depois ajo) não é atômico, então a verificação não vale nada sob concorrência.

A solução correta: deixe o banco garantir a unicidade

A regra de "um por externalOrderId" não deve viver só no código — ela tem que ser uma constraint do banco:

ALTER TABLE orders ADD CONSTRAINT uq_orders_external_id UNIQUE (external_order_id);

Com isso, mesmo que duas transações tentem inserir o mesmo pedido simultaneamente, o banco rejeita a segunda. Aí o seu código só precisa tratar essa rejeição como "ah, já existe" — e devolver o pedido existente:

public Result receber(OrderRequest req) {
    try {
        Order novo = calcular(req);
        repo.saveAndFlush(novo);          // flush para a violação estourar AGORA
        return Result.criado(novo);        // -> 201 Created
    } catch (DataIntegrityViolationException e) {
        // outra requisição ganhou a corrida: o pedido já existe
        Order existente = repo.findByExternalOrderId(req.externalOrderId())
                              .orElseThrow();
        return Result.jaExistia(existente); // -> 200 OK
    }
}

Repare na semântica de status:

201 Created quando você criou o pedido.
200 OK quando o pedido já existia (a requisição é idempotente — repetir não muda nada).

Essa distinção é importante: o Sistema A pode reenviar à vontade que o comportamento é sempre seguro e previsível. É exatamente o que se espera de uma API resiliente.

Totais: cuidado com `double`

Outro detalhe que parece bobo e quebra em produção: dinheiro não é double. 0.1 + 0.2 não dá 0.3 em ponto flutuante. Para totais de pedido, use BigDecimal com escala e arredondamento explícitos:

BigDecimal lineTotal = unitPrice
        .multiply(BigDecimal.valueOf(quantity))
        .setScale(2, RoundingMode.HALF_UP);

BigDecimal totalAmount = items.stream()
        .map(Item::lineTotal)
        .reduce(BigDecimal.ZERO, BigDecimal::add)
        .setScale(2, RoundingMode.HALF_UP);

Escala 2, HALF_UP, sempre. Assim o total fecha igual ao da planilha do financeiro — e você não vira o dev do "centavo sumido".

Observabilidade: o que salva você às 3 da manhã

Quando algo der errado (e vai), você precisa rastrear uma requisição do começo ao fim. Um correlation id propagado por header e logado em tudo resolve 80% das investigações:

String correlationId = Optional.ofNullable(request.getHeader("X-Correlation-Id"))
        .orElse(UUID.randomUUID().toString());
MDC.put("correlationId", correlationId);

Some a isso o Actuator (/actuator/health) e logs estruturados, e você consegue operar com confiança em vez de no escuro.

Recapitulando

Uma ingestão de pedidos pronta para produção precisa de:

Unicidade no banco (constraint), não só no código.
Tratar a violação como idempotência (201 ao criar, 200 quando já existe).
BigDecimal com escala e arredondamento explícitos para dinheiro.
Correlation id + observabilidade para conseguir investigar produção.

Nenhuma dessas peças é difícil isoladamente. O trabalho está em juntar tudo, testar sob concorrência e documentar as decisões para o time não desfazer depois.

Quer pular essa parte?

Eu empacotei exatamente esse padrão num template de produção em Java 21 + Spring Boot 3: ingestão idempotente sob concorrência, cálculo correto de totais, PostgreSQL + Liquibase, observabilidade, ADRs e runbook — sobe com um docker compose up e já vem com scripts que simulam os sistemas externos.

Em vez de gastar semanas montando a fundação, você parte dela.

👉 Conheça o Order Service Template

Felipe Ricarte Magalhães — Arquiteto de Software (hands-on), +17 anos em backend e integrações corporativas.

DEV Community: Felipe Ricarte

Multitenancy de verdade num SaaS de PDV: as decisões que você não pode errar

1. Isolamento de tenant: a decisão que atravessa tudo

2. Fiscal não pode derrubar a venda

3. Cobrar a mensalidade — e cortar o inadimplente — sem trabalho manual

4. Onboarding self-service: o cliente entra sozinho

O custo real é a soma

Atalho

RAG sobre o seu próprio código: o encanamento que separa o protótipo do produto

1. A dimensão do vetor é um contrato (e quase ninguém trata)

2. O provedor de LLM não pode estar grudado no domínio

3. Multitenancy desde o primeiro embedding

4. RAG sozinho não basta: combine com análise estática

O encanamento é o produto

Atalho

Cobrança recorrente em produção: o que ninguém te conta antes da primeira cobrança duplicada

1. Concorrência: o job que roda duas vezes

2. Retry determinístico: falhar não pode ser improviso

3. Outbox: o evento que não pode se perder

4. Idempotência no consumidor

O encanamento toma mais tempo que o produto

Atalho

Idempotência em ingestão de pedidos no Spring Boot: o que separa o protótipo da produção

O cenário

A tentativa ingênua (que falha)

A solução correta: deixe o banco garantir a unicidade

Totais: cuidado com double

Observabilidade: o que salva você às 3 da manhã

Recapitulando

Quer pular essa parte?

Totais: cuidado com `double`