This guide references the B2B Orders app, which is deprecated and has limited support in favor of the B2B Orders History app. It is strongly recommended to update your store theme with the B2B Suite app for compatibility and to follow the component's evolution. Note that the B2B Orders app is not compatible with the B2B Suite solution, and these instructions are not applicable for stores using the B2B Suite. For B2B Suite users, please consult the B2B Orders History documentation instead.

In a B2B business model, your company and your partners may need to share selected information, such as order statuses. This is necessary 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.

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

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:

• Search order
• Search order details
• Search order documents [OPTIONAL]

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.

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

Attribute	Type	Description
revendaId	integer	Resale ID number.
porCodigo	string	Definition of order code or ID that can be used to filter the query.
↳ codigo	string	Order code, such as the order ID, the client ID or the ERP order ID.
↳ tipo	integer	Type 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.
porPeriodo	object	Definition of dates to filter the query.
↳ dataInicial	string	Start date of the query.
↳ dataFim	string	End date of the query.
porNotaFiscal	object	Definition of invoice data to filter the query.
↳ notaFiscal	string	Invoice number.
↳ serieNotaFiscal	string	Invoice serial number.

Request body example

Response format

Attribute	Type	Description
itens	array of objects	Array of objects containing orders data.
↳	object	Object containing order data.
↳ pedidoErpId	string	ERP order number, which is the identification number of the order placed through the store ERP.
↳ pedidoClienteId	string	Identification number associated with the customer who made the purchase.
↳ totalPedido	number	Total value of the order.
↳ status	integer	Order status.
↳ dataPedido	string	Date of the order.
↳ observacao	string	Additional order information.
↳ notaFiscal	string	Invoice number.
↳ serieNotaFiscal	string	Invoice serial number.

Response body example

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

Attribute	Type	Description
pedidoErpId	string	ERP order number, which is the identification number of the order placed through the store ERP.
revendaId	integer	Resale ID number.

Request body example

Response format

Attribute	Type	Description
pedidoErpId	string	ERP order number, which is the identification number of the order placed through the store ERP.
status	integer	Order status.
itens	array of objects	Array of objects containing information about each item in the order.
↳	object	Object containing information about an item.
↳ partNumber	string
↳ descricaoDoProduto	string	Product description.
↳ quantidade	number	Item quantity.
↳ valorUnitario	number	Price per item.
↳ valorTotal	number	Total value.
↳ comissao	number	Comission.
revendaId	integer	Resale ID number.
clienteFinalId	string	Customer's ID.
clienteFinalCnpj	string	Customer's CNPJ number.
clienteFinalCpf	string	Customer's CPF number.
valorFrete	number	Freight value.
valorTotalPedido	number	Total order value.
dataPedido	string	Date of the order.
dataPrevisaoEntrega	string	Delivery date.
observacao	string	Additional information.
notaFiscal	string	Invoice number.
serieNotaFiscal	string	Invoice serial number.
linkTransportadora	string	Carrier link.
formattedAddres	string	Address.
zipcode	string	ZIP code.
methodPayment	string	Payment method used in the order.
corpname	string	Corporate name.
corpemail	string	Corporate email.
cityState	string	City and state.
methodPaymentInfo	string	Information about the payment method used in the order.
centrosDeDistribuicao	array of objects	Array containing objects that represent each Distribution Center.
↳	object	Object containing information per Distribution Center.
↳ distributionCenterPrefix	string	Prefix of the Distribution Center.
↳ itens	array of objects	Array containing objects with order items information.
↳	object	Object with order items information.
↳ partNumber	string
↳ descricaoDoProduto	string	Product description.
↳ quantidade	number	Item quantity.
↳ valorUnitario	number	Price per item.
↳ valorTotal	number	Total value.
↳ comissao	number	Comission.
↳ valorFrete	number	Freight value.
↳ valorTotalCD	number	Total delivery value including Distribution Center costs.

Response body example

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

Attribute	Type	Description
pedidoErpId	string	ERP order number, which is the identification number of the order placed through the store ERP.
revendaId	integer	Resale ID number.

Request body example

Response format

Attribute	Type	Description
pedidoErpId	string	ERP order number, which is the identification number of the order placed through the store ERP.
itens	array of objects	Array of objects containing information about each document in the order.
↳	object	Object containing information about a document.
↳ tipoArquivo	integer	Type of document. SegundaViaBoleto: 0, SegundaViaTransferencia: 1, Xml: 2, Danfe: 3, NumeroDeSerie: 4, GARE: 5, GNRE: 6, Outros: 7.
↳ descricao	string	Document description.
↳ url	string	Document URL.

Response body example

Follow the steps below to install the B2B Orders app.

1. Using the terminal and the VTEX IO CLI, 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.

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:

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