help-connection-to-api

GC.AUTH - oAuth - dostęp jako aplikacja i korzystanie z 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 serwisu autoryzacyjnego]/oauth/token
Body:
Format: x-www-form-urlencoded
Treść:
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
}

(Długość ważności tokena znajduje się w polu expires_in (podane w sekundach), po jego wygaśnięciu należy wygenerować nowy)

Przykładowa implementacja w środowisku .NET:

    private static string getToken()
    {
        HttpClient client = new HttpClient();
        HttpRequestMessage req = new HttpRequestMessage(HttpMethod.Get, "[url serwisu autoryzacyjnego]");
        req.Headers.Add("User-Agent", "Program");
        req.Content = new FormUrlEncodedContent(new Dictionary
        {
            { "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:

Pobranie ceny i stanu:
Metoda HTTP: GET
Żądanie: /v1/articles/priceAndAvailability?currency=PLN&numbers=00028287&numbers=00028284
Wartość zwracana:

{
  "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
Body:
Format: 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"
}

Wartość zwracana:

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

Pobranie informacji o zamówieniu:
Metoda HTTP: GET
Żądanie: /v1/orders?id=71297
Wartość zwracana:

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

zalogować się do serwisu autoryzacyjnego
wejść do działu Applications
utworzyć nową aplikację (wystarczy wypełnić pole "Name")
zaznaczyć opcję "Allow application to sign in"
kliknąć na "Choose contractors"
przypisać tożsamości biznesowe (numery klienta w systemie ERP) do których konto ma mieć dostęp
zapisać zmiany
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:


		cena rdzeń