Sample application
Following section will walk through CRUD scenarios including authentication and configuration. PaymentCustomer API will be used as example.
Other parts of API are described in PaymentAPI.
Configuration
#TODO
Accessing payment customer API
All calls to Payment API need to be executed by calling methods on PaymentCustomerApi instance. Create one using new keyword.
var
customerAPI =
new
SecuConnectApi.PaymentCustomersApi();
Authentication
Each call to API server need to be authenticated with token issued by API server through authentication endpoint. Tokens expire after some time, and different parts of API require different credentials - different tokens.
Authentication workflow
General workflow to authenticate looks as follow:
decide which credentials are required
create required credentials by calling OAuth*Credentials::from
pass it to Authenticator
call Authenticator::getToken
save result to API instance you want to use
Authentication for payment customer API
Payment Customer API require client credentials: client id, client secret. To pass those to authentication endpoint, pack credentials into OAuthClientCredentials and pass it to Authenticator object.
authenticator =
new
SecuConnectApi.Authenticator(
SecuConnectApi.OAuthClientCredentials.from(
'...'
,
'...'
)
);
Method getToken() will return token that can be passed to PaymentCustomersApi instance.
customerAPI.apiClient.authentications.oauth_token.accessToken = authenticator.getToken();
CRUD example
Following section explains how to create, read, update and delete PaymentCustomer's.
Preflight checklist
Before making first API call make sure that:
Correct host is set in Configuration
Authentication succeeded and token is saved to Configuration
Instance of desired part of API is accessible
Data models
Model vs DTO
API uses two kinds of structures for each represented entity. Model and DTO. Model provides full informations about entity, whereas DTO is stripped down data structure that contains only necessary information to perform create and update. In each operation documentation specify which one is expected as input/output.
PaymentCustomersProductModel |
|||
Represents all customer data |
|||
property |
description |
type |
possible values |
object |
The name of the smart object |
string |
payment.customers |
id |
id of payment container |
string |
(3 letters)_(30 alphanumeric signs) |
contract |
payment customer contract |
object (ProductInstanceUID) |
|
contact |
customer contact |
object (PaymentCustomersDTOContact) |
|
created |
PaymentCustomersProductModel creation date |
string |
2018-02-13T11:52:13+01:00 |
updated |
PaymentCustomersProductModel update date |
string |
2018-02-13T11:58:30+01:00 |
PaymentCustomersDTO |
|||
Represents data needed to create or update customer |
|||
property |
description |
type |
possible values |
contact |
customer contact |
|
PaymentCustomerDTOContact |
|||
Contact information for customer |
|||
property |
description |
type |
possible values |
forename |
customer forename |
string |
John |
surname |
customer surname |
string |
Doe |
companyname |
customer company name |
string |
Example Inc. |
salutation |
customer salutation |
string |
"Herr", "Frau" or any other appropriate |
gender |
customer gender |
string |
#TODO |
title |
customer academic title |
string |
"Dr." or any other appropriate |
|
customer email |
string |
|
phone |
customer phone number |
string |
0049-123-456789 |
mobile |
customer mobile number |
string |
0049-987-654321 |
dob |
customer date of birth |
string |
1901-02-03 |
picture |
Document id of an picture |
string |
|
url_website |
Uniform Resource Locator to customer webstite |
string |
|
birthplace |
customer birthplace |
string |
Dresden |
nationality |
customer nationality |
string |
DE |
address |
customer address |
object (Address) |
- |
Create a new customer
To create new Customer PaymentCustomersDTO need to be passed to paymentCustomersPost method from PaymentCustomersApi class.
With PaymentCustomersDTO prepared we can pass it to paymentCustomersPost.
var
customerDTO =
new
SecuConnectApi.PaymentCustomersDTO();
var
contact =
new
SecuConnectApi.PaymentCustomersDTOContact();
var
address =
new
SecuConnectApi.Address();
customerDTO.contact = contact;
contact.surname =
"John R."
;
contact.forename =
"Hacker"
;
contact.address = address;
address.country =
"PL"
;
address.city =
"Wroclaw"
;
address.street =
"Kurkowa"
;
address.postal_code =
"50-000"
;
address.street_number =
"14"
;
result = customerAPI.paymentCustomersPost(customerDTO);
result.then(
function
(data) {
customer = data;
},
function
(error) {
console.error(error);
});
Result is javascript Promise.
If call succeed result will resolve to PaymentCustomerProductModel.
If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:
ProductFormatException
ProductNotAllowedException
Update an existing customer
To update customer it's ID is required and PaymentCustomersDTO must be updated with new values of properties.
Let's reuse $customer object from previous section, and assume that $customerId contains customer ID, then we can update it by following code:
var
customerDTO =
new
SecuConnectApi.PaymentCustomersDTO();
var
contact =
new
SecuConnectApi.PaymentCustomersDTOContact();
var
address =
new
SecuConnectApi.Address();
customerDTO.contact = contact;
contact.surname =
"John Random"
;
contact.forename =
"Hacker"
;
contact.address = address;
address.country =
"PL"
;
address.city =
"Wroclaw"
;
address.street =
"Kurkowa"
;
address.postal_code =
"50-000"
;
address.street_number =
"14"
;
result = customerAPI.paymentCustomersIdPut(customer.id, customerDTO);
result.then(
function
(data) {
customer = data;
},
function
(error) {
console.error(error);
});
Result is javascript Promise.
If call succeed result will resolve to PaymentCustomerProductModel.
If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:
ProductFormatException
ProductNotAllowedException
Search for an existing Customer
Search for specific customer vs search for all customers
SDK exposes two methods responsible for search. One will get all models in a list, other will return single model (if it exists). In each case same data in each model are returned.
Choose whatever suite your needs more.
Existing customers can be search by id, PaymentCustomersAPI paymentCustomersGetById should be used for it:
result = customerAPI.paymentCustomersGetById(customer.id);
result.then(
function
(data) {
},
function
(error) {
console.error(error);
});
Result is javascript Promise.
If call succeed result will resolve to PaymentCustomerProductModel.
Obtain list of Customers
Existing customers can be listed using PyamentCustomersAPI paymentCustomersGet method.
result = customerAPI.paymentCustomersGet();
result.then(
function
(data) {
},
function
(error) {
console.error(error);
});
Result is javascript Promise.
If call succeed result will resolve to object containing count and data which will be a list of PaymentCustomerProductModel.
If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:
ProductFormatException
ProductNotAllowedException
Delete an existing customer
To delete customer, it's ID is required and should be passed to paymentCustomersIdDelete method from PaymentCustomersApi class.
result = customerAPI.paymentCustomersIdDelete(customer.id)
result.then(
function
(data) {
},
function
(error) {
console.error(error);
});
Result is javascript Promise.
If call succeed result will resolve to PaymentCustomerProductModel.
If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:
ProductNotAllowedException