Este tópico visa fomentar o conhecimento na nossa comunidade, principalmente no que tange ao módulo de pedidos e mais especificamente sobre como funciona o Faturamento e Rastreio dos pedidos aqui na plataforma VTEX via API e sua integração com marketplaces.
Existem duas formas distintas de realizar esse processo:
Sendo a primeira forma, divida em apenas 2 passos:
- As informações de faturamento e rastreio são enviadas para a nossa plataforma por meio da API Order invoice notification, quando o faturamento é feito referenciando os itens do pedido essas informações também devem ser enviadas nesse momento.
- As atualizações de rastreio são enviadas continuamente para a nossa plataforma por meio da API Update order tracking status até que o pacote seja entregue no destinatário e isso, seja informado através do campo “
isDelivered=true”.
A segunda forma possui 3 passos, e se aplica para os casos onde o ERP envia primeiramente apenas as informações referentes a nota fiscal do pedido, precisando então atualizar essas informações com a inclusão das informações de rastreio em um passo posterior, nesse caso é necessário seguir o seguinte passo a passo:
- Inserir nota fiscal com as informações de faturamento (sem informações de rastreio) por meio da API Order invoice notification, quando o faturamento é feito referenciando os itens do pedido essas informações também devem ser enviadas nesse momento.
- Enviar código e outras informações de rastreio na nota fiscal já inserida no passo anterior, através da API Update order’s partial invoice (send tracking number).
- Enviar as atualizações de rastreio continuamente para a nossa plataforma por meio da API Update order tracking status até que o pacote seja entregue no destinatário e isso, seja informado através do campo “
isDelivered=true”.
Os autores que devem realizar estas requisições são 
ERP e 
Transportadora. Considerando o fluxo ideal:
- Inserir nota fiscal → ERP
- Enviar informações de rastreio → Transportadora
- Enviar atualizações de rastreio → Transportadora
Em ordem:
1. 
Order Invoice Notification [POST]
Nos nossos logs, o nome desse workflow é NotifyInvoice.
Esse é o método que deve ser utilizado pelo ERP para inserir as informações de faturamento do pedido onde:
-
“
invoiceNumber” é o número da Nota Fiscal do pedido; -
“
invoiceValue” é o valor da Nota Fiscal do pedido, aqui cabe ressaltar que para que pedido passe para o status de “Faturado” ela deve conter o valor total do pedido; -
“
invoiceKey”, ou seja, é chave de acesso; -
“
invoiceUrl” é a URL da Nota Fiscal; -
“
embededInvoice” é campo onde deve ser inserido o XML da Nota Fiscal do pedido e é obrigatório para que o Status do pedido seja atualizado nos Maketplaces de integração certificada.
Como regra geral, deve ser enviada uma requisição por nota fiscal por pedido.
O que acontece se eu enviar mais de um
NotifyInvoicepara a mesma Nota Fiscal?
Como se trata de um método POST , a nota fiscal anterior será sobrescrita, e pode-se perder informações. Prevalece a última alteração enviada.
2. 
Update order’s partial invoice (send tracking number) [PATCH]
Nos nossos logs, o nome desse workflow é UpdatePartialInvoice.
Esse é o método que deve ser utilizado pela transportadora para inserir as informações de rastreio e entrega (como o próprio título indica) como:
-
“
trackingNumber” é o código de rastreio; -
“
trackingUrl” deve ser preenchido com a URL de rastreio; -
“
dispatchedDate” é a data de expedição; -
“
courier” é o campo dedicado ao nome da transportadora.
Assim como o anterior, é necessário que esses dados sejam enviados apenas uma vez por nota fiscal por pedido.
A menos que seja necessário trocar as informações de rastreio enviadas (não há necessidade de utilizar esse método múltiplas vezes por nota fiscal e por pedido).
Como se trata de um método PATCH , serão preenchidos apenas os parâmetros de rastreio do faturamento, que ficaram em branco na requisição do passo anterior.
O que acontece se eu enviar mais de um
UpdatePartialInvoicepara a mesma Nota Fiscal?
Como essa é uma API que utiliza o método PATCH apenas os parâmetros enviados na segunda vez serão sobrescritos. Os outros campos, enviados no passo anterior permanecem inalterados.
3) 
Update order tracking status [PUT]
Nos nossos logs, o nome desse workflow é UpdateTrackingStatus.
Esse é o método que deve ser utilizado pela transportadora para inserir as atualizações de rastreio, aqui cabe ressaltar que ele pode ser utilizado diversas vezes, até que o pedido tenha sido, de fato, entregue ao seu destinatário final, onde:
-
“
isDelivered” é o que campo que informa se o pedido foi ou não entregue; -
“
deliveredDate” é a data de entrega; -
“
events” é o array que contém local, data e descrição das atualizações.
Diferente dos passos anteriores, é esperado que sejam enviados múltiplas requisições para essa API. Como se trata de um método PUT , cada nova atualização será inserida dentro das informações do pedido, dentro do campo courierStatus. São registradas todas as atualizações enviadas, não só a última, diferente dos passos anteriores.
Observações importantes:
O recurso NotifyInvoice é necessário para usar esta solicitação de API. Ele está incluído nos seguintes perfis de acesso OMS - Full access e IntegrationProfile - Fulfillment Oms, entre outras funções padrão disponíveis no Admin. Caso deseje saiba mais sobre os Perfis de acesso.
Além disso, caso ainda tenha alguma dúvida sobre o assunto, sinta-se à vontade para perguntar por aqui! 
Karina Mota
Field Software Engineer | VTEX