Encomende a partir do seu sistema

Em cinco passos

1. Peça ao estúdio uma conta de parceiro: recebe uma chave e as suas condições — em conta ou pré-pagamento, um limite de crédito, um desconto.
2. Envie cada imagem (POST /uploads) e guarde o id que recebe.
3. Orçamente a encomenda (POST /quote): cada linha, as opções de envio, o IVA, o total — e se entraria logo em produção.
4. Faça-a (POST /orders) com a sua referência e uma Idempotency-Key. É orçamentada de novo aqui; envie expected_total para que um preço que mudou seja recusado, nunca cobrado.
5. Acompanhe-a no seu webhook, ou pergunte GET /orders?updated_since= de vez em quando.

Uma conta de parceiro, uma chave, uma pergunta: info@xyz-prints.com.

Autenticação

Cada pedido leva a sua chave de parceiro no cabeçalho Authorization: Bearer <chave>. A chave só abre esta API, e só as suas encomendas e ficheiros. Guarde-a no seu servidor — nunca num navegador ou numa aplicação. O estúdio cria e revoga chaves: peça uma nova se ela for exposta. Pode também restringir a sua chave aos endereços de onde os seus servidores chamam, para que uma chave exposta não sirva em mais lado nenhum.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  https://www.xyz-prints.com/api/v1/partner

Os valores são em EUR com IVA incluído, como na loja; a taxa segue o país de entrega e o seu número de IVA, verificado no VIES. Os preços são sempre calculados aqui — o seu sistema nunca calcula valores.

Ficheiros

Envie cada imagem uma vez, como campo file de multipart/form-data. Formatos: tiff, jpg, png, pdf, psd, heic, bmp. Até 2048 MB por ficheiro; um pedido único leva até 8 MB, por isso envie o que for maior em partes. Um PDF dá um id por página. Um ficheiro não encomendado em 72 horas é apagado.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  -F "file=@harbour-at-dusk.tif" \
  https://www.xyz-prints.com/api/v1/partner/uploads

{
  "files": [
    {
      "id": "k3Fq9w2LxP0aZt7c",
      "name": "harbour-at-dusk.tif",
      "bytes": 88213504,
      "width_px": 7200,
      "height_px": 9000,
      "dpi": 300,
      "dpi_assumed": false,
      "colour": {
        "mode": "RGB",
        "bit_depth": 16,
        "profile": true,
        "assigned": null
      },
      "expires_at": "2026-09-28T10:00:00.000Z"
    }
  ]
}

Em partes: corte o ficheiro em partes do mesmo tamanho (a última pode ser menor) e envie cada uma por POST em multipart com session (o seu id para o ficheiro: até 30 letras, algarismos, - e _), index (a partir de 0), total, chunk_size, size (o ficheiro inteiro, em bytes), name e chunk. Cada parte responde 202; a última responde 201 com o ficheiro.

A resposta dá os píxeis da imagem, a resolução que declara e o seu perfil de cor. A resolução na impressão depende do tamanho encomendado: o orçamento avisa abaixo de 100 DPI, o que o estúdio considera uma impressão razoável.

O que se pode encomendar

GET /catalogue lista os ids de hoje para cada tipo de linha. Abaixo, a mesma lista, lida agora.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  https://www.xyz-prints.com/api/v1/partner/catalogue

{
  "kind": "print",
  "qty": 2,
  "paper_id": 101,
  "width_cm": 40,
  "height_cm": 50,
  "file": "upl_…",
  "fit": "fill",
  "border_cm": 2
}

{
  "kind": "product",
  "qty": 3,
  "product": "the-slug"
}

Orçamente

POST /quote aceita o corpo de uma encomenda, sem a referência, e não grava nada. Responde o preço de cada linha, as opções de envio, o IVA e o total, avisos sobre as imagens (resolução baixa, recorte) e would_be: o estado em que a encomenda começaria hoje, com as suas condições.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  -H "Content-Type: application/json" \
  -d @order.json \
  https://www.xyz-prints.com/api/v1/partner/quote

{
  "lines": [
    {
      "kind": "print",
      "qty": 2,
      "paper_id": 101,
      "width_cm": 40,
      "height_cm": 50,
      "file": "k3Fq9w2LxP0aZt7c",
      "fit": "fill",
      "border_cm": 2
    }
  ],
  "delivery": {
    "mode": "ship"
  },
  "ship_to": {
    "first_name": "Ana",
    "last_name": "Silva",
    "address_1": "Rua das Flores 12",
    "city": "Porto",
    "postcode": "4050-262",
    "country": "PT",
    "phone": "+351 912 345 678"
  },
  "note": "Gift — no invoice in the parcel."
}

{
  "quote": {
    "currency": "EUR",
    "lines": [
      {
        "kind": "print",
        "name": "Hahnemühle Photo Rag 308",
        "qty": 2,
        "unit_price": 54.12,
        "total": 108.24,
        "vat_rate": 23,
        "details": [
          {
            "name": "File",
            "value": "harbour-at-dusk.tif"
          },
          {
            "name": "Sheet",
            "value": "40 × 50 cm"
          },
          {
            "name": "Image",
            "value": "36 × 46 cm"
          }
        ]
      }
    ],
    "warnings": [
      {
        "line": 0,
        "code": "cropped",
        "message": "fill cuts 3.2% of the picture away to cover the print; send fit to keep all of it."
      }
    ],
    "delivery": {
      "mode": "ship",
      "service": "ctt_express",
      "label": "CTT Expresso",
      "options": [
        {
          "id": "ctt_express",
          "label": "CTT Expresso",
          "price": 12.05,
          "days": [
            1,
            2
          ]
        }
      ]
    },
    "totals": {
      "goods": 108.24,
      "discount": 0,
      "shipping": 12.05,
      "vat": 22.49,
      "total": 120.29
    },
    "vat": {
      "rate": 23,
      "exempt": false,
      "reason": null,
      "number": "PT509999999",
      "status": "valid_domestic"
    },
    "would_be": {
      "state": "in_production",
      "holds": []
    }
  }
}

Encomende

POST /orders exige o cabeçalho Idempotency-Key: repetir com a mesma chave devolve o primeiro resultado e nunca cria uma segunda encomenda. A sua referência também é única — uma segunda encomenda com ela é recusada e a primeira vem na resposta. Envie expected_total, o total que o /quote lhe deu, e um preço que entretanto mudou é recusado (409 price_changed) em vez de cobrado.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: SHOP-10482-1" \
  -d @order.json \
  https://www.xyz-prints.com/api/v1/partner/orders

{
  "reference": "SHOP-10482",
  "lines": [
    {
      "kind": "print",
      "qty": 2,
      "paper_id": 101,
      "width_cm": 40,
      "height_cm": 50,
      "file": "k3Fq9w2LxP0aZt7c",
      "fit": "fill",
      "border_cm": 2
    }
  ],
  "delivery": {
    "mode": "ship"
  },
  "ship_to": {
    "first_name": "Ana",
    "last_name": "Silva",
    "address_1": "Rua das Flores 12",
    "city": "Porto",
    "postcode": "4050-262",
    "country": "PT",
    "phone": "+351 912 345 678"
  },
  "note": "Gift — no invoice in the parcel.",
  "expected_total": 120.29
}

{
  "order": {
    "number": 6214,
    "reference": "SHOP-10482",
    "state": "in_production",
    "holds": [],
    "status": "processing",
    "created_at": "2026-09-25T10:04:11.000Z",
    "updated_at": "2026-09-25T10:04:11.000Z",
    "currency": "EUR",
    "payment": {
      "terms": "account",
      "state": "unpaid",
      "paid_at": null
    },
    "totals": {
      "goods": 108.24,
      "discount": 0,
      "shipping": 12.05,
      "vat": 22.49,
      "total": 120.29,
      "refunded": 0
    },
    "vat": {
      "rate": 23,
      "exempt": false,
      "reason": null,
      "number": "PT509999999"
    },
    "delivery": {
      "mode": "ship",
      "service": "CTT Expresso",
      "ship_to": {
        "first_name": "Ana",
        "last_name": "Silva",
        "address_1": "Rua das Flores 12",
        "city": "Porto",
        "postcode": "4050-262",
        "country": "PT",
        "phone": "+351 912 345 678"
      },
      "tracking": null
    },
    "invoice": null,
    "note": "Gift — no invoice in the parcel.",
    "lines": [
      {
        "kind": "print",
        "name": "Hahnemühle Photo Rag 308",
        "qty": 2,
        "unit_price": 54.12,
        "total": 108.24,
        "vat_rate": 23,
        "details": [
          {
            "name": "File",
            "value": "harbour-at-dusk.tif"
          },
          {
            "name": "Sheet",
            "value": "40 × 50 cm"
          },
          {
            "name": "Image",
            "value": "36 × 46 cm"
          }
        ],
        "file": "k3Fq9w2LxP0aZt7c"
      }
    ]
  },
  "warnings": [
    {
      "line": 0,
      "code": "cropped",
      "message": "fill cuts 3.2% of the picture away to cover the print; send fit to keep all of it."
    }
  ]
}

ship_to é o destinatário: first_name e last_name, ou company; address_1, city, postcode e country (duas letras); telefone e e-mail ajudam a transportadora. A fatura é emitida à sua empresa — o estúdio guarda-a na sua conta. delivery.service escolhe uma das opções de envio do /quote; sem ela, a primeira. O destinatário não recebe nada do estúdio, a não ser que o peça.

Pagamento e aceitação

Em conta: uma encomenda que passa todas as verificações entra logo em produção. É faturada a si e paga por transferência contra a fatura; o estúdio regista o pagamento.

Pré-pagamento: a encomenda espera pelo valor. payment.pay_url é a sua página de pagamento (cartão, MB WAY, PayPal…); paga, entra em produção sozinha.

Uma retenção mantém a encomenda fora de produção até o estúdio a libertar; holds diz porquê:

• review — A sua conta está configurada para uma pessoa ver cada encomenda primeiro.
• credit_limit — Esta encomenda leva o saldo em conta além do seu limite de crédito.
• no_credit_limit — A sua conta é a crédito, mas ainda não foi acordado um limite de crédito — o estúdio define-o e depois liberta a encomenda.

O estado de uma encomenda

Uma encomenda retida, ou ainda à espera do pagamento, pode ser cancelada: POST /orders/{number}/cancel. Já em produção, escreva ao estúdio.

Acompanhe

GET /orders/{number} lê uma encomenda; GET /orders?reference= encontra a sua pela sua referência. Para manter o seu sistema a par sem webhook, pergunte GET /orders?updated_since=<o último updated_at que viu>: todas as encomendas alteradas desde então, da alteração mais antiga.

curl \
  -H "Authorization: Bearer $XYZ_KEY" \
  "https://www.xyz-prints.com/api/v1/partner/orders?updated_since=2026-09-25T10:04:11.000Z"

Webhooks

Dê ao estúdio um endereço https e cada alteração às suas encomendas é enviada por POST para lá, em JSON, com a encomenda tal como está. Responda com um 2xx em 8 segundos. Cada mensagem é enviada uma vez: se esteve em baixo, GET /orders?updated_since= põe-no a par. As mensagens podem chegar fora de ordem — compare data.order.updated_at.

O «Enviar um teste» do estúdio envia o evento ping, assinado da mesma forma, sem encomenda.

{
  "id": "evt_6f1c0a9b2d3e4f5a6b7c8d9e",
  "event": "order.shipped",
  "created_at": "2026-09-27T15:31:02.000Z",
  "data": {
    "tracking": "EA123456789PT",
    "order": {
      "number": 6214,
      "reference": "SHOP-10482",
      "state": "shipped",
      "holds": [],
      "status": "processing",
      "created_at": "2026-09-25T10:04:11.000Z",
      "updated_at": "2026-09-25T10:04:11.000Z",
      "currency": "EUR",
      "payment": {
        "terms": "account",
        "state": "unpaid",
        "paid_at": null
      },
      "totals": {
        "goods": 108.24,
        "discount": 0,
        "shipping": 12.05,
        "vat": 22.49,
        "total": 120.29,
        "refunded": 0
      },
      "vat": {
        "rate": 23,
        "exempt": false,
        "reason": null,
        "number": "PT509999999"
      },
      "delivery": {
        "mode": "ship",
        "service": "CTT Expresso",
        "ship_to": {
          "first_name": "Ana",
          "last_name": "Silva",
          "address_1": "Rua das Flores 12",
          "city": "Porto",
          "postcode": "4050-262",
          "country": "PT",
          "phone": "+351 912 345 678"
        },
        "tracking": "EA123456789PT"
      },
      "invoice": null,
      "note": "Gift — no invoice in the parcel.",
      "lines": [
        {
          "kind": "print",
          "name": "Hahnemühle Photo Rag 308",
          "qty": 2,
          "unit_price": 54.12,
          "total": 108.24,
          "vat_rate": 23,
          "details": [
            {
              "name": "File",
              "value": "harbour-at-dusk.tif"
            },
            {
              "name": "Sheet",
              "value": "40 × 50 cm"
            },
            {
              "name": "Image",
              "value": "36 × 46 cm"
            }
          ],
          "file": "k3Fq9w2LxP0aZt7c"
        }
      ]
    }
  }
}

Cada mensagem é assinada: X-WebOffice-Signature: t=<tempo unix>,v1=<HMAC-SHA256 de «t.corpo» com o seu segredo de assinatura, em hexadecimal>. Verifique-a contra o corpo tal como chegou, e recuse um t a mais de cinco minutos. O estúdio dá-lhe o segredo e pode renová-lo.

import crypto from 'node:crypto'

// raw: the request body exactly as it arrived (a string, before any JSON parsing)
// header: the X-WebOffice-Signature header; secret: your signing secret (whsec_…)
export function verified(raw, header, secret) {
  const parts = Object.fromEntries(String(header).split(',').map((kv) => kv.trim().split('=')))
  const t = Number(parts.t)
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
  const want = crypto.createHmac('sha256', secret).update(t + '.' + raw).digest('hex')
  const got = String(parts.v1 || '')
  return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))
}

Erros

Um erro responde um estado HTTP e { error: { code, message, fields } }; fields indica cada problema como o corpo o escreve (lines[0].width_cm). Os códigos são estáveis, as mensagens são para pessoas.

{
  "error": {
    "code": "invalid_lines",
    "message": "Hahnemühle Photo Rag 308: That size is too large for this paper — the largest print it can make is 111.8 × 1500 cm.",
    "fields": [
      {
        "field": "lines[0].width_cm",
        "code": "size_not_available",
        "message": "Hahnemühle Photo Rag 308: That size is too large for this paper — the largest print it can make is 111.8 × 1500 cm."
      }
    ]
  }
}

Por chave, a cada dez minutos: 600 pedidos, 2000 linhas orçamentadas (um orçamento ou uma encomenda conta as suas linhas) e 8192 MB de uploads. Por conta: 120 encomendas por hora, 20 GB de ficheiros à espera de encomenda e um corpo até 1024 KB. Acima de um limite a resposta é 429 com Retry-After (507 para os ficheiros). Pedidos com uma chave errada são limitados por endereço.

Todos os pedidos

O mesmo, em OpenAPI 3.1, para um gerador de código: https://www.xyz-prints.com/api/v1/partner/openapi.json?brand=xyz-prints