Fulfillment fiscal e expedição

Resultado esperado

1. A logística acessa uma fila exclusiva de pedidos com pagamento conciliado.
2. O operador separa, confere e registra indisponibilidades por item, sem alterar o histórico financeiro de forma livre.
3. A expedição gera uma etiqueta de transporte imprimível e um romaneio de separação.
4. O faturamento envia uma solicitação completa a um emissor fiscal, guarda chave, XML, DANFE/representação e eventos de retorno.
5. A transportadora atualiza coleta, trânsito, entrega ou ocorrência por integração autenticada e idempotente.
6. Crédito, complemento ou reembolso passam por uma decisão auditável e, quando aplicável, pelo provedor de pagamento.

Artefatos distintos

Regra de etiqueta

• cada remessa possui uma etiqueta principal por volume ou pacote;
• a etiqueta mostra dados essenciais de remetente, comprador, endereço, pedido, transportadora, rastreio, peso e volume;
• com até 15 linhas, ela pode trazer uma lista resumida de itens e quantidades, sempre sem valores;
• acima de 15 linhas, a etiqueta exibe apenas a referência do pedido, total de volumes e QR code/referência do romaneio; a relação completa fica em romaneio separado;
• o documento fiscal sempre recebe todos os itens e valores exigidos, independentemente do layout da etiqueta;
• impressão deve gerar HTML/PDF em formato previsível, com página de teste e seleção de impressora no navegador/ambiente local.

Jornada operacional

Portas obrigatórias

Área exclusiva da logística

Criar uma rota dedicada, por exemplo /ecommpanel/admin/fulfillment, com leitura focada na operação. A tela de pedidos continua sendo o histórico comercial; a nova fila não deve depender da edição ampla de pedido.

Painéis da fila

Permissões atuais e próximas integrações

main_admin mantém o controle total. logistics_operator recebe leitura e separação; logistics_manager também recebe despacho. Separação não implica faturamento, despacho não implica ajuste financeiro.

Entregue nesta fase

• rota exclusiva /ecommpanel/admin/fulfillment, usando a mesma fonte de verdade dos pedidos;
• checklist por item, quantidade conferida, falta/substituição com observação obrigatória e bloqueio de embalagem quando houver pendência;
• leitura por leitor USB/Bluetooth ou câmera que se comporte como teclado: SKU, EAN e GTIN incrementam uma unidade conferida do item correspondente, com validação contra o pedido aberto;
• romaneio e etiqueta HTML imprimíveis, sem valores comerciais, gerados como snapshots versionados em commerce_shipment_documents;
• QR code na etiqueta para /e-commerce/rastrear/[token], uma página pública noindex que mostra apenas referência reduzida, iniciais do destinatário, localidade, rastreio e eventos públicos; ela não mostra itens, preço, endereço completo, e-mail ou telefone;
• reimpressão auditável, com checksum e registro de última impressão;
• etiqueta liberada somente para pedido autorizado/pago e já embalado; despacho e entrega exigem a permissão específica de gestão logística;
• registro fiscal normalizado em commerce_fiscal_documents, com adapter selecionado exclusivamente por variáveis de runtime e visualização controlada no pedido e em Minha Conta;
• emissão fiscal efetiva, download de XML/DANFE, webhook de transportadora e ajuste financeiro continuam dependentes de fornecedor homologado e respectivo adapter.

Substituição, ajuste e pós-pagamento

1. O operador registra falta, avaria ou substituição com item original, item proposto, quantidade e motivo.
2. Antes da emissão fiscal, um responsável aprova a decisão e o sistema recalcula a diferença sem reescrever o pedido original.
3. Se houver diferença a favor do cliente, criar uma instrução de crédito interno ou reembolso pelo PSP; se houver complemento, criar cobrança adicional autorizada. Nunca capturar valor extra sem consentimento explícito.
4. Depois de autorizado o documento fiscal, não editar itens, valores ou impostos no registro original. O fluxo passa a depender de evento fiscal adequado, devolução, nota complementar ou cancelamento, conforme orientação contábil.
5. Toda decisão gera evento com ator, data, motivo, valores antes/depois e referência ao pagamento/documento correspondente.

Modelo de dados alvo

As tabelas abaixo pertencem ao runtime PostgreSQL e devem ser criadas por migração idempotente, nunca pelo build.

Segredos de certificados, adapters, webhook e PSP ficam apenas no ambiente de runtime. O banco deve guardar referências, hashes e metadados necessários para auditoria, nunca números completos de cartão, CVV ou segredo externo em texto.

Integrações externas

Emissor fiscal

O adapter recebe um pedido já congelado para faturamento e responde com estado normalizado: queued, authorized, rejected, cancelled ou error. O contrato precisa suportar:

• perfil do emitente: CNPJ, inscrição estadual, regime, endereço, série e ambiente de homologação/produção;
• perfil fiscal de produto: NCM, CFOP, origem, unidade, tributação e regras validadas pela contabilidade;
• destinatário: CPF/CNPJ, inscrição quando aplicável e endereço;
• totais de itens, frete, desconto, impostos e pagamento;
• XML, chave, protocolo e representação auxiliar retornados pelo emissor;
• reconsulta idempotente quando ocorrer falha de rede.

O EcommPanel oferece os campos e o status. A escolha de fornecedor, certificado, credenciamento estadual e regras tributárias deve ser homologada com contador e emissor fiscal antes de ativar produção.

Contrato de adapter já preparado

O runtime reconhece ECOM_FISCAL_ADAPTER e ECOM_FISCAL_ENVIRONMENT. As chaves iniciais aceitas são focusnfe, enotas, plugnotas e manual; uma chave diferente pode representar um adapter interno. A configuração não faz chamadas externas por si só: ela apenas registra a capacidade ativa e mantém o painel seguro enquanto o conector não estiver implementado.

Cada adapter deve ser idempotente por pedido/documento e preencher commerce_fiscal_documents com tipo, ambiente, status, número, série, chave de acesso, protocolo, data de emissão e disponibilidade de download. XML/DANFE ficam sob armazenamento protegido do adapter, nunca em resposta pública ou no payload do storefront.

Transportadora

O adapter de transportadora normaliza coleta, trânsito, ocorrência, tentativa e entrega. Cada webhook deve:

1. validar assinatura/segredo e, quando disponível, origem/IP do parceiro;
2. persistir o evento com chave idempotente antes de alterar o pedido;
3. ignorar repetição e impedir regressão de status;
4. mapear apenas eventos reconhecidos para a timeline do cliente;
5. encaminhar exceções para a fila humana, sem concluir entrega automaticamente em caso ambíguo.

Plano de implementação P0

P0.1 — Base operacional e permissões

• criar estados de fulfillment separados de status comercial, financeiro e de estoque;
• criar as permissões propostas e a rota exclusiva da operação;
• migrar dados atuais de pedido para uma projeção de fulfillment idempotente;
• liberar na fila somente financialStatus=paid ou equivalente conciliado;
• registrar auditoria para toda mudança de estado.

Saída: operador vê pedidos pagos e não consegue faturar, despachar ou ajustar valor fora da sua permissão.

P0.2 — Separação, divergência e romaneio

• exibir itens por pedido, SKU, quantidade, origem, alerta de estoque e observação;
• registrar quantidade separada, falta, avaria e substituição;
• criar romaneio imprimível sem preço;
• exigir revisão para divergência antes de liberar faturamento;
• incluir contato do cliente apenas no detalhe necessário para resolver exceção.

Saída: a equipe consegue separar um pedido sem usar planilha paralela e sem alterar o pedido original de forma silenciosa.

P0.3 — Etiqueta e despacho

• criar template de etiqueta principal e controle de versão/geração;
• aplicar a regra de até 15 linhas e romaneio separado para pedidos maiores;
• guardar hash do arquivo gerado, volume, peso, transportadora e rastreio;
• permitir reimpressão auditada sem gerar uma segunda remessa por acidente;
• bloquear despacho enquanto itens, etiqueta ou rastreio obrigatório estiverem incompletos.

Saída: cada despacho tem etiqueta rastreável, romaneio verificável e evidência de quem confirmou a saída.

P0.4 — Ajustes financeiros controlados

• criar uma solicitação de ajuste com motivo, valor, beneficiário e aprovador;
• conectar reembolso/crédito aos adapters de pagamento já normalizados;
• impedir redução de valor depois de faturamento sem fluxo fiscal correspondente;
• apresentar ao cliente uma linha clara de crédito, reembolso ou complemento no histórico do pedido.

Saída: substituições e faltas não viram alteração manual de total nem promessa sem lastro financeiro.

P0.5 — Adapter fiscal em homologação

• escolher emissor fiscal e implementar o conector sobre o contrato independente já registrado;
• cadastrar configuração do emitente e perfis fiscais, com segregação de segredos;
• gerar prévia, validar campos obrigatórios e enviar em ambiente de homologação;
• persistir retorno, XML, chave e rejeições; reprocessar por idempotência;
• só habilitar emissão produtiva após aceite contábil e testes do emissor.

Saída: um pedido conferido pode ser autorizado em homologação e o painel apresenta documento e falhas de forma auditável.

P0.6 — Adapter de transportadora e eventos

• escolher transportadora/agregador e implementar adapter por contrato;
• gerar/registrar postagem ou coletar rastreio conforme a capacidade do parceiro;
• receber webhook assinado, persistir, normalizar e atualizar timeline;
• oferecer reconsulta manual e fila de exceções;
• testar entrega, falha de entrega e evento duplicado.

Saída: o rastreio evolui sem edição manual recorrente e eventos externos não comprometem o estado do pedido.

Critérios de aceite final

• pedido pago aparece apenas uma vez na fila e pode ser assumido por operador;
• nenhum item é faturado sem conferência concluída ou revisão aprovada;
• etiqueta e romaneio não exibem preço, mas permitem identificar corretamente pedido, destinatário e itens;
• pedidos acima de 15 itens imprimem etiqueta resumida e romaneio completo separado;
• documento fiscal tem chave/protocolo/arquivo persistidos ou falha detalhada; não existe falso sucesso;
• reembolso, crédito e complemento possuem aprovação e referência financeira;
• webhook duplicado não duplica despacho, entrega, reembolso ou evento do cliente;
• permissões impedem que um operador de separação emita, cancele ou ajuste financeiramente um documento;
• cada integração pode ser desligada sem quebrar a leitura do pedido, deixando o estado como pendente de operação.

Checklist antes de ativar produção

• [ ] contador validou operação, CFOP, tributação, regime e regras por UF;
• [ ] emitente possui credenciamento/certificado e ambiente de homologação configurados no provedor escolhido;
• [ ] dados fiscais de produtos e destinatários foram revisados;
• [ ] equipe executou pedido de teste, divergência, faturamento, etiqueta, despacho, entrega e reembolso;
• [ ] impressão foi testada na impressora física usada pela operação;
• [ ] webhook foi testado com assinatura inválida, repetição e atraso;
• [ ] backup/restauração contém configurações, documentos de referência e metadados, sem segredos externos;
• [ ] runbook de incidente define quem pausa emissão, despacho ou atualização automática em caso de falha.