Referência da API Fabrixa Integration

Para aceder à API Integration, autentique os pedidos usando um Application Access Token e uma Application Key:

Cabeçalho de autorização

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Cabeçalho da chave do aplicativo

X-Application-Key: APPLICATION_KEY

Exemplo de comando cURL

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/ping' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Substitua APPLICATION_ACCESS_TOKEN pelo seu token de acesso real e APPLICATION_KEY pela sua chave de aplicativo real.

Os endpoints da API Integration são organizados por tipo de recurso e seguem o estilo REST. Cada endpoint representa um recurso, e as ações são executadas com métodos HTTP padrão.

Todos os pedidos e respostas da API Integration usam JSON, oferecendo uma interface consistente e simples.

Para obter detalhes completos sobre cada endpoint, incluindo exemplos de solicitação e resposta, consulte nosso Swagger documentation.

Formato de resposta

Todos os endpoints retornam dados em um formato padronizado com estes objetos:

{
  "links": {
    "self": "https://api.fabrixa.com/v2/integration/products",
    "first_page": "https://api.fabrixa.com/v2/integration/products?page=1",
    "last_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "next_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "prev_page": null
  },
  "meta": {
    "total": 2,
    "current_page": 1,
    "per_page": 10
  },
  "data": [
    {
      "id": 1,
      "name": "Product 1",
      "description": "Description of Product 1"
    },
    {
      "id": 2,
      "name": "Product 2",
      "description": "Description of Product 2"
    }
  ]
}

Descrição dos objetos de resposta

Todas as solicitações de API retornam códigos de status HTTP que fornecem informações sobre a resposta.

Corpo de resposta de erro

Um exemplo de corpo de resposta de erro:

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/ping"
    },
    "meta": [],
    "errors": {
        "messages": [
            "Application Key is not specified."
        ]
    }
}

errors contém detalhes sobre o que falhou. A matriz messages lista descrições de erros. Para uma solicitação incorreta, você receberá os nomes dos campos que falharam na validação.

A API de integração suporta um limite de 30 solicitações por aplicativo por minuto.

Se você exceder esse limite, receberá uma resposta 429 Too Many Requests.

Todas as respostas da API de integração incluem o cabeçalho X-RateLimit-Remaining, quantas solicitações o cliente ainda pode fazer, e o cabeçalho X-RateLimit-Limit, o total permitido por minuto.

O modo sandbox permite testar a sua integração de ponta a ponta antes de qualquer encomenda real ser produzida ou cobrada. Aplica-se a toda a sua conta: as encomendas de todos os canais de venda, incluindo a Integration API e as lojas Shopify e WooCommerce ligadas, não são produzidas nem debitadas do seu saldo. A sua conta está em modo sandbox enquanto o seu estado for a aguardar ativação.

Em modo sandbox, pode:

• ligar a sua loja Shopify ou WooCommerce, ou criar um canal Integration API;
• adicionar produtos e verificar preços e estimativas de envio;
• importar, criar, atualizar e cancelar encomendas;
• verificar que nenhuma destas encomendas é produzida nem debitada do seu saldo;
• verificar a entrega de webhooks e as assinaturas.

Para testar encomendas, adicione produtos do catálogo Fabrixa: abra um produto, clique em Vender este produto e escolha variantes e designs. Passam então a aparecer em Os meus produtos.

Para passar a sua conta para o modo sandbox, abra a Platform, vá a Definições → Empresa → Modo sandbox e clique em Passar para o modo sandbox. Também o pode ativar ao adicionar um novo canal de venda, incluindo um canal Integration API, ou escrever para support@fabrixa.com e nós passamos a sua conta para o modo sandbox. O modo sandbox só está disponível para contas ativas.

Quando estiver pronto, ative a conta você mesmo na Platform em Definições → Empresa → Modo sandbox. Também pode escrever para support@fabrixa.com e nós ativamo-la por si. As lojas ligadas e as credenciais da API continuam a funcionar, pelo que não é preciso reconfigurar nada.

Depois da ativação, todas as novas encomendas seguem para produção e são debitadas do seu saldo. As encomendas criadas antes da ativação continuam a ser encomendas de teste: nunca são produzidas nem cobradas, mesmo depois da ativação.

O catálogo é tudo o que a Fabrixa produz. Os seus produtos são os produtos do catálogo que adicionou à sua conta Fabrixa, com os seus próprios nomes, descrições, imagens e SKU. Uma linha de encomenda indica uma variante de produto - um tamanho ou uma versão de um produto - pelo seu sku ou variant_id: uma variante de um dos seus produtos, ou uma variante do catálogo encomendada diretamente.

Para listar os produtos que a Fabrixa produz, envie um pedido GET para https://api.fabrixa.com/v2/integration/catalog/products com as suas credenciais. Lista os produtos ativos que têm uma variante que um parceiro de impressão produz atualmente, e apenas essas variantes, cada uma com o seu SKU, preço de venda, dimensões e valores de opção.

Parâmetros de consulta

Solicitação de amostra

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/products?category_id=19&limit=10' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/products",
        "first_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "last_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 1305,
            "name": "Duvet Cover",
            "subtitle": "Duvet Cover with a pillow",
            "description": "
Soft personalized duvet cover.
",
            "slug": "duvet-cover",
            "code": "DUVET-001",
            "HS_code": "63023100",
            "created_at": "2024-08-16T09:32:07.000000Z",
            "updated_at": "2024-08-16T09:38:50.000000Z",
            "is_sellable": true,
            "variants_min_selling_price": "29.95",
            "variants_max_selling_price": "49.95",
            "type": {
                "id": 5,
                "name": "Duvet cover"
            },
            "status": {
                "id": 2,
                "name": "Active"
            },
            "categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "parent_category": {
                        "id": 8,
                        "name": "Bedroom",
                        "description": "Bedroom products"
                    }
                }
            ],
            "images": [
                {
                    "id": 5566,
                    "url": "https://storage.googleapis.com/example/catalog/duvet-cover.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "COT864311",
                    "selling_price": "29.95",
                    "width": "140.00",
                    "height": "200.00",
                    "length": "2.00",
                    "weight": "1.20",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:36:37.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": 2708,
                    "name": "Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "COT864314",
                    "selling_price": "49.95",
                    "width": "200.00",
                    "height": "220.00",
                    "length": "2.00",
                    "weight": "1.80",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:37:11.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Campos da resposta

Para listar as categorias em que o catálogo está organizado, envie um pedido GET para https://api.fabrixa.com/v2/integration/catalog/categories com as suas credenciais. A resposta contém as categorias de primeiro nível, cada uma com as suas subcategorias aninhadas em sub_categories e o número de produtos do catálogo que contém em products_count. Passe o id de uma categoria como category_id ao explorar o catálogo, ou o id de uma categoria de primeiro nível como parent_category_id para obter de uma vez os produtos de todas as suas subcategorias.

Parâmetros de consulta

Solicitação de amostra

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/categories?with_products_only=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/categories"
    },
    "meta": {
        "total": 1
    },
    "data": [
        {
            "id": 8,
            "name": "Bedroom",
            "description": "Bedroom products",
            "sort_number": 1,
            "slug": "bedroom",
            "products_count": 12,
            "sub_categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "sort_number": 1,
                    "slug": "duvet-covers",
                    "products_count": 7,
                    "images": [],
                    "sub_categories": []
                },
                {
                    "id": 20,
                    "name": "Pillows",
                    "description": "Personalized pillows and pillowcases",
                    "sort_number": 2,
                    "slug": "pillows",
                    "products_count": 4,
                    "images": [],
                    "sub_categories": []
                }
            ],
            "parent_category": null,
            "images": [
                {
                    "id": 781,
                    "url": "https://storage.googleapis.com/example/catalog/bedroom.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ]
        }
    ]
}

Para listar os produtos da sua conta, envie um pedido GET para https://api.fabrixa.com/v2/integration/products com as suas credenciais. Os seus produtos são os produtos do catálogo que adicionou à sua conta Fabrixa: têm os nomes, descrições e imagens que lhes deu aí, e as suas variantes os valores de SKU que escolheu. Só são listados os produtos ativos, dez por página a menos que passe limit.

Parâmetros de consulta

Solicitação de amostra

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/products?search=duvet' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/products",
        "first_page": "https://api.fabrixa.com/v2/integration/products?page=1",
        "last_page": "https://api.fabrixa.com/v2/integration/products?page=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "slug": "dreamy-duvet-cover",
            "width": "50.00",
            "height": "50.00",
            "length": "20.00",
            "weight": "100.00",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z",
            "type": {
                "id": 5,
                "name": "Duvet cover",
                "description": "Duvet cover with pillow"
            },
            "available_options": [
                {
                    "id": 151,
                    "name": "Duvet Size",
                    "values": [
                        {
                            "id": 471,
                            "value": "140x200"
                        },
                        {
                            "id": 474,
                            "value": "200x220"
                        }
                    ]
                }
            ],
            "categories": [
                {
                    "id": 912,
                    "name": "Bedding"
                }
            ],
            "collections": [
                {
                    "id": 77,
                    "name": "Spring 2025"
                }
            ],
            "images": [
                {
                    "id": 48120,
                    "is_main": true,
                    "image_size": "1200x1200",
                    "url": "https://storage.googleapis.com/example/shop/dreamy-duvet-cover.jpg",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 32323,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "DDC-140200",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                },
                {
                    "id": 32326,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "DDC-200220",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                }
            ]
        }
    ]
}

Para ler um único produto, envie um pedido GET para https://api.fabrixa.com/v2/integration/products/{product_id}, em que {product_id} é o seu id. A resposta tem os mesmos campos da lista. Um produto que não está na sua conta, mesmo um do catálogo, responde 404 Not Found com a mensagem Product not found.

Campos da resposta

Uma variante é uma versão encomendável de um produto - um tamanho, uma cor - e o que uma linha de encomenda indica, por sku ou por variant_id. Para ler uma variante de um dos seus produtos, envie um pedido GET para https://api.fabrixa.com/v2/integration/variants/{variant_id}, em que {variant_id} é o seu id. Uma variante de um produto que não está na sua conta responde 404 Not Found com a mensagem Variant not found.

Solicitação de amostra

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/variants/32323' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/variants/32323"
    },
    "meta": [],
    "data": {
        "id": 32323,
        "name": "Dreamy Duvet Cover",
        "subtitle": "140x200",
        "description": null,
        "SKU": "DDC-140200",
        "created_at": "2025-03-04T10:12:41.000000Z",
        "updated_at": "2025-03-04T10:12:41.000000Z",
        "width": "140.00",
        "height": "200.00",
        "length": "2.00",
        "weight": "1.20",
        "options": [
            {
                "id": 151,
                "name": "Duvet Size",
                "values": [
                    {
                        "id": 471,
                        "value": "140x200"
                    }
                ]
            }
        ],
        "images": [],
        "product": {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "description2": null,
            "slug": "dreamy-duvet-cover",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z"
        },
        "available_source_types": ["duvet", "pillow", "pillow-back"],
        "required_source_types": ["duvet", "pillow"]
    }
}

Campos da resposta

Uma linha de encomenda para esta variante, com um PDF cujas páginas são as suas camadas:

"rows": [
    {
        "sku": "DDC-140200",
        "quantity": 1,
        "sources": [
            {
                "type": "file",
                "url": "https://samples-files.com/samples/duvet-cover.pdf"
            }
        ]
    }
]

Que variantes podem ser encomendadas

Crie encomendas na Fabrixa a partir da sua loja ou plataforma, anexe os ficheiros de impressão necessários e acompanhe cada item durante o fulfillment.

Para criar uma encomenda através da Fabrixa Integration API, envie um pedido POST para https://api.fabrixa.com/v2/integration/orders. O request body deve incluir:

Solicitar estrutura corporal

Solicitação de amostra

{
  "number": "NL2024010201",
  "comments": "Customer agrees with a low resolution file.",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "variant_id": 2705,
      "quantity": 1,
      "client_barcode": "1234567890",
      "sources": [
        {
          "type": "file",
          "url": "https://samples-files.com/samples/sample.pdf"
        }
      ]
    }
  ],
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "3VJtP@example.com",
    "phone": "0612345678"
  },
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SABCD1234567",
    "tracking_url": "https://postnl.nl/tracktrace/3SABCD1234567",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-26T21:15:04.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

Para atualizar uma encomenda, envie um pedido PATCH para https://api.fabrixa.com/v2/integration/orders/{order_id}, em que {order_id} é o id da encomenda na Fabrixa. Só mudam os campos que enviar, e o estado da encomenda mantém-se. A resposta contém a encomenda atualizada. Pode alterar:

Solicitação de amostra

{
  "comments": "Deliver to the neighbours if nobody is home.",
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "19",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  }
}

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Deliver to the neighbours if nobody is home.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T09:41:18.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "19",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "errors": {
        "rows": [
            "Order rows cannot be changed. Cancel the order and create a new one."
        ]
    }
}

Para cancelar uma encomenda, envie um pedido POST sem body para https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, em que {order_id} é o id da encomenda na Fabrixa (o campo numérico id da encomenda), não o seu número de encomenda. A resposta contém a encomenda com o estado canceled e é enviado um webhook order.updated.

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "canceled",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T10:02:45.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

Se a encomenda não puder ser cancelada, a API responde com 412 Precondition Failed e uma mensagem com o motivo: o seu estado atual não o permite (o estado é indicado na mensagem) ou a produção já começou.

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "errors": {
        "messages": [
            "This order cannot be canceled in its current status (ready for shipping)."
        ]
    }
}

Uma encomenda é acompanhada através de três estados: o status da encomenda, o seu estado de produção fulfillment_status e o status de cada envio em shipments. Cada alteração é enviada no webhook order.updated e devolvida por GET /orders/{order_id}.

Status do pedido

O status de uma encomenda, pela ordem em que é atingido:

• imported - a encomenda foi recebida através da API. Todas as encomendas começam aqui.
• on hold - o saldo não cobre o custo da encomenda. Depois de carregado, a encomenda volta a imported e continua.
• accepted - a encomenda foi aceite e segue para produção.
• completed (definitivo) - todos os artigos foram produzidos.
• canceled (definitivo) - a encomenda foi cancelada. Isto é possível enquanto estiver imported, accepted ou on hold e a produção ainda não tiver começado.

Status de cumprimento

O fulfillment_status de uma encomenda e de cada linha da encomenda, pela ordem em que é atingido. Só avança, nunca recua:

• unfulfilled - a produção ainda não começou.
• scheduled - a encomenda está planeada num lote de produção. A partir daqui, já não pode ser cancelada.
• processing - a produção está em curso.
• partially fulfilled - alguns artigos estão concluídos, os restantes ainda estão em produção.
• fulfilled (definitivo) - todos os artigos estão concluídos. O status da encomenda passa então a completed.

Uma encomenda no seu todo nunca é rejeitada. Um artigo individual pode ser rejeitado no controlo de qualidade durante a produção. É então reimpresso: volta a unfulfilled e passa novamente pela produção, enquanto a encomenda mantém o seu estado e continua assim que o artigo estiver concluído.

Status do envio

O status de cada envio em shipments, pela ordem em que é atingido:

• pending - o envio está a ser preparado.
• registered - a etiqueta foi criada junto da transportadora.
• collected - a transportadora recolheu o volume.
• in transit - o volume está a caminho.
• delivered (definitivo) - o volume foi entregue.

Exceções:

• failed - a transportadora comunicou um problema.
• returned (definitivo) - o volume foi-nos devolvido.
• canceled (definitivo) - o envio foi cancelado.

Para obter o estado de fulfillment de uma encomenda específica, envie um pedido GET para https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. A resposta fornece os fulfillments associados à encomenda, incluindo estado dos itens, detalhes do produto e progresso das etapas de produção.

Exemplo de resposta

{
    "data": [
        {
            "id": 1499,
            "barcode": "1200004169200",
            "status": "unfulfilled",
            "created_at": "2024-08-19T12:38:59.000000Z",
            "updated_at": "2024-08-19T12:39:00.000000Z",
            "variant": {
                "id": 32327,
                "name": "Test iAPI blanket product",
                "subtitle": "100 x 150 cm",
                "SKU": "COF099191"
            },
            "product": {
                "id": 1306,
                "name": "Test iAPI blanket product",
                "subtitle": "Test iAPI blanket product"
            },
            "production_steps": [
                {
                    "id": 5,
                    "name": "Print duvet",
                    "description": "Printing the duvet according to the specified design and dimensions.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                },
                {
                    "id": 6,
                    "name": "Print pillow",
                    "description": "Printing the pillow cover with the assigned design.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                }
            ]
        }
    ]
}

A resposta inclui uma lista de cumprimentos, cada um fornecendo:

Cada registro de atendimento corresponde a um produto específico ou variante de produto no pedido, e cada cópia do produto no pedido tem seu próprio registro de atendimento - cada item é rastreado individualmente durante a produção.

Se nenhum atendimento for retornado para um pedido, o pedido ainda não entrou na fase de processamento.

Ao incluir source files na encomenda, confirme que cumprem os seguintes requisitos:

"sources": [
    {
        "type": "file",
        "url": "https://samples-files.com/samples/source.pdf"
    }
]

Requisitos PDF e ordem das páginas

A ordem das páginas no PDF é importante. As páginas são combinadas com as camadas do produto por posição, e a ordem esperada das páginas depende do tipo de produto. Certifique-se de que as páginas do seu PDF sigam a sequência correta de camadas do produto que você está enviando.

Importante: cada página do PDF deve corresponder às dimensões exigidas para sua camada de produto e estar orientada corretamente. Posicione a arte de forma que a parte superior do design fique alinhada com a parte superior da página. O tamanho ou a orientação incorretos da página podem causar problemas de dimensionamento, rotação ou alinhamento na produção.

Saiba quanto custará o envio de uma encomenda e quanto tempo estará a caminho antes de a fazer, calculado pelas mesmas regras que a Fabrixa aplica à própria encomenda.

Para saber para que países uma variante de produto pode ser enviada, envie um pedido GET para https://api.fabrixa.com/v2/integration/shipping/countries com as suas credenciais. A lista, ordenada por nome, contém os países para os quais o local que produz a variante tem uma tarifa de envio, para uma embalagem de envio em que a variante possa ser acondicionada. Um país que não conste da lista não tem tarifa de envio para a variante.

Parâmetros de consulta

Solicitação de amostra

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/countries?sku=DDC-140200' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/countries"
    },
    "meta": {
        "total": 2
    },
    "data": [
        {
            "code": "BE",
            "name": "Belgium",
            "min_shipping_price": "7.75",
            "max_shipping_price": "9.85",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 2
        },
        {
            "code": "NL",
            "name": "Netherlands",
            "min_shipping_price": "6.70",
            "max_shipping_price": "8.40",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 1
        }
    ]
}

Campos da resposta

Para saber quanto custaria o envio de uma variante de produto e quanto tempo ficaria em trânsito, envie um pedido GET para https://api.fabrixa.com/v2/integration/shipping/estimate com as suas credenciais. A estimativa segue as regras com que é calculado o preço de uma encomenda: as unidades são acondicionadas nas embalagens de envio do local que produz a variante, e o preço de cada volume é calculado para a rota desse local até ao país de destino. Nada é encomendado nem reservado, e o preço de uma encomenda é calculado no momento em que é feita, pelo que os seus portes podem ser diferentes se as tarifas mudarem entretanto.

Parâmetros de consulta

Solicitação de amostra

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/estimate?sku=DDC-140200&country_code=NL&quantity=2' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemplo de resposta

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/estimate"
    },
    "meta": [],
    "data": {
        "variant_id": 32323,
        "sku": "DDC-140200",
        "quantity": 2,
        "country_code": "NL",
        "origin_country": {
            "code": "PT",
            "name": "Portugal"
        },
        "packages_count": 1,
        "packages": [
            {
                "package_type": "Small Box",
                "length": 30,
                "width": 20,
                "height": 10,
                "quantity": 1,
                "price": "7.45",
                "eta_days": 3
            }
        ],
        "shipping_price": "7.45",
        "currency": "EUR",
        "eta_days": 3
    }
}

Campos da resposta

Um pedido que não passe a validação recebe a resposta 400 Bad Request com o motivo para cada campo, com as mesmas mensagens que uma linha de encomenda, por exemplo The variant not found. Quando nenhuma embalagem de envio comporta as unidades, a resposta é 400 Bad Request com a mensagem No shipping package can carry the variant.

Fabrixa Studio é uma ferramenta que permite aos usuários customizar e personalizar produtos em tempo real com uma interface intuitiva onde os usuários podem criar ou fazer upload de seus próprios designs.

O Fabrixa Studio é ideal para empresas que oferecem produtos personalizados – permitindo que os clientes visualizem seus designs antes de finalizar os pedidos.

Pode incorporar o Fabrixa Studio no seu site usando um iframe. Isto permite que os clientes personalizem produtos diretamente no site durante o checkout.

Exemplo de iframe para incorporação do Fabrixa Studio:

<iframe id="fabrixa-studio"
    src="https://studio.fabrixa.com?application_key={application_key}&sku={product_sku}&cart_item_key={cart_item_key}"
    name="FabrixaStudio"
    scrolling="no"
    frameborder="1"
    width="100%"
    height="100%"
    allowfullscreen="">
</iframe>

Substitua os valores de product_sku, cart_item_key e application_key pelos seus valores dinâmicos.

• application_key - chave exclusiva para autenticação na API de integração.
• product_sku - o SKU da variante do produto, recuperado da API de integração.
• cart_item_key - um valor exclusivo da plataforma de incorporação que identifica o item do carrinho associado ao produto. Usado para salvar as customizações do usuário; durante a criação do pedido identifica as personalizações salvas e as atribui ao pedido. Veja o exemplo abaixo.
• locale (opcional) - o idioma da interface do Studio e das suas mensagens de erro, p. ex. de_DE ou de. Sem ele, o Studio abre no idioma do navegador do comprador, se for suportado, caso contrário em inglês.

O cabeçalho do Studio mostra o nome do produto tal como está na sua loja - o mesmo título que os seus clientes veem - com as opções da variante escolhida por baixo. É a cópia do produto própria da sua loja, por isso um nome que edite na Fabrixa aparece também no Studio; locale não o traduz.

Solicitação para criar um pedido com cart_item_key

{
  "number": "NL2024010201",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "sku": "SB796162",
      "quantity": 1,
      "cart_item_key": "0cb76770-de2d-4524-aa48-47b6e5f0d8a5"
    }
  ],
  "customer": {
    "...": "..."
  },
  "shipping_address": {
    "...": "..."
  },
  "shipping_label": {
    "...": "..."
  }
}

Quando o botão Adicionar ao carrinho é clicado dentro do iframe, o seguinte comando é executado:

window.parent.postMessage('customizationFinished', '*');

Da mesma forma, quando o botão Voltar é clicado:

window.parent.postMessage('closeButtonClicked', '*');

O método postMessage facilita a comunicação de origem cruzada entre o iframe e sua janela pai, permitindo notificar o pai sobre ações específicas do usuário.

O primeiro argumento de postMessage são os dados que você deseja enviar. A string 'customizationFinished' indica que o usuário finalizou a personalização e está adicionando o produto ao carrinho. 'closeButtonClicked' indica que o usuário optou por voltar.

Na janela pai, ouça estas mensagens usando o ouvinte de eventos message:

window.addEventListener('message', function(event) {
    if (event.origin === 'https://studio.fabrixa.com') {
        if (event.data === 'customizationFinished') {
            // Handle the Add to Cart event
            console.log('Customization finished and item can be added to cart.');
        } else if (event.data === 'closeButtonClicked') {
            // Handle the Back button event
            console.log('Back button clicked.');
        }
    }
});

Sempre verifique o origin das mensagens recebidas para garantir que elas venham de uma fonte confiável. Dependendo da mensagem recebida, execute as ações necessárias - atualize a interface do usuário, processe o carrinho, etc. A validação do origin é crucial para a segurança - evita que scripts não autorizados interajam com seu aplicativo.

Após a conclusão da personalização, exiba o design final usando o URL de visualização abaixo. Este URL retorna uma imagem do produto customizado, adequada como o valor src em uma tag <img>. Ideal para mostrar o produto personalizado no carrinho, no resumo do pedido ou em qualquer lugar da interface da sua loja.

https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}

Substitua {CART_ITEM_KEY} pela chave real do item do carrinho e {APPLICATION_KEY} pela chave de aplicativo válida.

Exemplo de uso em uma tag de imagem:

<img
    src="https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}"
    alt="Customized Product Preview"
    style="max-width: 100%; height: auto;" />

Webhooks são usados ​​pela Fabrixa para notificar seu sistema sobre eventos em tempo real - atualizações de pedidos ou criações. Quando ocorre um evento, a Fabrixa envia um webhook para o seu servidor contendo as informações relevantes. Seu servidor deve expor um endpoint POST público para lidar com webhooks recebidos.

O pedido webhook inclui os seguintes headers para ajudar a identificar e validar o pedido recebido:

{
  "content-type": "application/json",
  "user-agent": "Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)",
  "x-webhook-signature": "YmEwNjBhMGMyMzE3ZWQ5NGQ5NDYwOGVhNzNhMjQ4M2MyODZkZmI3NTQ1YzYxYjdkMzNhZjgzYzBmMTkxYTAxMw==",
  "x-webhook-topic": "order.updated"
}

Detalhamento do cabeçalho

• content-type - sempre definido como application/json para webhooks.
• x-webhook-signature - a assinatura HMAC-SHA256 para verificação de solicitação.
• x-webhook-topic - o tipo de evento ou tópico do webhook. Por exemplo:
  • order.created - acionado quando um novo pedido é criado.
  • order.updated - acionado quando um pedido existente é atualizado.

Os webhooks são enviados com o User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); se o seu endpoint filtra tráfego automatizado, permita-o. Para ter a certeza de que um pedido vem da Fabrixa, verifique x-webhook-signature.

Os webhooks da Fabrixa notificam o seu sistema sobre alterações no estado da encomenda ou atividade. Cada webhook é acionado por um valor específico de x-webhook-topic. Topics atualmente suportados:

Um exemplo de carga enviada com o webhook. Esta carga representa uma atualização do pedido:

{
  "id": 23069,
  "number": "1250211835",
  "comments": null,
  "is_archived": false,
  "status": "accepted",
  "fulfillment_status": "fulfilled",
  "purchased_at": "2025-04-17T16:17:21.000000Z",
  "created_at": "2025-04-17T16:17:23.000000Z",
  "updated_at": "2025-04-18T07:43:52.000000Z",
  "rows": [
    {
      "id": 27954,
      "quantity": 1,
      "client_barcode": "1250211835",
      "fulfillment_status": "fulfilled",
      "variant": {
        "id": 293457,
        "name": "Sherpa fleece deken",
        "subtitle": "100x150",
        "SKU": "SFD787231",
        "product": {
          "id": 5319,
          "name": "Sherpa fleece deken",
          "subtitle": "Sherpa fleece deken"
        }
      },
      "sources": [
        {
          "type": "print",
          "url": "https://storage.googleapis.com/fabrixa-api/storage/99b10aaa-df4d-47e4-9bc9-b1d6a785df4c/orders/merchandise-sources/120002795400.pdf",
          "properties": {
            "fill_style": "contain"
          }
        }
      ]
    }
  ],
  "shipments": [
    {
      "id": 4182,
      "carrier": "PostNL",
      "method": "Standard",
      "status": "registered",
      "tracking_number": "3SABCD1234567",
      "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB",
      "packages": [
        {
          "tracking_number": "3SABCD1234567",
          "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB"
        }
      ],
      "expected_delivery_date": "2025-04-22",
      "created_at": "2025-04-18T07:43:50.000000Z"
    }
  ]
}

Assim que a encomenda é enviada, shipments lista cada envio com a transportadora (carrier), o método de envio (method), o estado (status: pending, registered, collected, in transit, delivered, failed, returned ou canceled) e o seguimento: tracking_number e tracking_url, e o mesmo para cada volume em packages quando um envio tem vários. É enviado um webhook order.updated sempre que o estado ou o seguimento de um envio muda, e GET /orders/{order_id} devolve o mesmo campo.

Para garantir que o pedido webhook é autêntico e não foi alterado, verifique o header x-webhook-signature. Recalcule a signature HMAC-SHA256 usando o raw request payload e a sua secret key, e compare com a signature recebida.

Exemplo de PHP bruto

$payload = file_get_contents('php://input');
$yourSecret = 'your-secret-key';
$expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
$receivedSignature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Exemplo de Laravel

public function handle(Request $request)
{
    $yourSecret = 'your-secret-key';
    $payload = $request->getContent();
    $expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
    $receivedSignature = $request->header('x-webhook-signature');

    if (!hash_equals($expectedSignature, $receivedSignature)) {
        abort(403, 'Invalid signature');
    }

    // Continue processing...
}

Substitua $yourSecret pela sua chave secreta compartilhada. Sempre use hash_equals para comparar assinaturas para mitigar ataques de temporização.

Por padrão, os webhooks são desativados após 10 tentativas de entrega malsucedidas. Se o seu endpoint retornar um status de falha, como 404 ou qualquer erro 5xx, o webhook tentará novamente por um total de 10 vezes. Se continuar retornando um código de resposta diferente de 2xx ou não 3xx, ele será desativado. As respostas bem-sucedidas incluem:

• 2xx - indica processamento bem-sucedido, por exemplo. 200 OK.
• 301 e 302 - respostas de redirecionamento indicando que o webhook foi tratado ou encaminhado com sucesso.

Recomendamos fortemente que seu endpoint retorne um código de status 200 OK o mais rápido possível para confirmar o recebimento bem-sucedido do webhook. Embora qualquer resposta 2xx ou 3xx seja considerada bem-sucedida, 200 é a mais comumente usada e confiável.

Para evitar tempos limite de entrega ou novas tentativas, retorne 200 OK imediatamente e lide com o processamento de carga útil do webhook de forma assíncrona, por exemplo, por meio de uma tarefa ou fila em segundo plano. Se o seu endpoint demorar muito para responder, ele poderá ser considerado uma falha, mesmo que a resposta seja bem-sucedida.

Respostas com códigos de status no intervalo 4xx ou 5xx, ou tempos limite, acionarão novas tentativas de acordo com o mecanismo de novas tentativas.