Convenções

Requisições e respostasLink para esta seção#

• Requisições e respostas são JSON. Envie Content-Type: application/json com um corpo.
• Os nomes dos campos são camelCase: listPrice, accountCode, nextOffset.
• Parâmetros de consulta são strings simples: ?limit=20&status=new.

Toda resposta bem-sucedida é um objeto com data:

{
  "data": [],
  "nextOffset": 50,
  "currency": "GBP"
}

Pedidos carregam seu próprio campo currency, fixo quando o pedido foi feito.

PaginaçãoLink para esta seção#

Listas usam limit e offset:

Continue a solicitar com offset=nextOffset até que nextOffset seja null:

let offset = 0
const all = []
while (offset !== null) {
  const res = await fetch(
    `https://tradecatalog.app/api/v1/products?limit=50&offset=${offset}`,
    {
      headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
    },
  )
  const page = await res.json()
  all.push(...page.data)
  offset = page.nextOffset
}

No /products, nextOffset é definido sempre que uma página estiver cheia. Se o tamanho do catálogo for um múltiplo exato de limit, a última solicitação retorna uma lista vazia data com nextOffset: null.

Algumas listas têm limite. GET /orders abrange os 200 pedidos mais recentes correspondentes, e GET /price-changes os 100 mais recentes.

DinheiroLink para esta seção#

Dinheiro é um número inteiro nas unidades menores da moeda, então não há erro de arredondamento:

Divida por 10 elevado à potência das casas decimais da moeda para exibi-lo. No JavaScript, Intl.NumberFormat faz isso para você:

const format = (minor, currency) => {
  const f = new Intl.NumberFormat('en-GB', { style: 'currency', currency })
  const digits = f.resolvedOptions().maximumFractionDigits
  return f.format(minor / 10 ** digits)
}
format(1234, 'GBP') // "£12.34"

Preços são os definidos pelo fornecedor em sua lista de preços. Se isso inclui imposto é definido pela taxLabel da workspace em GET /workspace: por exemplo,

PorcentagensLink para esta seção#

Porcentagens são pontos básicos: centésimos de porcentagem, como inteiros.

DatasLink para esta seção#

Datas são strings no formato ISO 8601 em UTC, como 2026-09-27T08:15:00.000Z. O fuso horário da workspace é timezone em GET /workspace.

IDsLink para esta seção#

IDs são strings UUID. Em qualquer lugar em que um endpoint aceite um cliente, você pode passar o ID do cliente ou seu código de conta (case-insensitive), conforme o que sua sistema tiver:

curl "https://tradecatalog.app/api/v1/prices?customer=OAK01&sku=HX-8510" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

Criando e atualizando (PUT)Link para esta seção#

PUT /products e PUT /customers criam ou atualizam em uma única chamada, até 100 linhas por vez:

• Produtos são correspondidos por SKU (case-insensitive).
• Clientes são correspondidos por código de conta, senão e-mail, senão nome.

Ambos são seguros para repetição. Enviar as mesmas linhas duas vezes dá o mesmo resultado; a segunda chamada apenas as relata como atualizadas.

Um PUT escreve os campos que você envia. Alguns campos de produto opcionais são limpos quando você os deixa de fora, outros são mantidos. Cada página de endpoint lista quais.

Limites de taxaLink para esta seção#

Cada chave pode fazer 120 solicitações por minuto. Acima disso, você recebe 429 rate_limited com Retry-After: 60. Espere e tente novamente. Erros tem um helper para tentar novamente.

Faça gravações em lote quando possível: uma PUT com 100 produtos conta como uma solicitação.

VersionamentoLink para esta seção#

A versão está no caminho: /api/v1.

• Dentro do v1, fazemos apenas mudanças aditivas: novos endpoints, novos parâmetros opcionais, novos campos nas respostas. Escreva seu código para ignorar campos que não conheça.
• Uma mudança quebradora receberá uma nova versão (/api/v2), mantendo o v1 em execução e anunciando a mudança no changelog.