Commerce

O Commerce é o miolo de uma operação de venda: ele guarda o que você vende, quanto disso existe em cada lugar, por quanto sai em cada canal e o que acontece com um pedido do momento em que ele nasce até o momento em que ele é entregue ou estornado. Ele não desenha a loja — ele responde às perguntas que a loja faz.

Na prática, uma rede com oito unidades para de ter oito planilhas de estoque e passa a ter oito StockLocation dentro de uma única loja, com movimentação rastreada peça por peça. Quando o pedido é confirmado, o histórico de status registra quem mudou, quando e por quê — e isso vale tanto para uma venda de sapato quanto para um pedido de delivery que passa por preparo, saída para entrega e conclusão.

O serviço está publicado nas pilhas de staging e de produção desde março de 2026, na porta 3026. Está marcado como beta por uma razão específica e não cosmética: os adaptadores para plataformas externas — Mercado Livre, Shopee, VTEX, Shopify e os demais nomes que aparecem no enum CommerceProviderType — ainda não foram implementados. O que existe hoje de sincronização é a máquina completa (mapeamento de SKU, resolução de conflito, jobs, webhooks) rodando contra o provedor interno. Ver §15 antes de vender integração de marketplace.

O cenário. Uma empresa vende. Começa vendendo por um canal, depois abre outro, depois abre uma segunda unidade física, depois um cliente grande pede tabela de preço própria. Nada disso é exótico — é o curso normal de um negócio que dá certo. O problema é que cada um desses passos, no software, costuma custar uma reescrita.

flowchart LR
  A["1 canal de venda"] -->|"abre o segundo canal"| B["2 canais"]
  B -->|"abre a segunda unidade"| C["2 canais + 2 estoques"]
  C -->|"cliente grande pede tabela própria"| D["2 canais + 2 estoques + 2 preços"]
  A -.->|reescrita| R1["custo de engenharia"]
  B -.->|reescrita| R1
  C -.->|reescrita| R1
  D -.->|reescrita| R1

O que trava hoje.

• O estoque mora em mais de um lugar e ninguém sabe qual está certo. A loja física tem o número dela, o marketplace tem o dele, e a diferença entre os dois só aparece quando um cliente compra algo que não existe. Vender e não ter é pior que não vender: cancelar pedido derruba reputação no canal e às vezes gera multa.
• Preço deixa de ser um número. Passa a ser preço de tabela, preço de atacado a partir de doze unidades, preço promocional entre sexta e domingo, preço específico de um canal. Cada uma dessas regras acaba virando um if em algum lugar do código, e a pergunta "por que este item saiu por este valor" fica sem resposta auditável.
• Pedido não é um registro, é um processo. Confirmado, em preparo, pronto, despachado, saiu para entrega, entregue, concluído. Sem uma máquina de estados explícita, alguém marca "entregue" um pedido que nunca foi confirmado, e o relatório de operação passa a mentir.
• Multi-empresa vira convenção. Uma plataforma que atende várias empresas clientes na mesma instância depende de todo desenvolvedor lembrar de filtrar por empresa em toda consulta. Funciona até o dia em que alguém não lembra.
• Integrar um canal novo custa um trimestre. Cada marketplace tem seu formato de produto, seu vocabulário de status de pedido e sua ideia de o que é um SKU. Sem uma camada canônica no meio, o segundo canal custa quase o mesmo que o primeiro.

O custo de não resolver. O e-commerce brasileiro fechou 2025 em R$ 235,5 bilhões e 438,9 milhões de pedidos, com projeção de R$ 259,8 bilhões para 2026 (ABIACOM, ex-ABComm, divulgado em 13/02/2026).

E ele se organizou em torno de marketplaces: no Brasil, 71% das compras online acontecem em marketplace contra 20% em loja própria (ECDB, Global eCommerce Outlook 2026, via E-Commerce Brasil em 02/03/2026 — o relatório não esclarece se o recorte é de pedidos, compradores ou receita). Vender em mais de um canal deixou de ser estratégia avançada e virou operação padrão de quem quer volume.

Cada canal adicional multiplica o número de lugares onde o mesmo SKU precisa estar correto. E o erro mais caro dessa conta não é técnico, é comercial: o pedido vendido sem lastro de estoque.

flowchart TD
  A["Estoque divergente entre canais"] --> B["Cliente compra o que não existe"]
  B --> C["Cancelamento por culpa do vendedor"]
  C --> D["Métrica de contrato do canal estoura"]
  D --> E["Queda de reputação e perda de exposição"]
  D --> F["Multa ou taxa de penalidade"]
  D --> G["Recebível bloqueado por mais tempo"]
  E --> H["Menos venda com o mesmo catálogo"]
  F --> H
  G --> H

Os marketplaces não tratam isso como acidente — tratam como métrica de contrato, e as margens são estreitas:

Um vendedor Mercado Líder tem margem de meio por cento. Em cem pedidos, o segundo oversell já custa o selo. É por isso que a precisão do estoque, num varejo multicanal, é problema de receita — não de inventário.

O custo de licença

E há o custo de licença. O modelo dominante no varejo brasileiro de médio e grande porte é o take rate — a plataforma cobra um percentual do que você fatura. A VTEX, referência da categoria no país, define no próprio formulário anual da SEC que "a taxa baseada em transação responde pela maior parte da nossa receita de assinatura e é primariamente estruturada como take rate", calculado sobre o valor dos pedidos incluindo impostos e frete (20-F FY2025). O pricebook público deles parte de 2,5% e desce até 0,5% conforme o porte do contrato (consultado em 2026-08-16).

É um modelo confortável no começo e desconfortável exatamente quando dá certo, porque a linha de custo cresce junto com a linha de receita sem que a plataforma passe a entregar mais.

flowchart LR
  subgraph TR["Take rate"]
    T1["Cliente fatura mais"] --> T2["Plataforma fatura mais"]
    T2 --> T3["Entrega da plataforma segue igual"]
  end
  subgraph FX["Custo desacoplado"]
    F1["Cliente fatura mais"] --> F2["Custo por loja e por pedido"]
    F2 --> F3["Margem do revendedor preservada"]
  end

E a direção do mercado é de mais cobrança sobre GMV, não menos: em 1º de junho de 2026 a BigCommerce — hoje Commerce.com — criou uma taxa de 2,0% a 0,6% sobre pedido processado fora dos gateways embarcados, encerrando o "sem taxa de transação" que era o argumento dela contra a Shopify.

A loja é a unidade de isolamento, não um campo

Toda rota de catálogo, estoque, preço, pedido e canal fica sob /api/v1/stores/:storeId/..., e o middleware resolveStore confirma que aquela loja existe, pertence à organização do token e está ativa — antes de qualquer serviço ser chamado. Não há caminho em que uma requisição alcance a regra de negócio sem esse carimbo.

flowchart LR
  R["Requisição HTTP"] --> A["authMiddleware"]
  A -->|"organizationId do token"| S["resolveStore"]
  S -->|"loja da organização e ativa"| P["requirePermission"]
  P --> N["Regra de negócio"]
  S -->|"loja de outra organização"| X["404"]

Preço tem uma resposta única e auditável

GET /price-lists/effective-price/:variantId resolve, para uma variante, uma quantidade e opcionalmente um canal, qual lista de preço vigente vence: filtra por validade e atividade, ordena por prioridade da lista e depois pela maior faixa de quantidade aplicável. A pergunta "por que saiu por este valor" tem uma resposta, não uma investigação.

flowchart LR
  V["variante"] --> E["findEffectivePrice"]
  Q["quantidade"] --> E
  C["canal opcional"] --> E
  E --> D["uma entrada vencedora, com a lista que a justifica"]
  E -->|"nenhuma lista se aplica"| B["basePrice da variante"]

Pedido com processo explícito

As transições válidas são uma tabela declarada em código (VALID_ORDER_TRANSITIONS), cada transição tem endpoint próprio com permissão própria, cada mudança grava carimbo de tempo dedicado e uma linha em CommerceOrderStatusHistory com autor e motivo. Cancelar e estornar são permissões separadas de "avançar o pedido".

stateDiagram-v2
  [*] --> DRAFT
  DRAFT --> CONFIRMED: confirm
  CONFIRMED --> PREPARING: prepare
  PREPARING --> READY: ready
  READY --> COMPLETED: complete
  READY --> SHIPPED: ship
  SHIPPED --> OUT_FOR_DELIVERY: out-for-delivery
  OUT_FOR_DELIVERY --> DELIVERED: deliver
  DELIVERED --> COMPLETED: complete
  note right of DRAFT
    A tabela completa, com cancelamento
    e estorno, está na seção 8.
  end note

Um modelo canônico para verticais diferentes

O mesmo Product atende PHYSICAL, DIGITAL, SERVICE e FOOD; o mesmo pedido atende PICKUP, DELIVERY, DINE_IN e DIGITAL; PriceModifier cobre adicional de lanche e opcional de serviço com a mesma estrutura. Trocar de vertical não exige trocar de building block.

Encaixa com o resto do catálogo

O token é o mesmo do IAM, os eventos saem no barramento compartilhado e são consumidos pelo Webhooks Engine, o pagamento é o building block Payments, a imagem do produto é o File Storage. Você não reintegra identidade a cada peça nova.

Panorama. O mercado de commerce se partiu em três famílias. No topo estão as plataformas composable — commercetools à frente — que vendem API-first para varejo global de grande porte, com contrato empresarial e implantação medida em trimestres. No meio está a plataforma completa, dominada no Brasil pela VTEX, que entrega loja, checkout, marketplace, OMS e encaixe fiscal em um pacote e cobra percentual sobre o que você vende. E na base está o open source — Medusa, Saleor, Vendure, Spree — que entrega o código e transfere a operação para o seu time.

flowchart TD
  M["Mercado de commerce"] --> C1["Composable API-first"]
  M --> C2["Plataforma completa"]
  M --> C3["Open source"]
  M --> C4["Hubs e ERPs de varejo, quarta família brasileira"]
  C1 --> N1["commercetools: contrato empresarial, implantação em trimestres"]
  C2 --> N2["VTEX: loja, checkout, marketplace, OMS e fiscal, com percentual sobre a venda"]
  C3 --> N3["Medusa, Saleor, Vendure, Spree: o código é seu, a operação também"]
  C4 --> N4["Bling, Olist Tiny, Plugg.to, Ideris, Anymarket, Magazord"]

Duas coisas se mexeram nesse mercado em 2026, e vale conhecê-las porque mudam a conversa com o comprador.

O que mudou em 2026

A cobrança sobre GMV está avançando, não recuando. A BigCommerce — que virou Commerce.com (NASDAQ: CMRC) em agosto de 2025 — reformou a precificação em 1º de junho de 2026 e criou uma taxa sobre pedido processado fora dos gateways embarcados: 2,0%, 1,0% e 0,6% conforme o plano, exatamente os mesmos degraus da Shopify. Isso enterrou o "sem taxa de transação" que era o argumento mais alto deles contra a Shopify. Do outro lado da linha, commercetools, Medusa e Vendure fizeram do "não cobramos sobre GMV" um argumento comercial explícito. Essa é hoje a divisória mais nítida da categoria. (página oficial da mudança, consultada em 2026-08-16)

O open source de commerce está estreitando. A Vendure trocou MIT por GPLv3 na versão 3. A Medusa fechou RBAC e SSO em 11 de agosto de 2026 — cinco dias antes desta redação —, deixando o núcleo em MIT mas movendo justamente os requisitos de compliance corporativa para licença comercial, inclusive para quem auto-hospeda (`ENTERPRISE-LICENSE.md`). A Spree oscilou de licença duas vezes em menos de dois anos. Restou a Saleor como único núcleo BSD-3 sem reserva — e é justamente a que cobra mais caro na nuvem, e sobre GMV.

A quarta família brasileira

No Brasil existe uma quarta família, e ela é a concorrente real da metade de sincronização. São os hubs de integração e ERPs de varejo, já consolidados sob quatro grupos: LWSA (Bling e Ideris), Stone/Linx (Plugg.to), Olist (Tiny) e DB1 (Anymarket), com a Magazord independente. Eles não competem com o Commerce inteiro — não têm modelo multi-tenant para revenda, nem se propõem a ser componente embutido no produto de outra empresa. Competem com o pedaço que o Commerce ainda não entrega, e é honesto dizer o preço deles:

Consultado em 2026-08-16 nas páginas oficiais de plano e nas fichas públicas do Reclame Aqui. Notas do Reclame Aqui têm volumes de reclamação muito diferentes entre si (de 15 a 582 por ano), então servem para ler o padrão de queixa — predominantemente contratual e de cobrança, não técnico —, e não para ranquear.

Onde a Catalisa entra

Nenhuma das quatro famílias foi desenhada para o caso que a Catalisa atende: um componente de catálogo, estoque, preço e pedido que outra empresa embute no produto dela, operando várias empresas clientes na mesma instância. Shopify e VTEX assumem que a loja é o produto final; commercetools assume um cliente do porte que sustenta contrato empresarial; Medusa e Saleor assumem que você opera a infraestrutura e resolve multi-tenancy sozinho; e os hubs brasileiros assumem que você é o varejista, não quem constrói a plataforma para ele.

Preços e licenças consultados em 2026-08-16 nas páginas oficiais de cada fornecedor. Onde o fornecedor não publica valor, a tabela diz "não".

Nossos diferenciais

1. O isolamento é estrutural, não disciplinar. Toda rota de domínio nasce sob /stores/:storeId, e o resolveStore valida a posse antes da regra de negócio. Copiar isso não é difícil tecnicamente — é difícil politicamente, porque exige que a decisão tenha sido tomada no primeiro dia. Uma plataforma que começou com uma conta por loja paga muito caro para chegar aqui depois.
2. Custo desacoplado do faturamento do cliente. No take rate, a plataforma fatura mais quando o cliente cresce sem passar a entregar mais por isso. A própria VTEX documenta o efeito colateral no relatório do segundo trimestre de 2026: GMV crescendo 7,0% em base FX-neutra contra receita de assinatura crescendo 1,3%, porque conta grande paga alíquota menor. Para quem revende operação de e-commerce, esse percentual sai direto da sua margem, e a curva não é negociável.
3. Um modelo canônico que já atende quatro verticais. PHYSICAL, DIGITAL, SERVICE e FOOD convivem no mesmo Product; PICKUP, DELIVERY, DINE_IN e DIGITAL convivem no mesmo pedido. Quem separou varejo de food service em produtos diferentes não junta os dois sem uma migração.
4. A peça encaixa nas outras 31. Identidade, pagamento, entrega de webhook, armazenamento de imagem, trilha de auditoria e cobrança já existem e falam o mesmo token. O concorrente entrega uma plataforma de commerce; a Catalisa entrega commerce dentro de uma plataforma.

Quando escolher o concorrente

Seja direto aqui, porque o comprador técnico vai descobrir sozinho de qualquer forma.

flowchart TD
  Q1{"Precisa vender em marketplace brasileiro já?"} -->|sim| H["Bling, Olist Tiny ou Anymarket"]
  Q1 -->|não| Q2{"Precisa de loja no ar em uma semana?"}
  Q2 -->|sim| SH["Shopify"]
  Q2 -->|não| Q3{"É varejista global de grande porte com time de plataforma?"}
  Q3 -->|sim| CT["commercetools"]
  Q3 -->|não| Q4{"Quer o código na mão e opera a infraestrutura?"}
  Q4 -->|sim| OS["Medusa ou Saleor"]
  Q4 -->|não| Q5{"Está construindo um produto que precisa de commerce por dentro, para várias empresas clientes?"}
  Q5 -->|sim| CC["Catalisa Commerce"]
  Q5 -->|não| VT["VTEX, se quer plataforma completa com marketplace e OMS"]

Se o que ele precisa é vender em marketplace brasileiro amanhã, o Commerce não entrega e não adianta contornar. Para um varejista que só quer conectar loja e canais, o Bling a R$ 60/mês ou o Olist Tiny a R$ 66/mês resolvem hoje, por menos do que custa uma reunião de projeto; para operação de porte com muitos canais, o Anymarket integra mais de 150. Para quem quer plataforma completa com marketplace, gestão de sellers e OMS no mesmo núcleo, a VTEX é a resposta madura, e o encaixe dela com o ecossistema brasileiro de pagamento e logística é trabalho de duas décadas. Nossos adaptadores externos simplesmente não existem (§15).

Se ele precisa de loja no ar em uma semana, com vitrine, checkout, meio de pagamento e tema pronto, a resposta é Shopify — e não há discussão, porque o Commerce é uma API e não uma loja. A conversão de checkout deles é o ativo defensável da categoria, e o preço de entrada é público até o Plus.

Se ele é um varejista global de grande porte com time de plataforma próprio, o commercetools tem limites de catálogo e um modelo B2B — hierarquia de unidades de negócio, milhares de associados por unidade — que nós não temos. Vale a ressalva, porém, e ela é factual: a empresa demitiu cerca de 20% do quadro em 2025, trocou de CEO três vezes em 16 meses e, em julho de 2026, lançou módulos avulsos prometendo modernização sem replatform — o que compradores leem como recuo do pitch composable puro. É risco de fornecedor a considerar dos dois lados da mesa.

Se ele tem time de engenharia forte e quer o código na mão, a Medusa e a Saleor entregam isso. Duas ressalvas úteis para a conversa: na Medusa, RBAC e SSO deixaram de ser MIT em 11 de agosto de 2026 e agora exigem acordo comercial mesmo no auto-hospedado; na Saleor, o núcleo continua BSD-3 puro, mas a nuvem começa em US$ 1.599/mês e cobra percentual sobre o GMV excedente.

O Commerce ganha quando o problema é construir um produto que precisa de commerce por dentro, para várias empresas clientes, sem pagar percentual sobre o faturamento delas e sem operar a infraestrutura. Fora desse recorte, recomende o concorrente e ganhe a credibilidade — ela volta na próxima conversa.

Unidade de cobrança: precificação em definição. O Commerce ainda não tem tabela publicada. Não invente número em proposta — descreva os drivers e leve o caso para a mesa comercial.

O que dispara custo.

O princípio que orienta a discussão. A unidade de cobrança não deve ser percentual do GMV. Cobrar por loja e por pedido mantém a conta previsível para quem compra e desacopla nossa receita do sucesso comercial dele — o que, num produto revendido dentro do produto de outra empresa, é a diferença entre um custo de infraestrutura e uma mordida na margem.

Comparação de custo — cenário: varejista brasileiro com R$ 50 milhões de GMV por ano, catálogo de 8 mil SKUs, uma operação.

Como ler esta tabela. Os valores da VTEX estão em reais e vêm do pricebook que a própria empresa expõe na loja de assinaturas — é referência comercial, não necessariamente o que uma conta enterprise negocia. Os demais estão na moeda do fornecedor, sem conversão, de propósito: somar câmbio a esta conta transformaria um número verificável em estimativa. A linha da VTEX é a única diretamente comparável ao cenário em reais. Antes de usar qualquer comparação em proposta, reconsulte a página do fornecedor e atualize a data — preço sem data é passivo, não ativo.

O detalhe que sustenta o argumento

No pricebook da VTEX, todos os planos partem de uma especificação Initial Take Rate = 2,5%, e o valor fixo pago é literalmente compra de redução dessa alíquota.

Pricebook público de assine.vtex.com, consultado em 2026-08-16. É referência comercial, não necessariamente o que uma conta enterprise negocia.

Ou seja, o cliente paga adiantado para que o percentual doa menos. É um modelo coerente para quem opera a própria loja e desconfortável para quem revende — porque o percentual incide sobre o faturamento do cliente final e sai da margem do revendedor.

ROI

O retorno não está na linha de licença — o open source auto-hospedado tem licença zero e continuará tendo. Está em duas contas.

A primeira conta é o que não se reescreve. Catálogo com variantes, estoque multi-local com reserva, resolução de preço efetivo e máquina de estados de pedido com histórico são, somados, meses de trabalho de um time que já tem o que fazer — e são o tipo de código cujo erro só aparece em produção, na forma de estoque negativo ou pedido em estado impossível. Some a isso o multi-tenancy, que Medusa, Saleor e Vendure deixam inteiramente por sua conta.

A segunda conta é o percentual, e ela é a que decide. Na conta acima, um take rate de 1,8% custa quase um milhão de reais por ano sobre R$ 50 milhões de GMV — e dobra se o cliente dobrar de tamanho, sem que a plataforma passe a entregar mais.

Trocar percentual variável por custo previsível por loja e por pedido é, para quem embute commerce no próprio produto, o argumento econômico central. Ele não depende de sermos mais baratos hoje: depende de a curva ser diferente.

O caminho da requisição

flowchart TD
  HTTP["HTTP"] --> APP["Hono app com basePath /commerce"]
  APP --> COMMON["applyCommonMiddleware"]
  COMMON --> HEALTH["GET /health — sonda de versão"]
  COMMON --> STORES["/api/v1/stores — storesRouter, CRUD de loja"]
  STORES --> AUTH["authMiddleware"]
  AUTH --> RESOLVE["resolveStore — tudo abaixo vive sob /:storeId"]
  RESOLVE --> PERM["requirePermission COMMERCE_*"]
  PERM --> ROUTERS["19 sub-routers em /api/v1/stores/:storeId/..."]
  ROUTERS --> ZOD["Zod parse e ResultAsync de T e AppError"]
  ZOD --> SVC["services, sync e jobs"]
  SVC --> REPO["repositories, 31 arquivos sobre Prisma"]
  SVC --> EV["EventPublisher"]
  REPO --> PG[("PostgreSQL, schema commerce, 32 tabelas")]
  EV --> REDIS[("Redis, barramento compartilhado")]

O applyCommonMiddleware aplica quatro proteções de borda, nesta ordem: limite de corpo de 1 MB, CORS, cabeçalhos de segurança e rate limit.

O que o resolveStore confere, na ordem. Cada linha da tabela era uma anotação dentro da caixa do middleware — e cada uma tem um código de erro próprio.

Os 19 sub-routers, por família

A camada de serviço

Decisões não óbvias.

• Tudo nasce sob /stores/:storeId, inclusive o que não parece precisar. É a decisão mais consequente do módulo. Ela custa uma URL mais longa e paga com uma invariante: nenhuma rota de domínio existe fora do escopo de uma loja já validada contra a organização do token. O middleware resolveStore roda antes de qualquer serviço, em todos os 19 sub-routers, sem exceção. A alternativa — passar organizationId para cada serviço e torcer — é a que produz vazamento entre clientes.

• A loja inativa devolve 403, não lista vazia. Desativar uma loja é uma ação operacional com consequência: as chamadas param, e param com uma mensagem que diz por quê. Devolver lista vazia faria o cliente acreditar que perdeu os dados.

• CATALISA é sempre o provedor PRIMARY, e é provisionado automaticamente. Quando você anexa o primeiro provedor externo a uma loja sem PRIMARY, o StoreProviderService cria o provedor interno como PRIMARY antes de anexar o seu. Isso resolve, de uma vez, a pergunta "quem manda quando os dois discordam": o seu catálogo manda, o canal é réplica. Só existe um PRIMARY por loja, e trocar exige rebaixar o atual primeiro.

• A sincronização de produtos roda em sequência, não em paralelo. No pullProducts e no pushProducts do sync engine, os itens são encadeados um a um com andThen. É mais lento de propósito: o SKU tem unicidade por loja (@@unique([storeId, sku])), e processar em paralelo produz corrida entre dois itens que reivindicam o mesmo SKU. Lote grande é lento — é o trade-off aceito para não corromper mapeamento.

• A resolução de conflito é por campo, com dono declarado. ProductMapping.fieldOwnership é um JSON que diz, campo a campo, qual provedor é dono daquele campo. Sem dono declarado, o valor interno vence. É deliberadamente conservador: na dúvida, a réplica não sobrescreve o original.

• O preço efetivo é uma consulta, não um cálculo espalhado. findEffectivePrice monta a decisão inteira em uma única query: filtra listas ativas e vigentes da organização e da loja, respeita minQuantity, opcionalmente restringe ao canal, ordena por priority da lista e depois por minQuantity decrescente, e devolve a primeira. Regra de preço que mora em vários lugares é regra que ninguém consegue explicar depois.

• O evento sai com safePublish. Falha de publicação não derruba a transação de negócio. Um pedido confirmado com evento não entregue é um problema de entrega; um pedido que não confirma porque o Redis piscou é um problema de venda.

Como a resolução de conflito decide, campo a campo

O CommerceConflictResolverService compara name, description, status e brand entre o valor interno e o externo, e resolve cada campo divergente de forma independente.

flowchart TD
  D["Campo diverge entre interno e externo"] --> O{"fieldOwnership declara dono para este campo?"}
  O -->|"o dono é este provedor"| EXT["Vence o valor externo"]
  O -->|"o dono é outro provedor"| INT1["Vence o valor interno"]
  O -->|"não há dono declarado"| P{"Este vínculo é PRIMARY?"}
  P -->|sim| INT2["Vence o valor interno — o dado interno é o primário"]
  P -->|não| INT3["Vence o valor interno — a réplica não sobrescreve o original"]
  EXT --> M["Produto mesclado"]
  INT1 --> M
  INT2 --> M
  INT3 --> M
  M --> S{"Houve conflito?"}
  S -->|sim| C["Mapeamento marcado como CONFLICT"]
  S -->|não| A["Mapeamento marcado como ACTIVE"]

Monolito vs. standalone. Em monolito, o Commerce resolve as dependências pelo container TypeDI e roda junto com os demais na porta 3000. Em standalone — o modo usado em produção — ele sobe sozinho na porta 3026 com MODULE_SELF=commerce. A diferença que importa: em standalone os middlewares globais do src/app.ts não rodam, e é por isso que o app.ts do módulo chama applyCommonMiddleware explicitamente. Sem essa chamada, o serviço subiria sem limite de corpo, sem cabeçalho de segurança e sem rate limit.

Glossário

Modelo de dados — schema commerce no PostgreSQL, 32 modelos.

Como os 32 modelos se ligam

Trinta e dois modelos não cabem em um desenho legível — o diagrama abaixo mostra o esqueleto: quem pendura em quem, do isolamento até o pedido.

erDiagram
  CommerceStore ||--o{ CommerceCategory : "organiza"
  CommerceStore ||--o{ CommerceProduct : "publica"
  CommerceStore ||--o{ CommerceStockLocation : "opera"
  CommerceStore ||--o{ CommercePriceList : "precifica com"
  CommerceStore ||--o{ CommerceChannel : "vende por"
  CommerceStore ||--o{ CommerceCart : "recebe"
  CommerceStore ||--o{ CommerceOrder : "fecha"
  CommerceStore ||--o{ CommerceStoreProvider : "sincroniza com"
  CommerceProduct ||--o{ CommerceProductVariant : "tem grade"
  CommerceProduct ||--o{ CommerceProductImage : "ilustra com"
  CommerceProduct ||--o{ CommercePriceModifier : "aceita adicional"
  CommerceProductVariant ||--o{ CommerceStockItem : "tem saldo em"
  CommerceStockLocation ||--o{ CommerceStockItem : "guarda"
  CommerceProductVariant ||--o{ CommerceStockReservation : "reserva"
  CommerceProductVariant ||--o{ CommerceStockMovement : "movimenta"
  CommerceProductVariant ||--o{ CommerceOrderItem : "é vendida em"
  CommercePriceList ||--o{ CommercePriceListEntry : "lista preço de"
  CommerceOrder ||--o{ CommerceOrderItem : "contém"
  CommerceOrder ||--o{ CommerceOrderStatusHistory : "registra"
  CommerceCart ||--o{ CommerceCartItem : "contém"
  CommerceStoreProvider ||--o{ CommerceProductMapping : "mapeia SKU"
  CommerceStoreProvider ||--o{ CommerceOrderMapping : "mapeia pedido"
  CommerceProviderConfig ||--o{ CommerceProviderSyncJob : "executa"
  CommerceProviderConfig ||--o{ CommerceProviderWebhookLog : "recebe"

Enumerações

Máquina de estados do pedido

As transições válidas estão declaradas em VALID_ORDER_TRANSITIONS (src/commerce/types/index.ts). Uma transição fora da tabela devolve 400 VALIDATION com a mensagem Cannot transition from X to Y.

stateDiagram-v2
  direction TB
  [*] --> DRAFT: POST /orders
  DRAFT --> CONFIRMED: confirm
  CONFIRMED --> PREPARING: prepare
  PREPARING --> READY: ready
  READY --> SHIPPED: ship
  READY --> OUT_FOR_DELIVERY: out-for-delivery
  READY --> COMPLETED: complete
  SHIPPED --> OUT_FOR_DELIVERY: out-for-delivery
  OUT_FOR_DELIVERY --> DELIVERED: deliver
  DELIVERED --> COMPLETED: complete
  DELIVERED --> REFUNDED: refund
  COMPLETED --> REFUNDED: refund
  DRAFT --> CANCELLED: cancel
  CONFIRMED --> CANCELLED: cancel
  PREPARING --> CANCELLED: cancel
  READY --> CANCELLED: cancel
  SHIPPED --> CANCELLED: cancel
  OUT_FOR_DELIVERY --> CANCELLED: cancel
  CANCELLED --> [*]
  REFUNDED --> [*]
  note right of DRAFT
    Único estado em que PATCH
    altera o pedido.
  end note

O que cada transição grava. Além de mudar o status, toda transição carimba o campo de tempo próprio, insere uma linha em CommerceOrderStatusHistory com autor e motivo, e publica commerce.order.<status em minúsculas> no barramento.

Efeitos colaterais de estoque nas transições

sequenceDiagram
  autonumber
  participant R as orders.router
  participant L as OrderLifecycleService
  participant DB as Repositórios
  participant S as StockService
  participant B as Barramento
  R->>L: transition para o status alvo
  L->>DB: findById do pedido pela organização
  L->>L: o alvo está em VALID_ORDER_TRANSITIONS?
  L->>DB: update com status e carimbo de tempo
  L->>DB: insert em CommerceOrderStatusHistory
  L->>B: safePublish do evento da transição
  alt alvo é CONFIRMED
    L->>S: reserveOrderStock
    Note over L,S: hoje não reserva nada — ver seção 15
  else alvo é CANCELLED
    L->>S: releaseReservations por order e orderId
  else alvo é COMPLETED
    L->>S: consumeReservations por order e orderId
  end
  L-->>R: pedido atualizado

Movimento de estoque e reserva

Saldo não é campo que se escreve: é consequência de uma movimentação registrada. quantity é o total físico e reservedQty é a parte separada — o disponível para venda é a diferença dos dois.

flowchart LR
  IN["INBOUND"] -->|"soma em toLocation"| SI["StockItem: quantity e reservedQty"]
  OUT["OUTBOUND"] -->|"subtrai de fromLocation"| SI
  TR["TRANSFER"] -->|"subtrai de from e soma em to"| SI
  ADJ["ADJUSTMENT"] -->|"subtrai de from e ou soma em to"| SI
  SI --> AV["Disponível igual a quantity menos reservedQty"]
  RES["reserveStock"] -->|"incrementa reservedQty"| SI
  REL["releaseReservations"] -->|"decrementa reservedQty"| SI
  CON["consumeReservations"] -->|"decrementa reservedQty e quantity"| SI

stateDiagram-v2
  [*] --> ACTIVE: reserveStock separa a quantidade
  ACTIVE --> RELEASED: releaseReservations devolve ao disponível
  ACTIVE --> CONSUMED: consumeReservations baixa do saldo
  RELEASED --> [*]
  CONSUMED --> [*]
  note right of ACTIVE
    O job CommerceReservationCleanupJob
    libera as reservas vencidas por expiresAt.
  end note

Ciclo de vida do carrinho

stateDiagram-v2
  [*] --> ACTIVE: POST /carts
  ACTIVE --> CONVERTED: checkout gera pedido em DRAFT
  ACTIVE --> EXPIRED: passou de expiresAt, padrão de 24h
  ACTIVE --> ABANDONED: estado previsto no enum, sem rotina que o atribua hoje
  CONVERTED --> [*]
  EXPIRED --> [*]
  ABANDONED --> [*]
  note right of EXPIRED
    Quem marca é o CommerceCartCleanupJob,
    que hoje não tem agendador — ver seção 15.
  end note

Estados dos demais recursos

O catálogo, a promoção, a sincronização e o mapeamento também têm status — e status sem diagrama é bug de integração esperando acontecer.

stateDiagram-v2
  direction LR
  state "Produto" as P {
    state "DRAFT" as PDRAFT
    state "ACTIVE" as PACTIVE
    state "ARCHIVED" as PARCH
    [*] --> PDRAFT
    PDRAFT --> PACTIVE
    PACTIVE --> PARCH
    PARCH --> PACTIVE
  }
  state "Variante" as V {
    state "ACTIVE" as VACTIVE
    state "INACTIVE" as VINACTIVE
    [*] --> VACTIVE
    VACTIVE --> VINACTIVE
    VINACTIVE --> VACTIVE
  }
  state "Promoção" as PR {
    state "DRAFT" as RDRAFT
    state "ACTIVE" as RACTIVE
    state "EXPIRED" as REXPIRED
    state "CANCELLED" as RCANCELLED
    [*] --> RDRAFT
    RDRAFT --> RACTIVE
    RACTIVE --> REXPIRED
    RACTIVE --> RCANCELLED
  }

stateDiagram-v2
  [*] --> PENDING: padrão do modelo no banco
  PENDING --> IN_PROGRESS: o sync engine cria o job já em IN_PROGRESS
  IN_PROGRESS --> COMPLETED: completeSyncJob grava os contadores
  IN_PROGRESS --> FAILED: failSyncJob grava errorMessage
  FAILED --> IN_PROGRESS: POST /provider-sync/jobs/:id/retry
  COMPLETED --> [*]

stateDiagram-v2
  direction LR
  [*] --> ACTIVE: upsert sem conflito de campo
  ACTIVE --> CONFLICT: o resolvedor detectou divergência
  CONFLICT --> ACTIVE: divergência resolvida na sincronização seguinte
  ACTIVE --> STALE: o mapeamento envelheceu
  STALE --> ACTIVE: nova sincronização atualiza
  [*] --> UNMAPPED: SKU sem correspondente externo

Prefixo: /commerce. Em standalone, a base é https://commerce.bb.stg.catalisa.app.

Regra estrutural que vale para tudo abaixo. Exceto /commerce/health, toda rota vive sob /commerce/api/v1/stores. As rotas de loja aplicam authMiddleware + requirePermission + um requireOrganization local. Todas as demais aplicam authMiddleware + resolveStore no use('*') do sub-router, e depois requirePermission por rota. O resolveStore já cobre o papel do requireOrganization: sem organizationId no token, ele devolve 403 antes de qualquer coisa.

Sobre a contagem. scripts/docs/contar-endpoints.sh commerce devolve 130, e é esse o número do frontmatter. As 7 transições de ciclo de vida do pedido (confirm, prepare, ready, ship, out-for-delivery, deliver, complete) são registradas por um helper lifecycleRoute(...) dentro de orders.router.ts e o script não as enxerga. O total real de caminhos HTTP servidos é 137. Todas estão documentadas abaixo.

Saúde

Lojas — /commerce/api/v1/stores

authMiddleware + requirePermission + requireOrganization.

Daqui em diante, {base} = /commerce/api/v1/stores/:storeId.

Categorias — {base}/categories

Produtos — {base}/products

Variantes — {base}/products/:productId/variants

Imagens de produto — {base}/products/:productId/images

Modificadores de preço — {base}/products/:productId/modifiers

Locais de estoque — {base}/stock-locations

Estoque e reservas — {base}/stock

Movimentações de estoque — {base}/stock-movements

Lotes — {base}/batches

Listas de preço — {base}/price-lists

A rota effective-price/:variantId é declarada antes de /:id. A ordem importa: invertida, effective-price seria capturada como um id de lista.

Promoções — {base}/promotions

Carrinhos — {base}/carts

Pedidos — {base}/orders

Cancelar e estornar têm permissão própria, separada de COMMERCE_ORDERS_MANAGE. Um operador de expedição avança o pedido sem poder cancelar nem estornar.

Canais — {base}/channels

Configurações de provedor — {base}/providers

Sincronização — {base}/provider-sync

Webhooks de provedor — {base}/provider-webhooks

Provedores da loja — {base}/store-providers

Mapeamentos de produto — {base}/product-mappings

Abaixo, o detalhe dos endpoints que um integrador usa primeiro.

POST /commerce/api/v1/stores

Cria a operação de venda. É o primeiro passo obrigatório — sem loja, nenhuma outra rota do módulo existe.

Request

{
  "name": "Loja Centro",
  "slug": "loja-centro",
  "type": "GENERAL",
  "currency": "BRL",
  "timezone": "America/Sao_Paulo"
}

{
  "name": "Loja Centro",
  "slug": "loja-centro",
  "type": "GENERAL",
  "currency": "BRL",
  "timezone": "America/Sao_Paulo"
}

Resposta 201 — { "data": { "id": "...", "slug": "loja-centro", "isActive": true, ... } }

Erros — 400 corpo inválido · 403 token sem organizationId · 409 slug já em uso na organização

POST {base}/products

Cria o produto. Ele nasce sem preço e sem estoque: quem carrega os dois é a variante.

Request

{
  "name": "Camiseta Básica",
  "type": "PHYSICAL",
  "status": "DRAFT",
  "brand": "Marca Própria",
  "categoryIds": ["6f1c...uuid"],
  "tags": ["verao", "algodao"],
  "attributes": { "material": "algodão", "genero": "unissex" }
}

{
  "name": "Camiseta Básica",
  "type": "PHYSICAL",
  "status": "DRAFT",
  "brand": "Marca Própria",
  "categoryIds": ["6f1c...uuid"],
  "tags": ["verao", "algodao"],
  "attributes": { "material": "algodão", "genero": "unissex" }
}

Resposta 201 — { "data": { "id": "...", "status": "DRAFT", ... } }

Erros — 400 corpo inválido ou type ausente · 404 loja inexistente ou de outra organização · 409 slug duplicado na loja

POST {base}/products/:productId/variants

A variante é o que se vende. Um produto sem variante não entra em pedido nem em carrinho.

Request

{
  "sku": "CAM-BAS-P-PRETA",
  "name": "Camiseta Básica P Preta",
  "basePrice": 79.90,
  "costPrice": 32.00,
  "compareAtPrice": 99.90,
  "barcode": "7891234567890",
  "options": { "tamanho": "P", "cor": "preta" }
}

{
  "sku": "CAM-BAS-P-PRETA",
  "name": "Camiseta Básica P Preta",
  "basePrice": 79.90,
  "costPrice": 32.00,
  "compareAtPrice": 99.90,
  "barcode": "7891234567890",
  "options": { "tamanho": "P", "cor": "preta" }
}

Erros — 400 corpo inválido · 409 SKU já existe na loja

POST {base}/stock-movements

Toda alteração de saldo passa por aqui. Não existe endpoint que escreva quantity direto: o saldo é sempre consequência de uma movimentação registrada.

Request

{
  "variantId": "9a2f...uuid",
  "type": "INBOUND",
  "quantity": 120,
  "toLocationId": "3c7d...uuid",
  "reason": "Recebimento NF 4471",
  "referenceType": "invoice",
  "referenceId": "b81e...uuid"
}

{
  "variantId": "9a2f...uuid",
  "type": "INBOUND",
  "quantity": 120,
  "toLocationId": "3c7d...uuid",
  "reason": "Recebimento NF 4471",
  "referenceType": "invoice",
  "referenceId": "b81e...uuid"
}

Resposta 201 — a movimentação criada. O StockItem correspondente é criado se ainda não existir.

Erros — 400 VALIDATION quando falta o local exigido pelo tipo (ex.: toLocationId required for INBOUND)

Sem trava de saldo negativo. O serviço não recusa uma saída maior que o disponível. Se a sua operação exige essa trava, valide antes com GET {base}/stock/levels/:variantId — ver §15.

GET {base}/stock/levels/:variantId

Saldo da variante em cada local.

Resposta 200

{
  "data": [
    {
      "variantId": "9a2f...",
      "locationId": "3c7d...",
      "quantity": 120,
      "reservedQty": 8,
      "reorderPoint": 20,
      "reorderQty": 100
    }
  ]
}

{
  "data": [
    {
      "variantId": "9a2f...",
      "locationId": "3c7d...",
      "quantity": 120,
      "reservedQty": 8,
      "reorderPoint": 20,
      "reorderQty": 100
    }
  ]
}

Disponível para venda é quantity - reservedQty. O campo não vem calculado — faça a conta no seu lado.

GET {base}/price-lists/effective-price/:variantId

Resolve qual preço vale agora para uma variante, uma quantidade e opcionalmente um canal.

Como a decisão é tomada

flowchart TD
  E["Entradas de lista de preço da variante"] --> F["Filtra"]
  F --> O["Ordena por priceList.priority DESC e depois por minQuantity DESC"]
  O --> R["Devolve a primeira"]

Resposta 200 — a entrada vencedora, com a lista de preço embutida. Se nenhuma lista se aplica, a resposta é vazia e o preço a usar é o basePrice da variante.

POST {base}/orders

Cria o pedido. Ele nasce em DRAFT e com uma linha de histórico já gravada.

Request

{
  "source": "STOREFRONT",
  "channelId": "1e4b...uuid",
  "customerId": "77aa...uuid",
  "customerName": "Maria Souza",
  "customerEmail": "maria@exemplo.com.br",
  "deliveryType": "DELIVERY",
  "deliveryFee": 12.50,
  "items": [
    { "variantId": "9a2f...uuid", "quantity": 2 },
    { "variantId": "5b81...uuid", "quantity": 1, "unitPrice": 45.00 }
  ]
}

{
  "source": "STOREFRONT",
  "channelId": "1e4b...uuid",
  "customerId": "77aa...uuid",
  "customerName": "Maria Souza",
  "customerEmail": "maria@exemplo.com.br",
  "deliveryType": "DELIVERY",
  "deliveryFee": 12.50,
  "items": [
    { "variantId": "9a2f...uuid", "quantity": 2 },
    { "variantId": "5b81...uuid", "quantity": 1, "unitPrice": 45.00 }
  ]
}

Como o total é calculado. subtotal = soma de quantity × unitPrice dos itens. total = subtotal + deliveryFee.

Desconto e imposto não entram no total. discount e tax existem no modelo e nascem em 0. Passar promotionId não aplica desconto automaticamente — a promoção é validada por POST {base}/promotions/validate e aplicada pelo seu lado. Ver §15.

Resposta 201 — o pedido com orderNumber sequencial da loja, itens e status: "DRAFT".

Erros — 400 corpo inválido ou lista de itens vazia · 404 variante inexistente

POST {base}/orders/:id/confirm

Move DRAFT → CONFIRMED. É a primeira transição do ciclo e a que a maioria das integrações chama logo após criar o pedido.

Request — corpo opcional. {"reason": "..."} é aceito e gravado no histórico.

O que acontece

1. Verifica que CONFIRMED está em VALID_ORDER_TRANSITIONS["DRAFT"].
2. Grava status e confirmedAt.
3. Insere linha em CommerceOrderStatusHistory com fromStatus, toStatus, reason e changedBy (o userId do token).
4. Publica commerce.order.confirmed.
5. Chama reserveOrderStock — que hoje não reserva nada (§15).

Resposta 200 — o pedido atualizado.

Erros — 400 VALIDATION com Cannot transition from X to CONFIRMED quando o estado atual não permite · 403 sem COMMERCE_ORDERS_MANAGE · 404 pedido de outra organização

Do zero a um pedido confirmado, com estoque movimentado e preço de atacado resolvido.

flowchart LR
  P1["1. Autenticar no IAM"] --> P2["2. Criar a loja"]
  P2 --> P3["3 e 4. Produto e variante"]
  P3 --> P4["5 e 6. Local de estoque e entrada"]
  P4 --> P5["7. Conferir o saldo"]
  P5 --> P6["8 e 9. Tabela de atacado e preço efetivo"]
  P6 --> P7["10 e 11. Criar e confirmar o pedido"]
  P7 --> P8["12. Ver o histórico"]
  P8 --> P9["13. Confirmar que o isolamento é real"]

Os comandos abaixo não foram executados nesta redação — o Commerce não está listado em documentacao/credenciais/AMBIENTES.md. Confirme o host de staging com o time de plataforma antes de rodar. Credenciais de staging, nunca de produção.

1. Autenticar no IAM

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://commerce.bb.stg.catalisa.app/commerce/api/v1

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://commerce.bb.stg.catalisa.app/commerce/api/v1

2. Criar a loja

STORE=$(curl -s -X POST "$BASE/stores" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Loja Demo","slug":"loja-demo","type":"GENERAL"}' | jq -r '.data.id')

echo "store: $STORE"

STORE=$(curl -s -X POST "$BASE/stores" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Loja Demo","slug":"loja-demo","type":"GENERAL"}' | jq -r '.data.id')

echo "store: $STORE"

Formato esperado da saída — um UUID:

store: 8f3c1d2a-5b47-4c9e-9f10-2ab3c4d5e6f7

store: 8f3c1d2a-5b47-4c9e-9f10-2ab3c4d5e6f7

3. Criar o produto

PROD=$(curl -s -X POST "$BASE/stores/$STORE/products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Camiseta Básica","type":"PHYSICAL","status":"ACTIVE"}' | jq -r '.data.id')

PROD=$(curl -s -X POST "$BASE/stores/$STORE/products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Camiseta Básica","type":"PHYSICAL","status":"ACTIVE"}' | jq -r '.data.id')

4. Criar a variante — é ela que carrega SKU e preço

VAR=$(curl -s -X POST "$BASE/stores/$STORE/products/$PROD/variants" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sku":"CAM-BAS-P-PRETA","name":"Camiseta Básica P Preta","basePrice":79.90}' \
  | jq -r '.data.id')

VAR=$(curl -s -X POST "$BASE/stores/$STORE/products/$PROD/variants" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sku":"CAM-BAS-P-PRETA","name":"Camiseta Básica P Preta","basePrice":79.90}' \
  | jq -r '.data.id')

5. Criar o local de estoque

LOC=$(curl -s -X POST "$BASE/stores/$STORE/stock-locations" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Depósito Central","code":"DEP-01","isDefault":true}' | jq -r '.data.id')

LOC=$(curl -s -X POST "$BASE/stores/$STORE/stock-locations" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Depósito Central","code":"DEP-01","isDefault":true}' | jq -r '.data.id')

6. Dar entrada no estoque

curl -s -X POST "$BASE/stores/$STORE/stock-movements" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"type\":\"INBOUND\",\"quantity\":120,
       \"toLocationId\":\"$LOC\",\"reason\":\"Carga inicial\"}" | jq '.data.type'

curl -s -X POST "$BASE/stores/$STORE/stock-movements" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"type\":\"INBOUND\",\"quantity\":120,
       \"toLocationId\":\"$LOC\",\"reason\":\"Carga inicial\"}" | jq '.data.type'

Resposta esperada:

"INBOUND"

"INBOUND"

7. Conferir o saldo

curl -s "$BASE/stores/$STORE/stock/levels/$VAR" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[0] | {quantity, reservedQty}'

curl -s "$BASE/stores/$STORE/stock/levels/$VAR" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[0] | {quantity, reservedQty}'

{ "quantity": 120, "reservedQty": 0 }

{ "quantity": 120, "reservedQty": 0 }

8. Criar a tabela de atacado

PL=$(curl -s -X POST "$BASE/stores/$STORE/price-lists" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Atacado","type":"WHOLESALE","priority":10}' | jq -r '.data.id')

curl -s -X POST "$BASE/stores/$STORE/price-lists/$PL/entries" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"price\":59.90,\"minQuantity\":12}" > /dev/null

PL=$(curl -s -X POST "$BASE/stores/$STORE/price-lists" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Atacado","type":"WHOLESALE","priority":10}' | jq -r '.data.id')

curl -s -X POST "$BASE/stores/$STORE/price-lists/$PL/entries" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"price\":59.90,\"minQuantity\":12}" > /dev/null

9. Testar o preço efetivo nas duas pontas

# 1 unidade: nenhuma entrada se aplica → use o basePrice (79.90)
curl -s "$BASE/stores/$STORE/price-lists/effective-price/$VAR?quantity=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.data'

# 12 unidades: a entrada de atacado vence
curl -s "$BASE/stores/$STORE/price-lists/effective-price/$VAR?quantity=12" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.price'

# 1 unidade: nenhuma entrada se aplica → use o basePrice (79.90)
curl -s "$BASE/stores/$STORE/price-lists/effective-price/$VAR?quantity=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.data'

# 12 unidades: a entrada de atacado vence
curl -s "$BASE/stores/$STORE/price-lists/effective-price/$VAR?quantity=12" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.price'

"59.9000"

"59.9000"

10. Criar o pedido

ORDER=$(curl -s -X POST "$BASE/stores/$STORE/orders" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"source\":\"API\",\"customerName\":\"Maria Souza\",
       \"items\":[{\"variantId\":\"$VAR\",\"quantity\":2}]}" | jq -r '.data.id')

ORDER=$(curl -s -X POST "$BASE/stores/$STORE/orders" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"source\":\"API\",\"customerName\":\"Maria Souza\",
       \"items\":[{\"variantId\":\"$VAR\",\"quantity\":2}]}" | jq -r '.data.id')

11. Confirmar o pedido

curl -s -X POST "$BASE/stores/$STORE/orders/$ORDER/confirm" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"reason":"Pagamento aprovado"}' | jq '{status: .data.status, at: .data.confirmedAt}'

curl -s -X POST "$BASE/stores/$STORE/orders/$ORDER/confirm" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"reason":"Pagamento aprovado"}' | jq '{status: .data.status, at: .data.confirmedAt}'

{ "status": "CONFIRMED", "at": "2026-08-16T14:02:11.417Z" }

{ "status": "CONFIRMED", "at": "2026-08-16T14:02:11.417Z" }

12. Ver o histórico

curl -s "$BASE/stores/$STORE/orders/$ORDER/history" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {fromStatus, toStatus, reason}'

curl -s "$BASE/stores/$STORE/orders/$ORDER/history" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {fromStatus, toStatus, reason}'

Resposta esperada — a linha gravada na criação, sem fromStatus, seguida de uma linha por transição:

{ "fromStatus": null, "toStatus": "DRAFT", "reason": null }
{ "fromStatus": "DRAFT", "toStatus": "CONFIRMED", "reason": "Pagamento aprovado" }

{ "fromStatus": null, "toStatus": "DRAFT", "reason": null }
{ "fromStatus": "DRAFT", "toStatus": "CONFIRMED", "reason": "Pagamento aprovado" }

13. Confirmar que o isolamento é real

# Um storeId que não é da sua organização responde 404, não 403 e não dado
curl -s -o /dev/null -w "%{http_code}\n" \
  "$BASE/stores/00000000-0000-0000-0000-000000000000/products" \
  -H "Authorization: Bearer $TOKEN"

# Um storeId que não é da sua organização responde 404, não 403 e não dado
curl -s -o /dev/null -w "%{http_code}\n" \
  "$BASE/stores/00000000-0000-0000-0000-000000000000/products" \
  -H "Authorization: Bearer $TOKEN"

Retorna 404. A loja de outra organização não existe do seu ponto de vista.

Publicar um produto completo, do zero ao pronto para venda

Objetivo. Sair de nada até um produto ativo, com grade, imagem, categoria e preço.

flowchart LR
  C["1. Categoria"] --> P["2. Produto vinculado à categoria"]
  P --> V["3. Grade de variantes"]
  V --> I["4. Imagem"]
  I --> F["5. Config fiscal"]
  F --> A["6. Ativar o produto"]
  A --> OK["Produto pronto para venda"]

1. Criar a categoria

CAT=$(curl -s -X POST "$BASE/stores/$STORE/categories" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Camisetas","slug":"camisetas"}' | jq -r '.data.id')

CAT=$(curl -s -X POST "$BASE/stores/$STORE/categories" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Camisetas","slug":"camisetas"}' | jq -r '.data.id')

2. Criar o produto já vinculado à categoria

PROD=$(curl -s -X POST "$BASE/stores/$STORE/products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\":\"Camiseta Básica\",\"type\":\"PHYSICAL\",
       \"categoryIds\":[\"$CAT\"],\"tags\":[\"verao\"]}" | jq -r '.data.id')

PROD=$(curl -s -X POST "$BASE/stores/$STORE/products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\":\"Camiseta Básica\",\"type\":\"PHYSICAL\",
       \"categoryIds\":[\"$CAT\"],\"tags\":[\"verao\"]}" | jq -r '.data.id')

3. Criar a grade de variantes — uma chamada por combinação

for t in P M G; do
  curl -s -X POST "$BASE/stores/$STORE/products/$PROD/variants" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"sku\":\"CAM-BAS-$t-PRETA\",\"name\":\"Camiseta Básica $t Preta\",
         \"basePrice\":79.90,\"options\":{\"tamanho\":\"$t\",\"cor\":\"preta\"}}" \
    | jq -r '.data.sku'
done

for t in P M G; do
  curl -s -X POST "$BASE/stores/$STORE/products/$PROD/variants" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"sku\":\"CAM-BAS-$t-PRETA\",\"name\":\"Camiseta Básica $t Preta\",
         \"basePrice\":79.90,\"options\":{\"tamanho\":\"$t\",\"cor\":\"preta\"}}" \
    | jq -r '.data.sku'
done

Resposta esperada — um SKU por linha:

CAM-BAS-P-PRETA
CAM-BAS-M-PRETA
CAM-BAS-G-PRETA

CAM-BAS-P-PRETA
CAM-BAS-M-PRETA
CAM-BAS-G-PRETA

4. Anexar a imagem — fileId do File Storage é preferível a url externa

curl -s -X POST "$BASE/stores/$STORE/products/$PROD/images" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"fileId":"a1b2...uuid","altText":"Camiseta preta vista frontal","isPrimary":true}'

curl -s -X POST "$BASE/stores/$STORE/products/$PROD/images" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"fileId":"a1b2...uuid","altText":"Camiseta preta vista frontal","isPrimary":true}'

5. Gravar a configuração fiscal

curl -s -X PUT "$BASE/stores/$STORE/products/$PROD/tax-config" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ncm":"61091000","cfop":"5102","icmsRate":0.18,"origem":"0"}'

curl -s -X PUT "$BASE/stores/$STORE/products/$PROD/tax-config" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ncm":"61091000","cfop":"5102","icmsRate":0.18,"origem":"0"}'

6. Ativar o produto

curl -s -X PATCH "$BASE/stores/$STORE/products/$PROD" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"ACTIVE"}' | jq '.data.status'

curl -s -X PATCH "$BASE/stores/$STORE/products/$PROD" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"ACTIVE"}' | jq '.data.status'

Resposta esperada:

"ACTIVE"

"ACTIVE"

Armadilhas.

• type é obrigatório na criação do produto e não tem valor padrão. Omitir devolve 400 sem que a mensagem deixe óbvio qual campo faltou.
• O SKU é único por loja, não por produto. Duas variantes de produtos diferentes com o mesmo SKU colidem com 409 — o que geralmente é o comportamento que você quer.
• Não existe endpoint de criação de grade em lote. Grade de 5 tamanhos × 4 cores são 20 chamadas.
• PUT em tax-config substitui o registro inteiro. Campo omitido some; ele não é um PATCH.
• A alíquota vai em fração, não em percentual: 0.18 para 18%. O schema recusa valores acima de 1.
• A config fiscal do produto sobrepõe a da categoria. Se você configurou a categoria e depois o produto, só a do produto vale.

Ligar um produto em um canal com preço próprio

Objetivo. O mesmo catálogo aparece diferente em cada ponto de venda.

flowchart LR
  CAT["Catálogo único da loja"] --> CH1["Canal STOREFRONT"]
  CAT --> CH2["Canal DELIVERY_PLATFORM"]
  CAT --> CH3["Canal POS"]
  CH1 --> D1["isAvailable e priceOverride por produto"]
  CH2 --> D2["isAvailable e priceOverride por produto"]
  CH3 --> D3["isAvailable e priceOverride por produto"]

1. Criar o canal

CH=$(curl -s -X POST "$BASE/stores/$STORE/channels" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"App de Delivery","type":"DELIVERY_PLATFORM"}' | jq -r '.data.id')

CH=$(curl -s -X POST "$BASE/stores/$STORE/channels" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"App de Delivery","type":"DELIVERY_PLATFORM"}' | jq -r '.data.id')

2. Ligar um produto por vez, com preço específico do canal

curl -s -X PUT "$BASE/stores/$STORE/channels/$CH/products/$PROD/availability" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"isAvailable":true,"priceOverride":94.90}'

curl -s -X PUT "$BASE/stores/$STORE/channels/$CH/products/$PROD/availability" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"isAvailable":true,"priceOverride":94.90}'

3. Ou ligar e desligar em lote

curl -s -X PUT "$BASE/stores/$STORE/channels/$CH/products/bulk" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"products\":[
        {\"productId\":\"$PROD\",\"isAvailable\":true,\"priceOverride\":94.90},
        {\"productId\":\"$PROD2\",\"isAvailable\":false}
      ]}"

curl -s -X PUT "$BASE/stores/$STORE/channels/$CH/products/bulk" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"products\":[
        {\"productId\":\"$PROD\",\"isAvailable\":true,\"priceOverride\":94.90},
        {\"productId\":\"$PROD2\",\"isAvailable\":false}
      ]}"

Armadilhas.

• Há dois mecanismos de preço por canal e eles não se conversam: priceOverride na disponibilidade (por produto) e PriceList do tipo CHANNEL com channelId (por variante). O effective-price só enxerga o segundo. Escolha um por operação; misturar produz preço que ninguém explica.
• Ausência de registro de disponibilidade não é o mesmo que indisponível. Se o seu storefront trata "sem registro" como disponível, criar o canal já publica todo o catálogo nele.
• Excluir a regra (DELETE .../availability) volta ao estado "sem registro" — não marca como indisponível.

Reservar estoque de verdade durante o checkout

Objetivo. Segurar a quantidade enquanto o cliente paga, sem depender do ciclo de vida do pedido.

Este é o ponto que mais gera chamado. POST /orders/:id/confirm não reserva estoque — a chamada existe no código, mas o método está vazio (§15). Enquanto isso não muda, faça a reserva pelo movimento explícito e libere ou consuma junto com a transição.

flowchart TD
  A["Checkout do cliente"] --> B["GET /stock/levels/:variantId"]
  B --> C{"Disponível maior ou igual ao pedido?"}
  C -->|não| D["Recuse antes de criar o pedido"]
  C -->|sim| E["POST /stock-movements OUTBOUND com referenceType order"]
  E --> F["POST /orders/:id/confirm"]
  F --> G{"O pedido foi cancelado?"}
  G -->|sim| H["POST /stock-movements INBOUND, o inverso, com a mesma referência"]
  G -->|não| I["Baixa já está feita; complete o pedido"]

1. Antes de confirmar, verifique o disponível

curl -s "$BASE/stores/$STORE/stock/levels/$VAR" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | (.quantity - .reservedQty)'

curl -s "$BASE/stores/$STORE/stock/levels/$VAR" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | (.quantity - .reservedQty)'

Resposta esperada — o disponível de cada local, um por linha:

120

120

2. Registre a saída amarrada ao pedido, como referência rastreável

curl -s -X POST "$BASE/stores/$STORE/stock-movements" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"type\":\"OUTBOUND\",\"quantity\":2,
       \"fromLocationId\":\"$LOC\",\"referenceType\":\"order\",
       \"referenceId\":\"$ORDER\",\"reason\":\"Baixa por pedido confirmado\"}"

curl -s -X POST "$BASE/stores/$STORE/stock-movements" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"type\":\"OUTBOUND\",\"quantity\":2,
       \"fromLocationId\":\"$LOC\",\"referenceType\":\"order\",
       \"referenceId\":\"$ORDER\",\"reason\":\"Baixa por pedido confirmado\"}"

3. Se o pedido for cancelado, estorne com o movimento inverso

curl -s -X POST "$BASE/stores/$STORE/stock-movements" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"type\":\"INBOUND\",\"quantity\":2,
       \"toLocationId\":\"$LOC\",\"referenceType\":\"order\",
       \"referenceId\":\"$ORDER\",\"reason\":\"Estorno de cancelamento\"}"

curl -s -X POST "$BASE/stores/$STORE/stock-movements" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"variantId\":\"$VAR\",\"type\":\"INBOUND\",\"quantity\":2,
       \"toLocationId\":\"$LOC\",\"referenceType\":\"order\",
       \"referenceId\":\"$ORDER\",\"reason\":\"Estorno de cancelamento\"}"

Armadilhas.

• Não há trava de saldo negativo. OUTBOUND de 10 com 3 em estoque passa e deixa o saldo em -7. A verificação é sua, e entre a verificação e a movimentação existe uma janela de corrida — em concorrência alta, serialize por variante no seu lado.
• As reservas que o stock.service sabe criar (reserveStock) não têm endpoint HTTP. Só o fluxo interno as cria. Pelas rotas você consulta e libera reserva, mas não cria.
• DELETE /stock/reservations/:id libera todas as reservas que compartilham o mesmo referenceType + referenceId daquela, não apenas a que você apontou. Para um pedido com vários itens, uma chamada libera o pedido inteiro.
• → CANCELLED e → COMPLETED chamam liberar e consumir reservas por ('order', orderId). Se você não criou reserva nenhuma, as duas chamadas não fazem nada — e é por isso que a baixa precisa ser sua.

Descobrir por que um pedido não avança

Objetivo. Resolver o 400 Cannot transition from X to Y sem abrir o código.

1. Descobrir em que estado ele está

curl -s "$BASE/stores/$STORE/orders/$ORDER" -H "Authorization: Bearer $TOKEN" \
  | jq '{status: .data.status, confirmedAt: .data.confirmedAt}'

curl -s "$BASE/stores/$STORE/orders/$ORDER" -H "Authorization: Bearer $TOKEN" \
  | jq '{status: .data.status, confirmedAt: .data.confirmedAt}'

Resposta esperada:

{ "status": "READY", "confirmedAt": "2026-08-16T14:02:11.417Z" }

{ "status": "READY", "confirmedAt": "2026-08-16T14:02:11.417Z" }

2. Ver como ele chegou aí

curl -s "$BASE/stores/$STORE/orders/$ORDER/history" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {from: .fromStatus, to: .toStatus, por: .changedBy, quando: .createdAt}'

curl -s "$BASE/stores/$STORE/orders/$ORDER/history" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {from: .fromStatus, to: .toStatus, por: .changedBy, quando: .createdAt}'

3. Seguir a árvore de diagnóstico

flowchart TD
  E["A chamada de transição falhou"] --> S{"Qual é o status HTTP?"}
  S -->|400| T{"O destino está na lista do estado atual?"}
  T -->|não| T1["Corrija o caminho pelo diagrama da seção 8"]
  T -->|sim| T2["Confira o corpo contra o schema da seção 9"]
  S -->|403| P{"Qual transição você chamou?"}
  P -->|cancel| P1["Falta COMMERCE_ORDERS_CANCEL"]
  P -->|refund| P2["Falta COMMERCE_ORDERS_REFUND"]
  P -->|"as demais"| P3["Falta COMMERCE_ORDERS_MANAGE"]
  S -->|404| N["Pedido de outra organização, ou storeId da URL não é o da loja do pedido"]
  S -->|"400 em PATCH"| A["Só pedido em DRAFT aceita PATCH"]

Ordem de diagnóstico:

1. O destino está na lista do estado atual? Confira o diagrama da §8. O erro mais comum é tentar deliver a partir de READY — o caminho passa por SHIPPED ou OUT_FOR_DELIVERY.
2. É 403 e não 400? Então é permissão. cancel exige COMMERCE_ORDERS_CANCEL e refund exige COMMERCE_ORDERS_REFUND — nenhuma das duas vem com COMMERCE_ORDERS_MANAGE.
3. É PATCH que falhou? Só pedido em DRAFT aceita PATCH. Depois de confirmado, dados do pedido são imutáveis pela API.
4. É 404? O pedido é de outra organização, ou o storeId da URL não é o da loja do pedido.

Anexar um provedor e disparar a primeira sincronização

Objetivo. Montar a topologia de sincronização e entender o que ela faz hoje.

O que acontece dentro de uma execução de sincronização

sequenceDiagram
  autonumber
  participant R as provider-sync.router
  participant E as SyncEngine
  participant J as CommerceProviderSyncJob
  participant P as Adaptador do provedor
  participant M as MappingService
  participant C as ConflictResolver
  R->>E: syncProducts com direção e storeProviderId
  E->>J: cria o job já em IN_PROGRESS
  E->>E: instantiateProvider pelo providerType
  alt tipo sem adaptador
    E->>J: failSyncJob com Unsupported provider type
    E-->>R: 500 INTERNAL
  else PULL
    E->>P: fetchProducts
    P-->>E: lista canônica
    loop um produto por vez, em sequência
      E->>M: findExternalMapping pelo SKU
      alt já mapeado
        E->>C: resolveProductConflict campo a campo
        C-->>E: produto mesclado e lista de conflitos
        E->>M: upsertProductMapping com ACTIVE ou CONFLICT
      else novo
        E->>E: cria produto e variantes internos
        E->>M: upsertProductMapping com ACTIVE
      end
    end
    E->>J: completeSyncJob com os contadores
    E->>R: evento commerce.provider.sync_completed
  end

1. Criar a configuração do provedor

CFG=$(curl -s -X POST "$BASE/stores/$STORE/providers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"providerType":"CATALISA","name":"Catálogo interno","credentials":{}}' \
  | jq -r '.data.id')

CFG=$(curl -s -X POST "$BASE/stores/$STORE/providers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"providerType":"CATALISA","name":"Catálogo interno","credentials":{}}' \
  | jq -r '.data.id')

2. Anexar à loja — o primeiro vínculo define a topologia

SP=$(curl -s -X POST "$BASE/stores/$STORE/store-providers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"providerConfigId\":\"$CFG\",\"role\":\"PRIMARY\",\"syncDirection\":\"BOTH\"}" \
  | jq -r '.data.id')

SP=$(curl -s -X POST "$BASE/stores/$STORE/store-providers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"providerConfigId\":\"$CFG\",\"role\":\"PRIMARY\",\"syncDirection\":\"BOTH\"}" \
  | jq -r '.data.id')

3. Sincronizar produtos

curl -s -X POST "$BASE/stores/$STORE/store-providers/$SP/sync/products" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{sincronizados: .data.itemsSynced, criados: .data.itemsCreated,
         atualizados: .data.itemsUpdated, ignorados: .data.itemsSkipped}'

curl -s -X POST "$BASE/stores/$STORE/store-providers/$SP/sync/products" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{sincronizados: .data.itemsSynced, criados: .data.itemsCreated,
         atualizados: .data.itemsUpdated, ignorados: .data.itemsSkipped}'