The orders API of Yourviews allows the store owners platform to send us the orders created in your e-commerce or physical store. It's highly recommended to send just delivered orders or orders in the last possible status (like "sent")
Upon receiving a "delivered" order, we start the days countdown to send the review e-mail;
It's possible to send all orders, even the pending ones and mark them as delivered or canceled afterwards, according to the given methods.
Remember to read about Intro & Auth API: https://yourviews.freshdesk.com/support/solutions/articles/5000734890-api-basic-auth-primeiros-passos-e-autenticac%C3%A3o
Insert Order
Endpoint: POST /order/
To insert and order you have to inform some of the fields bellow (marked as Required). Usually it's at least Order date, value and status, data about the user and purchased products. The following table compiles all fields (optional or required) that can be sent.
| Order | Main order node | ||
| Field | Description | Required? | Type |
| OrderId | Order number at the store. It's the primary key at order calls. | Yes | string |
| OrderDate | Order when the user purchased. Format: yyyy-MM-ddTHH:mm:ss | Yes | DateTime |
| Status | Order Status at the store. Free text. | Yes | string |
| IsDelivered | Has the order been delivered yet? It's recommended to send only delivered orders or at least the closest to it ("sent" for instance) | Yes | boolean |
| DeliveryDate | Date when the order has been delivered to the customer. Format: yyyy-MM-ddTHH:mm:ss | Yes, if IsDelivered=true | DateTime |
| InvoiceDate | Date the order has been invoiced. Format: yyyy-MM-ddTHH:mm:ss | Yes, if IsDelivered=true | DateTime |
| Total | Order total value. Format: xxx.xx. Eg: 143.50 | Yes | decimal |
| TrackingCode | Carrier's tracking code | No | string |
| User | Customer node | Required node | |
| Name | Customer full name | Yes | string |
| Email | Customer e-mail | Yes | string |
| City | Customer City | No | string |
| State | Customer State | No | string |
| ZipCode | Customer Zip Code | No | string |
| UserId | Customer Id at the platform | No | string |
| Attendant | [Physical Stores Only] Seller's who sold the product | Not required node | |
| IdAttendantStore | Seller Id at the platform internal system | Yes | string |
| Name | Seller name | Yes | string |
| StoreLocation | [Physical Stores Only] Information regarding the physical store | required only if Attendant != null. | |
| IdInternalStoreLocation | Point of sale Id | Yes | string |
| Name | Point of sale name | Yes | string |
| Manager | Point of sale manager | No | string |
| City | Point of sale city | No | string |
| Province | Point of sale state or province | No | string[2] |
| Number | Point of sale address number | No | string |
| Cep | Point of sale Zip code | No | string[10] |
| Products | Node with all the sold products | Nó obrigatório | |
| ProductId | Product's Id as shown in the frontend (product page) | Yes | string |
| Name | Product page as shown to consumer | Yes | string |
| IsActive | Is the product currently active at the store? | Yes | boolean |
| Image | Product picture with size usually around ~400px | Yes, if IsActive=true | string |
| Url | Product URL | Yes, if IsActive=true | string |
| Value | Product Sale price | Yes, if IsActive=true | decimal |
| Category | Node with categories of the product | Não | Category |
| CategoryId | Internal category Id | Yes | string |
| Name | Category name | Yes | string |
| Parent | Parent-category if available | Não | Category |
| Brand | Product Brand | Não | Brand |
| BrandId | Internal brand Id | Yes | string |
| Name | Brand name | Yes | string |
| Sku | Sku of the sold product | Não | Sku |
| SkudId | Sku ID as shown in the product page | Yes | string |
| Name | SKU unique name | Yes | string |
| Url | SKU URL (could be the same as the product Url) | Yes | string |
| Image | Sku Photo (could be the same as the product image) | Yes | string |
| Value | Sku sales price | Yes | decimal |
| GTIN | Sku Unique GTIN. More info regarding this code: https://support.google.com/merchants/answer/160161?hl=pt-BR | Yes if MPN not sent | string |
| MPN | Sku Unique MPN. More info regarding this code:https://support.google.com/merchants/answer/160161?hl=pt-BR | Yes if GTIN not sent | string |
Call example
The following JSON gives an ideia of how the data should be sent
Para exemplificar a tabela acima, o JSON abaixo dá uma ideia de como os dados devem ser enviados.
{
"OrderId": "order123",
"OrderDate": "2017-01-01T05:23:18",
"Status": "invoiced",
"IsDelivered": true,
"DeliveryDate": "2017-01-04T21:25:02",
"InvoiceDate": "2017-01-04T21:30:20",
"Total": 124.09,
"StoreLocation": {
"IdInternalStoreLocation": "1",
"Name": "Loja Raposo",
"Manager": "Ricardo",
"Street": "Rodovia Raposo Tavares",
"City": "São Paulo",
"Province": "SP",
"Number": "3175",
"Cep": "05577100"
},
"Attendant": {
"IdAttendantStore": "1",
"Name": "Vendedor 1"
},
"Products": [
{
"ProductId": "4452",
"Name": "Camiseta Skull",
"Url": "https://www.meusite.com.br/camiseta-skull",
"Image": "https://www.meusite.com.br/camiseta-skull.jpg",
"IsActive": true,
"Value": 120.10,
"Category": {
"CategoryId": "112",
"Name": "Camisetas",
"Parent": {
"CategoryId": "10",
"Name": "Moda Masculina",
Parent: null
}
},
"Brand": {
"BrandId": "123",
"Name": "Hering"
},
"Sku": {
"SkudId": "4452a",
"Name": "Camiseta Skull Branca",
"Url": "https://www.meusite.com.br/camiseta-skull/s/branca",
"Image": "https://www.meusite.com.br/camiseta-skull-branca.jpg",
"Value": 120.10,
"GTIN": null,
"MPN": "30224"
}
}
],
"User": {
"Name": "José Antonio",
"Email": "joseantonio@test.com",
"City": "São Paulo",
"State": "SP",
"ZipCode": "01413-000"
}
}Set as delivered
Endpoint: POST /order/SetDelivery/ORDER_ID?storeStatus=NEW_STATUS&trackingCode=TRACKING_CODE
Making an order as delivered means Yourviews will starting to countdown days to send the review email.
| ORDER_ID | Store's internal order ID. | Required |
| NEW_STATUS | Status text | Optional |
| TRACKING_CODE | Carriers tracking code | Optional |
Set as cancelled
Endpoint: POST /order/SetCancelled/ORDER_ID?storeStatus=NEW_STATUS
Marking as canceled means we will never sent the review email to this order.
| ORDER_ID | Store's internal order ID. | Required |
| NEW_STATUS | Status text | Optional |
Get Order
Endpoint: GET /order/ORDER_ID
Get a previous saved order in Yourviews. Useful for validation and testing.
| ORDER_ID | Store's internal order ID. | Required |
All nodes returns with a prefixed YourviewsXXXID. This is an internal field and can be ignored.