Documentation
Feedback
Guides
API Reference

Guides
Integration Guides
External Marketplace
Sending invoice and tracking code to the marketplace

When integrating orders fulfilled by VTEX sellers, it is important to include tracking codes and invoice data. There are some requirements needed, before connectors can make sure that invoice and tracking code were sent to the marketplace:

  • The tracking code and invoice information must be contained within the VTEX Order.
  • Connectors should offer a secure endpoint to receive VTEX notification from our Retrieve feed order status endpoint updating tracking code and invoice data
  • Tracking code and other data about the order’s delivery will only be made available to orders where the seller is in charge of delivery.

Invoice notification from VTEX

The invoice sent by VTEX consists of a notification for the connector's URL, with the following structure:

http://{{marketplaceServicesEndpoint}}/pub/orders/{{orderId}}/invoice.

If the connector does not take that into account in their integration, they might receive an error 400 in VTEX's Send Invoice requests.

Integrating tracking code and invoice data

The diagram below describes the notification flow, for integrating tracking code and invoice data:

Follow the steps below to integrate them, once receiving the notification. Make sure to review our Recommendations page before you start.

{"base64":"  ","img":{"width":5262,"height":1134,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":163337,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-marketplace-integration-invoice-tracking-0.jpg"}}

  1. VTEX Orders receive tracking and/or invoice data. This information can be inserted via Invoice notification from VTEX or manually in VTEX Admin. After receiving invoice information, the order status is updated to invoiced in VTEX. In this case, it is not possible to cancel the order anymore.
  2. VTEX OMS notifies the connector through the URL informed in the Place Fulfillment Order API by the connector through the property marketplaceServicesEndpoint, once the order is inserted in VTEX.
  3. Connector collects information sent through the notification. a. To collect information about invoice, use the properties:
    • invoiceNumber: invoice’s ID code.
    • invoiceUrl: URL that leads to the invoice document.
    • embeddedInvoice: invoice document’s XML file.
    • invoiceValue: value declared in the invoice.
    • invoiceKey: invoice’s key. b. To collect information about tracking code, use the properties:
    • courier: carrier’s name.
    • trackingNumber: number used by the carrier to identify the delivery
    • trackingUrl: carrier’s URL used by clients to track the order’s delivery.
  4. Connector transforms the information to the expected format in the marketplace.
  5. Connector sends the information to the marketplace.
  6. Marketplace validates and records information, and responds with a success or failure status.
  7. Connector generates an Order log for each situation.

Note that:

  • An order can have more than one invoice with partial values
  • The tracking code and/or invoice can be filled in at different moments. In this case it is important to understand the flow demanded by the marketplace for sending separate information.
  • Not all fields listed are demanded by the marketplace. Keep in mind to check which ones are in fact mandatory and the correct moment to send them.

Make sure that all steps are logged as either success or failure, to offer the operation's full traceability. Check out the Order logs page to learn more

API Reference

Use the endpoints described below to perform this step. It is important to note that when consuming this API, the connector must have a valid VTEX App Key and App Token.

{"base64":"  ","img":{"width":5262,"height":3389,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":460342,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-marketplace-integration-invoice-tracking-1.jpg"}}

All parameters in the endpoints below must be declared in the request. In case one of the parameters does not have a value, you must still send it as null.

Shopping cart simulation

Use the request example below to perform the Shopping Cart Simulation. Check out our Shopping cart Simulation API Reference to know more details.


_35
{
_35
"items":[
_35
{...}
_35
]
_35
"ratesAndBenefitsData":{
_35
"rateAndBenefitsIdentifiers":[]
_35
"teaser":[]
_35
}
_35
"paymentData":{
_35
"installmentOptions":[...]
_35
"paymentSystems":[...]
_35
"payments":[]
_35
"giftCards":[]
_35
"giftCardMessages":[]
_35
"availableAccounts":[]
_35
"availableTokens":[]
_35
}
_35
"selectableGifts":[]
_35
"marketingData":NULL
_35
"postalCode":NULL
_35
"country":"BRA"
_35
"logisticsInfo":[
_35
{...}
_35
]
_35
"messages":[]
_35
"purchaseConditions":{
_35
"itemPurchaseConditions":[...]
_35
}
_35
"pickupPoints":[]
_35
"subscriptionData":NULL
_35
"totals":[
_35
{...}
_35
]
_35
"itemMetadata":NULL
_35
}

Place fulfillment order

Use the request example below to place fulfillment order. Check out our Place fulfillment order API Reference to know more details.


_93
[
_93
{
_93
"items": [
_93
{
_93
"id": "1",
_93
"price": 900,
_93
"quantity": 1,
_93
"seller": "1"
_93
}
_93
],
_93
"isCreatedAsync": true,
_93
"marketplaceOrderGroup" : "794901324",
_93
"marketplaceOrderId": "2630580124",
_93
"marketplacePaymentValue": 1100,
_93
"marketplacePaymentReferenceValue": 1100,
_93
"marketplaceServicesEndpoint": "http://skyhubintegration.vtexinternal.com/api/skyhubintegration/commercialcondition?an=grocery1",
_93
"clientProfileData": {
_93
"CorporateDocument": null, //Cnpj
_93
"CorporateName": null, //nome da empresa
_93
"CorporatePhone": null, // ddd+telefone
_93
"Document": "14310315771", //cpf
_93
"DocumentType": null, //se pessoa fisica, colocar CPF, senão CNPJ
_93
"Email": "conta@dominio.com.br",
_93
"FirstName": "Nome",
_93
"IsCorporate": false, //caso pessoa juridica o valor deve ser true
_93
"LastName": "Sobrenome",
_93
"Phone": "41998718616",
_93
"StateInscription": null, //inscrição estadual
_93
"TradeName": null,
_93
"UserProfileId": null //utilizado somente com pedidos VTEX
_93
},
_93
"shippingData": {
_93
"address": {
_93
"addressId": "Casa",
_93
"addressType": "Residencial",
_93
"receiverName": "Marcelo",
_93
"city": "Curitiba",
_93
"complement": null,
_93
"country": "BRA",
_93
"geoCoordinates": [],
_93
"neighborhood": "Novo Mundo",
_93
"number": "4000",
_93
"postalCode": "81020230",
_93
"reference": null,
_93
"state": "PR",
_93
"street": "Rua Eduardo Carlos Pereira"
_93
},
_93
"logisticsInfo": [
_93
{
_93
"itemIndex": 0,
_93
"price": 200,
_93
"selectedDeliveryChannel":"delivery",
_93
"selectedSla": null,
_93
"lockTTL": "1d", //tempo para reserva do estoque do pedido
_93
"shippingEstimate":"1d" //tempo de entrega do pedido
_93
}
_93
],
_93
"selectedAddresses":[
_93
{
_93
"addressType": "Residencial",
_93
"receiverName": "Henrique Vianna",
_93
"addressId": "2",
_93
"postalCode": "81020-235",
_93
"city": "Curitiba",
_93
"state": "PR",
_93
"country": "BRA",
_93
"street": "Rua Eduardo Carlos Pereira",
_93
"number": "4125",
_93
"neighborhood": "Portão",
_93
"complement": "",
_93
"reference": null,
_93
"geoCoordinates": [
_93
-49.2892059,
_93
-25.4826319
_93
]
_93
}],
_93
"isFob": false //se entrega feita pelo lojista coloque false, senão true
_93
},
_93
"customData": {
_93
"customApps": [{
_93
"fields": {
_93
"orderIdMarketplace": "2630580148",
_93
"paymentIdMarketplace": "8191598627"
_93
},
_93
"id": "marketplace-integration",
_93
"major": 1
_93
}]
_93
},
_93
"openTextField": {
_93
"value": "{\"Phones\":[\"21998718616\"]}"
_93
}
_93
}
_93
]

Authorize dispatch

Use the request example below to authorize dispatch. Check out our Authorize Dispatch API Reference to know more details.


_10
[
_10
{
_10
"marketplaceOrderId": "956"
_10
}
_10
]

Contributors
4
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
4
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
On this page