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
DescriptionRequired?
Type
OrderId
Order number at the store. It's the primary key at order calls.    
Yesstring
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    Nostring




User
Customer node 
Required node
Name
Customer full name
Yes
string
Email
Customer e-mail
Yes
string
City
Customer City
No
string
State
Customer StateNo
string
ZipCode
Customer Zip CodeNo
string
UserIdCustomer Id at the platformNo
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 nameYes
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 productsNó obrigatório

ProductId
Product's Id as shown in the frontend (product page)
Yes
string
Name
Product page as shown to consumerYes
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 URLYes, if IsActive=true
string
Value
Product Sale priceYes, if IsActive=true
decimal
Category
Node with categories of the productNão    
Category
CategoryId
Internal category IdYes
string
Name
Category nameYes
string
Parent
Parent-category if availableNão
Category
Brand
Product BrandNão
Brand
BrandId
Internal brand IdYes
string
Name
Brand nameYes
string
Sku
Sku of the sold productNão
Sku
SkudId
Sku ID as shown in the product pageYes
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 priceYes
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_CODECarriers tracking codeOptional


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.