Saltar para o conteúdo principal

Guia de integração

Guia de integração Fabrixa API - autenticação, primeira encomenda, tratamento de webhooks, recuperação de erros
DEVELOPERS - GUIA DE INTEGRAÇÃO

Autenticação para cumprimento em quinze minutos.

Passo-a-passo do Fabrixa REST API: autenticar, listar produtos disponíveis, fazer uma encomenda, registar um webhook, tratar os eventos do ciclo de vida. JSON sobre HTTPS, autenticação de token de portador, pedidos idempotentes, webhooks seguros para repetição. Sem surpresas.

REST + JSON - AUTH DO PORTADOR - IDEMPOTENTE - ORIENTADO POR WEBHOOK

PRÉ-REQUISITOS

O que é necessário antes de começar.

01
API CHAVE

Emitida a partir do painel de controlo da sua conta Fabrixa. Chave Sandbox para desenvolvimento, chave de produção para encomendas em direto. Ambos são tokens ao portador.

02
PONTO DE EXTREMIDADE DO WEBHOOK

Um ponto de extremidade HTTPS acessível publicamente do seu lado que pode aceitar pedidos JSON POST. Localhost funciona em desenvolvimento através de ferramentas de tunelamento.

03
FICHEIROS DE OBRAS DE ARTE

Trabalho artístico pronto para impressão acessível através de URL HTTPS. Adobe Illustrator, Photoshop, raster ou vetor. Vamos buscar o ficheiro quando processamos o trabalho de impressão.

PASSO 1 - AUTENTICAR

Testar a chave API com uma chamada em espera.

Autenticação de token de urso. O URL de base da Sandbox é https://sandbox.api.fabrixa.com/v1; a produção troca o subdomínio.

GET /v1/account
# Verificar a autenticação e o acesso à conta
enrolar https://sandbox.api.fabrixa.com/v1/account \
  -H "Autorização: Portador $FABRIXA_API_KEY" \
  -H "Aceitar: aplicação/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "ambiente": "caixa de areia",
  "nível": "produção",
  "url_webhook": nulo
}

Um 401 significa que a chave está errada ou foi revogada. Gerar uma nova a partir do painel de controlo. Um 403 significa que a chave é válida, mas falta-lhe permissão para o recurso (raro em /conta).

PASSO 2 - LISTA DE PRODUTOS

Descubra os SKUs disponíveis para a sua conta.

Devolve o catálogo com IDs de produtos, materiais de base, tamanhos e níveis de preços. Armazenamento em cache localmente; a atualização do catálogo não é feita por pedido.

GET /v1/produtos
OBTER /v1/produtos?categoria=vestuário&página=1&limite=20

# Resposta (truncada)
{
  "dados": [
    {
      "product_id": "prod_tee_unisex_aop",
      "categoria": "vestuário.tees-tops",
      "nome": "T-shirt unissexo AOP",
      "base": "organic-cotton-160gsm",
      "tamanhos": ["XS","S","M","L","XL","XXL"],
      "imprimir": "reactive-aop",
      "production_hub": "PT",
      "lead_time_days": { "min": 6, "max": 9 }
    }
  ],
  "página": 1,
  "has_more": verdadeiro
}
PASSO 3 - EFECTUAR UMA ENCOMENDA

Criação de ordem idempotente.

Conjunto Chave de Idempotência em cada pedido de encomenda - seguro para repetir a mesma chamada sem criar encomendas duplicadas. Utilize um UUID por ordem lógica do seu lado.

POST /v1/encomendas
POSTAR /v1/encomendas
Chave de Idempotência: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "order_ref": "shopify-1042",
  "itens": [
    {
      "product_id": "prod_tee_unisex_aop",
      "tamanho": "L",
      "quantidade": 2,
      "url_da_obra": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "destinatário": {
    "nome": "Lena Costa",
    "linha_de_endereço1": "Rua das Flores 12",
    "cidade": "Porto",
    "país": "PT",
    "código_postal": "4050-262"
  },
  "embalagem": "etiqueta branca"
}

# 201 Criado
{
  "order_id": "ord_8e6f4b2a",
  "estado": "recebido",
  "estimated_dispatch": "2026-05-15",
  "webhook_events": ["order.printed","order.dispatched"]
}
PASSO 4 - PONTO DE EXTREMIDADE DO WEBHOOK

Subscrever o ciclo de vida da encomenda.

Defina o URL do webhook uma vez ao nível da conta. Todos os eventos do ciclo de vida da encomenda POST para esse URL. Verificar a assinatura HMAC antes do processamento.

PUT /v1/account/webhook
PUT /v1/conta/webhook

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "eventos": [
    "order.received",
    "order.printed",
    "order.dispatched",
    "order.failed"
  ]
}

Carga do Webhook # (POST para o seu ponto final)
{
  "evento": "order.dispatched",
  "order_id": "ord_8e6f4b2a",
  "order_ref": "shopify-1042",
  "carimbo de data/hora": "2026-05-15T11:32:08Z",
  "rastreio": {
    "transportadora": "DHL",
    "tracking_number": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Referência completa do evento e verificação da assinatura no página de webhooks.

TRATAMENTO DE ERROS E LIMITES DE TAXA

O que esperar quando as coisas correm mal.

FORMA DA RESPOSTA AO ERRO

Os erros são JSON, nunca HTML.

Resposta ao erro
{
  "erro": {
    "código": "obra_de_arte inacessível",
    "mensagem": "GET on artwork_url failed (timeout 30s)",
    "request_id": "req_94kQ7r2L",
    "repetível": verdadeiro
  }
}

Os códigos são cordas estáveis - seguras para ligar. repetível: verdadeiro significa que é seguro tentar novamente com a mesma chave de idempotência.

LIMITES DE TAXA

Janela deslizante, os cabeçalhos indicam-lhe o orçamento.

  • Caixa de areia: 60 req / minuto por chave
  • Produção: 600 req / minuto por chave (aumento a pedido)
  • Cabeçalhos: X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 resposta sobre o excesso com Tentar novamente depois segundos
  • As entregas de webhooks não contam para o seu orçamento de entrada
PRESO?

Falar com um engenheiro de soluções.

Para suporte de integração, questões de sandbox-key, requisitos personalizados ou planeamento de capacidade - canal técnico SE em vez da linha de vendas. Resposta média em um dia útil.

Carrinho (0 artigos)

Crie a sua conta