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.

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": "0647185332"
  },
  "shipping_address": {
    "address": "Pierre cuypershof",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0647185332"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SYZXG1585577",
    "tracking_url": "https://postnl.nl/tracktrace/3SYZXG1585577",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

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.

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.

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",
  "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 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:

Status do pedido

• Concluído - o pedido foi enviado ou retirado e o recebimento foi confirmado. Para produtos digitais, o cliente pagou e os arquivos estão disponíveis para download.
• Cancelado - pagamento cancelado pelo cliente; a transação não foi concluída.
• Em espera - o pedido está temporariamente bloqueado.
• Importado - o pedido foi importado para a plataforma.

Status de cumprimento

• Não atendido - o pedido ainda não foi preparado ou enviado.
• Atendido parcialmente - alguns itens foram processados ou enviados, outros ainda pendentes.
• Programado - o pedido está planejado e agendado para processamento.
• Rejeitado - a solicitação de atendimento foi recusada, geralmente devido a detalhes inválidos do pedido ou indisponibilidade.
• Atendido - o pedido foi totalmente processado e entregue ou disponibilizado ao cliente.

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": "imported",
  "fulfillment_status": "unfulfilled",
  "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": "unfulfilled",
      "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"
          }
        }
      ]
    }
  ]
}

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.