GC.AUTH — application access

This guide covers OAuth application access (the client-credentials flow) and using it with ERP.API.

Preparing to connect

Before making a connection to the API, the administrator will give you these parameters:

• URL of the authorization server
• URL of the API server
• resource_id
• scope
• client_id
• client_secret
• business identity

Authorization

You have to authorize every query to ERP.API with Bearer authentication.

Query specification:

• HTTP method: GET
• Address: https://[Authorization service URL]/oauth/token
• Body format: x-www-form-urlencoded
• Request body:

resource_id:   [resource_id]
grant_type:    client_credentials
client_id:     [client_id]
client_secret: [client_secret]

Response:

{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0
}

The expires_in value is the token validity time (in seconds); after it expires, you have to generate a new one.

Example of an implementation in .NET:

private static string getToken()
{
    HttpClient client = new HttpClient();
    HttpRequestMessage req = new HttpRequestMessage(HttpMethod.Get, "[authorization service URL]");
    req.Headers.Add("User-Agent", "Program");
    req.Content = new FormUrlEncodedContent(new Dictionary<string, string>
    {
        { "resource_id", "[resource_id]" },
        { "grant_type", "client_credentials" },
        { "client_id", "[client_id key]" },
        { "client_secret", "[client_secret key]" }
    });
    var resp = client.Send(req);
    string jsonString = @"[" + resp.Content.ReadAsStringAsync().Result + "]";
    JsonElement json = JsonDocument.Parse(jsonString).RootElement;
    var token = json[0];
    return (token.GetProperty("access_token").GetString());
}

Querying the API

Swagger documentation is available at the server address.

Query specification:

• Address: [URL of API server]
• Headers (the same in every query):

scope:             [scope]
authorization:     Bearer [access token]
business identity: [business identity]

Query examples

Price and availability

• HTTP method: GET
• Query: /v1/articles/priceAndAvailability?currency=PLN&numbers=00028287&numbers=00028284
• Response:

{
  "articles": [
    {
      "number": "03973527",
      "salesPrice": {
        "netValue": 10,
        "taxRate": 0.23,
        "taxValue": 2.3,
        "grossValue": 12.3
      },
      "retailPrice": {
        "netValue": 20,
        "taxRate": 0.23,
        "taxValue": 4.6,
        "grossValue": 24.6
      },
      "availabilities": [
        { "name": "MAG_A", "quantity": 13 },
        { "name": "MAG_B", "quantity": 17 }
      ]
    }
  ]
}

Making an order

• HTTP method: POST
• Query: v1/orders
• Body format: JSON
• Required values: currency, items
• Request body:

{
  "currency": "string",
  "items": [
    {
      "number": "string",
      "quantity": 0
    }
  ],
  "comment": "string",
  "paymentTypeId": "string",
  "documentTypeId": "string",
  "transportTypeId": "string",
  "cashNote": true,
  "branch": "string",
  "recipientOrderNo": "string"
}

• Response:

{
  "id": "71297",
  "number": "71297",
  "items": [
    {
      "number": "00028287",
      "quantity": 2,
      "singleItemPrice": {
        "netValue": 55.60,
        "taxRate": 0.23,
        "taxValue": 12.79,
        "grossValue": 68.39
      },
      "totalValuePrice": {
        "netValue": 111.20,
        "taxRate": 0.23,
        "taxValue": 25.58,
        "grossValue": 136.78
      },
      "miscMessages": []
    }
  ],
  "paymentTypeId": "1",
  "paymentTypeName": "Gotówka",
  "documentTypeId": "0",
  "documentTypeName": null,
  "transportTypeId": "1",
  "transportTypeName": "Odbiór własny",
  "cashNote": false,
  "branch": null
}

Order information

• HTTP method: GET
• Query: /v1/orders?id=71297
• Response:

{
  "headers": [
    {
      "id": "71297",
      "number": "72/2022",
      "currency": "PLN",
      "branch": null,
      "cashNote": false,
      "documentTypeId": null,
      "documentTypeName": null,
      "paymentTypeId": "1",
      "paymentTypeName": "Gotówka",
      "transportTypeId": "1",
      "transportTypeName": "Odbiór własny",
      "statusId": "2",
      "statusName": "Zatwier. ",
      "invoiceNumber": null,
      "dateOfCreation": "2022-07-05T00:00:00+02:00",
      "dateOfConfirmation": "2022-07-05T14:48:48.7+02:00",
      "dateOfRealization": null,
      "dateOfPayment": "2022-09-03T00:00:00+02:00",
      "goodsIssueNoteNo": null,
      "placeOfRealization": null,
      "internet": true,
      "itemsQuanity": 1,
      "deliveryPoint": null,
      "customerDocumentNumber": null,
      "comment": "komentarz",
      "price": {
        "netValue": 111.20,
        "taxValue": 25.58,
        "grossValue": 136.78
      },
      "route": null,
      "payer": {
        "code": "",
        "name": null,
        "taxId": null,
        "address": null,
        "bankAccount": null
      },
      "receiver": {
        "code": "",
        "name": null,
        "taxId": null,
        "address": null,
        "bankAccount": null
      }
    }
  ]
}

Administration of access to the API

To grant a new user access to the API:

1. Log in to the authorization service.
2. Enter Applications.
3. Create a new application (only the Name value is required).
4. Tick "Allow application to sign in".
5. Click "Choose contractors".
6. Assign the business identities (customer numbers in the ERP system) the account should have access to.
7. Save changes.
8. In the Permissions tab, grant permissions to functions (e.g. GET_PRICES, INVOICES, ORDERS_HISTORY, CATALOG).

You can reveal the client_id and client_secret fields by clicking: