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.
- 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.
- 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. - 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 deliverytrackingUrl
: carrier’s URL used by clients to track the order’s delivery.
- Connector transforms the information to the expected format in the marketplace.
- Connector sends the information to the marketplace.
- Marketplace validates and records information, and responds with a success or failure status.
- 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.
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]