APIs para programadores

A API de integrações do Customix permite-lhe obter as suas encomendas personalizadas para os seus próprios sistemas: os ficheiros de impressão gerados pelo Customix e tudo o que os seus clientes introduziram ao personalizar, como nomes, texto personalizado, cores e esquemas escolhidos. Recorra a ela quando uma ferramenta de produção, uma folha de cálculo ou uma plataforma de automatização como o Make precisar dos detalhes das suas encomendas sem que ninguém os copie à mão.

Para obter uma chave de API, aceda a Definições na barra lateral esquerda, abra o separador Integrações e clique em Criar chave no cartão Chave de API. Consulte How can get Customix API key para obter mais detalhes.

🔑 Autenticação

Todos os pedidos exigem a sua chave de API no cabeçalho:

Authorization: Bearer <your_api_key>

🌐 URL base

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

📘 Endpoints

1. Obter a lista de encomendas

Endpoint:

GET /orders

Descrição: obtém as suas encomendas personalizadas, por predefinição das mais recentes para as mais antigas.

Parâmetros:

Cabeçalhos:

Exemplo de pedido:

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

Resposta:

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

Respostas de erro:

2. Obter uma encomenda específica

Endpoint:

GET /orders/{id}

Descrição: obtém uma encomenda, com os respetivos ficheiros de impressão e valores de personalização.

Parâmetros:

Cabeçalhos:

Exemplo de pedido:

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

Resposta: uma única encomenda em data, com os mesmos campos de uma entrada da lista acima:

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

(Abreviada aqui; a resposta real inclui todos os campos apresentados no exemplo da lista.)

Respostas de erro:

3. Obter a personalização de uma encomenda específica

Endpoint:

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

Descrição: obtém uma personalização de uma encomenda.

Parâmetros:

Cabeçalhos:

Exemplo de pedido:

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

Resposta: a personalização por si só, não envolvida em 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" }
  ]
}

Respostas de erro:

🖊️ Valores de personalização

Cada personalização inclui values: uma entrada por cada campo de personalização guardado com a encomenda, os mesmos detalhes que vê como propriedades do item na encomenda no Shopify. Cada entrada tem:

• key: o identificador do campo no seu modelo. Mantém-se igual de encomenda para encomenda para o mesmo campo do mesmo modelo, por isso utilize-o para mapear campos na sua integração.
• label: o nome da opção que os seus clientes viram, por exemplo, "Name". Pode estar vazio em encomendas mais antigas.
• type: o tipo de opção, por exemplo text-field, color-picker, font-swatch, image-swatch, layout-swatch, date-picker ou file-upload.
• value: o que o seu cliente escolheu ou introduziu, sempre como texto.

Como value é apresentado para cada tipo de opção:

• Texto: exatamente o que o seu cliente escreveu.
• Seletor de cor: o código de cor que o seu cliente escolheu.
• Amostras de tipo de letra, imagem, cor e traço: o valor da amostra que o seu cliente escolheu.
• Amostras de esquema: o nome do esquema que o seu cliente escolheu, tal como estava designado quando fez a encomenda.
• Seletores de data e hora: a data ou a hora que o seu cliente escolheu.
• Carregamentos de ficheiros e vetores: um link para o ficheiro que o seu cliente carregou.
• Paletas e tipos de letra de nuvem de palavras: as cores ou os tipos de letra que o seu cliente escolheu, separados por vírgulas.
• As opções sem forma de texto, como estilos de mapa, localizações ou faixas do Spotify, são devolvidas com um valor vazio; utilize os ficheiros de impressão para essas.

⚠️ Códigos de erro comuns

📌 Notas

• Todas as respostas são em JSON.
• Limite de pedidos: 2 requests/second.
• Contacte [email protected] para esclarecer dúvidas.

Atualizado em: 14/09/2026