Customer

Overview

This article will help you to understand the APIs available to for Customer

You will learn,

How to create a customer
How to get all customers
How to get specific customer by customer id
How to activate and deactivate customers

Entity Relationship for Customer Order

Figure 1 : ER Diagram for Customer. This will only indicate reationships between other entties.

All Api Endpoints for Customer

Endpoint	Type	Description
api/biz/customers	POST	Create Cutomer
api/biz/customers	GET	Get Customers
api/biz/customers/{id}	GET	Get Customer By Id
api/biz/customers/{id}	DELETE	Delete Customer By Id
api/biz/customers/{id}	PUT	Update Customer By Id
api/biz/customers/{id}?action=next	GET	Get next customer
api/biz/customers/{id}?action=previous	GET	Get previous customer
api/biz/customers?action=activate	PUT	Activate Customer
api/biz/customers?action=deactivate	PUT	Deactivate Customer
api/biz/customers?action=block	PUT	Block Customer
api/biz/customers?action=bulk-save	PUT	Bulk Save Customers
api/biz/customers?action=validate-customer-KID-Alias&customerKidAlias={kid}	GET	Validate Customer KID

Customer Status Types

Status	Status Code
Active	30001
InActive	50001
Deleted	90001

How to Create a New Customer

To create a new customer you need to include only basic infomation about the customer in the payload. i.e. OrgNumber or Info.Name

But it is always recommanded to include additional infomation to the customer so it will be easy to interact with other API depend on Customer. ex. Invoice API, Order API ect.

Endpoint : api/biz/customers

Method Type : POST

Sample Request Payload : Appendix A - Sample Request for Create Customer

How to Add Contact Details to Customer

You can include following contact details with customer payload

Address - Set values for Info.Addresses array or Info.InvoiceAddress object or Info.ShippingAddress object

If you including address for invoice or shipping don't repeat same address in Info.Addresses array.

PhoneNumber - Set values for Info.Phones array or Info.DefaultPhone objectYou need to set a Type for the phone number.

Don't repeat the default phone number in Info.Phones array

Description	Type
Phone	150101
Mobile	150102
Fax	150103

Emails - Set Values for Info.Emails array or Info.DefaultEmail object

Don't repeat the default email in Info.Emails array

Set Default Report for Customer

You can set default report for Customer Invoice,Customer Order and Customer Quotes. This reports will be used to generate the Softcopies and Hardcopies of Invoices,Orders and Quotes.

Set DefaultCustomerInvoiceReportID property for customer invoice report

Set DefaultCustomerOrderReportID property for customer order report

Set DefaultCustomerQuoteReportID property for customer quote report

How Get Report Details

You can use following api to get report details by report type

Endpoint : api/report/type/{reportType}

Method : Get

Following values can be used for {reportType} parameter

Description	Parameter Value
INVOICE	1
ORDER	2
QUOTE	3

Get Customers

You can either use statistics API or customer API to get customer details. This article we'll look how to get customer data using custimer API. You can read statistics article to get more details about how to use statistics API.

Endpoint : api/biz/customers

Method Type : GET

All Unimicro APIs support OData (Open Data Protocol) configuration. You can use expand, select ,top skip and filter query operators to Filter, Select and Expand the customer details.

Below Request will skip first 20 records and return next 10 customers with contact details and filter it by Status Code 30001.

https://test.unimicro.no/api/biz/customers?expand=Info,Info.Phones,Info.DefaultPhone,Info.Addresses,Info.Emails,Info.DefaultEmail,Info.ShippingAddress,Info.InvoiceAddress,Dimensions,Info.DefaultBankAccount,Info.Contacts.Info,Info.Contacts.Info.DefaultEmail,Info.Contacts.Info.DefaultPhone&filter=StatusCode eq 30001&top=10&skip=20

Get Customer By Customer ID

In order to get a specific customer you can use below api by passing the customer ID as a parameter. By default this will return only basic information. Use OData expand query operator to get more details.

Endpoint : api/biz/customers/{id}

Method Type : GET

Content-Type : application/json

Parameter Name	Type	Description
id	int32	Customer Id

How to Activate, Deactivate and Block a Customer

By default when you create a customer, status code will be in Active (30001) status. Using following API you can activate,deactivate and block customers. These API will only change the status code of the customer entity.

Endpoint : api/biz/customers?action={action}&id={id}

Method Type : PUT

Parameter Name	Type	Description
action	string	Action Name
id	int32	Customer Id

Possible Action Values

Action Name	Description
activate	Change the customer status to Active
deactivate	Change the customer status to InActive
block	Change the customer status to Deleted

Validation Response

API will return BadRequest (400) response with an error message

{
    "ID": 69,
    "EntityID": 0,
    "PropertyName": "",
    "EntityType": "Customer",
    "Message": "Customer have references to one or more quote, order, invoice, project or workitem and cannot be deleted!",
    "Level": 30,
    "EntityValidationRule": null,
    "ComplexValidationRule": {
        "EntityType": "Order",
        "ValidationCode": 115001,
        "Message": "Customer have references to one or more quote, order, invoice, project or workitem and cannot be deleted!",
        "System": false,
        "Operation": 30,
        "Level": 30,
        "SyncKey": null,
        "ChangedByCompany": false,
        "OnConflict": 0,
        "ID": 69,
        "Deleted": false,
        "CreatedAt": null,
        "UpdatedAt": null,
        "CreatedBy": null,
        "UpdatedBy": null
    }
}

Internal Server Error Response

API will return InternalServerError (500) response for unhandled exception.

Example scenario, Trying to create a customer with invalid DimensionsID

{
  "Message": "MURA28RA: The UPDATE statement conflicted with the FOREIGN KEY constraint \"FK_Customer_DimensionsID_Dimensio..",
  "StackTrace": "",
  "Source": "",
  "InnerException": null,
  "ErrorReference": "MURA28RA"
}

Appendices

Appendix A - Create Customer Sample Request

{
    "CustomerNumber": 0,
    "CustomerNumberKidAlias": null,
    "BusinessRelationID": 0,
    "OrgNumber": "914012708",
    "IsPrivate": false,
    "Info": {
        "CustomValues": null,
        "Deleted": false,
        "DefaultBankAccountID": null,
        "Name": "John Doe",
        "ShippingAddressID": null,
        "StatusCode": null,
        "ID": 0,
        "UpdatedBy": null,
        "UpdatedAt": null,
        "DefaultEmailID": null,
        "CreatedBy": null,
        "InvoiceAddressID": null,
        "DefaultPhoneID": null,
        "DefaultContactID": null,
        "CreatedAt": null,
        "DefaultContact": null,
        "Contacts": [],
        "Addresses": [],
        "Phones": [],
        "Emails": [],
        "BankAccounts": [],
        "InvoiceAddress": {
            "ID": 0,
            "_createguid": "6588024e-24aa-4ee9-8bf5-bc28778f2e91",
            "_guid": "c5e1d7d9-89b8-4314-8023-eb89a8f577d7",
            "AddressLine1": "Address Line 1",
            "AddressLine2": "Address Line 2",
            "AddressLine3": "Address Line",
            "PostalCode": "12345",
            "City": "12345",
            "Country": "Norge",
            "CountryCode": "NO",
            "_isDirty": true
        },
        "ShippingAddress": {
            "ID": 0,
            "_createguid": "6588024e-24aa-4ee9-8bf5-bc28778f2e91",
            "_guid": "c5e1d7d9-89b8-4314-8023-eb89a8f577d7",
            "AddressLine1": "Address Line 1",
            "AddressLine2": "Address Line 2",
            "AddressLine3": "Address Line",
            "PostalCode": "12345",
            "City": "12345",
            "Country": "Norge",
            "CountryCode": "NO",
            "_isDirty": true
        },
        "DefaultPhone": {
            "ID": 0,
            "_createguid": "32e9a147-2ce8-4479-8578-44a94a0e0ae8",
            "_guid": "48fd0a66-bb3b-40a7-8db1-41b593b7e781",
            "Type": 150101,
            "Number": "9834834678",
            "CountryCode": "97",
            "Description": "Office",
            "_isDirty": true
        },
        "DefaultEmail": {
            "ID": 0,
            "_createguid": "95586df2-ecff-43de-8c4e-7d72c5d834ce",
            "_guid": "fdfd2177-e9dd-4cc9-84d9-215523d704b5",
            "EmailAddress": "user@softrig.com",
            "Description": "SoftRig User",
            "_isDirty": true
        },
        "DefaultBankAccount": null
    },
    "CreditDays": null,
    "DefaultDistributionsID": null,
    "Distributions": {
        "CustomerInvoiceDistributionPlanID": null,
        "CustomerInvoiceDistributionPlan": null,
        "CustomerOrderDistributionPlanID": null,
        "CustomerOrderDistributionPlan": null,
        "CustomerQuoteDistributionPlanID": null,
        "CustomerQuoteDistributionPlan": null,
        "CustomerInvoiceReminderDistributionPlanID": null,
        "CustomerInvoiceReminderDistributionPlan": null,
        "PayCheckDistributionPlanID": null,
        "PayCheckDistributionPlan": null,
        "AnnualStatementDistributionPlanID": null,
        "AnnualStatementDistributionPlan": null,
        "StatusCode": null,
        "CustomValues": null,
        "ID": 0,
        "Deleted": false,
        "CreatedAt": null,
        "UpdatedAt": null,
        "CreatedBy": null,
        "UpdatedBy": null
    },
    "PaymentTermsID": null,
    "PaymentTerms": null,
    "DeliveryTermsID": null,
    "DeliveryTerms": null,
    "WebUrl": null,
    "DimensionsID": null,
    "Dimensions": {
        "CustomValues": null,
        "Dimension6ID": null,
        "Dimension7ID": null,
        "Deleted": false,
        "Dimension9ID": null,
        "StatusCode": null,
        "ResponsibleID": null,
        "Dimension10ID": null,
        "ProjectID": 1,
        "DepartmentID": 2,
        "ID": 0,
        "UpdatedBy": null,
        "UpdatedAt": null,
        "Dimension5ID": null,
        "CreatedBy": null,
        "RegionID": null,
        "Dimension8ID": null,
        "CreatedAt": null,
        "ProjectTaskID": null,
        "Project": null,
        "Department": null,
        "ProjectTask": null,
        "Responsible": null,
        "Region": null,
        "Dimension5": null,
        "Dimension6": null,
        "Dimension7": null,
        "Dimension8": null,
        "Dimension9": null,
        "Dimension10": null,
        "Info": null,
        "_createguid": "40e9af2f-eb8b-4157-820a-e281b84ff149"
    },
    "GLN": null,
    "PeppolAddress": null,
    "EfakturaIdentifier": null,
    "EInvoiceAgreementReference": null,
    "CustomerInvoiceReminderSettingsID": null,
    "CustomerInvoiceReminderSettings": null,
    "DontSendReminders": false,
    "CustomerQuotes": [],
    "CustomerOrders": [],
    "CustomerInvoices": [],
    "CurrencyCodeID": null,
    "CurrencyCode": null,
    "AcceptableDelta4CustomerPaymentAccountID": null,
    "AcceptableDelta4CustomerPaymentAccount": null,
    "AcceptableDelta4CustomerPayment": 0,
    "SubAccountNumberSeriesID": 6,
    "SubAccountNumberSeries": null,
    "DefaultSellerID": 6,
    "DefaultSeller": {
        "CustomValues": {},
        "Deleted": false,
        "Name": "Anders",
        "StatusCode": null,
        "DefaultDimensionsID": null,
        "EmployeeID": 8,
        "TeamID": null,
        "ID": 6,
        "UpdatedBy": "638254e7-eb4b-4367-99c6-bd8a00ce7f40",
        "UpdatedAt": "2017-10-10T09:53:38.477Z",
        "CreatedBy": "57a77470-75c4-40a1-b462-8f1797dabe35",
        "UserID": 11,
        "CreatedAt": "2017-09-26T12:01:22.79Z"
    },
    "Sellers": [],
    "ReminderEmailAddress": "user@softrig.com",
    "Companies": [],
    "Account": null,
    "Localization": null,
    "DefaultCustomerInvoiceReportID": 4,
    "DefaultCustomerOrderReportID": 84,
    "DefaultCustomerQuoteReportID": 5,
    "FactoringNumber": null,
    "AvtaleGiro": false,
    "AvtaleGiroNotification": false,
    "StatusCode": null,
    "CustomValues": null,
    "ID": 0,
    "Deleted": false,
    "CreatedAt": null,
    "UpdatedAt": null,
    "CreatedBy": null,
    "UpdatedBy": null
}