Introduction

Welcome to the HazDash API! You can use our API to access HazDash API endpoints, which can manage your purchase orders.

We have language bindings in C#! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Epe HazDash server endpoints

API Development Server : https://api.hazdash.creativehiziggy.com
Development Identity Server : https://identity.hazdash.creativehiziggy.com

Authentication

For executing the API calls to our services, is required to have the following information : * Client Id * Client Secrete * Username * Password

Please contact HazDash team to retreive it.

To authorize, use this code:

using Newtonsoft.Json;

Console.WriteLine("Client to submit purchase orders!");
string url = "https://identity.hazdash.creativehiziggy.com/auth/realms/hazdash/protocol/openid-connect/token";
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Accept.Clear();
var parameters = new Dictionary<string, string>();
parameters.Add("client_id", "XXXXXXXXX");
parameters.Add("grant_type", "client_credentials");
parameters.Add("client_secret", "XXXXXXXXXX");
var req = new HttpRequestMessage(HttpMethod.Post, url) { Content = new FormUrlEncodedContent(parameters) };
var res = await client.SendAsync(req);
res.EnsureSuccessStatusCode();
var responseMEssage = await res.Content.ReadAsStringAsync();
var identityServerResponse = JsonConvert.DeserializeObject<IdentityResponse>(responseMEssage);
if(identityServerResponse != null)
{
    Console.WriteLine(identityServerResponse.access_token);
}


class IdentityResponse
{
    public string access_token { get; set; }
    public string refresh_token { get; set; }
}

Make sure to replace client_id,grant_type,client_secret,username, with your API key.

HazDash uses API keys to allow access to the API. HazDash expects for the API key to be included in all API requests to the server in a header that looks like the following: client_id: meowmeowmeow grant_type: meowmeowmeow client_secret: meowmeowmeow

You must replace meowmeowmeow with your personal API information that you have retreived from HazDash.

Ship Owners

For submiting purchase orders to the system is important to define the ship owner. Each batch of purchase orders can have only one ship owner.

Get Ship Owners

async Task<List<ShipOwner>>? GetShipOwners(string serverUrl, string token)
{
    string shipOwnerUrl = $"{serverUrl}/api/v1/shipowners";
    HttpClient clientShipOwners = new HttpClient();
    clientShipOwners.DefaultRequestHeaders.Accept.Clear();
    clientShipOwners.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    try
    {
        var res = await clientShipOwners.GetAsync(shipOwnerUrl);
        res.EnsureSuccessStatusCode();
        var responseMEssage = await res.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<List<ShipOwner>>(responseMEssage);
    }
    catch(Exception ex)
    {
        return null;
    }
}

class IdentityResponse
{
    public string access_token { get; set; }
    public string refresh_token { get; set; }
}

Function Parameters

Parameter	Description
serverUrl	HazDash Server URL
token	The access token from the identity server

The function parameter serverUrl is the url of HazDash server.

The above command returns JSON structured like this:

[
    {
        "id": 1,
        "name": "ShipOwner 1"
    },
    {
        "id": 2,
        "name": "ShipOnwer 2"
    }
]

Purchase Orders

The system accepts a batch of orders for a specific ship owner. Each batch should contain one or more purchase orders. HTTP METHOD : POST

Create Pruchase Orders

var poOrders = new PurchaseOrders();
for (int i = 0; i <= 10; i++)
{
    var item = new PurchaseOrder();
    item.poNumber = "B";
    item.productName = $"B product name {i}";
    item.productCode = $"B product code {i}";
    item.poDate = "10/01/2022";
    item.shipOwnerId = 1;
    item.vesselName = "Vessel A";
    item.quantity = 1;
    item.unit = "TEM";
    item.supplierRequestEmailAddress = "supplier@supplier.com";
    item.supplierRequestName = "supplier";
    poOrders.items.Add(item);
}

await CreatePurchaseOrders(identityServerResponse.access_token, poOrders);

async Task CreatePurchaseOrders(string token, PurchaseOrders orders, string serverUrl)
{
    string poRequestUrl = "https://{serverUrl}/api/v1/porequest";
    HttpClient clientPoRequest = new HttpClient();
    clientPoRequest.DefaultRequestHeaders.Accept.Clear();
    clientPoRequest.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    using (var content = new StringContent(JsonConvert.SerializeObject(orders), System.Text.Encoding.UTF8, "application/json"))
    {
        await clientPoRequest.PostAsync(poRequestUrl, content);
    }
}

class PurchaseOrders
{
    public PurchaseOrders()
    {
        this.items = new List<PurchaseOrder>();
    }
    public List<PurchaseOrder> items { get; set; }
}

class PurchaseOrder
{
    public string poNumber { get; set; }
    public string vesselName { get; set; }
    public string vesselImo { get; set; }
    public string equipmentManufacturer { get; set; }
    public string equipmentDescription { get; set; }
    public string productCode { get; set; }
    public string productName { get; set; }
    public string quantity { get; set; }
    public string poDate { get; set; }
    public string equipmentId { get; set; }
    public string productDescription { get; set; }
    public string general { get; set; }
    public string externalCategory { get; set; }
    public string supplierRequestName { get; set; }
    public string supplierRequestEmailAddress { get; set; }
    public int shipOwnerId { get; set; }

}

The example does not contain any error handling.

Purchase Order Body

Json Property	Description	Mandatory
poNumber	Purchase Ordre Number	YES
vesselName	The name of the vessel	YES if vessel imo is not defined
equipmentManufacturer	The equipment manufacturer of the purchase order item	NO
equipmentDescription	The equipment description of the purchase order item	NO
productCode	The product code of the purchase order item	NO
productName	The product name of the purchase order item	YES
quantity	The quantity (Delivery Unit) of the purchase order item	YES
poDate	The purchase order date of the order (format dd/MM/yyyy)	YES
equipmentId	The equipmentId of the purchase order item	NO
productDescription	The description of the purchase order item	NO
general	Generic text of the purchase order item	NO
externalCategory	3rd party system category	NO
supplierRequestName	Supplier company name	YES
supplierRequestEmailAddress	Supplier email address to manage the document request procedure	YES
shipOwnerId	HazDash Ship Owner Id	YES
quantity	The quantity of the purchase order item	YES
unit	The unit of the purchase order item	YES

The function parameter serverUrl is the url of HazDash server.

The above command returns JSON structured like this:

[
    {
        "poItemsRequest": [
            {
                "poNumber": "A",
                "vesselName": "Vessel A",
                "vesselImo": "",
                "equipmentManufacturer": "",
                "equipmentDescription": "",
                "productCode": "Product Code A",
                "productName": "Product Name A",
                "quantity": 1,
                "poDate": "12/05/20222",
                "equipmentId": "",
                "productDescription": "",
                "general": "",
                "externalCategory": "",
                "supplierRequestName": "supplier",
                "supplierRequestEmailAddress": "supplier@supplier.com",
                "shipOwnerId": 1
            },
            {
                "poNumber": "D",
                "vesselName": "Vessel A",
                "vesselImo": "",
                "equipmentManufacturer": "",
                "equipmentDescription": "",
                "productCode": "Product Code D",
                "productName": "Product Name D",
                "quantity": 1,
                "poDate": "12/05/20222",
                "equipmentId": "",
                "productDescription": "",
                "general": "",
                "externalCategory": "",
                "supplierRequestName": "supplier",
                "supplierRequestEmailAddress": "supplier@supplier.com",
                "shipOwnerId": 1
            }
        ],
        "shipOwnerId": 1,
    }
]

The response contains a list of items grouped by supplier request id. The system will generate for each supplier request id a separate batch. Each batch contains a list of all the purchase order items that are registered. The message contains a detailed information about the reason that the registration was not successfully done.

Get status of PO

Returns a list of my purchase orders, including status. HTTP METHOD : POST

var poOrders = new PurchaseOrders();
for (int i = 0; i <= 10; i++)
{
    var item = new PurchaseOrder();
    item.poNumber = "B";
    item.productName = $"B product name {i}";
    item.productCode = $"B product code {i}";
    item.poDate = "10/01/2022";
    item.shipOwnerId = 1;
    item.vesselName = "Vessel A";
    item.supplierRequestEmailAddress = "supplier@supplier.com";
    item.supplierRequestName = "supplier";
    item.quantity = 1;
    item.unit = "TEM";
    poOrders.items.Add(item);
}

await CreatePurchaseOrders(identityServerResponse.access_token, poOrders);

async Task<List<PurchaseOrder>> CreatePurchaseOrders(string token, PurchaseOrders orders, string serverUrl)
{
    string poRequestUrl = $"https://{serverUrl}/api/v1/porequest";
    HttpClient clientShipOwners = new HttpClient();
    clientShipOwners.DefaultRequestHeaders.Accept.Clear();
    clientShipOwners.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    try
    {
        var res = await clientShipOwners.GetAsync(poRequestUrl);
        res.EnsureSuccessStatusCode();
        var responseMEssage = await res.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<List<PurchaseOrder>>(responseMEssage);
    }
    catch(Exception ex)
    {
        return null;
    }
}


class PurchaseOrder
{
    public string poNumber { get; set; }
    public string vesselName { get; set; }
    public string vesselImo { get; set; }
    public string equipmentManufacturer { get; set; }
    public string equipmentDescription { get; set; }
    public string productCode { get; set; }
    public string productName { get; set; }
    public string quantity { get; set; }
    public string poDate { get; set; }
    public string equipmentId { get; set; }
    public string productDescription { get; set; }
    public string general { get; set; }
    public string externalCategory { get; set; }
    public string supplierRequestName { get; set; }
    public string supplierRequestEmailAddress { get; set; }
    public int shipOwnerId { get; set; }
    public string status { get; set; }
    public string statusId { get; set; }
}

The example does not contain any error handling.

The function parameter serverUrl is the url of HazDash server.

The above command returns JSON structured like this:

[
    {
        "poNumber": "A",
        "vesselName": "Vessel A",
        "vesselImo": "",
        "equipmentManufacturer": "",
        "equipmentDescription": "",
        "productCode": "Product Code A",
        "productName": "Product Code A",
        "quantity": 1,
        "poDate": "2022-09-04T14:32:15.000Z",
        "equipmentId": "",
        "productDescription": "",
        "general": "",
        "externalCategory": "",
        "supplierRequestName": "supplier",
        "supplierRequestEmailAddress": "supplier@supplier.com",
        "status": "Order is created",
        "statusId": 0
    }
]

Json Property	Description
poNumber	Purchase Ordre Number
vesselName	The name of the vessel
equipmentManufacturer	The equipment manufacturer of the purchase order item
equipmentDescription	The equipment description of the purchase order item
productCode	The product code of the purchase order item
productName	The product name of the purchase order item
quantity	The quantity (Delivery Unit) of the purchase order item
poDate	The purchase order date of the order (format dd/MM/yyyy)
equipmentId	The equipmentId of the purchase order item
productDescription	The description of the purchase order item
general	Generic text of the purchase order item
v	3rd party system category
supplierRequestName	Supplier company name
supplierRequestEmailAddress	Supplier email address to manage the document request procedure
status	The current status of the purchase order item
status	The status id

enum Status
{
  CREATED =0,
  INVITE_SUPPLIER =1,
  WAITING_FOR_SUPPLIER_SUBMISSION =2,
  SUBMIT_FOR_MAINTAINER_REVIEW =3,
  APPROVE_REQUEST =4,
  CLOSE_REQUEST =5,
  UNKNOWN =6,
}

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files...just save them to the includes folder and add them to the top of your index.md's frontmatter. Files are included in the order listed.

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.