Ir al contenido principal

Guía de integración

Guía de integración Fabrixa API - auth, first order, webhook handling, error recovery
DESARROLLADORES - GUÍA DE INTEGRACIÓN

De la autorización al cumplimiento en quince minutos.

Copy-paste tutorial de la Fabrixa REST API: autenticar, lista de productos disponibles, realizar un pedido, registrar un webhook, gestionar los eventos del ciclo de vida. JSON sobre HTTPS, autenticación con token de portador, solicitudes idempotentes, webhooks seguros contra reintentos. Sin sorpresas.

REST + JSON - BEARER AUTH - IDEMPOTENT - WEBHOOK-DRIVEN

PREREQUISITOS

Lo que necesitas antes de empezar.

01
LLAVE API

Se emite desde el panel de control de su cuenta Fabrixa. Clave Sandbox para desarrollo, clave de producción para pedidos reales. Ambas son fichas al portador.

02
PUNTO FINAL DE WEBHOOK

Un punto final HTTPS accesible públicamente en tu lado que pueda aceptar peticiones POST JSON. Localhost funciona en dev a través de herramientas de túnel.

03
ARCHIVOS DE OBRAS DE ARTE

Material gráfico listo para imprimir accesible a través de una URL HTTPS. Adobe Illustrator, Photoshop, trama o vector. Obtenemos el archivo cuando procesamos el trabajo de impresión.

PASO 1 - AUTENTIFICARSE

Pruebe la tecla API con una llamada hola.

Autenticación por token de portador. La URL base del Sandbox es https://sandbox.api.fabrixa.com/v1; la producción intercambia el subdominio.

GET /v1/cuenta
# Verificar la autenticidad y el acceso a la cuenta
rizo https://sandbox.api.fabrixa.com/v1/account \
  -H "Autorización: Portador $FABRIXA_API_KEY" \
  -H "Accept: application/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "medio ambiente": "caja de arena",
  "nivel": "producción",
  "webhook_url": null
}

Un 401 significa que la clave es errónea o está revocada. Genera una nueva desde el panel de control. Un 403 significa que la clave es válida pero que carece de permiso para el recurso (poco frecuente en /cuenta).

PASO 2 - LISTA DE PRODUCTOS

Descubra los SKU disponibles en su cuenta.

Devuelve el catálogo con los ID de producto, materiales base, tallas y niveles de precios. Caché local; la actualización del catálogo no es por solicitud.

GET /v1/productos
GET /v1/products?category=apparel&page=1&limit=20

# Respuesta (truncada)
{
  "datos": [
    {
      "product_id": "prod_tee_unisex_aop",
      "categoría": "ropa.camisetas",
      "nombre": "Camiseta unisex AOP",
      "base": "organic-cotton-160gsm",
      "tamaños": ["XS","S","M","L","XL","XXL"],
      "imprimir": "reactive-aop",
      "production_hub": "PT",
      "lead_time_days": { "min": 6, "max": 9 }
    }
  ],
  "página": 1,
  "has_more": verdadero
}
PASO 3 - HACER UN PEDIDO

Creación de orden idempotente.

Establecer Idempotencia-Clave en cada solicitud de pedido - seguro para reintentar la misma llamada sin crear pedidos duplicados. Utilice un UUID por orden lógica en su lado.

POST /v1/pedidos
POST /v1/pedidos
Idempotencia-Clave: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "pedido_ref": "shopify-1042",
  "artículos": [
    {
      "product_id": "prod_tee_unisex_aop",
      "tamaño": "L",
      "cantidad": 2,
      "url_obra_de_arte": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "destinatario": {
    "nombre": "Lena Costa",
    "dirección_línea1": "Rua das Flores 12",
    "ciudad": "Oporto",
    "país": "PT",
    "código postal": "4050-262"
  },
  "embalaje": "marca blanca"
}

# 201 Creado
{
  "order_id": "ord_8e6f4b2a",
  "status": "recibido",
  "envío_estimado": "2026-05-15",
  "webhook_events": ["pedido.impreso","pedido.expedido"]
}
PASO 4 - WEBHOOK ENDPOINT

Suscríbase al ciclo de vida del pedido.

Establezca la URL del webhook una vez a nivel de cuenta. Cada evento del ciclo de vida del pedido POST a esa URL. Verifique la firma HMAC antes de procesar.

PUT /v1/cuenta/webhook
PUT /v1/cuenta/webhook

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "eventos": [
    "pedido.recibido",
    "pedido.impreso",
    "pedido.expedido",
    "pedido.fallido"
  ]
}

# Carga útil del Webhook (POST a su endpoint)
{
  "evento": "pedido.expedido",
  "order_id": "ord_8e6f4b2a",
  "pedido_ref": "shopify-1042",
  "timestamp": "2026-05-15T11:32:08Z",
  "seguimiento": {
    "transportista": "DHL",
    "tracking_number": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Referencia completa del acontecimiento y verificación de la firma en el Página de webhooks.

TRATAMIENTO DE ERRORES Y LÍMITES DE VELOCIDAD

Qué esperar cuando las cosas van mal.

FORMA DE LA RESPUESTA DE ERROR

Los errores son JSON, nunca HTML.

Respuesta de error
{
  "error": {
    "código": "obra_inaccesible",
    "mensaje": "GET on artwork_url failed (timeout 30s)",
    "request_id": "req_94kQ7r2L",
    "reintentable": verdadero
  }
}

Los códigos son cadenas estables, seguras de encender. reintentable: true significa seguro volver a intentarlo con la misma clave de idempotencia.

LÍMITES TARIFARIOS

Ventana corredera, las cabeceras te indican el presupuesto.

  • Sandbox: 60 req / minuto por tecla
  • Producción: 600 req / minuto por llave (aumento a petición)
  • Cabeceras: X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 respuesta sobre el exceso con Reintentar después de segundos
  • Las entregas de Webhooks no cuentan para su presupuesto de entrada
¿ATACADO?

Hable con un ingeniero de soluciones.

Para soporte de integración, problemas de claves de sandbox, requisitos personalizados o planificación de capacidad - canal técnico SE en lugar de la línea de ventas. Respuesta media en un día laborable.

Carrito (0 artículos)

Crea tu cuenta