Українська

Authentication¶

Every request (except GET /health) must carry an API key.

The key¶

A v2 key looks like:

hp_live_Jcv2S9xM3kQ8...    (hp_<env>_<random>)

You create it in the interface (Integration setup). The full key is shown once, at creation — store it securely. Internally we keep only a lookup prefix and a SHA-256 hash, so the secret cannot be recovered from our database.

Sending the key¶

Pass it in the Authorization header, with or without the Bearer prefix:

curl https://crm.h-profit.com/bapi-v2/me \
  -H "Authorization: hp_live_your_key_here"

# equivalent
curl https://crm.h-profit.com/bapi-v2/me \
  -H "Authorization: Bearer hp_live_your_key_here"

A missing or invalid key returns 401:

{ "success": false, "error": { "code": "unauthorized", "message": "invalid or missing API key" } }

Scopes¶

Each key is granted a set of scopes of the form resource:action, where action is read or write. Examples: sales:read, products:write, webhooks:write.

* or full grants everything.
sales:* grants both sales:read and sales:write.

If a key lacks the scope an endpoint needs, the call returns 403:

{ "success": false, "error": { "code": "forbidden", "message": "insufficient scope",
  "details": { "required": ["sales:write"] } } }

Scope prefix	Covers
`reference`	reference data (`/reference`)
`warehouses` / `suppliers`	warehouses, suppliers
`products`	products, stock, product↔marketplace sync
`product_sync`	`/product_sync` bindings
`categories`	product categories
`clients`	clients + tags
`sales`	sales (the `orders` table)
`orders`	marketplace orders (`remote_orders`)
`shipments`	supplies / receiving
`expenses`	expenses
`productions`	production recipes & runs
`delivery`	city and branch lookups (`read`), Nova Poshta waybills (`write`, paid in your carrier account)
`webhooks`	webhook subscriptions & deliveries

Verifying a key: `GET /me`¶

Returns the key's context — never the secret. Handy for a first smoke test.

{
  "success": true,
  "data": {
    "user_id": 11,
    "integration_id": 4821,
    "label": "My shop integration",
    "scopes": ["*"]
  }
}

Health probe: `GET /health`¶

The only unauthenticated endpoint — a liveness check for monitoring.

{ "success": true, "data": { "service": "apiv2", "status": "ok", "ts": 1784551104 } }