Clienti · documentazione TradeCatalog

Un cliente è un conto commerciale: un'azienda a cui vendi, con un codice account, uno sconto account opzionale e le persone (acquirenti) che possono accedere per effettuare ordini per conto loro.

L'oggetto clienteCollegamento a questa sezione#

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	Descrizione
`id`	stringa	ID del cliente.
`accountCode`	stringa	Il tuo codice account. Unico nello spazio di lavoro, ignorando le maiuscole. Può essere modificato nell'app, quindi conserva il `id` per qualsiasi cosa a lungo termine.
`name`	stringa	Nome commerciale.
`legalName`	stringa o null	Nome registrato, quando diverso.
`email`	stringa o null	Email principale del contatto, in minuscolo.
`discountBp`	intero o null	Percentuale del cliente sul listino completo, in punti base. `null` per nessuna.
`adjustment`	stringa	`discount` (rimosso dal listino) o `markup` (aggiunto). I clienti esistenti sono `discount`.
`active`	booleano	I clienti inattivi non possono accedere o effettuare ordini.
`newsOptOut`	booleano	Il cliente ha disattivato le email delle offerte e delle notizie. Le email sui cambiamenti dei prezzi vengono comunque inviate.
`catalogueScope`	stringa	`all` (vede l'intero catalogo) o `approved` (vede e ordina solo il proprio elenco approvato). Impostato nella pagina del cliente; solo lettura nell'API.
`createdAt`	stringa	Quando il cliente è stato aggiunto.

Ovunque l'API richiede un cliente, puoi usare il id o il accountCode.

Elenco clientiCollegamento a questa sezione#

GET/api/v1/customers

Tutti i clienti, ordinati per nome.

Nome	Tipo	Obbligatorio	Descrizione
`limit`	intero	no	1 a 100. Default 100.
`offset`	intero	no	Righe da saltare. Default 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
}

Ottieni un clienteCollegamento a questa sezione#

GET/api/v1/customers/{id}

Il cliente più tutto ciò che influisce sui loro prezzi, e chi può accedere per loro.

Nome	In	Tipo	Obbligatorio	Descrizione
`id`	path	stringa	sì	ID del cliente o codice account.

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	Descrizione
`priceList`	Nome del listino dei prezzi da cui questo cliente acquista. `priceListId` è l'id di quel listino. Un prodotto senza prezzo sul listino ha prezzo su richiesta.
`discountRules`	Percentuali per prodotto, categoria e marca. `scope` è `product`, `category` o `brand`; `adjustment` è `discount` o `markup`; `target` è il suo nome. Le regole dei prodotti forniscono anche `sku`, `list` e `unit` (ciò che pagano).
`agreedPrices`	Prezzi concordati (fissi) validi ora, per SKU, in unità minori, con il prezzo `list` corrente e il prezzo `unit` che pagano. `note` è il commento; `noteVisible` indica se quel cliente lo vede. `internalNote` è riservato al personale e non viene mai mostrato al cliente.
`buyers`	Persone che possono accedere e effettuare ordini per questo cliente.
`pendingInvitations`	Inviti inviati ma non ancora accettati, e non scaduti.

Vedi come vengono calcolati i prezzi per capire come si combinano.

Crea o aggiorna clientiCollegamento a questa sezione#

PUT/api/v1/customerschiave di scrittura

Invia fino a 100 clienti per chiamata. Ogni riga viene abbinata a un cliente esistente in questo modo:

Se accountCode è impostato, per codice account. Nessun abbinamento significa un nuovo cliente con quel codice.
Altrimenti, se email è impostato, per email. Nessun abbinamento significa un nuovo cliente.
Altrimenti per nome, ignorando la maiuscola.

I nuovi clienti senza codice account ne ricevono uno creato dal loro nome.

CorpoCollegamento a questa sezione#

Campo	Tipo	Obbligatorio	Descrizione
`customers`	array	sì	Da 1 a 100 clienti. I codici di account devono essere unici all'interno della chiamata.
`customers[].accountCode`	stringa o null	sì	Fino a 50 caratteri. `null` per effettuare una corrispondenza tramite email o nome.
`customers[].name`	stringa	sì	Nome commerciale, fino a 160 caratteri.
`customers[].email`	stringa o null	sì	Email di contatto principale. `null` la cancella.
`customers[].discountBp`	intero o null	sì	Percentuale dell'intero elenco, da 0 a 10.000, per uno sconto o un aumento. `null` la cancella.
`customers[].adjustment`	`discount` o `markup`	no	In quale modo `discountBp` sposta il prezzo. Ometterlo per lasciare la direzione attuale. I nuovi clienti predefiniti a `discount`.
`customers[].priceList`	stringa o null	no	Nome di un elenco prezzi esistente. Ometterlo per lasciare invariato l'elenco. `null` posiziona il cliente su Standard. Un nome sconosciuto viene rifiutato.
`customers[].region`	stringa o null	no	Nome di una regione esistente. Ometterlo per lasciare invariata la regione. `null` la cancella. Un nome sconosciuto viene rifiutato.
`customers[].rep`	stringa o null	no	Email o nome utente di un dipendente assegnato a questo cliente. Ometterlo per lasciare invariato il rappresentante. `null` lo cancella. Un'email o un nome utente sconosciuti vengono rifiutati.

accountCode, name, email e discountBp sono obbligatori e vengono scritti come inviati: null cancella email e discountBp. In questo modo, un campo mancante nel tuo codice non può lasciare invariata una percentuale precedente. adjustment e priceList sono opzionali: lascia adjustment fuori per mantenere un aumento o uno sconto come è.

La tabella dei clienti ha la stessa scelta. Accanto a Sconto % può avere una colonna di Adattamento (discount o markup), una colonna di Elenco prezzi e una colonna di Rappresentante. La cella del rappresentante è l'email di quella persona, o il loro nome utente quando si registrano senza email. Una cella vuota lascia quel campo come è. Un nome di elenco sconosciuto o un rappresentante sconosciuto è un errore in quella riga.

Aggiornare un cliente non invia email a nessuno o non invita i compratori. Invita i compratori dalla pagina del cliente nell'app. Il nome registrato, lo stato attivo, le regole dello sconto e i prezzi concordati vengono modificati anche nell'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 }
}

Il cambiamento appare nel registro delle attività come nome della chiave.