Conventions

How HTTP methods, filters, pagination, includes and response shapes are used across every BOCP endpoint.

HTTP methods

Method	Purpose	Notes
`GET`	Read data	Never modifies state. Safe to retry.
`POST`	Create a new resource	Add a product, attach an image, issue a document, etc.
`PATCH`	Partial update	Send only the fields you want to change. Related fields (e.g. price + currency) must be sent together.
`PUT`	Replace	Used for a small number of endpoints (e.g. image from URL).
`DELETE`	Delete	Applies immediately. Not always fully reversible.

Write operations are real and immediate. Daily backups exist, but restoring from backup loses everything committed since the backup ran. Use a test account for integration work.

URL structure

https://secure.bocp.eu/app/rest/v1/2/module/sub_action/filter1:value1/filter2:value2/

Filter order does not matter. Filters are always key:value pairs separated by /. There are no query strings on list endpoints.

Standard filters (list endpoints)

Every list endpoint accepts the following filters. Endpoint-specific filters are documented on each endpoint page.

Filter	Example	Meaning
`year`	`year:2024`	Documents with a date in the full calendar year.
`yearmonth`	`yearmonth:202407`	Documents in a specific month.
`yearmonthday`	`yearmonthday:20240715`	Documents on a specific day.
`date`	`date:2024-07-15`	Alias of `yearmonthday`, accepts ISO date.
`modifiedafter`	`modifiedafter:2024-07-15%2012:00:00`	Documents modified strictly after this timestamp. Use for incremental sync.
`modifiedthrough`	`modifiedthrough:2024-07-15%2023:59:59`	Documents modified up to and including this timestamp.
`id`	`id:1234`	Return only the document with this BOCP ID.
`minid`	`minid:1234`	Documents with BOCP ID ≥ this value.
`skipcancelled`	`skipcancelled:1`	Exclude cancelled / deleted documents.
`documentnr`	`documentnr:INV-2024-0042`	Match a specific document number (supported on some endpoints).
`page`	`page:3`	Pagination. If missing, defaults to page 1.

Include / exclude

Some endpoints let you opt in to heavier or opt out of default data:

.../sales/list/include:items,transactions/exclude:invoiced/

Multiple values are comma-separated. Each endpoint lists the values it accepts.

Pagination

Every list endpoint returns at most 250 rows per page (this value is optimised by BOCP and may change). Two fields tell you whether more data exists:

{
  "page": 1,
  "has_more_pages": true
}

Ask for the next page with page:2. When you request a page that has no results, the server returns 404.

Response envelope

Every response — success or error — has the same shape:

{
  "is_error": false,
  "http_code": 200,
  "data": ...,
  "messages": ["Human-readable notes go here."],
  "request_route": "...",
  "your_ip": "1.2.3.4",
  "your_user": "api_user_xyz",
  "your_method": "GET"
}

Rate limiting

Please be a good citizen:

Cache data locally when possible — do not re-request the same information.
Use modifiedafter for incremental sync instead of re-listing everything.
Failed authentications trigger an automatic IP lock. Do not retry after a 401 — fix the credentials first.

» Continue to Errors.