Clientes · Documentação do TradeCatalog

Um cliente é uma conta comercial: uma empresa com quem você vende, com um código de conta, um desconto opcional para a conta e as pessoas (compradores) que podem fazer login para fazer pedidos por ela.

Objeto do clienteLink para esta seção#

json

{
  "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
  "accountCode": "OAK01",
  "name": "Oakfield Joinery",
  "legalName": "Oakfield Joinery Ltd",
  "email": "accounts@oakfieldjoinery.co.uk",
  "discountBp": 500,
  "active": true,
  "newsOptOut": false,
  "catalogueScope": "all",
  "createdAt": "2026-07-02T10:12:44.000Z"
}

Campo	Tipo	Descrição
`id`	string	ID do cliente.
`accountCode`	string	Seu código de conta. Único no workspace, ignorando maiúsculas. Pode ser alterado no app, então mantenha o `id` para qualquer coisa de longo prazo.
`name`	string	Nome comercial.
`legalName`	string ou nulo	Nome registrado, quando diferente.
`email`	string ou nulo	E-mail principal, em minúsculas.
`discountBp`	inteiro ou nulo	A porcentagem do cliente sobre a lista inteira, em pontos básicos. `null` para nenhuma.
`adjustment`	string	`discount` (removido da lista) ou `markup` (adicionado). Clientes existentes são `discount`.
`active`	booleano	Clientes inativos não podem fazer login ou fazer pedidos.
`newsOptOut`	booleano	O cliente desativou ofertas e e-mails de notícias. E-mails de alteração de preço ainda são enviados.
`catalogueScope`	string	`all` (vê toda a catálogo) ou `approved` (vê e faz pedidos apenas da sua lista aprovada). Definido na página do cliente; somente leitura na API.
`createdAt`	string	Quando o cliente foi adicionado.

Em qualquer lugar em que a API aceite um cliente, você pode usar o id ou o accountCode.

Listar clientesLink para esta seção#

GET/api/v1/customers

Todos os clientes, ordenados pelo nome.

Nome	Tipo	Obrigatório	Descrição
`limit`	inteiro	não	1 a 100. Padrão 100.
`offset`	inteiro	não	Linhas a pular. Padrão 0.

bash

curl "https://tradecatalog.app/api/v1/customers?limit=100" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/customers?limit=100', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: customers, nextOffset } = await res.json()

json

{
  "data": [
    {
      "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
      "accountCode": "OAK01",
      "name": "Oakfield Joinery",
      "legalName": "Oakfield Joinery Ltd",
      "email": "accounts@oakfieldjoinery.co.uk",
      "discountBp": 500,
      "active": true,
      "newsOptOut": false,
      "catalogueScope": "all",
      "createdAt": "2026-07-02T10:12:44.000Z"
    }
  ],
  "nextOffset": null
}

Obter um clienteLink para esta seção#

GET/api/v1/customers/{id}

O cliente mais tudo o que afeta seus preços, e quem pode fazer login por ele.

Nome	Em	Tipo	Obrigatório	Descrição
`id`	caminho	string	sim	ID do cliente ou código de conta.

bash

curl https://tradecatalog.app/api/v1/customers/OAK01 \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/customers/OAK01', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: customer } = await res.json()

json

{
  "data": {
    "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
    "accountCode": "OAK01",
    "name": "Oakfield Joinery",
    "legalName": "Oakfield Joinery Ltd",
    "email": "accounts@oakfieldjoinery.co.uk",
    "discountBp": 500,
    "priceListId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "priceList": "Standard",
    "active": true,
    "newsOptOut": false,
    "createdAt": "2026-07-02T10:12:44.000Z",
    "discountRules": [
      {
        "id": "d0e1f2a3-4b5c-4d6e-9f7a-8b9c0d1e2f3a",
        "scope": "product",
        "discountBp": 2000,
        "productId": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
        "sku": "HX-8510",
        "target": "Hex bolt M10 x 50 zinc",
        "list": 2280,
        "unit": 1824
      },
      {
        "id": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
        "scope": "brand",
        "discountBp": 1500,
        "productId": null,
        "sku": null,
        "target": "Northgate",
        "list": null,
        "unit": null
      },
      {
        "id": "f2a3b4c5-6d7e-4f80-9a1b-2c3d4e5f6a7b",
        "scope": "category",
        "discountBp": 1250,
        "productId": null,
        "sku": null,
        "target": "Hinges",
        "list": null,
        "unit": null
      }
    ],
    "agreedPrices": [
      {
        "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "productId": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
        "price": 1450,
        "note": "Contract price to March 2027",
        "noteVisible": true,
        "internalNote": "Agreed with their buyer",
        "sku": "HX-8512",
        "name": "Hex bolt M12 x 50 zinc",
        "list": 1980,
        "unit": 1450
      }
    ],
    "buyers": [{ "name": "Sam Patel", "email": "sam@oakfieldjoinery.co.uk" }],
    "pendingInvitations": [{ "email": "orders@oakfieldjoinery.co.uk" }]
  },
  "currency": "GBP"
}

Campo	Descrição
`priceList`	Nome da lista de preços com a qual este cliente compra. `priceListId` é o ID dessa lista. Um produto sem preço na lista é preço sob consulta.
`discountRules`	Porcentagens de produto, categoria e marca. `scope` é `product`, `category` ou `brand`; `adjustment` é `discount` ou `markup`; `target` é seu nome. As regras de produto também fornecem `sku`, `list` e `unit` (o que eles pagam).
`agreedPrices`	Preços acordados (fixos) válidos agora, por SKU, em unidades menores, com o preço atual `list` e o preço `unit` que eles pagam. `note` é o comentário; `noteVisible` diz se esse cliente o vê. `internalNote` é exclusivo para equipe e nunca é mostrado ao cliente.
`buyers`	Pessoas que podem fazer login e fazer pedidos por este cliente.
`pendingInvitations`	Convites enviados, mas não aceitos, e não expirados.

Veja como os preços são calculados para como esses se combinam.

Criar ou atualizar clientesLink para esta seção#

PUT/api/v1/customersescreva a chave

Envie até 100 clientes por chamada. Cada linha é correspondida a um cliente existente da seguinte forma:

Se accountCode estiver definido, por código de conta. Nenhum correspondente significa um novo cliente com esse código.
Caso contrário, se email estiver definido, por e-mail. Nenhum correspondente significa um novo cliente.
Caso contrário, por nome, ignorando maiúsculas.

Novos clientes sem código de conta recebem um criado a partir do seu nome.

CorpoLink para esta seção#

Campo	Tipo	Obrigatório	Descrição
`customers`	array	sim	1 a 100 clientes. Os códigos de conta devem ser únicos dentro da chamada.
`customers[].accountCode`	string ou nulo	sim	Até 50 caracteres. `null` para corresponder por e-mail ou nome.
`customers[].name`	string	sim	Nome comercial, até 160 caracteres.
`customers[].email`	string ou nulo	sim	E-mail do contato principal. `null` apaga-o.
`customers[].discountBp`	inteiro ou nulo	sim	Porcentagem da lista completa, de 0 a 10.000, para desconto ou acréscimo. `null` apaga-o.
`customers[].adjustment`	`discount` ou `markup`	não	Para qual direção `discountBp` move o preço. Omita para manter a direção atual. Novos clientes padrão para `discount`.
`customers[].priceList`	string ou nulo	não	Nome de uma lista de preços existente. Omita para manter a lista inalterada. `null` coloca o cliente no Padrão. Um nome desconhecido é rejeitado.
`customers[].region`	string ou nulo	não	Nome de uma região existente. Omita para manter a região inalterada. `null` apaga-a. Um nome desconhecido é rejeitado.
`customers[].rep`	string ou nulo	não	E-mail ou nome de usuário de um funcionário atribuído a este cliente. Omita para manter o representante inalterado. `null` apaga-o. Um e-mail ou nome de usuário desconhecido é rejeitado.

accountCode, name, email e discountBp são obrigatórios e escritos como enviados: null apaga email e discountBp. Dessa forma, um campo ausente no seu código não pode deixar silenciosamente um percentual antigo em vigor. adjustment e priceList são opcionais: deixe adjustment de fora para manter um acréscimo ou desconto como está.

A planilha de clientes tem a mesma escolha. Além de Desconto %, ela pode ter uma coluna de Ajuste (discount ou markup), uma coluna de Lista de Preços e uma coluna de Representante de Vendas. A célula do representante é o e-mail dessa pessoa, ou seu nome de usuário quando elas se conectam sem e-mail. Uma célula em branco deixa esse campo como está. Um nome de lista desconhecido ou representante é um erro nessa linha.

Atualizar um cliente não envia e-mails nem convida compradores. Convide compradores a partir da página do cliente no app. O nome registrado, status ativo, regras de desconto e preços acordados também são alterados no app.

bash

curl -X PUT https://tradecatalog.app/api/v1/customers \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "accountCode": "OAK01",
        "name": "Oakfield Joinery",
        "email": "accounts@oakfieldjoinery.co.uk",
        "discountBp": 500
      },
      {
        "accountCode": "BRK07",
        "name": "Brookside Builders",
        "email": null,
        "discountBp": null
      }
    ]
  }'

const res = await fetch('https://tradecatalog.app/api/v1/customers', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ customers }),
})
const { data } = await res.json()
console.log(`${data.created} new, ${data.updated} updated`)

json

{
  "data": { "created": 1, "updated": 1 }
}

A alteração aparece no log de atividades como o nome da chave.