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

Update a product of a company partially

Scopeproducts:write

Updates only the fields present in the body, leaving every other field of the product as it is — in particular main_tax, irpf_rate and equivalence_surcharge_rate.

  • Null vs omitted: a field sent as null is cleared, which is different from omitting it (see PatchProductRequest).
  • Only update verb: the total replacement PUT /v1/products/{product_id}, which reset the omitted fields to their creation defaults, is not carried over to the canonical form.
PATCH
/v1/companies/{company_id}/products/{product_id}

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
product_idstring

Product unique UUID

Formatuuid

Request Body

code?string|null

Unique alphanumeric product code. Send null to clear it.

Match^[a-zA-Z0-9_-]*$
Lengthlength <= 50
name?string

Product/service name. Cannot be cleared.

Lengthlength <= 255
description?string|null

Detailed description. Send null to clear it.

category?string
Value in"PRODUCT" | "SERVICE" | "CONSULTING" | "SOFTWARE" | "TRAINING" | "OTHER"
default_price?number|null

Suggested default price. Send null to clear it.

Multiple Of0.0001
Range0 <= value
unit?string|null

Unit of measure. Send null to clear it.

Lengthlength <= 50
main_tax?
equivalence_surcharge_rate?number|null

Equivalence surcharge percentage. Send null to state that none applies (equivalent to 0).

The merged result must be coherent with the regime key: if this PATCH does not send main_tax.regime_key, the stored regime is adjusted automatically (18 when the merged surcharge is > 0, 01 when it is not). With an explicit regime_key in this PATCH, an incoherent combination is rejected with a 422 (SURCHARGE_REQUIRES_REGIME / REGIME_REQUIRES_SURCHARGE).

Multiple Of0.01
Range0 <= value <= 100
irpf_rate?number|null

IRPF withholding percentage. Send null to state that none applies (equivalent to 0).

The rate must be one of IrpfPercentage (INVALID_IRPF otherwise) and one the company can bear, the same check as an invoice line (see WithholdingOptions in the tax configuration): an entity gets the rates of individuals rejected with IRPF_RATE_NOT_FOR_CORPORATE_ISSUER, and an individual gets 9.5 rejected with IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER.

Multiple Of0.01
Range0 <= value <= 100
active?boolean

Indicates whether the product is active.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/products/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "default_price": 135,    "description": "Servicios de consultoría estratégica por hora - Precio actualizado para 2025"  }'
{
  "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": "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": "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": "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": "UNPROCESSABLE_ENTITY",
    "message": "Data cannot be processed",
    "details": {
      "field": "Specific error description"
    }
  },
  "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"
  }
}

Get a product of a company GET

Retrieves one product of the catalog of this company. A product of another company answers `404` with `PRODUCT_NOT_FOUND`, exactly like one that does not exist or was deleted.

Delete a product of a company DELETE

Deletes a product from the catalog of this company. It no longer appears in the list and reading it answers `404`. Invoices already created keep their lines unchanged: a line copies its data and does not point to the product.