API for creating NCDB Orders

Best way how this REST API can be used is to integrate it into a school information system, where the school stores all data about all its students. When implemented into a school information system, the school can create NCDB Orders for selected students much more quickly, without really „touching“ NCDB itself. The school information system communicates with NCDB using the request-response model. This brings advantages of saving both time and human capacities, which, in the end, will speed up and improve the business. Format of the data sent through the API The communication format of this API is JSON. Regarding the photos, they are expected as direct data with appropriate Content-Type header. API doesn’t support base64 encoded photos.

Any user of an NCDB Card Issuer (with „NCDB issuing“ mode activated) can be authorized for using this API. The following picture shows how the user in NCDB should be set up. For our use case, the user has username „lukas.test“ and some secret password.

Open

Open

Let’s have a look at following example: The school wants to integrate the API for NCDB Orders into its information system. Through the API, the school wants to create new card holders and order ISIC cards for them. The photos of the students should be uploaded as well. In the following sections, only this use case will be described in detail. For more possibilities, please have a look into full documentation.

Basic description of the workflow: Through the API, regarding the use case described in previous section, the following steps will be performed: 1/ Create empty Card Order 2/ Create Card Holders 3/ Add photos for Card Holders 4/ Order cards for chosen Card Holders (add order entries into the Card Order) 5/ Finish Card Order Following examples will be shown in software Insomnia for REST API’s testing. Within this software, you can simulate the requests and responses. For test purpose, any other REST client can be also used. In all cases, we are going to test the API against test environment of the ALIVE Platform (with URL https://ncdb.test.aliveplatform.com/rest/2.0).

POST /cardOrders As the first step, we have to set up new empty Card Order. The authorization is made using the test user we created earlier. Authorization method is always Basic Authorization.

Whole request for test environment should look like:

The information about Card Order needs to be put into the body of the request using json format. Within the response, ID number of the card order is returned. This ID is needed for nexts steps. POST /cardholders The second step is to create new cardholder. Through the API, each cardholder needs to be created per one request. In the response, the API will return ID of this cardholder which will also be needed in further steps.

There is of course much more information that can be added to the cardholder through the POST request. For example postal address, which is needed in case you want to order plastic card for the cardholder. Look into full documentation for all possibilities. PUT /cardholders/{cardholderId} Sometimes it can happen that you need to change some data for a cardholder which already exists within NCDB. This can be easily done using PUT /cardholders/{cardholderId} request. At the end of the request URL, ID of cardholder you need to change must be added. Into the request body, you can put only the information that need to be changed or edited, so you don’t need to send all information again. PUT /cardholders/{cardholderId}/photo As the next step, a photo needs to be uploaded and added to the cardholder created in previous step. Here, ID of cardholder needs to be used again. Using cardholderId, you define to which cardholder the uploaded photo should be assigned. Content-type of the photo needs to be „image/jpeg”.

The whole API request for test environment looks like this:

POST /cardOrders/{cardOrderId}/entries Now, we already have an empty NCDB order, we have a cardholder with all necessary information and with photo. In this step, let’s put it all together. In this request, we have to define the cardOrder (cardOrderId needs to be added into the URL of the request) into which we want to add the existing cardHolders. These cardHolders should be defined within the request body (see the picture).

Within this step, we have just ordered new virtual ISIC card with specified validity for Card Holder with ID 195844. PUT /cardOrders/{cardOrderId} As the last step, we just finish the order by putting it into “CREATED” status.

After done, the order will be visible also among other card orders in NCDB. It will be in “Draft” status and needs to be processed further by ER user manually.

Schema of the workflow Workflow of the whole process described above is also displayed in following schema. Please note IDs of cardHolder and cardOrder and be careful in which API requests they need to be used.