Validador de Número de Pedido

Validação de número de pedido: formatos, estratégias e armadilhas no e-commerce e SaaS B2B

O número de pedido (Order ID) é o identificador canônico que um sistema usa para referenciar uma compra, contrato ou ordem de serviço. Ele ancora todo o fluxo downstream — separação, faturamento, atendimento, troca, contabilidade e fiscal — então o formato, a unicidade e a previsibilidade são decisões de engenharia surpreendentemente carregadas. Uma má escolha trava você em vazar métricas de negócio, fricção no SAC ou migrações caras depois.

Não existe padrão nacional único como CPF ou chave de NF-e. Cada empresa desenha seu esquema, normalmente combinando prefixo, componente de data e um núcleo sequencial ou aleatório: PED-2026-001234, ORD-2026-S-001, MAG-2026-77B8A2. O validador desta página checa as regras estruturais (tamanho, charset, prefixo, checksum) — a unicidade semântica ainda exige consulta ao banco.

As cinco estratégias mais comuns

• Inteiro sequencial (AUTO_INCREMENT BIGINT): menor, ordenável por criação, trivial de debugar. Defeito grave: vaza volume — concorrente que faz pedido segunda e outro sexta subtrai IDs e estima volume semanal. Fácil de enumerar (ID guessing em URLs).
• UUID v4 (128 bits aleatórios, 36 chars hex): colisão praticamente zero, imprevisível. Defeitos: feio em URL (/pedidos/3f29c1a8-3b7e-4c2a-...), incha índice do banco (fragmentação de B-tree), não ordenável.
• UUID v7 (time-ordered, RFC 9562, 2024): mantém a imprevisibilidade do v4 mas os primeiros 48 bits são timestamp em ms, então o índice fica compacto e ordenável. Default moderno recomendado.
• Snowflake (Twitter/Discord, inteiro de 64 bits): timestamp_ms | worker_id | sequence. Ordenável, distribuído, cabe em BIGINT, menor que UUID. Usado pelos backends de Mercado Livre e iFood.
• Legível por humano (PEDIDO-2026-00001): ótimo no SAC ("dite o número do pedido"), ruim quando você também precisa de imprevisibilidade criptográfica. Meio-termo: prefixo humano + sufixo aleatório (PED-2026-7K9MX2).

Resumo dos trade-offs

• Sequencial: pequeno, ordenável, vaza volume, enumerável — nunca exponha em URL pública.
• UUID v4: opaco, não vaza, feio, índice grande, sem ordem.
• UUID v7: opaco, ordenável, moderno — melhor default para sistemas novos.
• Snowflake: distribuído, ordenável, compacto — melhor para microsserviços de alto throughput.
• Hash-based (HMAC-SHA256(secret, internal_id)): mantém PK sequencial interno e publica ID opaco. Usado por Stripe (ch_3M...) e Shopify.

Casos de uso no comércio e SaaS brasileiros

Padrões reais no ecossistema BR:

• E-commerce: Magazine Luiza, Mercado Livre, Americanas e Shopee usam números opacos (10-15 chars alfanuméricos) para concorrentes não fazerem scraping de volumes. O campo infAdic/obsCont da NF-e carrega a referência interna do pedido.
• SaaS B2B: RD Station, Pipefy, Conta Azul tipicamente usam Snowflake ou UUID v7 com isolamento por tenant — cada cliente tem seu espaço de ID, normalmente prefixado com código do tenant.
• ERP corporativo: TOTVS Protheus e SAP Business One historicamente usam sequencial por filial (filial + ano + seq). Instalações modernas costumam adicionar um ID público hasheado para acesso via portal.
• Logística: uma NF-e pode referenciar vários pedidos, então o validador deve aceitar listas separadas por vírgula.
• Marketplaces: cada seller tem seu ID de pedido mais um ID do lado marketplace — juntar os dois é bug de integração frequente.

Anti-padrões e a lição do Soundcloud

O bug mais comum é expor ID interno sequencial na URL. Em 2017 um bug no Soundcloud permitiu que qualquer usuário iterasse /tracks/{id} e descobrisse uploads privados só chutando. A mesma classe de bug atingiu Trello, Snapchat e vários e-commerces brasileiros — a correção é sempre a mesma: manter PK sequencial interno no banco e publicar um ID opaco (UUID, Snowflake ou hash HMAC) para o mundo externo. O padrão hash-based é simples: public_id = base62(HMAC-SHA256(secret, internal_id))[:12]. O validador desta página checa apenas estrutura; você ainda precisa garantir unicidade no servidor e rate-limit no endpoint de consulta de pedido.

Pegadinhas de formato

• Mudar formato quebra link: todo email de confirmação, NF-e e integração externa carrega o ID para sempre. Decida uma vez, versione o esquema (PED-V2-...) se precisar mudar.
• Zeros à esquerda: 00001234 serializado como número JSON vira 1234 — sempre trate número de pedido como string ponta-a-ponta.
• Chars ambíguos: evite 0/O, 1/I/l, 5/S quando humanos vão ditar o ID no telefone — use Crockford base32 ou remova vogais (também evita palavrão acidental).
• Colisão multi-tenant: nunca compartilhe espaço de ID entre tenants sem prefixo — vazamento cross-tenant fica a um WHERE faltando de distância.

FAQ

Devo usar IDs incrementais ou aleatórios? Híbrido é a melhor prática moderna: PK sequencial BIGINT interno para joins e índice, ID opaco aleatório (UUID v7 ou hash HMAC) publicado externamente. Você ganha a eficiência do sequencial e a segurança do aleatório.

Qual tamanho ideal para o número de pedido público? Tipicamente 12-20 caracteres. Menos de 10 convida colisões e enumeração; mais de 24 atrapalha UX em email de confirmação e ligações no SAC. Stripe usa ~24 chars prefixados; a maioria dos e-commerces BR converge para 10-14.

Como tratar espaços de ID multi-tenant? Prefixe todo ID com código curto do tenant (ACME-PED-2026-...) ou use espaços de ID separados por tenant. Valide o prefixo do tenant em toda requisição — nunca confie só no body, já que IDs de outro tenant podem ser replayados.

O validador checa se o pedido existe? Não — ele valida somente estrutura (tamanho, prefixo, charset, checksum). Existência exige consulta ao banco. A checagem estrutural ainda é útil como pré-filtro rápido na borda para rejeitar IDs claramente malformados antes que cheguem ao ERP.