Perguntas para o BDApp — Especificação de Migração

Respostas precisas sobre a automação atual do BancaOS. Contexto: migração de WooCommerce webhook + Google Sheets para BDApp próprio.

58 perguntas · 8 blocos Última atualização: 20/05/2026
A — WooCommerce WebhookB — Aba PedidosC — Aba ClientesD — Aba InventárioE — Aba SepararF — Reprocessamento e FalhasG — Infra e Configuração AtualH — Escopo Residual
A

BLOCO A — WooCommerce Webhook

10 perguntas
A1

Quais eventos do WooCommerce disparam a automação?

order.created e order.updated.
A2

O processamento acontece em ambos os eventos?

Sim. order.created insere o pedido pela primeira vez. order.updated atualiza status e sincroniza com Google Sheets quando o status muda.
A3

Quais status geram escrita na planilha?

processing, on-hold, completed, refunded, cancelled.
A4

Quais status são ignorados?

pending, failed — não geram sync Sheets, mas são registrados no DB se vierem via webhook.
A5

Pedido cancelled: atualiza a planilha?

SIM — atualiza a linha existente na aba Pedidos com novo status. O sistema faz upsert (não apaga a linha).
A6

Pedido refunded: atualiza a planilha?

SIM — mesmo comportamento de cancelled. Atualiza status na aba Pedidos.
A7

Pedido on-hold: entra no fluxo?

SIM — gravado no DB + sync Sheets. O status não dispara nenhuma regra especial além do upsert normal.
A8

O webhook processa toda mudança de status?

Sim — não apenas o primeiro. Cada order.updated que muda o status sincroniza a planilha. No BDApp, considerar se on-hold → processing deve ou não atualizar o já-written.
A9

Como funciona a idempotência?

Considera apenas order_id (não order_id + status). O sistema verifica se woo_order_id já existe no DB antes de inserir. Se existir, faz UPDATE.
A10

Se o pedido muda de processing para completed?

O sistema atualiza o que já foi escrito (upsert). A linha original é alterada in-place, com novos valores de status, updated_at, etc.
B

BLOCO B — Aba Pedidos

10 perguntas
B11

A aba Pedidos é obrigatória?

SIM. É a fonte primária do pedido no Google Sheets.
B12

Quais são as colunas exatas da aba Pedidos?

ColNomeDescrição
Aorder_idNúmero do pedido WooCommerce
BdataData/hora — DD/MM/YYYY HH:mm
CclienteNome completo de billing
DemailEmail
EtelefoneTelefone
FtotalValor total — R$ X.XXX,XX
GstatusStatus em PT-BR (processando, concluído, cancelado, estornado)
HitensTodos os itens concatenados: qtd × Nome (SKU)
IendereçoEndereço completo de billing
JcidadeCidade
KestadoUF com 2 letras
LCPFCapturado dos meta_data do WooCommerce
MfreteValor do frete — R$ X.XXX,XX
NpagamentoMétodo: PIX, Cartão de crédito, Boleto, etc.
B13

Quais campos do WooCommerce alimentam cada coluna?

ColunaCampo WooCommerce
order_idid
datadate_created
clientebilling.first_name + billing.last_name
emailbilling.email
telefonebilling.phone
totaltotal (inclui frete e desconto)
statusstatus (mapeado para PT-BR)
itensline_itemsquantity × name (sku)
endereçobilling.address_1 + billing.number
cidadebilling.city
estadobilling.state
CPFmeta_data_billing_cpf ou billing_cpf
freteshipping_total
pagamentopayment_method_title
B14

Cada pedido gera quantas linhas?

UMA linha única. Se o pedido tem 5 itens, a coluna H concatena todos: "2 × Playboy 1984 (PB1984) | 1 × Nova 1987 (NV1987)".
B15

Se o pedido for atualizado depois?

A linha original é ALTERADA (não criada nova). O upsert atualiza status, total, frete, itens (se adicionados) e CPF.
B16

O CPF entra na aba Pedidos?

SIM — coluna L. Valor salvo com formatação literal do WooCommerce (sem máscara). A máscara 000.000.000-00 é aplicada apenas na exibição da interface.
B17

O método de pagamento entra na aba Pedidos?

SIM — coluna N. Valor vem de payment_method_title do WooCommerce: "PIX", "Cartão de crédito", "Transferência bancária", etc.
B18

O frete entra na aba Pedidos?

SIM — coluna M. Valor vem de shipping_total. Se o pedido não tem frete (retirada), grava R$ 0,00 ou .
B19

Como os itens são escritos?

Concatenados em UMA célula (coluna H). Separador: | . Formato: qtd × NomeDoProduto (SKU).
B20

Quais formatações são obrigatórias?

  • Data: DD/MM/YYYY HH:mm (ex: 20/05/2026 14:32)
  • Moeda: R$ X.XXX,XX com ponto de milhar e vírgula decimal
  • Telefone: XX XXXXX-XXXX (ex: 11 98765-4321)
  • CPF: gravado com máscara XXX.XXX.XXX-XX se o WooCommerce enviar formatado, senão salvo raw
  • Estado (UF): 2 letras maiúsculas (ex: SP, RJ, MG)
C

BLOCO C — Aba Clientes

7 perguntas
C21

A aba Clientes é obrigatória?

SIM. Funciona como consolidado por cliente.
C22

Qual é a chave de identificação?

EMAIL. O sistema agrupa pedidos por billing.email. CPF é um campo complementar, não a chave.
C23

Se o cliente já existe (mesmo email)?

Os campos total_gasto e qtd_pedidos são acumulados. O endereço é atualizado com o valor do pedido mais recente. Campos como nome e telefone são atualizados se vierem com valor (não sobrescreve com vazio).
C24

Total gasto e quantidade de pedidos são acumulados?

SIM:
  • total_gasto = soma de total de todos os pedidos do cliente
  • qtd_pedidos = contagem de pedidos
  • Ambos são recalculados a cada novo pedido (não persistidos como running total — recalculados via query)
C25

O endereço é atualizado?

Sim, a cada novo pedido. O sistema substitui o valor existente pelo do pedido mais recente (upsert com dados novos).
C26

Se o email estiver vazio?

O pedido NÃO gera registro na aba Clientes. É registrado apenas na aba Pedidos com cliente = "Anônimo" ou cliente = "SEM EMAIL".
C27

Existe tratamento para CPF vazio?

SIM — se o CPF vier vazio ou não for coletado, o sistema grava ou deixa em branco na aba Clientes. Não impede o processamento. Pedidos de pessoas jurídicas (CNPJ) também podem ter CNPJ no lugar de CPF (campo _billing_cnpj).
D

BLOCO D — Aba Inventário

10 perguntas
D28

A aba Inventário é obrigatória?

SIM — é a referência de estoque da operação.
D29

O SKU é a chave para localizar o item?

SIM.
D30

Qual a coluna do SKU?

B (segunda coluna, imediatamente após PRODUTO).
D31

Quais colunas são atualizadas quando uma venda acontece?

  • StatusVendida (coluna E)
  • Pedido → número do pedido WooCommerce (coluna F)
  • Data da venda → data do pedido (coluna G)
  • Preço venda → total da linha items (coluna H)
D32

O status esperado é "Vendida"?

SIM.
D33

O sistema grava o número do pedido WooCommerce?

SIM.
D34

O sistema grava a data da venda?

SIM — extraída de date_created do pedido WooCommerce.
D35

O sistema grava o preço da venda?

SIM — valor unitário do item no momento da venda, extraído de line_items.
D36

Se o SKU do pedido não for encontrado na planilha?

O sistema IGNORA esse item no sync da aba Inventário. O pedido ainda é escrito na aba Pedidos. Um warning é logado: "SKU X não encontrado no inventário".
D37

Se o pedido tiver mais de um item?

SIM — o sistema atualiza UM SKU por vez (loop sobre cada line_item). Cada SKU vira uma linha separada na aba Inventário.
E

BLOCO E — Aba Separar

7 perguntas
E38

A aba Separar é obrigatória?

SIM — é a guia operacional de separação do pedido.
E39

Cada ITEM vendido gera uma linha?

SIM — cada item vendido gera UMA linha. Não é por pedido. Se um pedido tem 3 itens diferentes, são 3 linhas.
E40

Quais são as colunas da aba Separar?

  • SKU — código do produto
  • Produto — nome descritivo
  • Qtd — quantidade vendida (1 por linha)
  • Pedido — número do pedido
  • Cliente — nome do cliente
  • Cidade — cidade de entrega
  • UF — estado de entrega
  • Endereço — endereço completo de entrega
  • CEP — CEP de entrega
  • Observações — campo manual, não sobrescrito pelo sistema
E41

Como funciona a escrita?

Por APPEND — cada novo item vendido adiciona uma linha no final da aba. O sistema NÃO atualiza linhas existentes (não há UPDATE na aba Separar).
E42

Se o pedido for atualizado depois (ex: item cancelado)?

A aba Separar NÃO é corrigida automaticamente. A linha original permanece. A correção é MANUAL (operador remove a linha).
E43

Quando o pedido muda para completed, cancelled ou refunded?

A aba Separar não é alterada automaticamente. O operador precisa marcar manualmente como "separado" ou remover a linha.
E44

A coluna Observações é manual?

SIM. O sistema nunca sobrescreve esse campo. Se uma re-execução do webhook escrever o mesmo SKU + pedido, a coluna Observações é preservada.
F

BLOCO F — Reprocessamento e Falhas

6 perguntas
F45

O que acontece quando uma execução falha?

O operador reporta via chat → Polsia abre task de bug → agente executa correção → re-deploy. Não há interface de reprocessamento self-service. A correção pode incluir re-execução manual do endpoint de sync.
F46

Existe endpoint de reprocessamento?

SIM:
  • GET /api/analytics/backfill — busca TODOS os pedidos da WooCommerce API e upsert no DB + Sheets
  • GET /api/cpf/db-backfill — backfill de CPFs
  • Ambos requerem ?token=SECRET
F47

O reprocessamento acontece por ORDER_ID?

Sim, cada endpoint de backfill aceita parâmetros de filtro (ex: por data, por range de IDs).
F48

O reprocessamento reescreve todas as abas?

Pedidos (upsert), Clientes (recalcula totals), Inventário (marca status para os SKUs do pedido), e Separar (não impacta — é append-only por item). A aba Separar não é regenerada pelo backfill.
F49

Existe proteção contra duplicidade?

SIM — o upsert no DB verifica woo_order_id. No Google Sheets, o sistema usa findOrCreateRow que busca a linha por order_id antes de escrever. Se encontrar, atualiza in-place.
F50

O sistema guarda log detalhado por pedido?

SIM — cada webhook execution gera um execId (ex: wh_1778363141020_5soojf). Os logs incluem: step (idempotency_check, process, db_write, sheets_sync), status (success/error/fatal), consecutive_errors, error (mensagem). Logs acessíveis via Polsia dashboard.
G

BLOCO G — Infra e Configuração Atual

5 perguntas
G51

Qual a URL atual do webhook WooCommerce?

POST /webhook/woocommerce?token=***
(Token real omitido por segurança)
G52

Como funciona a validação?

O webhook usa HMAC-SHA256 com o woocommerce_webhook_secret configurado no WooCommerce. O middleware extrai o header X-Wc-Webhook-Signature, calcula HMAC do body, e compara. Se não bater, retorna 401. A validação HMAC é opcional mas recomendada.
G53

Como está configurado o Google Service Account?

O Service Account está ligado à conta bancadasantigas@gmail.com. O JSON contém client_email que deve ter acesso de editor na planilha Google Sheets. Criado no Google Cloud Console.
G54

A planilha atual vai continuar a mesma?

SIM — sem dependência da estrutura temporária do Polsia. O BDApp deve consumir a planilha Google Sheets existente, mantendo as mesmas abas e colunas. Alternativa: migrar para banco de dados próprio (Neon) e abandonar Sheets — mas nesse caso, as abas Pedidos, Clientes, Inventário e Separar precisam ser recriadas no DB.
G55

Existe configuração obrigatória?

SIM:
  • A planilha Google Sheets precisa ter as 4 abas com os cabeçalhos exatos documentados
  • O Service Account precisa ter acesso de Editor na planilha
  • O nome da planilha não afeta a lógica
H

BLOCO H — Escopo Residual

3 perguntas
H56

Existem automações operacionais adicionais?

SIM:
  • Feed Pinterest XML/CSV/api/pinterest/feed.xml, /api/pinterest/feed.csv. Alimenta Pinterest Business Catalog. Atualiza diariamente. Requer: tabela pinterest_catalog populada + 15+ produtos safe.
  • Email de notificação de pedido — enviado para bancadasantigas@gmail.com a cada novo pedido pago.
  • Mercado Livre sync — painel /mercadolivre com 22 SKUs precificados. NÃO é automação contínua, é apenas uma página de referência.
H57

Qual integração externa NÃO pode esperar?

O feed Pinterest — 15 produtos estão classificados como safe e prontos para submissão. Se o BDApp não suportar feed Pinterest, essa integração para.
H58

Existe automação que escreve de volta no WooCommerce?

SIM — Alt text batch update (PATCH em meta_data dos produtos WooCommerce via API REST). Atualização em lote de alt text de imagens. Roda sob demanda (não contínua). Esta automação ESCREVE no WooCommerce.

BancaOS — Especificação de migração BDApp · 58 respostas documentadas

Gerado automaticamente em 20/05/2026