Para acceder a la API Integration, autentica las solicitudes usando un Application Access Token y una Application Key:

Encabezado de autorización

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Encabezado de clave de aplicación

X-Application-Key: APPLICATION_KEY

Ejemplo 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'

Reemplace APPLICATION_ACCESS_TOKEN con su token de acceso real y APPLICATION_KEY con su clave de aplicación real.

Los endpoints de la API Integration están organizados por tipo de recurso y siguen el estilo REST. Cada endpoint representa un recurso y las acciones se realizan con métodos HTTP estándar.

Todas las solicitudes y respuestas de la API Integration usan JSON, proporcionando una interfaz consistente y fácil de usar.

Para obtener detalles completos sobre cada punto final, incluidos ejemplos de solicitudes y respuestas, consulte nuestro Swagger documentation.

Formato de respuesta

Todos los puntos finales devuelven datos en un formato estandarizado con estos 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"
    }
  ]
}

Descripción de los objetos de respuesta

Todas las solicitudes de API devuelven códigos de estado HTTP que brindan información sobre la respuesta.

Cuerpo de respuesta de error

Un ejemplo de un cuerpo de respuesta de error:

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

errors contiene detalles sobre lo que falló. La matriz messages enumera descripciones de errores. Para una solicitud incorrecta, recibirá los nombres de los campos que no superaron la validación.

La API de integración admite un límite de 30 solicitudes por aplicación por minuto.

Si supera este límite recibirá una respuesta 429 Too Many Requests.

Todas las respuestas de la API de integración incluyen el encabezado X-RateLimit-Remaining, cuántas solicitudes aún puede realizar el cliente, y el encabezado X-RateLimit-Limit, el total permitido por minuto.

Crea pedidos en Fabrixa desde tu tienda o plataforma, adjunta los archivos de impresión requeridos y sigue cada artículo durante el fulfillment.

Para crear un pedido mediante la Fabrixa Integration API, envía una solicitud POST a https://api.fabrixa.com/v2/integration/orders. El request body debe incluir:

Solicitar estructura corporal

Solicitud de muestra

{
  "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 obtener el estado de fulfillment de un pedido específico, envía una solicitud GET a https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. La respuesta proporciona los fulfillments asociados al pedido, incluyendo estado de cada artículo, detalles del producto y progreso de producción.

Respuesta de muestra

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

La respuesta incluye una lista de cumplimientos, cada uno de los cuales proporciona:

Cada registro de cumplimiento corresponde a un producto específico o variante de producto dentro del pedido, y cada copia del producto en el pedido tiene su propio registro de cumplimiento: cada artículo se rastrea individualmente durante toda la producción.

Si no se devuelve ningún cumplimiento para un pedido, el pedido aún no ha entrado en la etapa de procesamiento.

Al incluir source files en el pedido, asegúrate de que cumplen los siguientes requisitos:

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

Requisitos PDF y orden de páginas

El orden de las páginas del PDF es importante. Las páginas se relacionan con las capas de productos por posición y el orden de páginas esperado depende del tipo de producto. Asegúrese de que las páginas de su PDF sigan la secuencia de capas correcta para el producto que está enviando.

Importante: cada página PDF debe coincidir con las dimensiones requeridas para su capa de producto y estar orientada correctamente. Coloque la obra de arte de modo que la parte superior del diseño se alinee con la parte superior de la página. El tamaño u orientación de página incorrectos pueden causar problemas de escala, rotación o alineación en producción.

Fabrixa Studio es una herramienta que permite a los usuarios personalizar y personalizar productos sin problemas en tiempo real con una interfaz intuitiva donde los usuarios pueden crear o cargar sus propios diseños.

Fabrixa Studio es ideal para empresas que ofrecen productos personalizados, ya que permite a los clientes visualizar sus diseños antes de finalizar los pedidos.

Puedes incrustar Fabrixa Studio en tu sitio web usando un iframe. Esto permite a los clientes personalizar productos directamente en tu sitio durante el checkout.

Ejemplo de iframe para incrustar 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>

Reemplace los valores de product_sku, cart_item_key y application_key con sus valores dinámicos.

• application_key: clave única para autenticarse en la API de integración.
• product_sku: el SKU de la variante del producto, recuperado de la API de integración.
• cart_item_key: un valor único de la plataforma de inserción que identifica el artículo del carrito asociado con el producto. Se utiliza para guardar las personalizaciones del usuario; durante la creación del pedido, identifica las personalizaciones guardadas y las asigna al pedido. Vea el ejemplo a continuación.

Solicitud para crear un pedido con 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": {
    "...": "..."
  }
}

Cuando se hace clic en el botón Agregar al carrito dentro del iframe, se ejecuta el siguiente comando:

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

De manera similar, cuando se hace clic en el botón Atrás:

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

El método postMessage facilita la comunicación entre orígenes entre el iframe y su ventana principal, lo que le permite notificar al padre sobre acciones específicas del usuario.

El primer argumento de postMessage son los datos que desea enviar. La cadena 'customizationFinished' indica que el usuario ha finalizado la personalización y está agregando el producto al carrito. 'closeButtonClicked' indica que el usuario ha elegido regresar.

En la ventana principal, escuche estos mensajes usando el detector 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.');
        }
    }
});

Siempre verifique el origin de los mensajes entrantes para asegurarse de que provengan de una fuente confiable. Dependiendo del mensaje recibido, realice las acciones necesarias: actualice la interfaz de usuario, procese el carrito, etc. Validar origin es crucial para la seguridad: evita que scripts no autorizados interactúen con su aplicación.

Una vez completada la personalización, muestre el diseño final utilizando la URL de vista previa a continuación. Esta URL devuelve una imagen del producto personalizado, adecuada como valor src en una etiqueta <img>. Ideal para mostrar el producto personalizado en su carrito, resumen de pedido o en cualquier lugar de la interfaz de su tienda.

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

Reemplace {CART_ITEM_KEY} con la clave de artículo del carrito real y {APPLICATION_KEY} con su clave de aplicación válida.

Uso de ejemplo en una etiqueta de imagen:

<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;" />

Fabrixa utiliza webhooks para notificar a su sistema sobre eventos en tiempo real: actualizaciones de pedidos o creaciones. Cuando ocurre un evento, Fabrixa envía un webhook a su servidor que contiene la información relevante. Su servidor debe exponer un punto final POST público para manejar los webhooks entrantes.

La solicitud webhook incluye los siguientes headers para ayudarte a identificar y validar la solicitud entrante:

{
  "content-type": "application/json",
  "x-webhook-signature": "YmEwNjBhMGMyMzE3ZWQ5NGQ5NDYwOGVhNzNhMjQ4M2MyODZkZmI3NTQ1YzYxYjdkMzNhZjgzYzBmMTkxYTAxMw==",
  "x-webhook-topic": "order.updated"
}

Desglose del encabezado

• content-type: siempre configurado en application/json para webhooks.
• x-webhook-signature: la firma HMAC-SHA256 para la verificación de solicitudes.
• x-webhook-topic: el tipo de evento o tema del webhook. Por ejemplo:
  • order.created: se activa cuando se crea un nuevo pedido.
  • order.updated: se activa cuando se actualiza un pedido existente.

Los webhooks de Fabrixa notifican a tu sistema cambios en el estado del pedido o actividad. Cada webhook se activa mediante un valor específico de x-webhook-topic. Topics admitidos actualmente:

Estados de pedido

• Completado: el pedido se envió o se recogió y se confirma la recepción. Para productos digitales, el cliente ha pagado y los archivos están disponibles para descargar.
• Cancelado: el cliente canceló el pago; la transacción no se completó.
• En espera: el pedido está bloqueado temporalmente.
• Importado: el pedido se importó a la plataforma.

Estados de cumplimiento

• No cumplido: el pedido aún no se ha preparado ni enviado.
• Parcialmente cumplido: algunos artículos se han procesado o enviado, otros aún están pendientes.
• Programado: el pedido está planificado y programado para su procesamiento.
• Rechazado: la solicitud de cumplimiento se ha rechazado, a menudo debido a detalles del pedido no válidos o indisponibilidad.
• Cumplido: el pedido ha sido completamente procesado y entregado o puesto a disposición del cliente.

Un ejemplo de la carga útil enviada con el webhook. Esta carga útil representa una actualización de 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 asegurar que la solicitud webhook es auténtica y no ha sido alterada, verifica el header x-webhook-signature. Recalcula la signature HMAC-SHA256 usando el raw request payload y tu secret key, y compárala con la signature recibida.

Ejemplo de PHP sin formato

$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');
}

Ejemplo 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...
}

Reemplace $yourSecret con su clave secreta compartida. Utilice siempre hash_equals para comparar firmas y mitigar los ataques de sincronización.

Los webhooks se desactivan de forma predeterminada después de 10 intentos de entrega fallidos. Si su punto final devuelve un estado fallido como 404 o cualquier error de 5xx, el webhook lo volverá a intentar un total de 10 veces. Si continúa devolviendo un código de respuesta que no sea 2xx o 3xx, se desactivará. Las respuestas exitosas incluyen:

• 2xx: indica un procesamiento exitoso, p. 200 OK.
• 301 y 302: respuestas de redirección que indican que el webhook se ha manejado o reenviado correctamente.

Recomendamos encarecidamente que su punto final devuelva un código de estado 200 OK lo más rápido posible para acusar recibo del webhook. Si bien cualquier respuesta 2xx o 3xx se considera exitosa, 200 es la más utilizada y confiable.

Para evitar tiempos de espera de entrega o reintentos, devuelva 200 OK inmediatamente y maneje el procesamiento de carga útil del webhook de forma asíncrona, por ejemplo, a través de un trabajo en segundo plano o una cola. Si su punto final tarda demasiado en responder, se puede considerar un error incluso si la respuesta finalmente es exitosa.

Las respuestas con códigos de estado en el rango 4xx o 5xx, o tiempos de espera, activarán reintentos según el mecanismo de reintento.