Procarte API

API Reference

Connect your systems to Procarte.

Integrate with the Procarte REST API from your backend. Authenticate with OAuth 2.0 and use assigned token scopes to control access to available resources.

Request and response examples sit beside each section. Choose a format above to update all request examples.

Base URL

https://api.procarte.pl/v2

Quick start

Make your first authenticated request in three steps.

Get your client credentials
Use the client_id and client_secret assigned to your integration. Keep the secret on your backend.
Request an access token
Send your credentials using HTTP Basic Auth to POST /oauth/token.
Call the API
Include Authorization: Bearer <access_token> with every request to a protected endpoint.

Authentication

OAuth 2.0

The API uses the OAuth 2.0 client_credentials grant for server-to-server integrations. First obtain a short-lived access token, then send it as a Bearer token with every protected API request.

Keep the client_secret private. Do not embed it in browser or mobile-app code. Client credentials are intended for a trusted backend integration.

Client credentials authenticate your integration. Bearer tokens authenticate subsequent API requests.

Grant type

client_credentials

Protected request header

Authorization: Bearer <access_token>

Get an access token

POST/oauth/token

Authenticate the API client with HTTP Basic Auth: the client ID is the username and the client secret is the password. The token request uses application/x-www-form-urlencoded.

The scope parameter is optional. If omitted, the token receives all scopes assigned to the API client. If provided, every requested scope must be assigned to that client; otherwise the API returns 403 invalid_scope.

Using the token

expires_in is the token lifetime in seconds. Send Authorization: Bearer <access_token> with every protected API request. When the token expires, request a new one using the client credentials. Refresh tokens are not supported.

Existing tokens keep the scopes they were issued with. Request a new token after the scopes assigned to the API client are changed.

Request

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=products:read_id products:read_name products:read_quantity" \
  https://api.procarte.pl/v2/oauth/token

Response · example token lifetime200 OK

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "products:read_id products:read_name products:read_quantity"
}

Products

List products

GET/products

Returns a paginated product list with fields allowed by the token scopes.

Query parameters

Parameter	Description	Scope
`page`	Page number.	Defaults to `1`
`page_size`	Number of products per page. The lower of the requested value and the client limit is applied.	Defaults to `50`
`id`	One or more IDs separated by commas.	`products:read_id`
`product_code`	Exact product code.	`products:read_product_code`
`name`	Product name fragment.	`products:read_name`
`category`	Exact category.	`products:read_category`
`brand`	Exact brand.	`products:read_brand`

Fields follow your scopes

The response includes only fields allowed by the access token. Filters also require the corresponding scope shown above.

Request

curl "https://api.procarte.pl/v2/products?page=1&page_size=50&name=FoxESS%20Storage%20Battery%20HV%20EP12" \
  -H "Authorization: Bearer $TOKEN"

Response200 OK

{
  "data": [{
    "id": 3679,
    "name": "FoxESS Storage Battery HV EP12",
    "quantity": 95
  }],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 1,
    "total_pages": 1
  }
}

Orders

Create an order

POST/orders

Creates a sales order. Requires the orders:create scope.

Idempotency-Key is required

Send a unique key for each new order. Reuse it when retrying the same request. Learn about safe retries →

JSON body

Field	Requirements
`external_order_id`	Required, max. 120 characters. Identifier from the integrating system.
`items`	Between 1 and 100 order lines.
`items[].product_id` / `product_code`	Exactly one of these fields is required.
`items[].quantity`	Required value greater than zero.
`shipping_address`	Required: `street`, `city`, `postal_code`, `country`.
`notes`	Optional, max. 1,000 characters.
`requested_delivery_date`	Optional, format `YYYY-MM-DD`.
`currency`	Optional, three-letter ISO 4217 currency code. Defaults to `PLN`.

Request

curl -X POST https://api.procarte.pl/v2/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9d7b8c34-9840-4d49-a977-f5bb2efbbd7d" \
  -d '{
    "external_order_id": "EXT-10001",
    "currency": "PLN",
    "items": [
      { "product_code": "03-053", "quantity": 2 }
    ],
    "shipping_address": {
      "name": "Procarte PV",
      "street": "Przęsłowa 4",
      "city": "Kielce",
      "postal_code": "25-671",
      "country": "Poland"
    },
    "requested_delivery_date": "2026-08-01",
    "notes": "Morning delivery."
  }'

Response201 Created

{
  "order_id": "22f4e368-c7c4-4199-9405-cded7dcdc477",
  "external_order_id": "EXT-10001",
  "status": "created",
  "order_number": "API-EXT-10001",
  "created_at": "2026-07-24T12:26:46Z",
  "updated_at": "2026-07-24T12:26:47Z"
}

Get order status

GET/orders/{order_id}

Returns the order status. Requires the orders:read scope.

Use the order_id returned when creating the order.

Timestamps

Order timestamps are returned in UTC using ISO 8601 format. created_at is the time the order was stored by the API, and updated_at is the time of the latest local status update.

Request

curl https://api.procarte.pl/v2/orders/$ORDER_ID \
  -H "Authorization: Bearer $TOKEN"

Response200 OK

{
  "order_id": "22f4e368-c7c4-4199-9405-cded7dcdc477",
  "external_order_id": "EXT-10001",
  "status": "created",
  "order_number": "API-EXT-10001",
  "created_at": "2026-07-24T12:26:46Z",
  "updated_at": "2026-07-24T12:26:47Z"
}

Safe retries

Every order creation request must include an Idempotency-Key header. Retrying the same request with the same key returns the same result. Reusing the key or external_order_id with different order content returns 409.

Keep the key with the order

Store the original key in your integration so you can reuse it if the request times out.

Limits

Limit	Rule
Requests	Global API client limit, 60 requests per minute by default. When exceeded, the API returns `429` and `Retry-After`.
Products per page	Limit configured separately for each API client.
Order lines	Maximum 100 lines in one order.

If the request limit is exceeded, wait for the delay specified in the response before retrying.

Rate limit response headers

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Errors

Every error response contains a stable machine-readable error.code and a human-readable error.message. Use the HTTP status and error code together when handling errors.

Status	Code	Meaning
`401`	`invalid_token`	Access token is invalid or expired. Obtain a new token and retry the request.
`403`	`insufficient_scope`	The access token does not include the scope required by the endpoint.
`404`	`order_not_found`	Order does not exist or is not available to the API client.
`409`	`idempotency_conflict`	Idempotency key or external order ID was reused with different content. Reconcile the existing request.
`422`	`unknown_product`, `inactive_product`, `insufficient_stock`	Order cannot be completed with the supplied product or stock data. Correct the data before retrying.
`429`	`rate_limited`	Retry after the delay specified by `Retry-After`.
`500`	`internal_error`	Unexpected API error. Retry with exponential backoff.
`502`	`order_creation_failed`	Order creation failed in the downstream system. Retry with exponential backoff and reuse the same `Idempotency-Key`.
`503`	`service_busy`	Order processing is temporarily busy. Retry with exponential backoff.

All errors share the same JSON structure. Check the HTTP status together with error.code.

Error response500 Internal Server Error

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error."
  }
}