Referencia de la API Fabrixa Integration

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.

El modo sandbox te permite probar tu integración de principio a fin antes de que se produzca o se cobre ningún pedido real. Se aplica a toda tu cuenta: los pedidos de todos los canales de venta, incluidos la Integration API y las tiendas Shopify y WooCommerce conectadas, no se producen ni se cargan a tu saldo. Tu cuenta está en modo sandbox mientras su estado sea pendiente de activación.

En modo sandbox puedes:

• conectar tu tienda Shopify o WooCommerce, o crear un canal de Integration API;
• añadir productos y comprobar precios y estimaciones de envío;
• importar, crear, actualizar y cancelar pedidos;
• comprobar que ninguno de estos pedidos se produce ni se carga a tu saldo;
• verificar la entrega de webhooks y las firmas.

Para probar pedidos, añade productos del catálogo de Fabrixa: abre un producto, haz clic en Vender este producto y elige variantes y diseños. Después aparecen en Mis productos.

Para pasar tu cuenta a modo sandbox, abre Platform, ve a Configuración → Empresa → Modo sandbox y haz clic en Pasar a modo sandbox. También puedes activarlo al añadir un nuevo canal de venta, incluido un canal de Integration API, o escribir a support@fabrixa.com y la pasaremos nosotros a modo sandbox. El modo sandbox solo está disponible para cuentas activas.

Cuando estés listo, activa tú mismo la cuenta en Platform en Configuración → Empresa → Modo sandbox. También puedes escribir a support@fabrixa.com y la activaremos por ti. Tus tiendas conectadas y las credenciales de API siguen funcionando, así que no hay que reconfigurar nada.

Tras la activación, todos los pedidos nuevos pasan a producción y se cargan a tu saldo. Los pedidos creados antes de la activación siguen siendo de prueba: nunca se producen ni se cobran, ni siquiera después de la activación.

El catálogo es todo lo que Fabrixa produce. Tus productos son los productos del catálogo que has añadido a tu cuenta de Fabrixa, con tus propios nombres, descripciones, imágenes y SKU. Una línea de pedido nombra una variante de producto - una talla o versión de un producto - por su sku o variant_id: una variante de uno de tus productos, o una variante del catálogo pedida directamente.

Para listar los productos que Fabrixa produce, envía una solicitud GET a https://api.fabrixa.com/v2/integration/catalog/products con tus credenciales. Lista los productos activos que tienen una variante que un socio de impresión produce actualmente, y solo esas variantes, cada una con su SKU, precio de venta, dimensiones y valores de opción.

Parámetros de consulta

Solicitud de muestra

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'

Respuesta de muestra

{
    "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 de la respuesta

Para listar las categorías en las que se organiza el catálogo, envía una solicitud GET a https://api.fabrixa.com/v2/integration/catalog/categories con tus credenciales. La respuesta contiene las categorías de primer nivel, cada una con sus subcategorías anidadas en sub_categories y el número de productos del catálogo que contiene en products_count. Pasa el id de una categoría como category_id al explorar el catálogo, o el id de una categoría de primer nivel como parent_category_id para obtener de una vez los productos de todas sus subcategorías.

Parámetros de consulta

Solicitud de muestra

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'

Respuesta de muestra

{
    "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 los productos de tu cuenta, envía una solicitud GET a https://api.fabrixa.com/v2/integration/products con tus credenciales. Tus productos son los productos del catálogo que añadiste a tu cuenta de Fabrixa: llevan los nombres, descripciones e imágenes que les diste allí, y sus variantes los valores de SKU que elegiste. Solo se listan los productos activos, diez por página a menos que pases limit.

Parámetros de consulta

Solicitud de muestra

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'

Respuesta de muestra

{
    "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 leer un solo producto, envía una solicitud GET a https://api.fabrixa.com/v2/integration/products/{product_id}, donde {product_id} es su id. La respuesta lleva los mismos campos que la lista. Un producto que no está en tu cuenta, incluso uno del catálogo, responde 404 Not Found con el mensaje Product not found.

Campos de la respuesta

Una variante es una versión de un producto que se puede pedir - una talla, un color - y lo que nombra una línea de pedido, por sku o por variant_id. Para leer una variante de uno de tus productos, envía una solicitud GET a https://api.fabrixa.com/v2/integration/variants/{variant_id}, donde {variant_id} es su id. Una variante de un producto que no está en tu cuenta responde 404 Not Found con el mensaje Variant not found.

Solicitud de muestra

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'

Respuesta de muestra

{
    "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 de la respuesta

Una línea de pedido para esta variante, con un PDF cuyas páginas son sus capas:

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

Qué variantes se pueden pedir

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

Respuesta de muestra

{
    "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 actualizar un pedido, envía una solicitud PATCH a https://api.fabrixa.com/v2/integration/orders/{order_id}, donde {order_id} es el id del pedido en Fabrixa. Solo cambian los campos que envíes y el estado del pedido se mantiene. La respuesta contiene el pedido actualizado. Puedes cambiar:

Solicitud de muestra

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

Respuesta de muestra

{
    "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 un pedido, envía una solicitud POST sin body a https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, donde {order_id} es el id del pedido en Fabrixa (el campo numérico id del pedido), no tu número de pedido. La respuesta contiene el pedido con el estado canceled y se envía un webhook order.updated.

Respuesta de muestra

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

Si el pedido no se puede cancelar, la API responde con 412 Precondition Failed y un mensaje con el motivo: su estado actual no lo permite (el estado aparece en el mensaje) o la producción ya ha comenzado.

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

Un pedido se sigue con tres estados: el status del pedido, su estado de producción fulfillment_status y el status de cada envío en shipments. Cada cambio se envía en el webhook order.updated y lo devuelve GET /orders/{order_id}.

Estados de pedido

El status de un pedido, en el orden en que se alcanza:

• imported - el pedido se ha recibido a través de la API. Todo pedido empieza aquí.
• on hold - el saldo no cubre el coste del pedido. Cuando se recarga, el pedido vuelve a imported y continúa.
• accepted - el pedido ha sido aceptado y pasa a producción.
• completed (definitivo) - todos los artículos se han producido.
• canceled (definitivo) - el pedido ha sido cancelado. Es posible mientras está imported, accepted u on hold y la producción aún no ha empezado.

Estados de cumplimiento

El fulfillment_status de un pedido y de cada línea del pedido, en el orden en que se alcanza. Solo avanza, nunca retrocede:

• unfulfilled - la producción no ha empezado.
• scheduled - el pedido está planificado en un lote de producción. A partir de aquí ya no se puede cancelar.
• processing - la producción está en curso.
• partially fulfilled - algunos artículos están terminados, el resto sigue en producción.
• fulfilled (definitivo) - todos los artículos están terminados. El status del pedido pasa entonces a completed.

Un pedido en su conjunto nunca se rechaza. Un artículo concreto puede rechazarse en el control de calidad durante la producción. Entonces se vuelve a imprimir: vuelve a unfulfilled y pasa de nuevo por producción, mientras el pedido mantiene su estado y continúa cuando el artículo está terminado.

Estados de envío

El status de cada envío en shipments, en el orden en que se alcanza:

• pending - el envío se está preparando.
• registered - la etiqueta se ha creado con el transportista.
• collected - el transportista ha recogido el paquete.
• in transit - el paquete está en camino.
• delivered (definitivo) - el paquete ha sido entregado.

Excepciones:

• failed - el transportista ha informado de un problema.
• returned (definitivo) - el paquete nos ha sido devuelto.
• canceled (definitivo) - el envío ha sido cancelado.

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.

Conoce cuánto costará el envío de un pedido y cuánto tiempo estará en camino antes de hacerlo, calculado con las mismas reglas que Fabrixa aplica al propio pedido.

Para saber a qué países se puede enviar una variante de producto, envía una solicitud GET a https://api.fabrixa.com/v2/integration/shipping/countries con tus credenciales. La lista contiene, ordenados por nombre, los países a los que la ubicación que produce la variante tiene una tarifa de envío para un paquete de envío en el que se puede empaquetar la variante. Un país que no figura en la lista no tiene tarifa de envío para la variante.

Parámetros de consulta

Solicitud de muestra

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'

Respuesta de muestra

{
    "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 de la respuesta

Para saber cuánto costaría el envío de una variante de producto y cuánto tiempo estaría en camino, envía una solicitud GET a https://api.fabrixa.com/v2/integration/shipping/estimate con tus credenciales. La estimación sigue las reglas con las que se calcula el precio de un pedido: las unidades se empaquetan en los paquetes de envío de la ubicación que produce la variante, y el precio de cada paquete se calcula según la ruta desde esa ubicación hasta el país de destino. No se pide ni se reserva nada, y el precio de un pedido se calcula cuando se realiza, así que su envío puede costar distinto si las tarifas cambian entretanto.

Parámetros de consulta

Solicitud de muestra

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'

Respuesta de muestra

{
    "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 de la respuesta

Una solicitud que no supera la validación se responde con 400 Bad Request y el motivo de cada campo, con los mismos mensajes que una línea de pedido, por ejemplo The variant not found. Cuando ningún paquete de envío puede contener las unidades, la respuesta es 400 Bad Request con el mensaje No shipping package can carry the variant.

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.
• locale (opcional): el idioma de la interfaz de Studio y de sus mensajes de error, p. ej. de_DE o de. Sin él, Studio se abre en el idioma del navegador del comprador si es compatible; si no, en inglés.

El encabezado de Studio muestra el nombre del producto tal como está en su tienda, el mismo título que ven sus clientes, con las opciones de la variante elegida debajo. Es la copia propia del producto en su tienda, así que un nombre que edite en Fabrixa también aparece en Studio; locale no lo traduce.

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",
  "user-agent": "Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)",
  "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 se envían con el User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); si tu endpoint filtra el tráfico automatizado, permítelo. Para asegurarte de que una solicitud viene de Fabrixa, verifica x-webhook-signature.

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:

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

Cuando el pedido se envía, shipments enumera cada envío con su transportista (carrier), método de envío (method), estado (status: pending, registered, collected, in transit, delivered, failed, returned o canceled) y seguimiento: tracking_number y tracking_url, y lo mismo para cada paquete en packages cuando un envío tiene varios. Se envía un webhook order.updated cada vez que cambia el estado o el seguimiento de un envío, y GET /orders/{order_id} devuelve el mismo campo.

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.