Consulting B2B order statuses
In a B2B business model, your company and your partners may need to share selected information, such as order statuses.
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.
For more information on how to set up the B2B Orders app and its related external APIs to the ERP, check the following section.
Step by step
-
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
. -
In your browser, access your account's admin as in
https://{workspace}--{account}.myvtex.com/admin
.
️ Remember to replace the values between the curly brackets according to your scenario.
- Under
Account Settings
, go toApps > My apps
. Look for the B2B Orders app and install it. - Click on
Settings
to set up the necessary information for communicating with the desired service. That is:
- Link endpoint - the endpoint address of the desired service.
- Login - credentials for accessing the service.
- Token - authentication token for accessing the service.
️ So that the B2B Orders app can properly work, your ERP API must have different endpoints for each of the following scenarios: search orders, search order details, and search order documents. To learn more about it, check the ERP API requirements section.
- Save your changes.
Once your changes are duly saved, a new option, namely Orders B2B, will be available in your client's menu, as in the following image:
ERP API requirements
To facilitate its implementation, the B2B Orders app comes with a well-defined pattern for communicating with the ERP API.
This pattern implies that your company's ERP API has different endpoints for each of the following scenarios:
️ For specific needs, not satisfied by the scenarios presented, you might need to customize the B2B Orders app.
In the following, we present the possible requests and response format for each one of the ERP API's related endpoints.
Search order
By exposing the POST
api/v1/pedido/pesquisa
endpoint, your company's client will be able to search for orders in the ERP by filling one of the following objects: porPeriodo
, porCodigo
or porNotaFiscal
.
Request format
{
"revendaId": number,
"porCodigo": {
"codigo": string,
"tipo": number (PedidoId: 0, PedidoClienteId: 1, PedidoErpId: 2)
},
"porPeriodo": {
"dataInicial": Date,
"dataFim": Date
},
"porNotaFiscal": {
"notaFiscal": string,
"serieNotaFiscal": string
}
}
Response format
{
"itens": [
{
"pedidoErpId": string,
"pedidoClienteId": string,
"totalPedido": number,
"status": number,
"dataPedido": Date,
"observacao": string,
"notaFiscal": string,
"serieNotaFiscal": string,
}
]
}
Search order details
By exposing the GET
api/v1/pedido?pedidoErpId={pedidoErpId}&revendaId={revendaId}
endpoint, your company's client will be able to consult the details of a specific order directly from the ERP.
Request format
{
pedidoErpId: string
revendaId: number
}
Response format
{
"pedidoErpId": string,
"status": 0,
"itens": [
{
"partNumber": string,
"descricaoDoProduto": string,
"quantidade": decimal number,
"valorUnitario": decimal number,
"valorTotal": decimal number,
"comissao": decimal number
}
],
"revendaId": 2,
"clienteFinalId": string,
"clienteFinalCnpj": string,
"clienteFinalCpf": string,
"valorFrete": decimal number,
"valorTotalPedido": decimal number,
"dataPedido": Date,
"dataPrevisaoEntrega": Date,
"observacao": string,
"notaFiscal": string",
"serieNotaFiscal": string,
"linkTransportadora": string,
"formattedAddres": string,
"zipcode": string,
"methodPayment": string,
"corpname": string,
"corpemail": string,
"cityState": string,
"methodPaymentInfo": string,
"centrosDeDistribuicao": [
{
"distributionCenterPrefix": string,
"itens": [
{
"partNumber": string,
"descricaoDoProduto": string,
"quantidade": decimal number,
"valorUnitario": decimal number,
"valorTotal": decimal number,
"comissao": decimal number
}
],
"valorFrete": decimal number,
"valorTotalCD": decimal number
},
{
"distributionCenterPrefix": string,
"itens": [
{
"partNumber": string,
"descricaoDoProduto": string,
"quantidade": decimal number,
"valorUnitario": decimal number,
"valorTotal": decimal number,
"comissao": decimal number
}
],
"valorFrete": decimal number,
"valorTotalCD": decimal number
}
]
}
[OPTIONAL] Search order documents
By exposing the GET
api/v1/arquivospedido?pedidoErpId={pedidoErpId}&revendaId={revendaId}
endpoint, your company's client will be able to consult the document files related to a given order by providing the related order number.
Request format
{
pedidoErpId: string
revendaId: number
}
Response format
{
"pedidoErpId": string,
"itens": [
{
"tipoArquivo": number (SegundaViaBoleto: 0, SegundaViaTransferencia: 1, Xml: 2, Danfe: 3, NumeroDeSerie: 4, GARE: 5, GNRE: 6, Outros: 7),
"descricao": string,
"url": string"
},
{
"tipoArquivo": number,
"descricao": string,
"url": string"
}
]
}
Updated 1 day ago