Migrating from SOAP WebServices
What are we talking about?
Neteven has a legacy set of SOAP WebServices that merchants used to create and update products, update stock and prices and manage the order sales cycle.
This legacy SOAP WebServices which spanned over 4 different versions is considered obsolete with the release of the RESTful Merchant API. Merchants connected to the SOAP WebServices are strongly advised to migrate over to the RESTful Merchant API, as it will be the only one maintained over time.
Am I concerned?
You are only concerned by this section if you have an already live connection to Neteven using the Neteven SOAP WebServices and you need to migrate existing methods to the REST API.
What is still the same?
While the entry point changes from SOAP WebServices to a RESTful API, the Neteven system behind remains the same: the content of products, orders, workflows etc. is unchanged.
What has changed?
Not only interaction protocols have changed (from SOAP to HTTP) but also the way to authenticate, the structure of datatype of the message body (from XML to JSON) and the fields themselves, as well as the workflow logic behind the API.
An important aspect of switching from SOAP to REST is how ressources, methods and endpoints are now separated. With the SOAP WebServices, only 4 different endpoints were available and they were used for different things.
Furthermore, you will need a new specific set of credentials to use the Merchant API. Please refer to your Neteven point of contact to receive it.
Content comparison:
- Field names are more explicit and transparent as to what is visible in the UI and exports
- Updating Items (Stock / Price) is relatively similar: the SKU is the main product identifier in both API's
- Orders Lines are now properly regrouped under the 'parent' order_id
- Marketplace names between SOAP Webservices and the REST API may slightly differ. We recommend using the field marketplace_ID rather than the field marketplace_name if your internal process varies depending on the marketplace.
Below is an example to illustrate the difference of content between the SOAP Webservices and the REST API when retrieving a single Marketplace order object.
SOAP Webservices
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns1:GetOrdersResponse xmlns:ns1="urn:NWS:examples">
<ns1:PageNumber>1</ns1:PageNumber>
<ns1:PagesTotal>1</ns1:PagesTotal>
<ns1:GetOrdersResult>
<ns1:MarketPlaceOrder>
<ns1:ID>9811700</ns1:ID>
<ns1:OrderID>7526358</ns1:OrderID>
<ns1:OrderLineID>9811700</ns1:OrderLineID>
<ns1:Status>Confirmed</ns1:Status>
<ns1:CustomerId>13982125</ns1:CustomerId>
<ns1:MarketPlaceId>19</ns1:MarketPlaceId>
<ns1:MarketPlaceOrderId>SANDBOX_7501319_002</ns1:MarketPlaceOrderId>
<ns1:MarketPlaceOrderLineId>SANDBOX_7501319_3_002</ns1:MarketPlaceOrderLineId>
<ns1:MarketPlaceName>sandbox</ns1:MarketPlaceName>
<ns1:MarketPlaceSaleId>SANDBOX_7501319_002</ns1:MarketPlaceSaleId>
<ns1:SKU>HPOLBICNOINOI-M</ns1:SKU>
<ns1:DateSale>2014-09-24T15:18:16</ns1:DateSale>
<ns1:DatePayment>2014-09-24T15:18:16</ns1:DatePayment>
<ns1:TrackingNumber>TestWS1-1-Order001-TrackingNumber-7526358</ns1:TrackingNumber>
<ns1:TrackingInfo>TestWS1-1-Order001-TrackingInfo-7526358</ns1:TrackingInfo>
<ns1:TrackingURL>TestWS1-1-Order001-TrackingURL-7526358</ns1:TrackingURL>
<ns1:AmountPaid currency_id="EUR">77.69</ns1:AmountPaid>
<ns1:PaymentMethod>Unknown</ns1:PaymentMethod>
<ns1:Quantity>1</ns1:Quantity>
<ns1:Price currency_id="EUR">77.69</ns1:Price>
<ns1:InsuranceCost currency_id="EUR">0.00</ns1:InsuranceCost>
<ns1:ShippingCost currency_id="EUR">0.00</ns1:ShippingCost>
<ns1:FinalShippingCost currency_id="EUR">0.00</ns1:FinalShippingCost>
<ns1:OrderShippingCost currency_id="EUR">0.00</ns1:OrderShippingCost>
<ns1:VAT currency_id="EUR">12.95</ns1:VAT>
<ns1:TotalCostWithVAT currency_id="EUR">77.69</ns1:TotalCostWithVAT>
<ns1:MarketplaceFee currency_id="EUR">0.00</ns1:MarketplaceFee>
<ns1:Ecotax>0.00</ns1:Ecotax>
<ns1:ProcessingFee>0.00</ns1:ProcessingFee>
<ns1:WarehouseId>513</ns1:WarehouseId>
<ns1:WarehouseShippable>1</ns1:WarehouseShippable>
<ns1:BillingAddress>
<ns1:FirstName>anonymized</ns1:FirstName>
<ns1:LastName>anonymized</ns1:LastName>
<ns1:Address1>anonymized</ns1:Address1>
<ns1:Address2>anonymized</ns1:Address2>
<ns1:CityName>NESGO livraison</ns1:CityName>
<ns1:PostalCode>95500 livraison</ns1:PostalCode>
<ns1:StateProvince/>
<ns1:CountryCode>FR</ns1:CountryCode>
<ns1:Country>FRANCE livraison</ns1:Country>
<ns1:Phone>anonymized</ns1:Phone>
<ns1:Mobile>anonymized</ns1:Mobile>
<ns1:Fax>anonymized</ns1:Fax>
<ns1:Email>anonymized</ns1:Email>
<ns1:Company>anonymized</ns1:Company>
<ns1:Pseudo>anonymized</ns1:Pseudo>
</ns1:BillingAddress>
<ns1:ShippingAddress>
<ns1:FirstName>anonymized</ns1:FirstName>
<ns1:LastName>anonymized</ns1:LastName>
<ns1:Address1>anonymized</ns1:Address1>
<ns1:Address2>anonymized</ns1:Address2>
<ns1:CityName>NESGO</ns1:CityName>
<ns1:PostalCode>95500</ns1:PostalCode>
<ns1:StateProvince/>
<ns1:CountryCode>FR</ns1:CountryCode>
<ns1:Country>FRANCE</ns1:Country>
<ns1:Phone>anonymized</ns1:Phone>
<ns1:Mobile>anonymized</ns1:Mobile>
<ns1:Fax>anonymized</ns1:Fax>
<ns1:Email>anonymized</ns1:Email>
<ns1:Company>anonymized</ns1:Company>
<ns1:Pseudo>anonymized</ns1:Pseudo>
</ns1:ShippingAddress>
<ns1:DeliveryInstructions/>
</ns1:MarketPlaceOrder>
<ns1:MarketPlaceOrder>
<ns1:ID>9811701</ns1:ID>
<ns1:OrderID>7526358</ns1:OrderID>
<ns1:OrderLineID>9811701</ns1:OrderLineID>
<ns1:Status>toConfirm</ns1:Status>
<ns1:CustomerId>13982125</ns1:CustomerId>
<ns1:MarketPlaceId>19</ns1:MarketPlaceId>
<ns1:MarketPlaceOrderId>SANDBOX_7501319_002</ns1:MarketPlaceOrderId>
<ns1:MarketPlaceOrderLineId>SANDBOX_7501319_2_002</ns1:MarketPlaceOrderLineId>
<ns1:MarketPlaceName>sandbox</ns1:MarketPlaceName>
<ns1:MarketPlaceSaleId>SANDBOX_7501319_002</ns1:MarketPlaceSaleId>
<ns1:SKU>69023-AAM-GHTP</ns1:SKU>
<ns1:DateSale>2014-09-24T15:18:16</ns1:DateSale>
<ns1:DatePayment>2014-09-24T15:18:16</ns1:DatePayment>
<ns1:TrackingNumber>TestWS1-1-Order001-TrackingNumber-7526358</ns1:TrackingNumber>
<ns1:TrackingInfo>TestWS1-1-Order001-TrackingInfo-7526358</ns1:TrackingInfo>
<ns1:TrackingURL>TestWS1-1-Order001-TrackingURL-7526358</ns1:TrackingURL>
<ns1:AmountPaid currency_id="EUR">2878.80</ns1:AmountPaid>
<ns1:PaymentMethod>Unknown</ns1:PaymentMethod>
<ns1:Quantity>3</ns1:Quantity>
<ns1:Price currency_id="EUR">2878.80</ns1:Price>
<ns1:InsuranceCost currency_id="EUR">0.00</ns1:InsuranceCost>
<ns1:ShippingCost currency_id="EUR">0.00</ns1:ShippingCost>
<ns1:FinalShippingCost currency_id="EUR">0.00</ns1:FinalShippingCost>
<ns1:OrderShippingCost currency_id="EUR">0.00</ns1:OrderShippingCost>
<ns1:VAT currency_id="EUR">479.80</ns1:VAT>
<ns1:TotalCostWithVAT currency_id="EUR">2878.80</ns1:TotalCostWithVAT>
<ns1:MarketplaceFee currency_id="EUR">0.00</ns1:MarketplaceFee>
<ns1:Ecotax>0.00</ns1:Ecotax>
<ns1:ProcessingFee>0.00</ns1:ProcessingFee>
<ns1:WarehouseShippable>0</ns1:WarehouseShippable>
<ns1:BillingAddress>
<ns1:FirstName>anonymized</ns1:FirstName>
<ns1:LastName>anonymized</ns1:LastName>
<ns1:Address1>anonymized</ns1:Address1>
<ns1:Address2>anonymized</ns1:Address2>
<ns1:CityName>NESGO livraison</ns1:CityName>
<ns1:PostalCode>95500 livraison</ns1:PostalCode>
<ns1:StateProvince/>
<ns1:CountryCode>FR</ns1:CountryCode>
<ns1:Country>FRANCE livraison</ns1:Country>
<ns1:Phone>anonymized</ns1:Phone>
<ns1:Mobile>anonymized</ns1:Mobile>
<ns1:Fax>anonymized</ns1:Fax>
<ns1:Email>anonymized</ns1:Email>
<ns1:Company>anonymized</ns1:Company>
<ns1:Pseudo>anonymized</ns1:Pseudo>
</ns1:BillingAddress>
<ns1:ShippingAddress>
<ns1:FirstName>anonymized</ns1:FirstName>
<ns1:LastName>anonymized</ns1:LastName>
<ns1:Address1>anonymized</ns1:Address1>
<ns1:Address2>anonymized</ns1:Address2>
<ns1:CityName>NESGO</ns1:CityName>
<ns1:PostalCode>95500</ns1:PostalCode>
<ns1:StateProvince/>
<ns1:CountryCode>FR</ns1:CountryCode>
<ns1:Country>FRANCE</ns1:Country>
<ns1:Phone>anonymized</ns1:Phone>
<ns1:Mobile>anonymized</ns1:Mobile>
<ns1:Fax>anonymized</ns1:Fax>
<ns1:Email>anonymized</ns1:Email>
<ns1:Company>anonymized</ns1:Company>
<ns1:Pseudo>anonymized</ns1:Pseudo>
</ns1:ShippingAddress>
<ns1:DeliveryInstructions/>
</ns1:MarketPlaceOrder>
<ns1:MarketPlaceOrder>
<ns1:ID>9811699</ns1:ID>
<ns1:OrderID>7526358</ns1:OrderID>
<ns1:OrderLineID>9811699</ns1:OrderLineID>
<ns1:Status>toConfirm</ns1:Status>
<ns1:CustomerId>13982125</ns1:CustomerId>
<ns1:MarketPlaceId>19</ns1:MarketPlaceId>
<ns1:MarketPlaceOrderId>SANDBOX_7501319_002</ns1:MarketPlaceOrderId>
<ns1:MarketPlaceOrderLineId>SANDBOX_7501319_1_002</ns1:MarketPlaceOrderLineId>
<ns1:MarketPlaceName>sandbox</ns1:MarketPlaceName>
<ns1:MarketPlaceSaleId>SANDBOX_7501319_002</ns1:MarketPlaceSaleId>
<ns1:SKU>HCAPLEONOI-TU</ns1:SKU>
<ns1:DateSale>2014-09-24T15:18:16</ns1:DateSale>
<ns1:DatePayment>2014-09-24T15:18:16</ns1:DatePayment>
<ns1:TrackingNumber>TestWS1-1-Order001-TrackingNumber-7526358</ns1:TrackingNumber>
<ns1:TrackingInfo>TestWS1-1-Order001-TrackingInfo-7526358</ns1:TrackingInfo>
<ns1:TrackingURL>TestWS1-1-Order001-TrackingURL-7526358</ns1:TrackingURL>
<ns1:AmountPaid currency_id="EUR">190.31</ns1:AmountPaid>
<ns1:PaymentMethod>Unknown</ns1:PaymentMethod>
<ns1:Quantity>1</ns1:Quantity>
<ns1:Price currency_id="EUR">190.31</ns1:Price>
<ns1:InsuranceCost currency_id="EUR">0.00</ns1:InsuranceCost>
<ns1:ShippingCost currency_id="EUR">0.00</ns1:ShippingCost>
<ns1:FinalShippingCost currency_id="EUR">0.00</ns1:FinalShippingCost>
<ns1:OrderShippingCost currency_id="EUR">0.00</ns1:OrderShippingCost>
<ns1:VAT currency_id="EUR">31.72</ns1:VAT>
<ns1:TotalCostWithVAT currency_id="EUR">190.31</ns1:TotalCostWithVAT>
<ns1:MarketplaceFee currency_id="EUR">0.00</ns1:MarketplaceFee>
<ns1:Ecotax>0.00</ns1:Ecotax>
<ns1:ProcessingFee>0.00</ns1:ProcessingFee>
<ns1:WarehouseShippable>0</ns1:WarehouseShippable>
<ns1:BillingAddress>
<ns1:FirstName>anonymized</ns1:FirstName>
<ns1:LastName>anonymized</ns1:LastName>
<ns1:Address1>anonymized</ns1:Address1>
<ns1:Address2>anonymized</ns1:Address2>
<ns1:CityName>NESGO livraison</ns1:CityName>
<ns1:PostalCode>95500 livraison</ns1:PostalCode>
<ns1:StateProvince/>
<ns1:CountryCode>FR</ns1:CountryCode>
<ns1:Country>FRANCE livraison</ns1:Country>
<ns1:Phone>anonymized</ns1:Phone>
<ns1:Mobile>anonymized</ns1:Mobile>
<ns1:Fax>anonymized</ns1:Fax>
<ns1:Email>anonymized</ns1:Email>
<ns1:Company>anonymized</ns1:Company>
<ns1:Pseudo>anonymized</ns1:Pseudo>
</ns1:BillingAddress>
<ns1:ShippingAddress>
<ns1:FirstName>anonymized</ns1:FirstName>
<ns1:LastName>anonymized</ns1:LastName>
<ns1:Address1>anonymized</ns1:Address1>
<ns1:Address2>anonymized</ns1:Address2>
<ns1:CityName>NESGO</ns1:CityName>
<ns1:PostalCode>95500</ns1:PostalCode>
<ns1:StateProvince/>
<ns1:CountryCode>FR</ns1:CountryCode>
<ns1:Country>FRANCE</ns1:Country>
<ns1:Phone>anonymized</ns1:Phone>
<ns1:Mobile>anonymized</ns1:Mobile>
<ns1:Fax>anonymized</ns1:Fax>
<ns1:Email>anonymized</ns1:Email>
<ns1:Company>anonymized</ns1:Company>
<ns1:Pseudo>anonymized</ns1:Pseudo>
</ns1:ShippingAddress>
<ns1:DeliveryInstructions/>
</ns1:MarketPlaceOrder>
</ns1:GetOrdersResult>
</ns1:GetOrdersResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
REST API
{
"data": {
"order": {
"order_id": 7526358,
"marketplace_order_id": "SANDBOX_7501319_002",
"order_lines_count": 3,
"date_creation": "2014-09-24T15:22:21",
"date_sale": "2014-09-24T15:18:16",
"date_payment": "2014-09-24T15:18:16",
"prices": {
"currency_id": "EUR",
"total_price_including_taxes_excluding_shipping": 3146.80,
"total_price_excluding_taxes_excluding_shipping": 2622.33
},
"shipping_information": {
"carrier_name": "TestWS1-1-Order001-TrackingInfo-7526358",
"tracking_url": "TestWS1-1-Order001-TrackingURL-7526358",
"tracking_number": "TestWS1-1-Order001-TrackingNumber-7526358"
},
"address_delivery": {
"title": "anonymized",
"first_name": "anonymized",
"last_name": "anonymized",
"street1": "anonymized",
"street2": "anonymized",
"city": "anonymized",
"country_code": "FR",
"country": "FRANCE",
"postcode": "95500",
"phone1": "secret",
"phone2": "anonymized",
"fax": "anonymized",
"email": "anonymized",
"login": "anonymized",
"company_name1": "anonymized",
"company_name2": "anonymized",
"delivery_relay_name": "anonymized",
"delivery_relay_contractlevel": "anonymized",
"delivery_relay_id": "anonymized"
},
"address_invoice": {
"title": "anonymized",
"first_name": "anonymized",
"last_name": "anonymized",
"street1": "anonymized",
"street2": "anonymized",
"city": "anonymized",
"country_code": "FR",
"country": "FRANCE",
"postcode": "95500",
"phone1": "secret",
"phone2": "anonymized",
"fax": "anonymized",
"email": "anonymized",
"login": "anonymized",
"company_name1": "anonymized",
"company_name2": "anonymized"
},
"order_lines": [
{
"order_line_id": 9811699,
"marketplace_order_line_id": "SANDBOX_7501319_1_002",
"status_current": "TO CONFIRM",
"item": {
"sku": "HCAPLEONOI-TU",
"ean": "3606852811431",
"marketplace_product_id": "SANDBOX_PRODUCT_3029_HCAPLEONOI-TU",
"quantity": 1
},
"prices": {
"currency_id": "EUR",
"total_price_including_taxes_excluding_shipping": 190.31,
"total_price_excluding_taxes_excluding_shipping": 158.59
}
},
{
"order_line_id": 9811700,
"marketplace_order_line_id": "SANDBOX_7501319_3_002",
"status_current": "TO SHIP",
"item": {
"sku": "HPOLBICNOINOI-M",
"marketplace_product_id": "SANDBOX_PRODUCT_3029_HPOLBICNOINOI-M",
"quantity": 1,
"warehouse_name": "Aurel_warehouse"
},
"prices": {
"currency_id": "EUR",
"total_price_including_taxes_excluding_shipping": 77.69,
"total_price_excluding_taxes_excluding_shipping": 64.74
}
},
{
"order_line_id": 9811701,
"marketplace_order_line_id": "SANDBOX_7501319_2_002",
"status_current": "TO CONFIRM",
"item": {
"sku": "69023-AAM-GHTP",
"ean": "3231760424042",
"marketplace_product_id": "SANDBOX_PRODUCT_3029_69023-AAM-GHTP",
"quantity": 3
},
"prices": {
"currency_id": "EUR",
"total_price_including_taxes_excluding_shipping": 2878.80,
"total_price_excluding_taxes_excluding_shipping": 2399.00
}
}
]
}
},
"metadata": {
"number_of_results": 1,
"api_version": 1,
"api_version_expiration_date": "2022-12-31"
}
}Action mapping tables
Authentication
Action | SOAP WS method | REST API endpoint |
|---|---|---|
Authenticate | Request body header: md5 signature | POST/login time limited JWT Bearer token |
Product, stock and prices
Action | SOAP WS method | REST API endpoint |
|---|---|---|
Create a new product | PostItems | POST merchant/products/import-file |
Update product content | PostItems | POST merchant/products/import-file |
Create a warehouse | N/A | POST/merchant/warehouses |
Retrieve the existing warehouses | N/A | GET/merchant/warehouses |
Retrieve product data | GetItems Parse Response Body for relevant information | N/A |
Update Stock information | PostItems | PATCH /merchant/items/stocks |
Update Price information | PostItems | PATCH /merchant/items/prices |
Retrieve Stock information | GetItems Parse Response Body for relevant information | GET/merchant/items/stocks |
Retrieve Price information | GetItems Parse Response Body for relevant information | GET/merchant/items/prices |
Order management
Action | SOAP WS method | REST API endpoint |
|---|---|---|
Retrieve new orders | GetOrders Request Body fields: Custom filters | GET /merchant/orders/new |
Retrieve a specific order | GetOrders Request Body fields: OrderID | GET/merchant/orders/{order-id} |
Acknowledge order lines | PostOrders (WS1-3 +) Request Body fields: OrderLineAck / MerchantOrderLineId | PATCH /merchant/orders/{order-id}/lines/{order-line-id}/ack |
Confirm order lines | PostOrders Request Body fields: Status = Confirmed | PATCH /merchant/orders/{order-id}/lines/{order-line-id}/confirm |
Cancel order lines | PostOrders Request Body fields: Status = Canceled | PATCH /merchant/orders/{order-id}/lines/{order-line-id}/cancel |
Ship order lines | PostOrders Request Body fields: Status = Shipped | PATCH /merchant/orders/{order-id}/lines/{order-line-id}/ship |
Refund order lines | PostOrders Request Body fields: Status = Refunded | PATCH /merchant/orders/{order-id}/lines/{order-line-id}/refund |
Check state of Status change request | N/A | GET /merchant/orders/{order-id}/lines/{order-line-id}/status |