Sample Request
{
GET /v1/customers/11000002?companyId=EN
}
Validation Rules for GET Method – Single
GET_001 - Invalid authorisation
| Element | Details |
|---|
| Scenario ID | GET_001 |
| Scenario Name | Invalid authorisation |
| HTTP Code | 401 |
| GIVEN | The token provided does not pass authorisation |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 401 error and a message |
| Example Error Message | {"statusCode": 401, "message": "Invalid JWT."} |
GET_002 - User is not authorised to access API
| Element | Details |
|---|
| Scenario ID | GET_002 |
| Scenario Name | User is not authorised to access API |
| HTTP Code | 403 |
| GIVEN | The user is not authorised to access the API |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 403 error and a message |
| Example Error Message | {"code": 2030, "message": "User is not authorized"} |
GET_003 - Missing mandatory parameter
| Element | Details |
|---|
| Scenario ID | GET_003 |
| Scenario Name | Missing mandatory parameter |
| HTTP Code | 405 |
| GIVEN | The user does not provide a customerId for the request |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 405 error |
| Example Error Message | 405 Method Not Allowed |
GET_004 - Customer does not exist
| Element | Details |
|---|
| Scenario ID | GET_004 |
| Scenario Name | Customer does not exist |
| HTTP Code | 404 |
| GIVEN | The user provides a customerId which does not exist |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 404 error |
| Example Error Message | {"code": 1040, "message": "The entity of the following parameters [Company: EN, Customer: 213549674] was not found."} |
Sample Request
{
"aliasName": "ShortName",
"companyId": "EN",
"countryCode": "GB",
"customerGroupId": "1",
"customerId": "",
"customerName": "NewCustomerName",
"externalReference": 123456,
"invoice": {
"calculatePayDiscountOnTax": true,
"checkCreditOnHeadOffice": false,
"creditLimit": 300000.0,
"currencyCode": "GBP",
"hasFixedCurrency": true,
"hasFixedPaymentTerms": true,
"hasFixedTaxSystem": false,
"languageCode": "EN",
"paymentTermsId": "30"
},
"payment": {
"bankAccount": "123456789",
"debtCollectionCode": "IK1",
"payMethod": "IP",
"postalAccount": "987654321",
"status": "Active"
},
"contactPoints": [
{
"additionalContactInfo": {
"contactPerson": "ContactName"
},
"address": {
"countryCode": "GB",
"place": "LONDON WC2R 3LT",
"streetAddress": "2 Customer Address Street"
},
"contactPointType": "1",
"phoneNumbers": {
"telephone1": "+44 71 828939"
}
}
]
}
Note: This request does not contain a customerId and therefore relies on auto-numbering setup to automatically assign a new customerId.
Validation Rules for POST Method – Single
POST_001 - Autonumbering does not permit manual assignment
| Element | Details |
|---|
| Scenario ID | POST_001 |
| Scenario Name | Autonumbering does not permit manual assignment |
| HTTP Code | 422 |
| GIVEN | If there is an autonumbering series with manual assignment not permitted and the request body contains a customerId |
| WHEN | The API is called |
| BUT | — |
| THEN | The API stops with a 422 error which states that the Auto-numbering series is missing |
| Example Error Message | {"code": 1010, "message": "Auto-numbering series is missing"} |
POST_002 - Autonumbering series cannot be established
| Element | Details |
|---|
| Scenario ID | POST_002 |
| Scenario Name | Autonumbering series cannot be established |
| HTTP Code | 422 |
| GIVEN | There are multiple autonumbering series available |
| WHEN | The API is called |
| BUT | — |
| THEN | The API stops with a 422 error which states that the Auto-numbering series is missing |
| Example Error Message | {"code": 1010, "message": "Auto-numbering series is missing"} |
POST_003 - Autonumbering does not allow manual assignment
| Element | Details |
|---|
| Scenario ID | POST_003 |
| Scenario Name | Autonumbering does not allow manual assignment |
| HTTP Code | 422 |
| GIVEN | There is a single autonumbering series which does not permit providing a manual customerId and the request body contains a customerId |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 422 error which states that you may not manually provide a customer ID |
| Example Error Message | {"code": 1010, "message": "You cannot enter a new ID manually (CustomerID)."} |
POST_004 - Missing mandatory fields
| Element | Details |
|---|
| Scenario ID | POST_004 |
| Scenario Name | Missing mandatory fields |
| HTTP Code | 422 |
| GIVEN | A user is authorised AND the JSON body is missing a field that is marked mandatory in the schema |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 422 error and a message |
| Example Error Message | "The {0} field is required." |
POST_005 - Illegal value
| Element | Details |
|---|
| Scenario ID | POST_005 |
| Scenario Name | Illegal value |
| HTTP Code | 422 |
| GIVEN | A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that is not permitted (for example, restricted to a list of attribute values) |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 422 error and a message |
| Example Error Message | "countryCode": [{"code": 3010, "message": "Illegal value."}] |
POST_006 - Invalid format of fields
| Element | Details |
|---|
| Scenario ID | POST_006 |
| Scenario Name | Invalid format of fields |
| HTTP Code | 400 |
| GIVEN | A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that does not meet the requirements of the data type defined in the schema |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 400 error and a message |
| Example Error Message | `{“code”: 1010, “message”: “The JSON value could not be converted to System.DateTime. Path: $.payment.expiryDate |
POST_007 - Maximum string length is exceeded
| Element | Details |
|---|
| Scenario ID | POST_007 |
| Scenario Name | Maximum string length is exceeded |
| HTTP Code | 422 |
| GIVEN | A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that exceeds the maximum length defined in the schema |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 400 error and a message |
| Example Error Message | "The field {0} must be a string or array type with a maximum length of {1}." |
POST_008 - Duplicated customer
| Element | Details |
|---|
| Scenario ID | POST_008 |
| Scenario Name | Duplicated customer |
| HTTP Code | 400 |
| GIVEN | A user is authorised AND the JSON body contains all mandatory properties AND all the properties meet the schema requirements AND the customer ID provided already exists in the system |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 400 error and a message |
| Example Error Message | "Your entry is not saved because meanwhile data has been changed by another user. Reload and try again." |
POST_009 - Invalid authorisation
| Element | Details |
|---|
| Scenario ID | POST_009 |
| Scenario Name | Invalid authorisation |
| HTTP Code | 401 |
| GIVEN | The token provided does not pass authorisation |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 401 error and a message |
| Example Error Message | {"statusCode": 401, "message": "Invalid JWT."} |
POST_010 - User is not authorised to access API
| Element | Details |
|---|
| Scenario ID | POST_010 |
| Scenario Name | User is not authorised to access API |
| HTTP Code | 403 |
| GIVEN | The user is not authorised to access the API |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 403 error and a message |
| Example Error Message | {"code": 2030, "message": "User is not authorized"} |
POST_011 - Missing general address
| Element | Details |
|---|
| Scenario ID | POST_011 |
| Scenario Name | Missing general address |
| HTTP Code | 400 |
| GIVEN | A user is authorised AND the JSON body does not contain at least one contactPoint of the “General” type |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 400 error and a message |
| Example Error Message | {"code": 3010, "message": "General address has to be entered"} |
POST_012 - Missing mandatory relation
| Element | Details |
|---|
| Scenario ID | POST_012 |
| Scenario Name | Missing mandatory relation |
| HTTP Code | 422 |
| GIVEN | A user is authorised AND the JSON body does not contain a relation that is mandatory |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 422 error and a message |
| Example Error Message | {"code": 3010, "message": "Relation for attribute LEGALID is mandatory."} |
POST_013 - Missing mandatory flexi-field values
| Element | Details |
|---|
| Scenario ID | POST_013 |
| Scenario Name | Missing mandatory flexi-field values |
| HTTP Code | 422 |
| GIVEN | A user is authorised AND the JSON body does not contain a flexi-field value that is set as mandatory in the flexi-field group definition |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 422 error and a message |
| Example Error Message | "customFieldGroups": {"Test_value": {"n2_fx": "", "notificationMessages": {"n2_fx": [{"code": 3010, "message": "Please enter a value"}]}}} |
POST_014 - Flexi-field value is not valid
| Element | Details |
|---|
| Scenario ID | POST_014 |
| Scenario Name | Flexi-field value is not valid |
| HTTP Code | 422 |
| GIVEN | A user is authorised AND the JSON body contains a flexi-field value that is not permitted according to the flexi-field group definition |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 422 error and a message |
| Example Error Message | {"code": 3010, "message": "The value entered is not valid according to the restrictions for this field."} |
POST_015 - Invalid JSON structure
| Element | Details |
|---|
| Scenario ID | POST_015 |
| Scenario Name | Invalid JSON structure |
| HTTP Code | 400 |
| GIVEN | A user is authorised |
| WHEN | The PATCH request body is malformed |
| BUT | — |
| THEN | The API stops with a 400 error |
| Example Error Message | — |
Sample Request
DELETE /v1/customers/11000002?companyId=EN
Limits & Notes
- Only a single customer can be updated.
- This endpoint does not delete the customer, but alters the status to “Closed”.
- The operation may be undone with a Replace operation through the PATCH endpoint on the path “/payment/status”.
- To fully delete the customer, you need to use the deletion routine “Delete customers and suppliers” available in the system administration menu.
Validation Rules for DELETE Method
DEL_001 - Invalid authorisation
| Element | Details |
|---|
| Scenario ID | DEL_001 |
| Scenario Name | Invalid authorisation |
| HTTP Code | 401 |
| GIVEN | The token provided does not pass authorisation |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 401 error and a message |
| Example Error Message or Response | {"statusCode": 401, "message": "Invalid JWT."} |
DEL_002 - User is not authorised to access API
| Element | Details |
|---|
| Scenario ID | DEL_002 |
| Scenario Name | User is not authorised to access API |
| HTTP Code | 403 |
| GIVEN | The user is not authorised to access the API |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 403 error and a message |
| Example Error Message or Response | {"code": 2030, "message": "User is not authorized"} |
DEL_003 - Customer does not exist
| Element | Details |
|---|
| Scenario ID | DEL_003 |
| Scenario Name | Customer does not exist |
| HTTP Code | 404 |
| GIVEN | The user provides a customerId which does not exist |
| WHEN | The API request is sent |
| BUT | — |
| THEN | The API stops with a 404 error and a message |
| Example Error Message or Response | {"code": 1040, "message": "The entity of the following parameters [Company: EN, Customer: 213549674] was not found."} |