Punkty klienta (Child-Customer-Id)

Jeden login w AMPER często obsługuje kilka punktów klienta: oddziały, sklepy sieci albo profile z osobnymi cenami. Integracja, która przypisuje swoje sklepy do konkretnych punktów, pobiera listę punktów loginu i w każdym zapytaniu wskazuje punkt nagłówkiem Child-Customer-Id.

Punkty wybiera się tylko przy logowaniu integratora (token). Klucz API jest przypisany do jednego klienta i punktu nie wybiera.

Lista punktów

GET https://{amper_ws}/external/v1/customers/related/
Authorization: Bearer <access_token>

Odpowiedź 200 OK:

[
  {
    "id": 42,
    "name": "Hurtownia Kowalski sp. z o.o.",
    "short_name": "KOWALSKI",
    "tax_id": "1234567890",
    "address": "15-453 Białystok, Nowy Świat 9/4",
    "customer_external_id": "ERP-KLIENT-0042"
  },
  {
    "id": 57,
    "name": "Hurtownia Kowalski – oddział Łomża",
    "short_name": "KOWALSKI-LOM",
    "tax_id": "1234567890",
    "address": "18-400 Łomża, Polowa 12",
    "customer_external_id": null
  }
]

Pole	Opis
id	ID punktu (klienta) w AMPER – wartość nagłówka Child-Customer-Id i pola customer_id w create-order
name	pełna nazwa
short_name	nazwa skrócona
tax_id	NIP
address	adres domyślny w jednym tekście: kod pocztowy, miasto, ulica; pusty tekst, gdy punkt nie ma adresu domyślnego
customer_external_id	ID w systemie ERP – to samo, które przyjmuje pole customer_external_id w create-order; null, gdy klient nie pochodzi z ERP

Na liście są:

• klient, do którego należy login,
• klienci z nim powiązani w AMPER (np. oddziały) – ci sami, których sklep B2B pokazuje w wyborze kontrahenta.

Lista zawiera tylko aktywnych klientów i zawsze dotyczy zalogowanego loginu – nagłówek Child-Customer-Id nie ma na nią wpływu. Zwracana jest w całości, bez stronicowania. Konta integracji ERP (Translator) i administratorzy też dostają tylko swoją listę, nie listę wszystkich klientów. Z kluczem API lista jest pusta.

Punkty zmieniają się rzadko. Pobieraj listę przy konfiguracji integracji i np. raz dziennie, żeby zauważyć nowe i wyłączone punkty.

Wybór punktu w zapytaniu

Dodaj nagłówek Child-Customer-Id z id punktu do zapytań GET w /external/v1/. API zwraca wtedy dane tego punktu – jego ceny, asortyment, stany i promocje:

GET https://{amper_ws}/external/v1/products/
Authorization: Bearer <access_token>
Child-Customer-Id: 57

Bez nagłówka API zwraca dane klienta, do którego należy login.

Nagłówek przyjmuje tylko id z listy punktów. Klient spoza listy, punkt nieaktywny, nieistniejące id albo wartość, która nie jest liczbą, dają odpowiedź 403:

{ "detail": "You may not act for the customer named in the request headers (Child-Customer-Id)." }

API nie podmienia wtedy punktu na klienta loginu, więc integracja nie dostanie przez pomyłkę cen i stanów innego punktu. Po takim 403 pobierz listę punktów ponownie: punkt mógł zostać wyłączony albo odłączony od loginu. Z kluczem API nie wysyłaj nagłówka – zapytanie z nim też kończy się kodem 403.

Zamówienia

W POST /external/v1/create-order punkt wskazuje pole customer_id (albo customer_external_id) w treści żądania – nagłówek nie ma tam znaczenia. Użyj id albo customer_external_id z listy punktów. Szczegóły: Tworzenie zamówienia „create-order”.

Limit zapytań

Limit 3 jednoczesnych zapytań dotyczy loginu, nie punktu: zapytania do różnych punktów jednego loginu dzielą te same 3 miejsca. Synchronizuj punkty po kolei. Szczegóły: Stronicowanie, limity i kody odpowiedzi.

Przykład: synchronizacja wszystkich punktów

import requests

base_url = "https://{amper_ws}/external/v1"
auth = {"Authorization": f"Bearer {access_token}"}

points = requests.get(f"{base_url}/customers/related/", headers=auth, timeout=120).json()
for point in points:
    headers = {**auth, "Child-Customer-Id": str(point["id"])}
    offset = 0
    while True:
        response = requests.get(f"{base_url}/products/", headers=headers, timeout=120,
                                params={"limit": 500, "offset": offset, "ordering": "id"})
        response.raise_for_status()
        page = response.json()
        save_products(point["id"], page["results"])  # zapis w sklepie przypisanym do punktu
        if not page["next"]:
            break
        offset += 500

Logowanie, odświeżanie tokena i ponawianie po 429 pokazuje klient z artykułu Przykłady kodu.