Products

Create new product/service

Creates a new product or service in the catalog

POST
/v1/products

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates

Formatuuid

Request Body

code?string|null

Unique alphanumeric product code (optional)

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

Product/service name

Lengthlength <= 255
description?string

Detailed description (optional)

category?string

Product/service category:

  • PRODUCT - Physical, tangible products
  • SERVICE - General services
  • CONSULTING - Consulting and advisory services
  • SOFTWARE - Development, licenses, SaaS
  • TRAINING - Courses, workshops, training
  • OTHER - Other unclassified types
Value in"PRODUCT" | "SERVICE" | "CONSULTING" | "SOFTWARE" | "TRAINING" | "OTHER"
default_price?number

Suggested default price (optional)

Multiple Of0.0001
Range0 <= value
unit?string

Unit of measure (optional)

Lengthlength <= 50
main_tax?

Complete tax information with cross-validations:

  • IVA: only percentages 0, 4, 10, 21
  • IGIC: only percentages 0, 3, 5, 7, 9.5, 15, 20
  • IPSI: only percentages 0.5, 1, 2, 4, 8, 10
  • OTHER: any percentage between 0 and 100
equivalence_surcharge?number

Equivalence surcharge percentage (optional)

Multiple Of0.01
Range0 <= value <= 100
irpf?number

IRPF withholding percentage (optional)

Multiple Of0.01
Range0 <= value <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/products" \  -H "Content-Type: application/json" \  -d '{    "name": "Technical consulting"  }'
{
  "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": 5.2,
    "irpf": 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 required"
  },
  "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"
  }
}
{
  "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": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Update user preferred language PUT

Updates the authenticated user's preferred language. This language is used for: - UI translations - Template names and colors in invoice customization - Emails sent to the user **Supported languages:** - `es` - Spanish (default) - `en` - English - `ca` - Catalan

Create multiple products POST

Creates multiple products in one operation (max 100)