Guia de integração do OMS com NFC-e para o VTEX inStore

Guilherme Bruzzi

Guilherme Bruzzi

Última atualização

Como salvar os dados extras de NCM e ICMS de cada produto

A Nomenclatura Comum do Mercosul (NCM) é um atributo usado para definir a aliquota de impostos que um produto deve ser associado. Na VTEX você pode encontrar esse campo no catálogo como TaxCode . Para viabilizar a venda de produtos em loja física é necessário atrelar ICMSs do produto por estado. Esse cadastro deve ser feito como campos de especificação de cada produto (ICMS_RJ, ICMS_SP, etc..).

Para inserir dados no catálogo e campos de especificação as APIs de Catálogo como as de especificação: https://documenter.getpostman.com/view/845/catalogsystem-102/Hs44#e21ae8bb-789e-df19-e4a9-30985d9fcafb

Claro que também é possível fazer essa operação de forma manual. Para saber mais clique aqui.

Como consultar pedidos prontos para emissão da NFC-e

É necessário consultar a API de List Orders do OMS de tempos em tempos (esse período deve ser definido pelo lojista com o seu integrador: https://documenter.getpostman.com/view/94611/oms/Hs41#cb3e529d-595d-9958-2608-1cbe2bcad15c

No caso de usar um programa como o Millenium Sat Server o pedido já estará com status invoiced e na política comercial usada por esse canal de venda.

No caso de ter que faturar o pedido assim que o pedido for pago na loja, é necessário passar um endpoint para o time do inStore configurar como endereço de impressão.

Como cadastrar uma API para receber esses pedidos

O endpoint de impressão é uma rota que estará em uma máquina com IP fixo na própria loja ou endpoint https aberto na internet.

O servidor que disponibilizar esse endpoint já deve ter a capacidade de guardar uma configuração com a conta e as credenciais válidas de um vendedor criado para a finalidade de impressão de cupom fiscal pelo time do inStore.

Esse endpoint receberá um POST do cliente do inStore com um json de payload que conterá a conta e o id do pedido a ter a nota e cupom fiscais gerados (exemplo):

{ Account: instore, OrderID: 752973318278-01, }

Com isso deverá enviar para uma impressora o pedido de impressão do cupom fiscal, recibo dos cartões e guardar a NFC-e no admin da VTEX (ver próxima seção).

Para ter o nome, valor, tipo e recibo dos pagamentos de cartão, NCM e o ICMS de cada produto, deverá com o OrderID fazer o request de Get Order: https://documenter.getpostman.com/view/94611/oms/Hs41#a99bf2c3-a08e-e484-2013-92020e6e498d

Recomendamos também enviar a NFC-e para o email do cliente.

No json retornado essas informações ficam nas chaves: “items”, “paymentData.transactions.payments”, “customData.customApps.fields”, “TaxCode” e “clientProfileData” (email do cliente).

Como enviar a NFC-e pro admin da VTEX

O programa Millenium Sat Server já imprime o cupom fiscal e guarda a NFC-e no OMS permitindo qualquer ERP apenas copiar o pedido já faturado.

Essa seção destina-se aos ERPs que também desejam, após fazer a impressão do cupom fiscal (como detalhado na seção anterior), salvar o pedido no OMS.

Após ter os dados da Secretaria da Fazenda (SEFAZ) com a NFC-e basta fazer 3 requests pro OMS:

O primeiro request é o POST de invoice que salva a NFC-e: https://documenter.getpostman.com/view/94611/oms/Hs41#ae72ac09-42b8-5bb0-f85c-0e95c9a861f8

O segundo request é o de verificar o status do pedido para ver se está ready-for-invoiced ou ready-for-handling (deve-se ficar em espera ocupada até chegar em algum desses status): https://documenter.getpostman.com/view/94611/oms/Hs41#a99bf2c3-a08e-e484-2013-92020e6e498d

O terceiro e último request é o POST de mudar o status do pedido para invoiced e o seu endpoint termina com “/changestate/start-invoicing”: https://documenter.getpostman.com/view/94611/oms/Hs41#7e5af057-cf4a-9740-b41d-3e3a8bb2627d