API per sviluppatori

L'API Integrations di Customix ti permette di importare i tuoi ordini personalizzati nei tuoi sistemi: i file di stampa generati da Customix e tutto ciò che i tuoi clienti hanno inserito durante la personalizzazione, come nomi, testi personalizzati, colori e layout scelti. Usala quando uno strumento di produzione, un foglio di calcolo o una piattaforma di automazione come Make ha bisogno dei dettagli dei tuoi ordini senza che nessuno debba copiarli a mano.

Per ottenere una chiave API, vai a Impostazioni nella barra laterale sinistra, apri la scheda Integrazioni, poi fai clic su Crea chiave nella scheda Chiave API. Per i dettagli, consulta Come ottenere la chiave API di Customix.

🔑 Autenticazione

Tutte le richieste richiedono la tua chiave API nell'header:

Authorization: Bearer <your_api_key>

🌐 URL di base

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

📘 Endpoint

1. Ottenere l'elenco degli ordini

Endpoint:

GET /orders

Descrizione: recupera i tuoi ordini personalizzati, per impostazione predefinita dal più recente.

Parametri:

Header:

Richiesta di esempio:

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

Risposta:

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

Risposte di errore:

2. Ottenere un ordine specifico

Endpoint:

GET /orders/{id}

Descrizione: recupera un ordine, con i suoi file di stampa e i valori di personalizzazione.

Parametri:

Header:

Richiesta di esempio:

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

Risposta: un singolo ordine in data, con gli stessi campi di una voce dell'elenco sopra:

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

(Qui abbreviata: la risposta reale include tutti i campi mostrati nell'esempio dell'elenco.)

Risposte di errore:

3. Ottenere la personalizzazione di un ordine specifico

Endpoint:

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

Descrizione: recupera una personalizzazione di un ordine.

Parametri:

Header:

Richiesta di esempio:

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

Risposta: la personalizzazione da sola, non racchiusa in 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" }
  ]
}

Risposte di errore:

🖊️ Valori della personalizzazione

Ogni personalizzazione include dei values: una voce per ogni campo di personalizzazione salvato con l'ordine, gli stessi dettagli che vedi come proprietà dell'articolo nell'ordine in Shopify. Ogni voce ha:

• key: l'identificatore del campo nel tuo modello. Resta lo stesso da un ordine all'altro per lo stesso campo dello stesso modello, quindi usalo per mappare i campi nella tua integrazione.
• label: il nome dell'opzione che i tuoi clienti hanno visto, ad esempio "Name". Può essere vuoto negli ordini meno recenti.
• type: il tipo di opzione, ad esempio text-field, color-picker, font-swatch, image-swatch, layout-swatch, date-picker o file-upload.
• value: ciò che il cliente ha scelto o inserito, sempre come testo.

Come viene espresso value per ogni tipo di opzione:

• Testo: esattamente ciò che il cliente ha scritto.
• Selettore di colore: il codice del colore scelto dal cliente.
• Campioni di font, immagine, colore e contorno: il valore del campione scelto dal cliente.
• Campioni di layout: il nome del layout scelto dal cliente, così come era denominato quando è stato effettuato l'ordine.
• Selettori di data e ora: la data o l'ora scelta dal cliente.
• Caricamenti di file e vettoriali: un link al file caricato dal cliente.
• Palette e font delle nuvole di parole: i colori o i font scelti dal cliente, separati da virgole.
• Le opzioni che non hanno una forma testuale, come stili di mappa, località o brani Spotify, restituiscono un valore vuoto: per queste usa i file di stampa.

⚠️ Codici di errore comuni

📌 Note

• Tutte le risposte sono in JSON.
• Limite di richieste: 2 requests/second.
• Contatta [email protected] per qualsiasi domanda.

Aggiornato il: 14/09/2026