NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Products

List the products of a company

Scopeproducts:read

Returns a paginated list of the products/services of this company, with optional filters.

  • q: searching is done on this collection, there is no separate search path. q matches the name, the code and the description, so it returns at least everything the withdrawn GET /v1/products/search returned, in the paginated envelope of this list.
GET
/v1/companies/{company_id}/products

Authorization

AuthorizationBearer <token>

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

Path Parameters

company_idstring

Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid

Query Parameters

page?integer

Page number, starting at 1. The response echoes it back as pagination.current_page.

Default1
Range1 <= value
limit?integer

How many items to return per page. The response echoes it back as pagination.items_per_page.

Default20
Range1 <= value <= 100
q?string

Search by name, code or description

Lengthlength <= 100
category?string

Filter by product category

Value in"PRODUCT" | "SERVICE" | "CONSULTING" | "SOFTWARE" | "TRAINING" | "OTHER"
active?boolean

Filter by active/inactive status

name?string

Filter by name (partial search case-insensitive)

code?string

Filter by code (partial search)

min_price?number

Minimum price

Range0 <= value
max_price?number

Maximum price

Range0 <= value
sort_by?string
Value in"name" | "code" | "category" | "default_price" | "created_at"
sort_order?string
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/products"

Product catalog list with pagination metadata

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "code": "SRV-001",
        "name": "Consultoría estratégica",
        "description": "Servicios de consultoría estratégica por hora",
        "category": "CONSULTING",
        "default_price": 125,
        "unit": "hora",
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "active": true,
        "created_at": "2025-01-10T10:00:00Z",
        "updated_at": "2025-01-10T10:00:00Z"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "code": "PROD-LAPTOP-001",
        "name": "Ordenador portátil HP ProBook 450 G10",
        "description": "Incluye garantía de 2 años",
        "category": "PRODUCT",
        "default_price": 850,
        "unit": "unidad",
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "active": true,
        "created_at": "2025-01-15T14:30:00Z",
        "updated_at": "2025-01-15T14:30:00Z"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "code": "SRV-002",
        "name": "Diseño gráfico - Proyecto completo",
        "category": "SERVICE",
        "default_price": 500,
        "unit": "proyecto",
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "active": false,
        "created_at": "2025-01-08T09:00:00Z",
        "updated_at": "2025-02-01T11:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "items_per_page": 20,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  },
  "meta": {
    "timestamp": "2025-02-09T11:00:00Z",
    "request_id": "req_list_productos_001"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "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": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "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": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "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"
  }
}

Delete several customers (deprecated) DELETE

Deletes the customers listed in `ids`. - **Deprecated:** use `DELETE /v1/companies/{company_id}/customers/bulk`, which behaves identically. ## Partial results - **Partial:** the customers that can be deleted are deleted, and the rest keep their place in `customers_deletion` with the status that explains why. - **`HAS_INVOICES`:** a customer that has invoices cannot be deleted and comes back with that row status. ## What deleting means - **Semantics:** each deletion behaves as `DELETE /v1/customers/{customer_id}`. The customer is retained for tax record-keeping purposes but is no longer exposed by the API, its identifier is released for reuse, and invoices already issued to it keep their own copy of the recipient's details. - **Not deactivating:** deleting frees the identifier, so the same NIF can be registered again, while `PATCH` with `active: false` leaves the customer where it is with its NIF still taken. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

Create a product for a company POST

Creates a product or service in the catalog of the company in the path and returns it with its `id`. A product holds reusable defaults for invoice lines: name, price, unit and taxes. - **Required:** only `name`. Omitted, `category` is `SERVICE`, and the product is created active. - **`code`:** optional, and unique within the company. A code another product of the company already uses answers `409` with `PRODUCT_DUPLICATE`. - **Taxes:** `equivalence_surcharge_rate` has to be coherent with `main_tax.regime_key`; an incoherent pair answers `422` (see the field). - **Several at once:** `POST /v1/companies/{company_id}/products/bulk` creates up to 100 in one call.