Search
My Products
Help

Visma.net ERP Sales Order Service 1.0.9.28: Service in beta state - breaking changes for API

‎03-11-2021 14:22
by TGB (Updated ‎03-11-2021 14:25 by TGB )

We are transitioning the Visma.net ERP Sales Order Service from alpha to beta state. This indicates that we will no longer introduce any breaking changes in existing endpoints. If this will be required we will introduce a new version of the endpoint. The journey to frequently add more functionality will continue, but we will give you (the ISVs) 6 months to migrate to the new version of an endpoint if we introduce a breaking change. This will create better predictability for you as a consumer of the Visma.net ERP Sales Order Service API and ensure you will be able to serve your customers the best way possible.

 

Rename Site to Warehouse

We want to be consistent in our naming and use Warehouse as the term for sites and warehouses. We're also moving the (formerly) defaultSiteId to the shipping section to be consistent with the GET endpoint response.

POST /api/v3/salesorders

Rename defaultSiteId to preferredWarehouseId, and move to shipping.

Before change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"defaultSiteId": "Site1"
}

 

 

 

After change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"shipping": {
	"preferredWarehouseId": "Site1"
        }
}

 

 

 

Rename siteId to warehouseId

Before change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"orderLines": [
		{
			"inventoryId": "SomeItem1",
		"quantity": 2.0,
		"siteId": "Site1"
		}
	]
}

 

 

 

After change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"orderLines": [
		{
			"inventoryId": "SomeItem1",
		"quantity": 2.0,
		"warehouseId": "Site1"
		}
	]
}

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines

Rename siteId to warehouseId.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
     {
			"lineId": 1,
		"inventory": {
				"baseUnit": "STK",
				"id": "SomeItem1"
		},
			"quantity": 2.0,
		"siteId": "Site1"
     }
]
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
     {
			"lineId": 1,
		"inventory": {
				"baseUnit": "STK",
				"id": "SomeItem1"
		},
			"quantity": 2.0,
		"warehouseId": "Site1"
     }
]
}

 

 

 

GET /api/v3/customers/{customerId}/locations

Rename siteId to warehouseId.

Before change

 

 

 

Response:
[
     {
		"internalId": 1,
		...
	"siteId": "Site1"
}
]

 

 

 

After change

 

 

 

GET /api/v3/customers/{customerId}/locations
 
Response:
[
     {
		"internalId": 1,
		...
	"warehouseId": "Site1"
}
]

 

 

 

Rename Customer Fields

We want to be consistent and not repeat parent object's name in properties

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}

Rename customerOrder to order, customerRefNo to refNo. Rename customerId to id.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"customer": {
		"customerId": "10000",
		"name": "some name",
		"customerOrder": "arbitrary order number",
		"customerRefNo": "reference number"
}
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"customer": {
		"id": "10000",
		"name": "some name",
		"order": "arbitrary order number",
		"refNo": "reference number"
}
}

 

 

 

Rename DiscountPrice

Rename property for consistency

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines

Rename discountPrice to discountAmount.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
     {
			"lineId": 1,
		"inventory": {
				"baseUnit": "STK",
				"id": "SomeItem1"
		},
			"quantity": 2.0,
		"discountPrice": 1.00
     }
]
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
     {
			"lineId": 1,
		"inventory": {
				"baseUnit": "STK",
				"id": "SomeItem1"
		},
			"quantity": 2.0,
		"discountAmount": 1.00
     }
]
}

 

 

 

Use descriptive names instead of codes

We want to return names of property values when we can, as opposed to codes used internally by the system. Please note that these changes are currently feature toggled and can be tried out today by enabling the switch for one or more companies if necessary.

POST /api/v3/salesorders

Use names for status.

Before change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"status": "N"
}

 

 

 

After change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"status": "Open"
}

 

 

 

Use names for shipping/rule.

Before change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"shipping": {
 	"rule": "B"
}
}

 

 

 

After change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"shipping": {
 	"rule": "BackOrderAllowed"
}
}

 

 

 

Use names for shippingRule.

Before change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"orderLines": 
[
		{
			"inventoryId": "SomeItem1",
		"quantity": 2.0,
		"shippingRule": "B"
		}
	]
}

 

 

 

After change

 

 

 

POST /api/v3/salesorders
{
	"type": "SO",
	"customer": {
		"id": "10000"
	},
	"orderLines": 
[
		{
			"inventoryId": "SomeItem1",
		"quantity": 2.0,
		"shippingRule": "BackOrderAllowed"
		}
	]
}

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}

Use name for status.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"status": {
		"description": "N"
}
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"status": {
		"description": "Open"
}
}

 

 

 

Use name for shipping/rule.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"shipping": {
		"rule": "L"
}
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"shipping": {
		"rule": "CancelRemainder"
}
}

 

 

 

GET /api/v3/salesorders(/{salesOrderType})

Use name for status.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}
GET /api/v3/salesorders
 
Response:
{
	"value": [
		{
		"type": "SO",
 		"orderId": "10001",
     		"status": "H"
 	}
]
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}
GET /api/v3/salesorders
 
Response:
{
	"value": [
		{
		"type": "SO",
 		"orderId": "10001",
     		"status": "Hold"
 	}
]
}

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines

Use name for lineType.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
		{
			"lineId": 3,
		"lineType": "GI"
 	}
]
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
		{
			"lineId": 3,
		"lineType": "GoodsForInventory"
 	}
]
}

 

 

 

Use name for operation.

Before change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
		{
			"lineId": 3,
		"operation": "I"
 	}
]
}

 

 

 

After change

 

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
		{
			"lineId": 3,
		"operation": "Issue"
 	}
]
}

 

 

 

Use Tax consistently

We want to switch to use Tax as a term for VAT and tax in general.

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}

Change names in the totals section

Note that this only applies if expand=all, or expand=financialInformation.

 

Before change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}?expand=all
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"totals": {
		"orderTotal": 1000.00,
       	"orderTotalInBaseCurrency": 1000.00,
		"vatTaxableTotal": 100.0,
		"vatTaxableTotalInBaseCurrency": 100.0,
		"vatExemptTotal": 0.0,
		"vatExemptTotalInBaseCurrency": 0.0,
 	"taxTotal": 25.00,
     	"taxTotalInBaseCurrency": 25.00,
}
}

 

 

After change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}?expand=all
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"totals": {
		"orderTotal": 1000.00,
       	"orderTotalInBaseCurrency": 1000.00,
		"taxableTotal": 100.0,
		"taxableTotalInBaseCurrency": 100.0,
		"taxExemptTotal": 0.0,
		"taxExemptTotalInBaseCurrency": 0.0,
 	"taxTotal": 25.00,
     	"taxTotalInBaseCurrency": 25.00,
}
}

 

 

Change names in the customer section

Note that this only applies if expand=all, or expand=customer.

 

Before change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}?expand=all
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"customer": {
		"vatZone": {
 	 		"id": "01",
 			"description": "some description"
 		}
}
}

 

 

After change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}?expand=all
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"customer": {
		"taxZone": {
 	 		"id": "01",
 			"description": "some description"
 		}
 	}
}

 

 

Use consistent format for Subaccount

We want to be consistent in the notation for subaccounts, using the same segment id/segment value we use when posting a new sales order.

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines

Use the new format for lines.

Before change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
		{
			"lineId": 3,
			...
		"subaccountId": "101"
 	}
]
}

 

 

After change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}/lines
 
Response:
{
	"value": [
		{
			"lineId": 3,
			...
		"subaccount": {
 			"1": "1",
			"2": "0",
			"3": "1"
		}
 	}
]
}

 

 

Use consistent name for for Shipping information

We want to be consistent in the notation for shipping information, using "shipping" and not "shipment".

GET /api/v3/salesorders(/{salesOrderType})

Change name for shipmentScheduledDate to shippingScheduledDate.

Before change

 

 

GET /api/v3/salesorders/{salesOrderType}
 
Response:
{
	"value": [
		{
			"type": "SO",
			"orderId": "100001",
			...
		"shipmentScheduledDate": "2021-06-04T00:00:00"
 	}
]
}

 

 

After change

 

 

GET /api/v3/salesorders/{salesOrderType}
 
Response:
{
	"value": [
		{
			"type": "SO",
			"orderId": "100001",
			...
		"shippingScheduledDate": "2021-06-04T00:00:00"
 	}
]
}

 

 

Use consistent name for for payment settings section

We want to use a better name for the payment section in the sales order head as it relates to the payment settings tab in the UI using "paymentSettings" and not "payment".

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}

Change name for payment to paymentSettings.

Before change

 

 

GET /api/v3/salesorders/{salesOrderType}/{salesOrderId}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"payment": {
		"paymentMethod": {...},
		"cashAccountId": "1"
}
}

 

 

After change

 

 

GET /api/v3/salesorders/{salesOrderType}
 
Response:
{
	"type": "SO",
	"orderId": "10001",
	...
"paymentSettings": {
		"paymentMethod": {...},
		"cashAccountId": "1"
}
}

 

 


If you are new to the neXtGen services, please look at the Getting started with the first neXtGen service: Visma.net ERP Sales Order API for an introduction.

Categories:
0 Kudos
Choose your region:
Choose your Region
Go