API dla deweloperów

Customix Integrations API pozwala pobierać personalizowane zamówienia do własnych systemów: pliki do druku wygenerowane przez Customix i wszystko, co klienci wprowadzili podczas personalizacji, np. imiona, własne teksty, kolory i wybrane układy. Użyj go, gdy narzędzie produkcyjne, arkusz kalkulacyjny lub platforma automatyzacji, taka jak Make, potrzebuje szczegółów zamówień bez ręcznego kopiowania.

Aby uzyskać klucz API, przejdź do Ustawienia na lewym pasku bocznym, otwórz kartę Integracje, a następnie kliknij Utwórz klucz na karcie Klucz API. Szczegóły znajdziesz w artykule How can get Customix API key.

🔑 Uwierzytelnianie

Wszystkie żądania wymagają klucza API w nagłówku:

Authorization: Bearer <your_api_key>

🌐 Bazowy URL

https://app.customix.io/api/integrations/v1

📘 Punkty końcowe

1. Pobierz listę zamówień

Punkt końcowy:

GET /orders

Opis: pobiera Twoje personalizowane zamówienia, domyślnie od najnowszych.

Parametry:

Nagłówki:

Przykładowe żądanie:

GET https://app.customix.io/api/integrations/v1/orders?shop=abcdef&limit=2

Odpowiedź:

{
  "data": [
    {
      "shop": "abcdef.myshopify.com",
      "order_id": 123456789,
      "order_number": "#1001",
      "currency": "USD",
      "customer": "John Doe",
      "email": "[email protected]",
      "ip": "123.123.123.123",
      "total_price": 123.45,
      "financial_status": "paid",
      "fulfillment_status": "fulfilled",
      "ordered_at": "2025-01-21 01:01:01",
      "customizations": [
        {
          "id": "01jjavmg7t7vqj5z6qvxwie14b",
          "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
          "campaign_id": "01jphjdfmtxhaio94h0wd0kv0c",
          "shopify_line_item_id": 11106133639222,
          "shopify_product_id": 11179841648222,
          "shopify_variant_id": 11191300929074,
          "platform": "shopify",
          "line_item_quantity": 1,
          "files": [
            {
              "id": "01jb3092vabc7m8qw4cdqv09we",
              "name": "default",
              "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png"
            }
          ],
          "values": [
            { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" },
            { "key": "layout_100003", "label": "Layout", "type": "layout-swatch", "value": "Portrait" },
            { "key": "100004", "label": "Color", "type": "color-picker", "value": "#1a2b3c" }
          ]
        }
      ]
    }
  ]
}

Odpowiedzi z błędem:

2. Pobierz konkretne zamówienie

Punkt końcowy:

GET /orders/{id}

Opis: pobiera jedno zamówienie wraz z plikami do druku i wartościami personalizacji.

Parametry:

Nagłówki:

Przykładowe żądanie:

GET https://app.customix.io/api/integrations/v1/orders/123456789?shop=abcdef

Odpowiedź: pojedyncze zamówienie w data, z tymi samymi polami co jeden wpis z powyższej listy:

{
  "data": {
    "shop": "abcdef.myshopify.com",
    "order_id": 123456789,
    "order_number": "#1001",
    "customizations": [
      {
        "id": "01jjavmg7t7vqj5z6qvxwie14b",
        "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
        "line_item_quantity": 1,
        "files": [
          { "id": "01jb3092vabc7m8qw4cdqv09we", "name": "default", "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png" }
        ],
        "values": [
          { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" }
        ]
      }
    ]
  }
}

(Tutaj skrócone. Prawdziwa odpowiedź zawiera wszystkie pola pokazane w przykładzie listy.)

Odpowiedzi z błędem:

3. Pobierz personalizację konkretnego zamówienia

Punkt końcowy:

GET /orders/{order_id}/customizations/{public_customization_id}

Opis: pobiera jedną personalizację zamówienia.

Parametry:

Nagłówki:

Przykładowe żądanie:

GET https://app.customix.io/api/integrations/v1/orders/123456789/customizations/01jjavmg7t7vqj5z6qvxwpc9kd?shop=abcdef

Odpowiedź: sama personalizacja, nieopakowana w data:

{
  "id": "01jjavmg7t7vqj5z6qvxwie14b",
  "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
  "campaign_id": "01jphjdfmtxhaio94h0wd0kv0c",
  "shopify_line_item_id": 11106133639222,
  "shopify_product_id": 11179841648222,
  "shopify_variant_id": 11191300929074,
  "platform": "shopify",
  "line_item_quantity": 1,
  "files": [
    {
      "id": "01jb3092vabc7m8qw4cdqv09we",
      "name": "default",
      "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png"
    }
  ],
  "values": [
    { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" },
    { "key": "layout_100003", "label": "Layout", "type": "layout-swatch", "value": "Portrait" }
  ]
}

Odpowiedzi z błędem:

🖊️ Wartości personalizacji

Każda personalizacja zawiera values: po jednym wpisie dla każdego pola personalizacji zapisanego w zamówieniu, czyli te same szczegóły, które widzisz jako właściwości pozycji zamówienia w Shopify. Każdy wpis zawiera:

• key: identyfikator pola w Twoim szablonie. Pozostaje taki sam w każdym zamówieniu dla tego samego pola tego samego szablonu, więc używaj go do mapowania pól w integracji.
• label: nazwa opcji widoczna dla klientów, na przykład „Name”. W starszych zamówieniach może być pusta.
• type: rodzaj opcji, na przykład text-field, color-picker, font-swatch, image-swatch, layout-swatch, date-picker lub file-upload.
• value: to, co klient wybrał lub wpisał, zawsze jako tekst.

Jak value wygląda dla poszczególnych rodzajów opcji:

• Tekst: dokładnie to, co wpisał klient.
• Selektor koloru: kod koloru wybrany przez klienta.
• Próbki czcionek, obrazów, kolorów i obrysu: wartość próbki wybranej przez klienta.
• Próbki układu: nazwa układu wybranego przez klienta, taka jak w chwili składania zamówienia.
• Selektory daty i godziny: data lub godzina wybrana przez klienta.
• Przesłane pliki i wektory: link do pliku przesłanego przez klienta.
• Palety i czcionki chmury słów: kolory lub czcionki wybrane przez klienta, oddzielone przecinkami.
• Opcje, które nie mają postaci tekstowej, takie jak style map, lokalizacje czy utwory ze Spotify, zwracają pustą wartość. Dla nich użyj plików do druku.

⚠️ Typowe kody błędów

📌 Uwagi

• Wszystkie odpowiedzi są w formacie JSON.
• Limit żądań: 2 requests/second.
• W razie pytań napisz na adres [email protected].

Zaktualizowano: 14/09/2026