GC.AUTH — dostęp jako aplikacja

Ten przewodnik opisuje dostęp aplikacji przez OAuth (przepływ client-credentials) i korzystanie z niego w ERP.API.

Przygotowanie

Przed podłączeniem się do API administrator poda Ci następujące wartości:

• URL serwera autoryzacyjnego
• URL serwera API
• resource_id
• scope
• client_id
• client_secret
• business identity

Autoryzacja

Każde zapytanie do ERP.API należy autoryzować za pomocą Bearer Authentication.

Specyfikacja żądania:

• Metoda HTTP: GET
• Adres: https://[URL serwera autoryzacyjnego]/oauth/token
• Format body: x-www-form-urlencoded
• Treść żądania:

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

Wartość zwracana:

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

Wartość expires_in to czas ważności tokena (w sekundach); po jego wygaśnięciu należy wygenerować nowy.

Przykładowa implementacja w .NET:

private static string getToken()
{
    HttpClient client = new HttpClient();
    HttpRequestMessage req = new HttpRequestMessage(HttpMethod.Get, "[URL serwera autoryzacyjnego]");
    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());
}

Zapytania do API

Pod URL serwera API dostępna jest również dokumentacja w formacie Swagger.

Specyfikacja żądań:

• Adres: [URL serwera API]
• Nagłówki (wspólne dla wszystkich zapytań):

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

Przykładowe zapytania

Cena i dostępność

• Metoda HTTP: GET
• Żądanie: /v1/articles/priceAndAvailability?currency=PLN&numbers=00028287&numbers=00028284
• Odpowiedź:

{
  "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 }
      ]
    }
  ]
}

Złożenie zamówienia

• Metoda HTTP: POST
• Żądanie: v1/orders
• Format body: JSON
• Wartości wymagane: currency, items
• Składnia:

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

• Odpowiedź:

{
  "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
}

Informacje o zamówieniu

• Metoda HTTP: GET
• Żądanie: /v1/orders?id=71297
• Odpowiedź:

{
  "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
      }
    }
  ]
}

Administracja dostępem do API

Aby udzielić nowemu użytkownikowi dostępu do API, administrator musi:

1. Zalogować się do serwisu autoryzacyjnego.
2. Wejść do działu Applications.
3. Utworzyć nową aplikację (wystarczy wypełnić pole Name).
4. Zaznaczyć opcję „Allow application to sign in".
5. Kliknąć „Choose contractors".
6. Przypisać tożsamości biznesowe (numery klienta w systemie ERP), do których konto ma mieć dostęp.
7. Zapisać zmiany.
8. W zakładce Permissions nadać uprawnienia do poszczególnych funkcji (np. GET_PRICES, INVOICES, ORDERS_HISTORY, CATALOG).

Pola client_id oraz client_secret można wyświetlić, klikając: