Search the products
Scopeproducts:readSearches the active products by name or code and returns at most 20 of them, for autocomplete.
- Deprecated — withdrawn, not moved: its replacement is
GET /v1/companies/{company_id}/products?q=, which searches the name, the code and the description, so it returns at least everything this endpoint returned. - Response shape: it differs, and that is why this notice exists. Here
datais a plain array of products, limited to 20 active ones, while theredatais the paginated envelope of the list (data.products+data.pagination). Change the way you read the response when you migrate.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Query Parameters
Search term (empty to get recent products).
This parameter was previously named q. The old name is still accepted for backwards
compatibility (see q below) and will be withdrawn in a future major version — send
search.
length <= 100Deprecated — former name of search, still honoured so existing integrations keep
working. Ignored when search is also present. Use search.
length <= 100Result limit (max 20)
101 <= value <= 20Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/products/search"{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"code": "SERV-001",
"name": "Technical consulting",
"description": "Specialized technical consulting services in web development",
"category": "CONSULTING",
"default_price": 85.5,
"unit": "hours",
"main_tax": {
"type": "IVA",
"percentage": 21,
"regime_key": "01"
},
"equivalence_surcharge_rate": 5.2,
"irpf_rate": 15,
"active": true,
"created_at": "2025-01-18T10:30:00Z",
"updated_at": "2025-01-18T15:45:30Z"
}
],
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation constraint violation.",
"details": {
"limit": "must be greater than or equal to 1"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}List the products GET
Returns a paginated list of products and services, with optional filters. - **Deprecated:** use `GET /v1/companies/{company_id}/products`, which returns the same list. The free-text filter is named `q` there, not `search`.
Replace a product PUT
Replaces an existing product with the body you send. - **Not a partial update:** leaving out `main_tax`, `equivalence_surcharge_rate` or `irpf_rate` resets them to the creation defaults (IVA 21%, 0% and 0%), so send the product complete. To change only some fields, use `PATCH /v1/companies/{company_id}/products/{product_id}`. - **Deprecated:** this route will be retired on the date announced in its `Sunset` response header. The canonical form has a single update verb, `PATCH /v1/companies/{company_id}/products/{product_id}`, which is not a drop-in replacement for this one: it changes only the fields present in the body and resets nothing on its own. To reproduce a total replacement, send every field and pass `null` in the ones you want cleared.