Dúvidas Frequentes: Como faturar um pedido e enviar as atualizações de rastreio? | Como fazer integração de faturamento e rastreio com marketplaces?

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:

  1. 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.
  2. 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:

  1. 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.
  2. 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).
  3. 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 :red_circle: ERP e :articulated_lorry:Transportadora. Considerando o fluxo ideal:

  1. Inserir nota fiscal → :red_circle: ERP
  2. Enviar informações de rastreio → :articulated_lorry: Transportadora
  3. Enviar atualizações de rastreio → :articulated_lorry: Transportadora

Em ordem:

1. :page_facing_up: Order Invoice Notification [POST]

Nos nossos logs, o nome desse workflow é NotifyInvoice.

Esse é o método que deve ser utilizado pelo :red_circle: 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 NotifyInvoice para 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. :envelope_with_arrow: 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 :articulated_lorry: 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 UpdatePartialInvoice para 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) :truck: Update order tracking status [PUT]

Nos nossos logs, o nome desse workflow é UpdateTrackingStatus.

Esse é o método que deve ser utilizado pela :articulated_lorry: 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! :smiling_face:

Karina Mota
Field Software Engineer | VTEX

6 Likes

Importante informar que para a maioria dos marketplaces o campo embededInvoice com o XML é obrigatório para que a integração ocorra corretamente.

3 Likes