Querying B2B order statuses

In a B2B business model, your company and your partners may need to share selected information, such as order statuses. This is necessary when you want to show the status of external orders — orders made outside VTEX — to customers on your ecommerce, for example.

For these scenarios, we recommend that you install and set up the B2B Orders app in your VTEX account. By communicating with your Enterprise Resource Planning (ERP), this app allows your business’ customers to securely check their order status at any time they want.

⚠️

The B2B Orders app is not compatible with the B2B Suite solution. Therefore, these instructions do not apply to stores using the B2B Suite. If you are using the B2B Suite, refer to the B2B Orders History documentation instead.

Check the following sections for information on the ERP API requirements and on how to install the B2B Orders app in your store.

ERP API requirements

The B2B Orders app comes with a specific pattern for communicating with the ERP API. For the query to work properly, your ERP API must have different endpoints for each of the following scenarios:

If you have specific business needs which are not satisfied by the scenarios presented, you can customize the B2B Orders app.

The possible requests and response formats for each of the ERP API's required endpoints are presented below.

Search order

By exposing the POST api/v1/pedido/pesquisa endpoint, it will be possible to search for external orders by filling one of the following objects: porPeriodo, porCodigo or porNotaFiscal.

Request format

AttributeTypeDescription
revendaIdintegerResale ID number.
porCodigostringDefinition of order code or ID that can be used to filter the query.
codigostringOrder code, such as the order ID, the client ID or the ERP order ID.
tipointegerType of code that will be used in the query.

If you want to filter the query using PedidoId (web order number, which is the identification number of the order placed through the store’s website), the value should be 0.

To filter the query using PedidoClienteId (identification number associated with the customer who made the purchase), the value should be 1.

To filter the query using PedidoErpId (ERP order number), set the value to 2.
porPeriodoobjectDefinition of dates to filter the query.
dataInicialstringStart date of the query.
dataFimstringEnd date of the query.
porNotaFiscalobjectDefinition of invoice data to filter the query.
notaFiscalstringInvoice number.
serieNotaFiscalstringInvoice serial number.

Request body example

{
  "revendaId": 55,
  "porCodigo": {
    "codigo": "1234",
    "tipo": 1
  },
  "porPeriodo": {
    "dataInicial": "2022-07-11T23:28:30Z",
    "dataFim": "2022-10-11T23:28:30Z"
  },
  "porNotaFiscal": {
    "notaFiscal": "987654321",
    "serieNotaFiscal": "123"
  }
}

Response format

AttributeTypeDescription
itensarray of objectsArray of objects containing orders data.
objectObject containing order data.
pedidoErpIdstringERP order number, which is the identification number of the order placed through the store ERP.
pedidoClienteIdstringIdentification number associated with the customer who made the purchase.
totalPedidonumberTotal value of the order.
statusintegerOrder status.
dataPedidostringDate of the order.
observacaostringAdditional order information.
notaFiscalstringInvoice number.
serieNotaFiscalstringInvoice serial number.

Response body example

{
  "itens": [
    {
      "pedidoErpId": "12345",
      "pedidoClienteId": "10987",
      "totalPedido": 456,
      "status": 1,
      "dataPedido": "2022-10-11T23:28:30Z",
      "observacao": "",
      "notaFiscal": "987654321",
      "serieNotaFiscal": "123"
    }
  ]
}

Search order details

By exposing the GET api/v1/pedido?pedidoErpId={pedidoErpId}&revendaId={revendaId} endpoint, it will be possible to fetch the details of a specific order directly from the ERP.

Request format

AttributeTypeDescription
pedidoErpIdstringERP order number, which is the identification number of the order placed through the store ERP.
revendaIdintegerResale ID number.

Request body example

{
  "pedidoErpId": "12345",
  "revendaId": 2
}

Response format

AttributeTypeDescription
pedidoErpIdstringERP order number, which is the identification number of the order placed through the store ERP.
statusintegerOrder status.
itensarray of objectsArray of objects containing information about each item in the order.
objectObject containing information about an item.
partNumberstring
descricaoDoProdutostringProduct description.
quantidadenumberItem quantity.
valorUnitarionumberPrice per item.
valorTotalnumberTotal value.
comissaonumberComission.
revendaIdintegerResale ID number.
clienteFinalIdstringCustomer's ID.
clienteFinalCnpjstringCustomer's CNPJ number.
clienteFinalCpfstringCustomer's CPF number.
valorFretenumberFreight value.
valorTotalPedidonumberTotal order value.
dataPedidostringDate of the order.
dataPrevisaoEntregastringDelivery date.
observacaostringAdditional information.
notaFiscalstringInvoice number.
serieNotaFiscalstringInvoice serial number.
linkTransportadorastringCarrier link.
formattedAddresstringAddress.
zipcodestringZIP code.
methodPaymentstringPayment method used in the order.
corpnamestringCorporate name.
corpemailstringCorporate email.
cityStatestringCity and state.
methodPaymentInfostringInformation about the payment method used in the order.
centrosDeDistribuicaoarray of objectsArray containing objects that represent each Distribution Center.
objectObject containing information per Distribution Center.
distributionCenterPrefixstringPrefix of the Distribution Center.
itensarray of objectsArray containing objects with order items information.
objectObject with order items information.
partNumberstring
descricaoDoProdutostringProduct description.
quantidadenumberItem quantity.
valorUnitarionumberPrice per item.
valorTotalnumberTotal value.
comissaonumberComission.
valorFretenumberFreight value.
valorTotalCDnumberTotal delivery value including Distribution Center costs.

Response body example

{
  "pedidoErpId": "12345",
  "status": 0,
  "itens": [
    {
      "partNumber": "123",
      "descricaoDoProduto": "Beautifully handmade laptop case/sleeve made in the Nepal Himalaya. It can be slipped inside your backpack or carried alone with space for all your work bits and pieces!",
      "quantidade": 2.0,
      "valorUnitario": 22.0,
      "valorTotal": 44.0,
      "comissao": 4.0
    }
  ],
  "revendaId": 2,
  "clienteFinalId": "109",
  "clienteFinalCnpj": "55616766000197",
  "clienteFinalCpf": "48654007028",
  "valorFrete": 10.0,
  "valorTotalPedido": 58.0,
  "dataPedido": "2022-10-11T23:28:30Z",
  "dataPrevisaoEntrega": "2022-10-11T23:28:30Z",
  "observacao": "",
  "notaFiscal": "987654321",
  "serieNotaFiscal": "123",
  "linkTransportadora": "https://www.google.com/",
  "formattedAddres": "Quadra SHIN QI 4 Conjunto 3",
  "zipcode": "71510230",
  "methodPayment": "Credit Card",
  "corpname": "Knowledge Inc.",
  "corpemail": "[email protected]",
  "cityState": "BrasiliaDF",
  "methodPaymentInfo": "Credit Card",
  "centrosDeDistribuicao": [
    {
      "distributionCenterPrefix": "CD1",
      "itens": [
        {
          "partNumber": "123",
          "descricaoDoProduto": "Beautifully handmade laptop case/sleeve made in the Nepal Himalaya. It can be slipped inside your backpack or carried alone with space for all your work bits and pieces!",
          "quantidade": 2.0,
          "valorUnitario": 22.0,
          "valorTotal": 44.0,
          "comissao": 4.0
        }
      ],
      "valorFrete": 10.0,
      "valorTotalCD": 10.0
    }
  ]
}

[OPTIONAL] Search order documents

By exposing the GET api/v1/arquivospedido?pedidoErpId={pedidoErpId}&revendaId={revendaId} endpoint, it will be possible to query the document files related to a given order by providing the related order number.

Request format

AttributeTypeDescription
pedidoErpIdstringERP order number, which is the identification number of the order placed through the store ERP.
revendaIdintegerResale ID number.

Request body example

{
  "pedidoErpId": "12345",
  "revendaId": 2
}

Response format

AttributeTypeDescription
pedidoErpIdstringERP order number, which is the identification number of the order placed through the store ERP.
itensarray of objectsArray of objects containing information about each document in the order.
objectObject containing information about a document.
tipoArquivointegerType of document. SegundaViaBoleto: 0, SegundaViaTransferencia: 1, Xml: 2, Danfe: 3, NumeroDeSerie: 4, GARE: 5, GNRE: 6, Outros: 7.
descricaostringDocument description.
urlstringDocument URL.

Response body example

{
  "pedidoErpId": "12345",
  "itens": [
    {
      "tipoArquivo": 0,
      "descricao": "Boleto",
      "url": "https://www.google.com/"
    }
  ]
}

Installing the B2B Orders app

Follow the steps below to install the B2B Orders app.

  1. Using the terminal and the Toolbelt, install the B2B Orders app in the desired workspace by running vtex install vtex.omnichannel-order-status.
  2. In your browser, access your account's admin as in https://{workspace}--{account}.myvtex.com/admin. ️Remember to replace {workspace} and {account} with the workspace and account you are using.
  3. Under Account Settings, go to Apps > My apps.
  4. Look for the B2B Order app.
  5. Click on Settings on the B2B Order app card.
  6. Fill the following fields with the required information to communicate with the external service:
    • Link endpoint: the endpoint address of the desired service.
    • Login: access credentials of the external service.
    • Token: authentication token to access the service.
  7. Click on Save.

b2b-ordersb2b-orders

Once your changes are duly saved, a new tab, named Orders B2B, will be available in your client's menu on the My Account page, as shown in the following image:

client-viewclient-view

Read our article Understanding B2B Orders for more information on the B2B Orders app.


Did this page help you?