Dla deweloperów

API SilkCRM

Połącz sklep internetowy salonu (Shopify, WooCommerce albo własny) z SilkCRM: pokaż w sklepie ofertę salonu, wydawaj vouchery i karnety sprzedane online, a o zdarzeniach w salonie dowiaduj się z webhooków.

Adres bazowy: https://app.silkcrm.net/api/rest/v1
Uwierzytelnianie: Authorization: Bearer silk_live_…
Format: JSON, kwoty w groszach, czasy w ISO 8601
Wersja: v1 · 1.0.0 · OpenAPI 3.1 (JSON)

Szybki start

Pierwsze zapytanie w pięć minut

REST API SilkCRM dla sklepów internetowych salonów: odczyt oferty salonu oraz wydawanie voucherów kwotowych i karnetów sprzedanych w sklepie.

Sprawdź plan salonu. Dostęp przez API mają plany Pro i wyższe. Inny plan dostaje 403 feature_not_available_on_plan.
Wygeneruj klucz API. W aplikacji wejdź w Ustawienia → Zaawansowane → Klucze API. W karcie „Nowy klucz” wpisz nazwę (np. „Sklep Shopify”), w „Poziom uprawnień” zostaw „Tylko odczyt”, w „Dodatkowe uprawnienia” zaznacz „Sklep internetowy (vouchery i karnety ze sklepu)” i kliknij „Utwórz klucz”. Taki klucz ma zakresy read:* i write:commerce. Pełny klucz zobaczysz tylko raz.
Trzymaj klucz po stronie serwera. Zapisz go w zmiennej środowiskowej SILK_API_KEY serwera sklepu. Nigdy nie wstawiaj go do kodu wykonywanego w przeglądarce klientki: kto zna klucz, wydaje vouchery w imieniu salonu.
Wyślij pierwsze zapytanie i sprawdź, które salony widzi klucz:

Salony konta

curl "https://app.silkcrm.net/api/rest/v1/locations" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "data": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000001",
      "name": "Salon Alicja - Centrum",
      "address": "ul. Marszałkowska 10",
      "city": "Warszawa",
      "phone": "+48221234567",
      "timezone": "Europe/Warsaw",
      "accepts_online_bookings": true
    },
    {
      "id": "8f1c0000-0000-4000-8000-000000000002",
      "name": "Salon Alicja - Mokotów",
      "address": "ul. Puławska 120",
      "city": "Warszawa",
      "phone": "+48221234567",
      "timezone": "Europe/Warsaw",
      "accepts_online_bookings": false
    }
  ],
  "next_cursor": null
}

Uwierzytelnianie

Każde zapytanie niesie klucz API salonu w nagłówku Authorization: Bearer silk_live_…. Inne sposoby logowania (np. OAuth) dostają 403 api_key_required. Odczyty wymagają zakresu read:*, zapisy - zakresu write:commerce (nie wynika z write:all). Plan salonu musi obejmować dostęp przez API (inaczej 403 feature_not_available_on_plan).

Dokument OpenAPI 3.1 pobierzesz bez klucza: https://app.silkcrm.net/api/rest/v1/openapi.json. Zaimportuj go do Postmana, Insomnii albo generatora klienta.

Przypadki użycia

Typowe scenariusze sklepu

Każdy przykład pochodzi z prawdziwego przebiegu na koncie testowym. Wybór języka (curl, JavaScript, PHP dla WordPressa i WooCommerce) obowiązuje na całej stronie.

Voucher kupiony w sklepie

Klientka płaci w sklepie za voucher kwotowy. Sklep po opłaceniu zamówienia zakłada (albo odnajduje) jej kartę w Silku i wydaje voucher. Silk nic klientce nie wysyła, wiadomość z kodem zostaje po stronie sklepu.

Znajdź albo załóż kartę klientki po telefonie lub e-mailu z zamówienia. Zgody marketingowe przekazujesz tylko wtedy, gdy klientka je w sklepie zaznaczyła. POST /clients/resolve

Nowa klientka z telefonem, e-mailem i zgodą SMS

curl -X POST "https://app.silkcrm.net/api/rest/v1/clients/resolve" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-client' \
  -d '{
  "external_order_id": "#1043",
  "shop": "shopify",
  "client": {
    "phone": "500 100 200",
    "email": "anna.nowak@example.com",
    "first_name": "Anna",
    "last_name": "Nowak",
    "consents": {
      "sms": {
        "granted": true,
        "granted_at": "2026-11-03T10:00:00.000Z"
      }
    }
  }
}'

OdpowiedźJSON

HTTP 200

{
  "dry_run": false,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "created": true
}

Wydaj voucher na zwrócone client_id. amount_cents to wartość vouchera, paid_cents to kwota zapłacona w sklepie (mniejsza przy rabacie). POST /vouchers

Voucher 200 zł sprzedany z rabatem za 180 zł

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-voucher' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "1",
  "shop": "shopify",
  "amount_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "gift_message": "Wszystkiego najlepszego!"
}'

OdpowiedźJSON

HTTP 201

{
  "id": "8f1c0000-0000-4000-8000-000000000008",
  "status": "active",
  "amount_cents": 20000,
  "balance_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

Przy zwrocie zamówienia unieważnij voucher. Działa wyłącznie dla vouchera utworzonego przez API dla tego samego zamówienia i tylko, dopóki nie został użyty. POST /vouchers/{id}/void

Zwrot vouchera w sklepie

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers/8f1c0000-0000-4000-8000-000000000008/void" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-refund-voucher' \
  -d '{
  "external_order_id": "#1043",
  "shop": "shopify",
  "reason": "Klientka zwróciła zamówienie"
}'

OdpowiedźJSON

HTTP 200

{
  "id": "8f1c0000-0000-4000-8000-000000000008",
  "status": "void",
  "amount_cents": 20000,
  "balance_cents": 0,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

Karnet kupiony w sklepie

Sklep sprzedaje karnet z szablonu, który salon oznaczył jako sprzedawany poza kasą. Szablony promocyjne nie są sprzedawane przez API.

Pobierz szablony karnetów i pokaż w sklepie te, które można sprzedać. GET /pass-templates

Szablony karnetów

curl "https://app.silkcrm.net/api/rest/v1/pass-templates" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "data": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000006",
      "name": "Karnet 5 manicure",
      "description": "Pięć wizyt manicure hybrydowego.",
      "uses_total": 5,
      "price_cents": 50000,
      "validity_days": 365,
      "service_ids": [
        "8f1c0000-0000-4000-8000-000000000003"
      ],
      "sellable": true
    }
  ],
  "next_cursor": null
}

Po opłaceniu zamówienia wydaj karnet z szablonu na kartę klientki. POST /passes

Karnet z szablonu sprzedawanego poza kasą, z rabatem

curl -X POST "https://app.silkcrm.net/api/rest/v1/passes" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-pass' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "3",
  "shop": "shopify",
  "template_id": "8f1c0000-0000-4000-8000-000000000006",
  "paid_cents": 45000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007"
}'

OdpowiedźJSON

HTTP 201

{
  "id": "8f1c0000-0000-4000-8000-000000000009",
  "status": "active",
  "template_id": "8f1c0000-0000-4000-8000-000000000006",
  "name": "Karnet 5 manicure",
  "uses_total": 5,
  "uses_left": 5,
  "paid_cents": 45000,
  "unit_value_cents": 9000,
  "service_ids": [
    "8f1c0000-0000-4000-8000-000000000003"
  ],
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "expires_at": "2027-11-03T10:15:00.000Z",
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

Ponowione powiadomienie sklepu

Shopify i WooCommerce potrafią wysłać to samo powiadomienie o zamówieniu kilka razy. Wysyłaj każdy zapis z Idempotency-Key zbudowanym z numeru zamówienia i pozycji: ponowienie dostaje tę samą odpowiedź z nagłówkiem Idempotent-Replay: true, a drugi voucher nie powstaje.

To samo żądanie wysłane drugi raz z tym samym kluczem idempotencji:

Ponowienie z tym samym Idempotency-Key - ta sama odpowiedź, bez drugiego vouchera

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-voucher' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "1",
  "shop": "shopify",
  "amount_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "gift_message": "Wszystkiego najlepszego!"
}'

OdpowiedźJSON

HTTP 201
Idempotent-Replay: true

{
  "id": "8f1c0000-0000-4000-8000-000000000008",
  "status": "active",
  "amount_cents": 20000,
  "balance_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

Testy bez skutków (dry-run)

Nagłówek Silk-Dry-Run: 1 wykonuje zapis w całości, łącznie z walidacją i regułami salonu, po czym go wycofuje. Tak sprawdzisz integrację na prawdziwym koncie, zanim sklep zacznie wydawać vouchery naprawdę.

Próba wydania vouchera: odpowiedź ma dry_run: true i id: null.

Próba (Silk-Dry-Run: 1) - nic nie zostaje zapisane, id = null

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-voucher' \
  -H 'Silk-Dry-Run: 1' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "1",
  "shop": "shopify",
  "amount_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "gift_message": "Wszystkiego najlepszego!"
}'

OdpowiedźJSON

HTTP 201
Silk-Dry-Run: 1

{
  "id": null,
  "status": "active",
  "amount_cents": 20000,
  "balance_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": null,
  "dry_run": true
}

Reguły salonu obowiązują także w próbie: kwota poza zakresem daje ten sam 422 z nagłówkiem Silk-Dry-Run: 1 i bez niego. Poniżej ten błąd na zwykłym zapisie:

Kwota poza zakresem ustawionym przez salon

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-voucher-2' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "2",
  "shop": "shopify",
  "amount_cents": 100000,
  "paid_cents": 100000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "gift_message": "Wszystkiego najlepszego!"
}'

OdpowiedźJSON

HTTP 422

{
  "error": {
    "code": "voucher_amount_out_of_range",
    "message": "Kwota vouchera jest poza zakresem ustawionym przez salon.",
    "details": {
      "min_cents": 5000,
      "max_cents": 50000
    },
    "request_id": "req-8f1c0001"
  }
}

Sprawdzenie stanu zamówienia

Jedno zapytanie zwraca wszystko, co Silk utworzył dla zamówienia sklepu: vouchery i karnety z ich bieżącym stanem. Przydaje się do uzgodnień i do panelu obsługi sklepu. Znak # w numerze zamówienia koduj jako %23.

Stan zamówienia #1043: GET /orders/{external_order_id}

Wszystko, co Silk utworzył dla zamówienia #1043 (# zakodowany jako %23)

curl "https://app.silkcrm.net/api/rest/v1/orders/%231043" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "external_order_id": "#1043",
  "shop": "shopify",
  "vouchers": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000008",
      "status": "active",
      "amount_cents": 20000,
      "balance_cents": 20000,
      "paid_cents": 18000,
      "client_id": "8f1c0000-0000-4000-8000-000000000007",
      "recipient_phone": null,
      "purchaser_client_id": null,
      "gift_message": "Wszystkiego najlepszego!",
      "expires_at": null,
      "external_order_id": "#1043",
      "created_at": "2026-11-03T10:15:00.000Z"
    }
  ],
  "passes": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000009",
      "status": "active",
      "template_id": "8f1c0000-0000-4000-8000-000000000006",
      "name": "Karnet 5 manicure",
      "uses_total": 5,
      "uses_left": 5,
      "paid_cents": 45000,
      "unit_value_cents": 9000,
      "service_ids": [
        "8f1c0000-0000-4000-8000-000000000003"
      ],
      "client_id": "8f1c0000-0000-4000-8000-000000000007",
      "expires_at": "2027-11-03T10:15:00.000Z",
      "external_order_id": "#1043",
      "created_at": "2026-11-03T10:15:00.000Z"
    }
  ]
}

Wizyta z zadatkiem opłaconym w sklepieWkrótce - od 11 listopada 2026

Rezerwacja wizyty z zadatkiem pobranym przez sklep. Zakres i szczegóły opublikujemy razem z udostępnieniem funkcji.

Referencja

Referencja REST API v1

Wszystkie operacje z dokumentu OpenAPI, w kolejności: Katalog, Klientki, Vouchery, Karnety, Zamówienia. Adres każdej operacji to https://app.silkcrm.net/api/rest/v1 + ścieżka.

Katalog

Oferta salonu do pokazania w sklepie: salony, usługi, specjalistki, szablony karnetów.

GET/locations

Lista salonów

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: listLocations

Salony (lokalizacje) konta, posortowane po identyfikatorze. accepts_online_bookings mówi, czy salon przyjmuje rezerwacje online; katalog usług i specjalistek odpowiada także dla salonu, który ich nie przyjmuje.

Parametry

Parametry
Parametr	Gdzie	Opis
`limit`	zapytanie	Liczba elementów na stronie (1-100, domyślnie 50).
`cursor`	zapytanie	Kursor następnej strony z pola `next_cursor` poprzedniej odpowiedzi. Nieprzezroczysty; zły kursor = 400 `invalid_cursor`.

Odpowiedź 200 · LocationList

Strona listy salonów.

Pola odpowiedzi Lista salonów
Pole	Typ	Uwagi
`data`wymagane	`array<Location>`
`data[].id`wymagane	`string`
`data[].name`wymagane	`string`
`data[].address`wymagane	`string \| null`
`data[].city`wymagane	`string \| null`
`data[].phone`wymagane	`string \| null`
`data[].timezone`wymagane	`string`
`data[].accepts_online_bookings`wymagane	`boolean`
`next_cursor`wymagane	`string \| null`

Kody odpowiedzi

200Lista salonów
400Niepoprawne zapytanie.invalid_request invalid_cursor
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /locations

curl "https://app.silkcrm.net/api/rest/v1/locations" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "data": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000001",
      "name": "Salon Alicja - Centrum",
      "address": "ul. Marszałkowska 10",
      "city": "Warszawa",
      "phone": "+48221234567",
      "timezone": "Europe/Warsaw",
      "accepts_online_bookings": true
    },
    {
      "id": "8f1c0000-0000-4000-8000-000000000002",
      "name": "Salon Alicja - Mokotów",
      "address": "ul. Puławska 120",
      "city": "Warszawa",
      "phone": "+48221234567",
      "timezone": "Europe/Warsaw",
      "accepts_online_bookings": false
    }
  ],
  "next_cursor": null
}

GET/locations/{location_id}/services

Usługi salonu

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: listServices

Usługi widoczne online (bez archiwalnych i ukrytych, dostępnych tylko z linku). Odpowiada także dla salonu, który nie przyjmuje rezerwacji online (patrz accepts_online_bookings w GET /locations). Ceny w groszach; price_mode mówi, które pola ceny są wypełnione.

Parametry

Parametry
Parametr	Gdzie	Opis
`location_id`wymagany	ścieżka	Identyfikator salonu z `GET /locations`. Obcy i nieistniejący salon = ten sam 404.
`limit`	zapytanie	Liczba elementów na stronie (1-100, domyślnie 50).
`cursor`	zapytanie	Kursor następnej strony z pola `next_cursor` poprzedniej odpowiedzi. Nieprzezroczysty; zły kursor = 400 `invalid_cursor`.

Odpowiedź 200 · ServiceList

Strona listy usług.

Pola odpowiedzi Usługi salonu
Pole	Typ	Uwagi
`data`wymagane	`array<Service>`
`data[].id`wymagane	`string`
`data[].name`wymagane	`string`
`data[].category`wymagane	`string \| null`
`data[].duration_minutes`wymagane	`integer`	≥ 0
`data[].price_mode`wymagane	`string`	jedno z: fixed, range, per_hour, from
`data[].price_cents`wymagane	`object`
`data[].price_min_cents`wymagane	`object`
`data[].price_max_cents`wymagane	`object`
`data[].variants`wymagane	`array<ServiceVariant>`
`data[].variants[].key`wymagane	`string`
`data[].variants[].name`wymagane	`string`
`data[].variants[].price_cents`wymagane	`integer`	≥ 0
`data[].variants[].duration_minutes`wymagane	`integer`	≥ 0
`data[].requires_specialist`wymagane	`boolean`
`next_cursor`wymagane	`string \| null`

Kody odpowiedzi

200Usługi salonu
400Niepoprawne zapytanie.invalid_request invalid_cursor
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /locations/{location_id}/services

curl "https://app.silkcrm.net/api/rest/v1/locations/8f1c0000-0000-4000-8000-000000000001/services" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "data": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000003",
      "name": "Manicure hybrydowy",
      "category": "Paznokcie",
      "duration_minutes": 60,
      "price_mode": "fixed",
      "price_cents": 12000,
      "price_min_cents": null,
      "price_max_cents": null,
      "variants": [],
      "requires_specialist": true
    },
    {
      "id": "8f1c0000-0000-4000-8000-000000000004",
      "name": "Strzyżenie damskie",
      "category": "Fryzjerstwo",
      "duration_minutes": 45,
      "price_mode": "range",
      "price_cents": null,
      "price_min_cents": 10000,
      "price_max_cents": 16000,
      "variants": [
        {
          "key": "krotkie",
          "name": "Krótkie",
          "price_cents": 10000,
          "duration_minutes": 45
        },
        {
          "key": "dlugie",
          "name": "Długie",
          "price_cents": 16000,
          "duration_minutes": 45
        }
      ],
      "requires_specialist": true
    }
  ],
  "next_cursor": null
}

GET/locations/{location_id}/specialists

Specjalistki salonu

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: listSpecialists

Osoby przyjmujące klientki w salonie. service_ids wskazuje wyłącznie usługi z GET /locations/{location_id}/services (widoczne online). Odpowiada także dla salonu bez rezerwacji online.

Parametry

Parametry
Parametr	Gdzie	Opis
`location_id`wymagany	ścieżka	Identyfikator salonu z `GET /locations`. Obcy i nieistniejący salon = ten sam 404.
`limit`	zapytanie	Liczba elementów na stronie (1-100, domyślnie 50).
`cursor`	zapytanie	Kursor następnej strony z pola `next_cursor` poprzedniej odpowiedzi. Nieprzezroczysty; zły kursor = 400 `invalid_cursor`.

Odpowiedź 200 · SpecialistList

Strona listy specjalistek.

Pola odpowiedzi Specjalistki salonu
Pole	Typ	Uwagi
`data`wymagane	`array<Specialist>`
`data[].id`wymagane	`string`
`data[].display_name`wymagane	`string`
`data[].service_ids`wymagane	`array<string>`
`next_cursor`wymagane	`string \| null`

Kody odpowiedzi

200Specjalistki salonu
400Niepoprawne zapytanie.invalid_request invalid_cursor
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /locations/{location_id}/specialists

curl "https://app.silkcrm.net/api/rest/v1/locations/8f1c0000-0000-4000-8000-000000000001/specialists" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "data": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000005",
      "display_name": "Kasia",
      "service_ids": [
        "8f1c0000-0000-4000-8000-000000000003",
        "8f1c0000-0000-4000-8000-000000000004"
      ]
    }
  ],
  "next_cursor": null
}

GET/pass-templates

Szablony karnetów

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: listPassTemplates

Aktywne szablony karnetów ze stałą ceną. Sklep może sprzedać wyłącznie szablon z sellable: true (salon sprzedaje go poza kasą). Szablony promocyjne („N-ty zabieg za X zł”) nie mają stałej ceny i nie pojawiają się na liście.

Parametry

Parametry
Parametr	Gdzie	Opis
`limit`	zapytanie	Liczba elementów na stronie (1-100, domyślnie 50).
`cursor`	zapytanie	Kursor następnej strony z pola `next_cursor` poprzedniej odpowiedzi. Nieprzezroczysty; zły kursor = 400 `invalid_cursor`.

Odpowiedź 200 · PassTemplateList

Strona listy szablonów karnetów.

Pola odpowiedzi Szablony karnetów
Pole	Typ	Uwagi
`data`wymagane	`array<PassTemplate>`
`data[].id`wymagane	`string`
`data[].name`wymagane	`string`
`data[].description`wymagane	`string \| null`
`data[].uses_total`wymagane	`integer`	≥ 1
`data[].price_cents`wymagane	`integer`	≥ 0
`data[].validity_days`wymagane	`object`
`data[].service_ids`wymagane	`array<string>`
`data[].sellable`wymagane	`boolean`
`next_cursor`wymagane	`string \| null`

Kody odpowiedzi

200Szablony karnetów
400Niepoprawne zapytanie.invalid_request invalid_cursor
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /pass-templates

curl "https://app.silkcrm.net/api/rest/v1/pass-templates" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "data": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000006",
      "name": "Karnet 5 manicure",
      "description": "Pięć wizyt manicure hybrydowego.",
      "uses_total": 5,
      "price_cents": 50000,
      "validity_days": 365,
      "service_ids": [
        "8f1c0000-0000-4000-8000-000000000003"
      ],
      "sellable": true
    }
  ],
  "next_cursor": null
}

Klientki

Karta klientki salonu po telefonie lub e-mailu z zamówienia.

POST/clients/resolve

Znajdź albo załóż kartę klientki

Zakres klucza: write:commerceLimit: 60 zapytań na minutęoperationId: resolveClient

Dopasowuje klientkę po telefonie (dowolny zapis, np. 500 100 200, +48 500-100-200), a bez niego po e-mailu; brak dopasowania zakłada nową kartę. Odpowiedź niesie wyłącznie identyfikator karty, nigdy dane osobowe. Dane istniejącej karty nie są nadpisywane.

Zgody marketingowe ze sklepu: wyłącznie NADANIE (granted: true z chwilą udzielenia). Zgoda jest pomijana, gdy jest starsza niż ostatnie cofnięcie tego kanału przez klientkę; zgoda e-mail nie wraca nigdy po odbiciu albo skardze u dostawcy poczty.

Karta nie jest wiązana z pozycją zamówienia - jedna klientka obsługuje wiele zamówień. W dry-runie nowa karta ma client_id: null.

Wymaga zakresu write:commerce i nagłówka Idempotency-Key. Treść jest walidowana PRZED kontrolą klucza idempotencji (zła treść = 400 invalid_request także bez klucza). Silk-Dry-Run: 1 wykonuje całą operację i ją wycofuje.

Parametry

Parametry
Parametr	Gdzie	Opis
`Idempotency-Key`wymagany	nagłówek	Klucz idempotencji zapisu, osobny dla każdego klucza API. Ten sam klucz i ta sama treść = powtórka zapisanej odpowiedzi; ta sama wartość z inną treścią = 409 `idempotency_key_reused`. Brak = 400 `idempotency_key_required`, zły format = 400 `invalid_request`.
`Silk-Dry-Run`	nagłówek	`1` = próba bez skutków (zapis wycofany), `0` albo brak = zwykły zapis. Każda inna wartość = 400 `invalid_request`.

Treść żądania

Treść POST /clients/resolve.

Pola żądania Znajdź albo załóż kartę klientki
Pole	Typ	Uwagi
`external_order_id`wymagane	`string`	1-100 znaków
`external_order_line_id`	`string`	do 100 znaków
`shop`	`string`	jedno z: shopify, woocommerce, other
`client`wymagane	`ClientInput`
`client.phone`	`string`	1-40 znaków
`client.email`	`string`	format email · do 255 znaków
`client.first_name`	`string`	1-100 znaków
`client.last_name`	`string`	do 100 znaków
`client.consents`	`object`
`client.consents.sms`	`ConsentGrant`
`client.consents.sms.granted`wymagane	`boolean`	zawsze true
`client.consents.sms.granted_at`wymagane	`string`	format date-time
`client.consents.email`	`ConsentGrant`
`client.consents.email.granted`wymagane	`boolean`	zawsze true
`client.consents.email.granted_at`wymagane	`string`	format date-time

Odpowiedź 200 · ResolveClientResponse

Identyfikator karty klientki, bez danych osobowych.

Pola odpowiedzi Znajdź albo załóż kartę klientki
Pole	Typ	Uwagi
`dry_run`wymagane	`boolean`
`client_id`wymagane	`string \| null`
`created`wymagane	`boolean`

Kody odpowiedzi

200Znajdź albo załóż kartę klientki
400Niepoprawne zapytanie.invalid_request idempotency_key_required
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
409Konflikt z wcześniejszym zapisem.idempotency_key_reused
422Zapytanie poprawne, ale salon nie może go zrealizować.client_identity_required client_limit_reached
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

POST /clients/resolve

curl -X POST "https://app.silkcrm.net/api/rest/v1/clients/resolve" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-client' \
  -d '{
  "external_order_id": "#1043",
  "shop": "shopify",
  "client": {
    "phone": "500 100 200",
    "email": "anna.nowak@example.com",
    "first_name": "Anna",
    "last_name": "Nowak",
    "consents": {
      "sms": {
        "granted": true,
        "granted_at": "2026-11-03T10:00:00.000Z"
      }
    }
  }
}'

OdpowiedźJSON

HTTP 200

{
  "dry_run": false,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "created": true
}

Vouchery

Vouchery kwotowe sprzedane w sklepie: wydanie, odczyt, zwrot.

POST/vouchers

Wydaj voucher kwotowy

Zakres klucza: write:commerceLimit: 60 zapytań na minutęoperationId: createVoucher

Voucher kwotowy sprzedany w sklepie. Odbiorczyni to DOKŁADNIE jedno z: client_id, client (znajdź albo załóż kartę) i recipient_phone (numer bez karty - voucher czeka pod nim). Opcjonalna purchaser to osoba płacąca, gdy voucher jest prezentem.

paid_cents < amount_cents = sprzedaż z rabatem: wartość vouchera zostaje pełna, zapłata trafia do paid_cents. Kwota musi mieścić się w zakresie ustawionym przez salon (422 voucher_amount_out_of_range z details.min_cents/max_cents).

VAT i fiskalizacja: sprzedaż vouchera to wpłata na bon wielokrotnego przeznaczenia - sklep NIE wystawia za nią paragonu fiskalnego, salon fiskalizuje przy realizacji vouchera. Silk niczego nie wysyła klientce (ani SMS, ani e-mail).

Pozycja zamówienia (external_order_id + external_order_line_id + shop) realizuje się raz: drugi zapis tej pozycji innym kluczem idempotencji = 409 order_line_already_fulfilled z details.existing_id.

Parametry

Parametry
Parametr	Gdzie	Opis
`Idempotency-Key`wymagany	nagłówek	Klucz idempotencji zapisu, osobny dla każdego klucza API. Ten sam klucz i ta sama treść = powtórka zapisanej odpowiedzi; ta sama wartość z inną treścią = 409 `idempotency_key_reused`. Brak = 400 `idempotency_key_required`, zły format = 400 `invalid_request`.
`Silk-Dry-Run`	nagłówek	`1` = próba bez skutków (zapis wycofany), `0` albo brak = zwykły zapis. Każda inna wartość = 400 `invalid_request`.

Treść żądania

Treść POST /vouchers: dokładnie jedno z client_id, client, recipient_phone.

Pola żądania Wydaj voucher kwotowy
Pole	Typ	Uwagi
`external_order_id`wymagane	`string`	1-100 znaków
`external_order_line_id`	`string`	do 100 znaków
`shop`	`string`	jedno z: shopify, woocommerce, other
`amount_cents`wymagane	`integer`	≥ 1
`paid_cents`wymagane	`integer`	≥ 0
`client_id`	`string`	1-100 znaków
`client`	`ClientInput`
`client.phone`	`string`	1-40 znaków
`client.email`	`string`	format email · do 255 znaków
`client.first_name`	`string`	1-100 znaków
`client.last_name`	`string`	do 100 znaków
`client.consents`	`object`
`client.consents.sms`	`ConsentGrant`
`client.consents.sms.granted`wymagane	`boolean`	zawsze true
`client.consents.sms.granted_at`wymagane	`string`	format date-time
`client.consents.email`	`ConsentGrant`
`client.consents.email.granted`wymagane	`boolean`	zawsze true
`client.consents.email.granted_at`wymagane	`string`	format date-time
`recipient_phone`	`string`	1-40 znaków
`purchaser`	`PurchaserInput`
`purchaser.client_id`	`string`	1-100 znaków
`purchaser.client`	`ClientInput`
`purchaser.client.phone`	`string`	1-40 znaków
`purchaser.client.email`	`string`	format email · do 255 znaków
`purchaser.client.first_name`	`string`	1-100 znaków
`purchaser.client.last_name`	`string`	do 100 znaków
`purchaser.client.consents`	`object`
`purchaser.client.consents.sms`	`ConsentGrant`
`purchaser.client.consents.sms.granted`wymagane	`boolean`	zawsze true
`purchaser.client.consents.sms.granted_at`wymagane	`string`	format date-time
`purchaser.client.consents.email`	`ConsentGrant`
`purchaser.client.consents.email.granted`wymagane	`boolean`	zawsze true
`purchaser.client.consents.email.granted_at`wymagane	`string`	format date-time
`gift_message`	`string`	do 500 znaków

Odpowiedź 201 · Voucher

Voucher kwotowy. amount_cents = wartość, balance_cents = saldo, paid_cents = zapłata w sklepie. W dry-runie pola obiektów, które dopiero by powstały, są null.

Pola odpowiedzi Wydaj voucher kwotowy
Pole	Typ	Uwagi
`id`wymagane	`string \| null`
`status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`amount_cents`wymagane	`integer`	≥ 0
`balance_cents`wymagane	`integer`	≥ 0
`paid_cents`wymagane	`integer`	≥ 0
`client_id`wymagane	`string \| null`
`recipient_phone`wymagane	`string \| null`
`purchaser_client_id`wymagane	`string \| null`
`gift_message`wymagane	`string \| null`
`expires_at`wymagane	`string \| null`
`external_order_id`wymagane	`string \| null`
`created_at`wymagane	`string \| null`
`dry_run`	`boolean`

Kody odpowiedzi

201Wydaj voucher kwotowy
400Niepoprawne zapytanie.invalid_request idempotency_key_required
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
409Konflikt z wcześniejszym zapisem.idempotency_key_reused order_line_already_fulfilled
422Zapytanie poprawne, ale salon nie może go zrealizować.client_not_found client_identity_required client_limit_reached vouchers_disabled voucher_amount_out_of_range payment_exceeds_value
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

POST /vouchers

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-voucher' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "1",
  "shop": "shopify",
  "amount_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "gift_message": "Wszystkiego najlepszego!"
}'

OdpowiedźJSON

HTTP 201

{
  "id": "8f1c0000-0000-4000-8000-000000000008",
  "status": "active",
  "amount_cents": 20000,
  "balance_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

GET/vouchers/{id}

Odczytaj voucher

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: getVoucher

Aktualny stan vouchera: saldo, status, ważność. external_order_id = numer zamówienia sklepu, z którego voucher powstał (null dla vouchera z kasy salonu).

Parametry

Parametry
Parametr	Gdzie	Opis
`id`wymagany	ścieżka	Identyfikator zwrócony przy wydaniu. Obcy, nieistniejący i obiekt innego rodzaju = ten sam 404.

Odpowiedź 200 · Voucher

Voucher kwotowy. amount_cents = wartość, balance_cents = saldo, paid_cents = zapłata w sklepie. W dry-runie pola obiektów, które dopiero by powstały, są null.

Pola odpowiedzi Odczytaj voucher
Pole	Typ	Uwagi
`id`wymagane	`string \| null`
`status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`amount_cents`wymagane	`integer`	≥ 0
`balance_cents`wymagane	`integer`	≥ 0
`paid_cents`wymagane	`integer`	≥ 0
`client_id`wymagane	`string \| null`
`recipient_phone`wymagane	`string \| null`
`purchaser_client_id`wymagane	`string \| null`
`gift_message`wymagane	`string \| null`
`expires_at`wymagane	`string \| null`
`external_order_id`wymagane	`string \| null`
`created_at`wymagane	`string \| null`
`dry_run`	`boolean`

Kody odpowiedzi

200Odczytaj voucher
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /vouchers/{id}

curl "https://app.silkcrm.net/api/rest/v1/vouchers/8f1c0000-0000-4000-8000-000000000008" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "id": "8f1c0000-0000-4000-8000-000000000008",
  "status": "active",
  "amount_cents": 20000,
  "balance_cents": 20000,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z"
}

POST/vouchers/{id}/void

Unieważnij voucher (zwrot w sklepie)

Zakres klucza: write:commerceLimit: 60 zapytań na minutęoperationId: voidVoucher

Zwrot zamówienia w sklepie. Unieważnić można wyłącznie obiekt utworzony przez API dla TEGO SAMEGO zamówienia (external_order_id + shop z treści; pozycja nie musi się zgadzać). Voucher lub karnet z kasy salonu, z innego zamówienia, obcy, innego rodzaju i nieistniejący dają ten sam 404 not_found. Obiekt zrealizowany choćby w części (każda niezwrócona realizacja, także voucher wykorzystany w całości albo wygasły po realizacji) = 409 fund_partially_used; zamknięty bez niezwróconej realizacji (już unieważniony, wygasły nietknięty) = 409 fund_already_closed.

Parametry

Parametry
Parametr	Gdzie	Opis
`id`wymagany	ścieżka	Identyfikator zwrócony przy wydaniu. Obcy, nieistniejący i obiekt innego rodzaju = ten sam 404.
`Idempotency-Key`wymagany	nagłówek	Klucz idempotencji zapisu, osobny dla każdego klucza API. Ten sam klucz i ta sama treść = powtórka zapisanej odpowiedzi; ta sama wartość z inną treścią = 409 `idempotency_key_reused`. Brak = 400 `idempotency_key_required`, zły format = 400 `invalid_request`.
`Silk-Dry-Run`	nagłówek	`1` = próba bez skutków (zapis wycofany), `0` albo brak = zwykły zapis. Każda inna wartość = 400 `invalid_request`.

Treść żądania

Treść zwrotu: numer zamówienia, z którego powstał obiekt; reason domyślnie „Zwrot w sklepie internetowym”.

Pola żądania Unieważnij voucher (zwrot w sklepie)
Pole	Typ	Uwagi
`external_order_id`wymagane	`string`	1-100 znaków
`external_order_line_id`	`string`	do 100 znaków
`shop`	`string`	jedno z: shopify, woocommerce, other
`reason`	`string`	do 200 znaków

Odpowiedź 200 · Voucher

Voucher kwotowy. amount_cents = wartość, balance_cents = saldo, paid_cents = zapłata w sklepie. W dry-runie pola obiektów, które dopiero by powstały, są null.

Pola odpowiedzi Unieważnij voucher (zwrot w sklepie)
Pole	Typ	Uwagi
`id`wymagane	`string \| null`
`status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`amount_cents`wymagane	`integer`	≥ 0
`balance_cents`wymagane	`integer`	≥ 0
`paid_cents`wymagane	`integer`	≥ 0
`client_id`wymagane	`string \| null`
`recipient_phone`wymagane	`string \| null`
`purchaser_client_id`wymagane	`string \| null`
`gift_message`wymagane	`string \| null`
`expires_at`wymagane	`string \| null`
`external_order_id`wymagane	`string \| null`
`created_at`wymagane	`string \| null`
`dry_run`	`boolean`

Kody odpowiedzi

200Unieważnij voucher (zwrot w sklepie)
400Niepoprawne zapytanie.invalid_request idempotency_key_required
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
409Konflikt z wcześniejszym zapisem.idempotency_key_reused fund_partially_used fund_already_closed
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

POST /vouchers/{id}/void

curl -X POST "https://app.silkcrm.net/api/rest/v1/vouchers/8f1c0000-0000-4000-8000-000000000008/void" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-refund-voucher' \
  -d '{
  "external_order_id": "#1043",
  "shop": "shopify",
  "reason": "Klientka zwróciła zamówienie"
}'

OdpowiedźJSON

HTTP 200

{
  "id": "8f1c0000-0000-4000-8000-000000000008",
  "status": "void",
  "amount_cents": 20000,
  "balance_cents": 0,
  "paid_cents": 18000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "recipient_phone": null,
  "purchaser_client_id": null,
  "gift_message": "Wszystkiego najlepszego!",
  "expires_at": null,
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

Karnety

Karnety sprzedane w sklepie: wydanie, odczyt, zwrot.

POST/passes

Wydaj karnet

Zakres klucza: write:commerceLimit: 60 zapytań na minutęoperationId: createPass

Karnet z szablonu, który salon sprzedaje poza kasą (sellable: true w GET /pass-templates). Karnet wymaga karty klientki: DOKŁADNIE jedno z client_id i client.

paid_cents mniejsze od ceny szablonu = sprzedaż z rabatem: liczba wejść zostaje z szablonu, wartość jednego wejścia (unit_value_cents) liczy się od zapłaty.

VAT i fiskalizacja: sprzedaż karnetu fiskalizuje sklep - Silk nie wystawia paragonu. Silk niczego nie wysyła klientce.

Pozycja zamówienia realizuje się raz: drugi zapis tej pozycji innym kluczem idempotencji = 409 order_line_already_fulfilled z details.existing_id.

Parametry

Parametry
Parametr	Gdzie	Opis
`Idempotency-Key`wymagany	nagłówek	Klucz idempotencji zapisu, osobny dla każdego klucza API. Ten sam klucz i ta sama treść = powtórka zapisanej odpowiedzi; ta sama wartość z inną treścią = 409 `idempotency_key_reused`. Brak = 400 `idempotency_key_required`, zły format = 400 `invalid_request`.
`Silk-Dry-Run`	nagłówek	`1` = próba bez skutków (zapis wycofany), `0` albo brak = zwykły zapis. Każda inna wartość = 400 `invalid_request`.

Treść żądania

Treść POST /passes: dokładnie jedno z client_id i client.

Pola żądania Wydaj karnet
Pole	Typ	Uwagi
`external_order_id`wymagane	`string`	1-100 znaków
`external_order_line_id`	`string`	do 100 znaków
`shop`	`string`	jedno z: shopify, woocommerce, other
`template_id`wymagane	`string`	1-100 znaków
`paid_cents`wymagane	`integer`	≥ 0
`client_id`	`string`	1-100 znaków
`client`	`ClientInput`
`client.phone`	`string`	1-40 znaków
`client.email`	`string`	format email · do 255 znaków
`client.first_name`	`string`	1-100 znaków
`client.last_name`	`string`	do 100 znaków
`client.consents`	`object`
`client.consents.sms`	`ConsentGrant`
`client.consents.sms.granted`wymagane	`boolean`	zawsze true
`client.consents.sms.granted_at`wymagane	`string`	format date-time
`client.consents.email`	`ConsentGrant`
`client.consents.email.granted`wymagane	`boolean`	zawsze true
`client.consents.email.granted_at`wymagane	`string`	format date-time

Odpowiedź 201 · Pass

Karnet. uses_left = pozostałe wejścia, unit_value_cents = wartość jednego wejścia. W dry-runie pola obiektów, które dopiero by powstały, są null.

Pola odpowiedzi Wydaj karnet
Pole	Typ	Uwagi
`id`wymagane	`string \| null`
`status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`template_id`wymagane	`string \| null`
`name`wymagane	`string`
`uses_total`wymagane	`integer`	≥ 0
`uses_left`wymagane	`integer`	≥ 0
`paid_cents`wymagane	`integer`	≥ 0
`unit_value_cents`wymagane	`object`
`service_ids`wymagane	`array<string>`
`client_id`wymagane	`string \| null`
`expires_at`wymagane	`string \| null`
`external_order_id`wymagane	`string \| null`
`created_at`wymagane	`string \| null`
`dry_run`	`boolean`

Kody odpowiedzi

201Wydaj karnet
400Niepoprawne zapytanie.invalid_request idempotency_key_required
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
409Konflikt z wcześniejszym zapisem.idempotency_key_reused order_line_already_fulfilled
422Zapytanie poprawne, ale salon nie może go zrealizować.client_not_found client_identity_required client_limit_reached passes_disabled pass_template_not_sellable pass_template_promotional payment_exceeds_value
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

POST /passes

curl -X POST "https://app.silkcrm.net/api/rest/v1/passes" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-pass' \
  -d '{
  "external_order_id": "#1043",
  "external_order_line_id": "3",
  "shop": "shopify",
  "template_id": "8f1c0000-0000-4000-8000-000000000006",
  "paid_cents": 45000,
  "client_id": "8f1c0000-0000-4000-8000-000000000007"
}'

OdpowiedźJSON

HTTP 201

{
  "id": "8f1c0000-0000-4000-8000-000000000009",
  "status": "active",
  "template_id": "8f1c0000-0000-4000-8000-000000000006",
  "name": "Karnet 5 manicure",
  "uses_total": 5,
  "uses_left": 5,
  "paid_cents": 45000,
  "unit_value_cents": 9000,
  "service_ids": [
    "8f1c0000-0000-4000-8000-000000000003"
  ],
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "expires_at": "2027-11-03T10:15:00.000Z",
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

GET/passes/{id}

Odczytaj karnet

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: getPass

Aktualny stan karnetu: pozostałe wejścia, status, ważność. external_order_id = numer zamówienia sklepu, z którego karnet powstał (null dla karnetu z kasy salonu).

Parametry

Parametry
Parametr	Gdzie	Opis
`id`wymagany	ścieżka	Identyfikator zwrócony przy wydaniu. Obcy, nieistniejący i obiekt innego rodzaju = ten sam 404.

Odpowiedź 200 · Pass

Karnet. uses_left = pozostałe wejścia, unit_value_cents = wartość jednego wejścia. W dry-runie pola obiektów, które dopiero by powstały, są null.

Pola odpowiedzi Odczytaj karnet
Pole	Typ	Uwagi
`id`wymagane	`string \| null`
`status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`template_id`wymagane	`string \| null`
`name`wymagane	`string`
`uses_total`wymagane	`integer`	≥ 0
`uses_left`wymagane	`integer`	≥ 0
`paid_cents`wymagane	`integer`	≥ 0
`unit_value_cents`wymagane	`object`
`service_ids`wymagane	`array<string>`
`client_id`wymagane	`string \| null`
`expires_at`wymagane	`string \| null`
`external_order_id`wymagane	`string \| null`
`created_at`wymagane	`string \| null`
`dry_run`	`boolean`

Kody odpowiedzi

200Odczytaj karnet
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /passes/{id}

curl "https://app.silkcrm.net/api/rest/v1/passes/8f1c0000-0000-4000-8000-000000000009" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "id": "8f1c0000-0000-4000-8000-000000000009",
  "status": "active",
  "template_id": "8f1c0000-0000-4000-8000-000000000006",
  "name": "Karnet 5 manicure",
  "uses_total": 5,
  "uses_left": 5,
  "paid_cents": 45000,
  "unit_value_cents": 9000,
  "service_ids": [
    "8f1c0000-0000-4000-8000-000000000003"
  ],
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "expires_at": "2027-11-03T10:15:00.000Z",
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z"
}

POST/passes/{id}/void

Unieważnij karnet (zwrot w sklepie)

Zakres klucza: write:commerceLimit: 60 zapytań na minutęoperationId: voidPass

Parametry

Parametry
Parametr	Gdzie	Opis
`id`wymagany	ścieżka	Identyfikator zwrócony przy wydaniu. Obcy, nieistniejący i obiekt innego rodzaju = ten sam 404.
`Idempotency-Key`wymagany	nagłówek	Klucz idempotencji zapisu, osobny dla każdego klucza API. Ten sam klucz i ta sama treść = powtórka zapisanej odpowiedzi; ta sama wartość z inną treścią = 409 `idempotency_key_reused`. Brak = 400 `idempotency_key_required`, zły format = 400 `invalid_request`.
`Silk-Dry-Run`	nagłówek	`1` = próba bez skutków (zapis wycofany), `0` albo brak = zwykły zapis. Każda inna wartość = 400 `invalid_request`.

Treść żądania

Treść zwrotu: numer zamówienia, z którego powstał obiekt; reason domyślnie „Zwrot w sklepie internetowym”.

Pola żądania Unieważnij karnet (zwrot w sklepie)
Pole	Typ	Uwagi
`external_order_id`wymagane	`string`	1-100 znaków
`external_order_line_id`	`string`	do 100 znaków
`shop`	`string`	jedno z: shopify, woocommerce, other
`reason`	`string`	do 200 znaków

Odpowiedź 200 · Pass

Karnet. uses_left = pozostałe wejścia, unit_value_cents = wartość jednego wejścia. W dry-runie pola obiektów, które dopiero by powstały, są null.

Pola odpowiedzi Unieważnij karnet (zwrot w sklepie)
Pole	Typ	Uwagi
`id`wymagane	`string \| null`
`status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`template_id`wymagane	`string \| null`
`name`wymagane	`string`
`uses_total`wymagane	`integer`	≥ 0
`uses_left`wymagane	`integer`	≥ 0
`paid_cents`wymagane	`integer`	≥ 0
`unit_value_cents`wymagane	`object`
`service_ids`wymagane	`array<string>`
`client_id`wymagane	`string \| null`
`expires_at`wymagane	`string \| null`
`external_order_id`wymagane	`string \| null`
`created_at`wymagane	`string \| null`
`dry_run`	`boolean`

Kody odpowiedzi

200Unieważnij karnet (zwrot w sklepie)
400Niepoprawne zapytanie.invalid_request idempotency_key_required
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
409Konflikt z wcześniejszym zapisem.idempotency_key_reused fund_partially_used fund_already_closed
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

POST /passes/{id}/void

curl -X POST "https://app.silkcrm.net/api/rest/v1/passes/8f1c0000-0000-4000-8000-000000000009/void" \
  -H "Authorization: Bearer $SILK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-refund-pass' \
  -d '{
  "external_order_id": "#1043",
  "shop": "shopify"
}'

OdpowiedźJSON

HTTP 200

{
  "id": "8f1c0000-0000-4000-8000-000000000009",
  "status": "void",
  "template_id": "8f1c0000-0000-4000-8000-000000000006",
  "name": "Karnet 5 manicure",
  "uses_total": 5,
  "uses_left": 0,
  "paid_cents": 45000,
  "unit_value_cents": 9000,
  "service_ids": [
    "8f1c0000-0000-4000-8000-000000000003"
  ],
  "client_id": "8f1c0000-0000-4000-8000-000000000007",
  "expires_at": "2027-11-03T10:15:00.000Z",
  "external_order_id": "#1043",
  "created_at": "2026-11-03T10:15:00.000Z",
  "dry_run": false
}

Zamówienia

Wszystko, co Silk utworzył dla zamówienia sklepu.

GET/orders/{external_order_id}

Stan zamówienia sklepu w Silku

Zakres klucza: read:*Limit: 120 zapytań na minutęoperationId: getOrder

Vouchery i karnety utworzone przez API dla numeru zamówienia, w aktualnym stanie (po zwrocie status void). Numer zamówienia jest przycinany ze spacji; # koduj jako %23. Brak czegokolwiek dla tego numeru = 404 not_found.

Parametry

Parametry
Parametr	Gdzie	Opis
`external_order_id`wymagany	ścieżka	Numer zamówienia sklepu, przycinany ze spacji, wielkość liter ma znaczenie. Znak `#` koduj jako `%23` (np. `/orders/%231043`) - surowy `#` zaczyna fragment adresu i nie dociera do serwera.
`shop`	zapytanie	Zawęża do zamówień jednego sklepu. Bez parametru: wszystkie sklepy, a przy kilku `shop` w odpowiedzi = `null`.

Odpowiedź 200 · Order

Vouchery i karnety utworzone przez API dla zamówienia sklepu.

Pola odpowiedzi Stan zamówienia sklepu w Silku
Pole	Typ	Uwagi
`external_order_id`wymagane	`string`
`shop`wymagane	`object`
`vouchers`wymagane	`array<Voucher>`
`vouchers[].id`wymagane	`string \| null`
`vouchers[].status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`vouchers[].amount_cents`wymagane	`integer`	≥ 0
`vouchers[].balance_cents`wymagane	`integer`	≥ 0
`vouchers[].paid_cents`wymagane	`integer`	≥ 0
`vouchers[].client_id`wymagane	`string \| null`
`vouchers[].recipient_phone`wymagane	`string \| null`
`vouchers[].purchaser_client_id`wymagane	`string \| null`
`vouchers[].gift_message`wymagane	`string \| null`
`vouchers[].expires_at`wymagane	`string \| null`
`vouchers[].external_order_id`wymagane	`string \| null`
`vouchers[].created_at`wymagane	`string \| null`
`vouchers[].dry_run`	`boolean`
`passes`wymagane	`array<Pass>`
`passes[].id`wymagane	`string \| null`
`passes[].status`wymagane	`string`	jedno z: pending_payment, active, used_up, expired, void
`passes[].template_id`wymagane	`string \| null`
`passes[].name`wymagane	`string`
`passes[].uses_total`wymagane	`integer`	≥ 0
`passes[].uses_left`wymagane	`integer`	≥ 0
`passes[].paid_cents`wymagane	`integer`	≥ 0
`passes[].unit_value_cents`wymagane	`object`
`passes[].service_ids`wymagane	`array<string>`
`passes[].client_id`wymagane	`string \| null`
`passes[].expires_at`wymagane	`string \| null`
`passes[].external_order_id`wymagane	`string \| null`
`passes[].created_at`wymagane	`string \| null`
`passes[].dry_run`	`boolean`

Kody odpowiedzi

200Stan zamówienia sklepu w Silku
400Niepoprawne zapytanie.invalid_request
401Brak ważnego klucza API.unauthorized
403Brak dostępu.api_key_required insufficient_scope feature_not_available_on_plan tenant_suspended
404Nie znaleziono (obcy i nieistniejący zasób bez rozróżnienia).not_found
429Przekroczony limit zapytań.rate_limited
500Błąd po stronie Silk.internal_error

GET /orders/{external_order_id}

curl "https://app.silkcrm.net/api/rest/v1/orders/%231043" \
  -H "Authorization: Bearer $SILK_API_KEY"

OdpowiedźJSON

HTTP 200

{
  "external_order_id": "#1043",
  "shop": "shopify",
  "vouchers": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000008",
      "status": "active",
      "amount_cents": 20000,
      "balance_cents": 20000,
      "paid_cents": 18000,
      "client_id": "8f1c0000-0000-4000-8000-000000000007",
      "recipient_phone": null,
      "purchaser_client_id": null,
      "gift_message": "Wszystkiego najlepszego!",
      "expires_at": null,
      "external_order_id": "#1043",
      "created_at": "2026-11-03T10:15:00.000Z"
    }
  ],
  "passes": [
    {
      "id": "8f1c0000-0000-4000-8000-000000000009",
      "status": "active",
      "template_id": "8f1c0000-0000-4000-8000-000000000006",
      "name": "Karnet 5 manicure",
      "uses_total": 5,
      "uses_left": 5,
      "paid_cents": 45000,
      "unit_value_cents": 9000,
      "service_ids": [
        "8f1c0000-0000-4000-8000-000000000003"
      ],
      "client_id": "8f1c0000-0000-4000-8000-000000000007",
      "expires_at": "2027-11-03T10:15:00.000Z",
      "external_order_id": "#1043",
      "created_at": "2026-11-03T10:15:00.000Z"
    }
  ]
}

Błędy

Kształt błędu i kody

Każdy błąd ma ten sam kształt: { "error": { "code", "message", "details"?, "request_id" } }. Rozgałęziaj się po code (lista w schemacie Error, pole x-error-codes), nie po treści message (po polsku, może się zmienić). request_id podaj przy zgłoszeniu. Obcy i nieistniejący zasób to ten sam 404 not_found.

Przykład błędu 422JSON

{
  "error": {
    "code": "voucher_amount_out_of_range",
    "message": "Kwota vouchera jest poza zakresem ustawionym przez salon.",
    "details": { "min_cents": 5000, "max_cents": 50000 },
    "request_id": "req-8f1c0001"
  }
}

Kody błędów REST API v1
Kod	HTTP	Znaczenie
`unauthorized`	401	Brak ważnego klucza API. Podaj go w nagłówku Authorization: Bearer silk_live_….
`api_key_required`	403	To API przyjmuje wyłącznie klucz API salonu (silk_live_…), nie inne sposoby logowania.
`insufficient_scope`	403	Klucz API nie ma uprawnienia do tej operacji. Zapisy wymagają zakresu write:commerce.
`feature_not_available_on_plan`	403	Plan salonu nie obejmuje dostępu przez API.
`tenant_suspended`	403	Konto salonu jest zawieszone. Skontaktuj się z obsługą SilkCRM.
`rate_limited`	429	Przekroczono limit zapytań. Spróbuj ponownie za chwilę.
`invalid_request`	400	Zapytanie ma niepoprawne parametry albo treść.
`invalid_cursor`	400	Kursor stronicowania jest nieprawidłowy. Pobierz listę od początku.
`not_found`	404	Nie znaleziono zasobu.
`idempotency_key_required`	400	Zapis wymaga nagłówka Idempotency-Key.
`idempotency_key_reused`	409	Ten Idempotency-Key był już użyty z inną treścią zapytania.
`order_line_already_fulfilled`	409	Ta pozycja zamówienia została już zrealizowana.
`client_not_found`	422	Nie znaleziono klientki salonu.
`client_identity_required`	422	Podaj numer telefonu albo adres e-mail klientki.
`client_limit_reached`	422	Salon osiągnął limit klientek w swoim planie.
`vouchers_disabled`	422	Salon nie sprzedaje voucherów.
`voucher_amount_out_of_range`	422	Kwota vouchera jest poza zakresem ustawionym przez salon.
`passes_disabled`	422	Salon nie sprzedaje karnetów.
`pass_template_not_sellable`	422	Tego karnetu nie można sprzedać.
`pass_template_promotional`	422	Karnetu promocyjnego nie można sprzedać przez API.
`payment_exceeds_value`	422	Kwota zapłaty przekracza wartość vouchera lub karnetu.
`fund_partially_used`	409	Voucher lub karnet został już częściowo wykorzystany.
`fund_already_closed`	409	Voucher lub karnet jest już zamknięty.
`internal_error`	500	Wystąpił błąd po stronie Silk. Spróbuj ponownie; jeśli się powtarza, podaj request_id.

Limity

Limity zapytań

Limity liczą się osobno dla każdej trasy i każdego klucza API: odczyty 120 zapytań na minutę, zapisy 60 zapytań na minutę (osobne liczniki). Po przekroczeniu: 429 rate_limited z details.retry_after (sekundy) i nagłówkiem Retry-After.

Limity zapytań
Rodzaj	Limit	Licznik
Odczyt (GET)	120 zapytań na minutę	osobno dla każdej trasy i każdego klucza API
Zapis (POST)	60 zapytań na minutę	osobny licznik zapisów, dla każdej trasy i każdego klucza API

Idempotencja

Ponawianie zapisów bez duplikatów

Każdy zapis wymaga nagłówka Idempotency-Key (1-255 znaków A-Z a-z 0-9 _ - : .). Ponowienie z tym samym kluczem i tą samą treścią zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replay: true - bez drugiego skutku.

Klucze są osobne dla każdego klucza API: nowy klucz API to nowa przestrzeń kluczy idempotencji.
Porównywane są metoda, ścieżka i treść (bez query string). Ten sam klucz z inną treścią = 409 idempotency_key_reused. Ścieżka jest porównywana dosłownie, więc ten sam klucz z inaczej zapisaną ścieżką (ukośnik na końcu, inne kodowanie identyfikatora) też daje 409 idempotency_key_reused.
Zapamiętywane są wyłącznie odpowiedzi 2xx. Po błędzie ten sam klucz można ponowić z poprawioną treścią.
Równoległe żądanie z tym samym kluczem czeka na pierwsze i dostaje jego odpowiedź jako powtórkę.
Treść jest walidowana przed kontrolą klucza: zła treść daje 400 invalid_request nawet bez nagłówka.
Niezależnie od klucza pozycja zamówienia (external_order_id + external_order_line_id + shop) realizuje się raz: 409 order_line_already_fulfilled z details.existing_id.

Dobry klucz idempotencji to numer zamówienia i pozycji, np. order-1043-voucher. Przykład powtórki: ponowione powiadomienie sklepu.

Dry-run

Próba bez skutków

Nagłówek Silk-Dry-Run: 1 wykonuje zapis w całości i go wycofuje: odpowiedź ma "dry_run": true, nagłówek Silk-Dry-Run: 1, a obiekty, które dopiero by powstały, mają id: null. Brak nagłówka albo 0 = zwykły zapis; każda inna wartość = 400 invalid_request. Dry-run z kluczem idempotencji już użytym w prawdziwym zapisie zwraca zapisaną PRAWDZIWĄ odpowiedź (z "dry_run": false) oraz Silk-Dry-Run: 1.

Wartości nagłówka Silk-Dry-Run
Nagłówek Silk-Dry-Run	Skutek
`1`	Próba: zapis wykonany i wycofany, odpowiedź z `dry_run: true` i nagłówkiem `Silk-Dry-Run: 1`
`0` albo brak	Zwykły zapis
każda inna wartość	400 `invalid_request`

Konwencje

Konwencje i zamówienia sklepu

Kwoty w groszach (*_cents, liczby całkowite). Czasy w ISO 8601. Identyfikatory to nieprzezroczyste napisy (UUID). Listy są stronicowane kursorem (limit, cursor → next_cursor, null = ostatnia strona).

Zamówienia sklepu

Każdy zapis podaje external_order_id (1-100 znaków, przycinany ze spacji), opcjonalnie external_order_line_id i shop (shopify, woocommerce, other - domyślnie other). W ścieżce (GET /orders/{external_order_id}) znak # koduj jako %23. Unieważnić (zwrot) można wyłącznie obiekt utworzony przez API dla tego samego zamówienia (external_order_id + shop) - każdy inny przypadek to 404.

Dane osobowe

Klientki i zgody

Odpowiedzi nie niosą danych osobowych - wyłącznie identyfikatory kart (wyjątek: recipient_phone, który podał sam sklep). Zgody marketingowe ze sklepu to wyłącznie nadanie; zgoda starsza niż ostatnie cofnięcie kanału jest pomijana, a zgoda e-mail nie wraca nigdy po odbiciu albo skardze u dostawcy poczty. Silk niczego nie wysyła klientce przy wydaniu vouchera ani karnetu.

Fiskalizacja

VAT i fiskalizacja

Voucher kwotowy: sprzedaż to wpłata na bon wielokrotnego przeznaczenia - sklep NIE wystawia paragonu fiskalnego, salon fiskalizuje przy realizacji. Karnet: sprzedaż fiskalizuje sklep; Silk nie wystawia paragonu przy sprzedaży ze sklepu.

Kto wystawia paragon
Produkt	Sprzedaż w sklepie	Kiedy powstaje paragon
Voucher kwotowy	Sklep NIE wystawia paragonu fiskalnego: sprzedaż vouchera to wpłata na bon wielokrotnego przeznaczenia.	Przy realizacji vouchera w salonie. Paragon wystawia salon.
Karnet	Sprzedaż fiskalizuje sklep. Silk nie wystawia paragonu przy sprzedaży karnetu ze sklepu.	Przy sprzedaży, w sklepie.

To opis tego, jak działa Silk. Rozliczenie podatkowe konkretnego salonu potwierdź z jego księgową.

Webhooki

Webhooki wychodzące

Webhooki powiadamiają Twój system o zdarzeniach w salonie: nowej wizycie, płatności, opinii. To osobny mechanizm od REST API v1: konfiguruje go salon w aplikacji (plany Pro i wyższe), a dostawa nie zależy od klucza API.

Konfiguracja

Ustawienia → Zaawansowane → Webhooki → „Nowy webhook”. Wypełnij „URL endpointu” (publiczny adres Twojego serwera), „Sekret HMAC” (8-500 znaków, wymagany przy tworzeniu), opcjonalny „Opis”, zaznacz „Zdarzenia” i kliknij „Dodaj webhook”. Przycisk „Test” wysyła zdarzenie próbne z polem test: true w data, a tabela „Log dostaw” pokazuje każdą próbę ze statusem i odpowiedzią Twojego serwera.

Zdarzenia

Zdarzenia webhooków
Zdarzenie	Kiedy	Pola w data
`appointment.created`	Nowa wizyta została utworzona.	`appointment_idlocation_idsource`
`appointment.updated`	Wizyta została zmieniona.	`appointment_idstartendspecialist_idestimated_price`
`appointment.cancelled`	Wizyta została anulowana.	`appointment_idprevious_statuscancellation_reasonnotecancellation_penalty_amount`
`appointment.completed`	Wizyta została ukończona.	`appointment_idprevious_statusnote`
`client.created`	Nowy klient został utworzony.	`client_id`
`client.updated`	Profil klienta został zaktualizowany.	`client_idchangeslifecycle_stagelead_status`
`payment.completed`	Płatność za wizytę została rozliczona.	`appointment_idreceipt_idsubtotaltotalpayment_idamountmethod`
`review.received`	Otrzymano opinię klienta po wizycie.	`review_idratingappointment_idclient_idsource`
`lead.created`	Utworzono nowy lead sprzedażowy.	`lead_idsourceassigned_tolocation_id`

Treść dostawy

Każda dostawa to POST z kopertą zdarzenia. Pole data zależy od typu zdarzenia i może z czasem dostać nowe pola: ignoruj te, których nie znasz.

Koperta zdarzeniaJSON

{
  "id": "6b1f0f7e-3c2a-4d8e-9a51-2f0c7d1e4a10",
  "type": "appointment.created",
  "version": "v1",
  "timestamp": "2026-11-06T09:15:00.000Z",
  "tenant_id": "8f1c0000-0000-4000-8000-0000000000aa",
  "actor": { "id": "8f1c0000-0000-4000-8000-0000000000bb", "type": "user" },
  "data": {
    "appointment_id": "8f1c0000-0000-4000-8000-0000000000cc",
    "location_id": "8f1c0000-0000-4000-8000-000000000001",
    "source": "staff"
  }
}

Nagłówki dostawy webhooka
Nagłówek	Wartość	Znaczenie
`Content-Type`	application/json	Treść to JSON koperty zdarzenia.
`X-BeautyCRM-Delivery`	UUID dostawy	Ten sam przy każdej próbie tej samej dostawy. Użyj go do odrzucania duplikatów.
`X-BeautyCRM-Event`	np. appointment.created	Typ zdarzenia.
`X-BeautyCRM-Signature`	sha256=<hex>	HMAC SHA-256 z sekretem endpointu, liczony z `timestamp.delivery.treść`.
`X-BeautyCRM-Timestamp`	np. 2026-11-06T09:15:00.000Z	Chwila wysłania tej próby (ISO 8601). Nowa przy każdym ponowieniu.

Weryfikacja podpisu

Podpis to HMAC SHA-256 z sekretem endpointu, liczony z napisu {X-BeautyCRM-Timestamp}.{X-BeautyCRM-Delivery}.{surowa treść}, zapisany szesnastkowo z prefiksem sha256=. Licz go z bajtów, które przyszły, zanim sparsujesz JSON: ponowna serializacja zmienia treść i podpis się nie zgodzi. Porównuj w stałym czasie i odrzucaj dostawy ze znacznikiem czasu starszym niż kilka minut.

Weryfikacja podpisu webhooka

import crypto from "node:crypto";
import express from "express";

const app = express();
const MAX_AGE_MS = 5 * 60 * 1000;
const SECRET = process.env.SILK_WEBHOOK_SECRET;
if (!SECRET) throw new Error("Brak SILK_WEBHOOK_SECRET - ustaw sekret HMAC webhooka.");

// Podpis liczymy z SUROWEJ treści, więc parser JSON-a dopiero po weryfikacji.
app.post("/webhooks/silkcrm", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.get("X-BeautyCRM-Timestamp") ?? "";
  const deliveryId = req.get("X-BeautyCRM-Delivery") ?? "";
  const signature = req.get("X-BeautyCRM-Signature") ?? "";
  // Zły format nagłówka = 401 od razu (inaczej bufory różnej długości wywróciłyby timingSafeEqual).
  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return res.status(401).end();

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${timestamp}.${deliveryId}.${rawBody}`)
    .digest();
  const received = Buffer.from(signature.slice("sha256=".length), "hex");

  const valid = crypto.timingSafeEqual(expected, received);
  const age = Math.abs(Date.now() - Date.parse(timestamp));
  if (!valid || !(age < MAX_AGE_MS)) return res.status(401).end();

  const event = JSON.parse(rawBody);
  // Odrzuć duplikat po deliveryId, potem obsłuż event.type i event.data.
  res.status(200).end();
});

Dostawa i ponowienia

Sukces to dowolna odpowiedź 2xx w ciągu 10 sekund. Odpowiadaj od razu, a zdarzenie przetwarzaj w tle. Przekierowania (do 5) są śledzone, ale każdy adres musi być publiczny.
Silk próbuje dostarczyć zdarzenie 3 razy: od razu, po około minucie i po około 5 minutach. Zadanie ponowień chodzi co 5 minut, więc odstęp bywa dłuższy.
Ponowienie ma ten sam X-BeautyCRM-Delivery i nowy X-BeautyCRM-Timestamp. Odrzucaj duplikaty po identyfikatorze dostawy, a nie po treści. Kolejność dostaw nie jest gwarantowana.
Po trzeciej nieudanej próbie dostawa zostaje oznaczona jako nieudana, endpoint jest wyłączany, a salon dostaje powiadomienie „Webhook został dezaktywowany”. Po naprawie włącz go przełącznikiem „Endpoint aktywny”. Nieudane dostawy nie są wysyłane ponownie.

CLI

Dane salonu w terminalu

Pakiet @silkcrm/cli (polecenie silk) daje dostęp do narzędzi AI salonu z terminala: przychody, KPI, wizyty, rozliczenia. Używa tego samego klucza API, ale woła narzędzia AI (/api/v1/ai/tools), a nie REST API v1. Wymaga Node.js 20.19.6 lub nowszego.

Instalacja i kluczTerminal

npx @silkcrm/cli --help
# albo globalnie:
npm i -g @silkcrm/cli

export SILK_API_KEY=silk_live_...            # klucz z Ustawień
export SILK_API_URL=https://app.silkcrm.net  # opcjonalnie

PoleceniaTerminal

silk revenue --last 30d
silk kpi --last 7d
silk appointments --from 2026-11-01 --to 2026-11-30
silk billing

silk tools list
silk tools schema aggregate_revenue
silk tools call aggregate_revenue --arg range_days=30
silk tools call list_appointments --json-args '{"date_from":"2026-11-01","date_to":"2026-11-07"}'

# każde polecenie z --json zwraca surowy JSON (do jq i skryptów)
silk kpi --last 7d --json

Skróty (revenue, kpi, appointments, billing) tylko odczytują dane.
silk tools call wykonuje dowolne narzędzie, na które pozwala zakres klucza. Narzędzia zmieniające dane pytają o potwierdzenie (albo przyjmują --yes).
Dane klientek wracają jako tokeny zamiast imion i telefonów.

MCP

Salon w asystencie AI (MCP)

Serwer MCP daje asystentom AI (Claude, ChatGPT i innym klientom MCP) te same narzędzia salonu co CLI. Autoryzacja, izolacja salonów, kontrola ról i anonimizacja danych klientek zostają po stronie SilkCRM.

Zdalny serwer (HTTP)

Adres: https://app.silkcrm.net/mcp. Serwer przyjmuje logowanie OAuth kontem SilkCRM (tak łączy się konektor dodany w claude.ai) albo klucz API w nagłówku Authorization: Bearer silk_live_…. W claude.ai dodaj własny konektor z tym adresem i zaloguj się kontem salonu. Podłączonych asystentów zobaczysz w aplikacji: Ustawienia → Zaawansowane → Integracje → „Połączenia AI”, gdzie zmienisz ich zakres albo je odłączysz.

Lokalny serwer (stdio)

Pakiet @silkcrm/mcp uruchamia serwer na Twoim komputerze (Node.js 18 lub nowszy) z kluczem API w zmiennej SILK_API_KEY. Claude Desktop: Ustawienia → Developer → Edit Config.

claude_desktop_config.jsonJSON

{
  "mcpServers": {
    "silkcrm": {
      "command": "npx",
      "args": ["-y", "@silkcrm/mcp"],
      "env": {
        "SILK_API_KEY": "silk_live_TWOJ_KLUCZ"
      }
    }
  }
}

Claude CodeTerminal

# lokalnie (stdio), klucz API ze zmiennej środowiskowej
claude mcp add silkcrm -e SILK_API_KEY=$SILK_API_KEY -- npx -y @silkcrm/mcp

# zdalnie (HTTP), ten sam klucz API w nagłówku
claude mcp add --transport http silkcrm https://app.silkcrm.net/mcp \
  --header "Authorization: Bearer $SILK_API_KEY"

Instrukcja krok po kroku, którą może przeprowadzić sam asystent: silkcrm.net/silkcrm-mcp.md.

Wersje

Wersje i zmiany

Wersja stoi w ścieżce: /api/rest/v1. Zmiany zgodne wstecz (nowa operacja, nowe pole w odpowiedzi, nowy parametr opcjonalny) wchodzą bez zmiany wersji, więc Twój kod powinien ignorować pola, których nie zna. Zmiana niezgodna wstecz oznacza nową wersję w ścieżce.

1.0.0 2026-11-06
- Pierwsze wydanie REST API v1 dla sklepów internetowych salonów.
- Katalog: salony, usługi, specjalistki, szablony karnetów.
- Karta klientki po telefonie lub e-mailu z zamówienia, ze zgodami marketingowymi (tylko nadanie).
- Vouchery kwotowe i karnety: wydanie, odczyt, unieważnienie przy zwrocie w sklepie.
- Stan zamówienia sklepu w Silku.
- Idempotencja zapisów, tryb próby Silk-Dry-Run, jednolity kształt błędów.

Pytania o integrację: tech@silkcrm.net. Do zgłoszenia dołącz request_id z odpowiedzi i prefiks klucza, nigdy cały klucz.