Registering an Available Wholesaler

Note

Part of the Wholesaler Integrations guide. See Scope, Webhooks and Errors first for the wholesaler OAuth scope and the webhook delivery/signing mechanics referenced below.

This is the first step of the integration: without a registered AvailableWholesaler, clinics cannot find or link you, and none of the other endpoints in this guide will accept your token for a wholesaler that doesn’t exist yet.

Note

Step 0, before any of this: your application itself must already be registered as an integration — see Adding an Application in Provet. You can’t obtain a wholesaler-scoped access token until that’s done. Consider subscribing to the installation webhook described in Get Notified for Installations of Your Applications in a Provet Organisation so you’re notified as soon as a clinic installs your application, and can automate the rest of onboarding (registering your AvailableWholesaler for them, etc.) from there.

Step 1 — Register an Available Wholesaler

An AvailableWholesaler lives in the clinic’s Provet database and represents a wholesaler integration a specific clinic can later pick from a list. In practice, you create or update this entry once your system is registered as an integration with Provet.

# Create a new available wholesaler.
curl -X POST "https://[env.]provetcloud.com/<provet_id>/api/0.1/available_wholesaler/" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Veterinary Supplies",
    "email": "orders@acmevet.example",
    "register_number": "FI12345678",
    "webhook_callback_url": "https://acmevet.example/webhooks/inbound",
    "verification_salt": "<generated_secret>"
  }'

# List all registered available wholesalers.
curl "https://[env.]provetcloud.com/<provet_id>/api/0.1/available_wholesaler/" \
  -H "Authorization: Bearer <oauth_access_token>"

# Retrieve one by ID.
curl "https://[env.]provetcloud.com/<provet_id>/api/0.1/available_wholesaler/<id>/" \
  -H "Authorization: Bearer <oauth_access_token>"

# Update one (e.g. rotate verification_salt, or update webhook_callback_url).
curl -X PATCH "https://[env.]provetcloud.com/<provet_id>/api/0.1/available_wholesaler/<id>/" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"verification_salt": "<new_generated_secret>"}'

# Delete one.
curl -X DELETE "https://[env.]provetcloud.com/<provet_id>/api/0.1/available_wholesaler/<id>/" \
  -H "Authorization: Bearer <oauth_access_token>"

[env.] is the deployment the clinic lives on (e.g. us., enterprise., or omitted for the default environment).

The owning integration is always taken from your access token — a value sent in the request body is ignored, and creating one with a legacy API key instead of an OAuth 2.0 access token answers 401.

`webhook_callback_url` and `verification_salt`

webhook_callback_url must use HTTPS and point to a publicly reachable host — private, loopback, and localhost addresses are rejected with 400, since deliveries can carry decrypted credentials (see Step 2 — Clinic connects the wholesaler). This applies while you are developing too, so point the URL at a public tunnel to your local receiver, or at a deployed one, rather than at your own machine.

verification_salt is the shared secret used to sign every webhook delivered to that URL — see “Webhook signature verification” in Scope, Webhooks and Errors for the full scheme.

Note

Despite the field name, this is a shared secret, not a salt: it is the HMAC key, it is never sent to you in a delivery, and it must be protected like any other credential. Generate it from a cryptographically secure random source — 32 random bytes rendered as 64 hexadecimal characters is a good default, for example openssl rand -hex 32. Do not derive it from your company name, your client id, or anything else guessable.

In short:

Accepted on create and update, as a field on available_wholesaler/.
Required on create — a registration cannot be created without one.
Write-only — Provet never returns it on any response, so keep your own copy.
16 to 128 characters, and any character is accepted. It is encoded as UTF-8 to form the HMAC key, so a value outside US-ASCII must be encoded the same way on your side when you verify.
Updates take effect atomically for the next delivery, with no grace period, so rotation is coordinated from your side (see Scope, Webhooks and Errors).

These records are later used in two places: clinic staff see them when choosing a wholesaler to connect, and your system authenticates later uploads against the registered AvailableWholesaler.

Step 2 — Clinic connects the wholesaler

This step is internal to Provet. Clinic staff pick your wholesaler from a list in the UI and link it to their AvailableWholesaler registration, from Stock > Inventory > Wholesalers > Create Wholesaler, selecting “Integration” as the wholesaler type — your available wholesaler is shown as one of the options. See Add Wholesalers for the customer-facing walkthrough of this screen, and Wholesalers in Provet for how clinics manage wholesalers more generally.

Once linked:

A Wholesaler is created in the clinic’s database, pointing back at your AvailableWholesaler.
Provet POSTs a wholesaler.created event to your webhook_callback_url.

Use the wholesaler.id you receive as the wholesaler_pk for catalog uploads (Making Products Available) and to correlate incoming orders (Handling Orders).

`wholesaler.created` event reference

Note

This event is also published in the API reference, whose machine-readable payload schema you can generate a client from.

Provet POSTs this event to available_wholesaler.webhook_callback_url when a clinic connects the wholesaler. It only fires for integration wholesalers, so it always describes a Wholesaler created from one of your AvailableWholesaler registrations. Any field the clinic left blank is sent as null.

{
  "event": "wholesaler.created",
  "event_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "available_wholesaler": {
    "id": 7,
    "name": "Acme Veterinary Supplies",
    "email": "orders@acmevet.example",
    "register_number": "FI12345678"
  },
  "wholesaler": {
    "id": 123,
    "customer_number": "CLINIC-42",
    "customer_username": "clinic42-login",
    "customer_password": "s3cr3t",
    "department": {"id": 4, "name": "Main Clinic"}
  }
}

Field	Type	Optional	Meaning
`event`	string	No	Always `"wholesaler.created"`.
`event_id`	string	No	UUID identifying this event. See deduplication rules.
`available_wholesaler.id`	number	No	ID of your registered `AvailableWholesaler`.
`available_wholesaler.name`	string	No	Name of that `AvailableWholesaler`.
`available_wholesaler.email`	string / null	Yes	Contact email registered for the `AvailableWholesaler`.
`available_wholesaler.register_number`	string / null	Yes	Business / registration number registered for the `AvailableWholesaler`.
`wholesaler.id`	number	No	Per-clinic `Wholesaler` ID — the `wholesaler_pk` you use for catalog uploads.
`wholesaler.customer_number`	string / null	Yes	The clinic’s customer number with the wholesaler.
`wholesaler.customer_username`	string / null	Yes	Login / username the clinic entered for this wholesaler.
`wholesaler.customer_password`	string / null	Yes	Password the clinic entered, decrypted. Treat it as a secret.
`wholesaler.department`	object / null	Yes	Set when credentials are specific to one clinic location; `null` when they apply wholesaler-wide. Contains `id` and `name` of the Department / Clinic Location.

Note

name, email, and register_number live under available_wholesaler because they describe the integration you registered. For an integration wholesaler the clinic cannot edit them, so they are not repeated on the wholesaler object.

Provet customers can choose to enable wholesalers globally in their organization, or locally in specific clinic locations / departments. The credential fields carry department-specific values when department is present, otherwise the wholesaler-global values.

Errors specific to registration

Situation	Response
OAuth token invalid/expired	401
Update / delete on an `available_wholesaler` registered by a different OAuth application	403 `Token does not match this wholesaler.`
Creating an `available_wholesaler` with a legacy API key instead of an OAuth2 token	401

See the error reference for the integration-specific errors that can occur across every phase.

Registering an Available Wholesaler

Step 1 — Register an Available Wholesaler

webhook_callback_url and verification_salt

Step 2 — Clinic connects the wholesaler

wholesaler.created event reference

Errors specific to registration

`webhook_callback_url` and `verification_salt`

`wholesaler.created` event reference