Guides

HTTP Methods

Complete guide on using GET, POST, PUT and DELETE in the BeeL. API.

The BeeL. API uses standard HTTP methods following REST principles. Each method has a specific purpose and expected behavior.

Summary

MethodPurposeIdempotentModifies data
GETRead/query✅ Yes❌ No
POSTCreate resources❌ No✅ Yes
PUTUpdate resources✅ Yes✅ Yes
DELETERemove resources✅ Yes✅ Yes

GET — Read Data

GET methods are used to query information without modifying any resources.

Characteristics

  • ✅ Idempotent: Multiple requests produce the same result
  • ✅ Cacheable: Responses can be cached
  • ❌ Does not modify data: Read-only

Basic Usage

# Get a specific invoice
curl "https://app.beel.es/api/v1/invoices/{invoice_id}" \
  -H "Authorization: Bearer beel_sk_xxx"

Filtering and Pagination

Query parameters are passed in the URL:

# List invoices with filters
curl "https://app.beel.es/api/v1/invoices?status=ISSUED&limit=10&page=1" \
  -H "Authorization: Bearer beel_sk_xxx"

Common Parameters

  • page: Page number (starts at 1)
  • limit: Items per page (max 100)
  • Endpoint-specific filters (e.g., status, customer_id)

Typical Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "invoice_number": "FAC-2025-0001",
      ...
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 15,
    "total_items": 150,
    "items_per_page": 10,
    "has_next": true,
    "has_previous": false
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

POST — Create Resources

POST methods are used to create new resources.

Characteristics

  • ❌ Not idempotent: Creating twice generates two different resources
  • ✅ Must use Idempotency-Key: To prevent accidental duplicates
  • ✅ Returns the created resource

Basic Usage

curl -X POST "https://app.beel.es/api/v1/invoices" \
  -H "Authorization: Bearer beel_sk_xxx" \
  -H "Idempotency-Key: create-invoice-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "issue_date": "2025-01-15",
    "recipient": {
      "recipient_type": "EXISTING",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "lines": [
      {
        "description": "Web development consulting",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 50.00
      }
    ]
  }'

Successful Response

HTTP/1.1 201 Created

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoice_number": null,
    "status": "DRAFT",
    ...
  }
}

Best Practices

  1. Always use Idempotency-Key for resource creation
  2. Validate data before sending the request
  3. Handle 4xx and 5xx errors appropriately
  4. Check for 201 Created status to confirm success

PUT — Update Resources

PUT methods are used to update existing resources.

Characteristics

  • ✅ Idempotent: Multiple updates with the same data produce the same result
  • ✅ Partial update: Only send the fields you want to change
  • ⚠️ Requires resource ID in the URL

Basic Usage

curl -X PUT "https://app.beel.es/api/v1/customers/{customer_id}" \
  -H "Authorization: Bearer beel_sk_xxx" \
  -H "Idempotency-Key: update-customer-456" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-email@example.com",
    "phone": "+34912345678"
  }'

Partial Update

You only need to send the fields you want to modify:

{
  "email": "new@example.com"
}

Fields not included remain unchanged.

Successful Response

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "legal_name": "Company SL",
    "email": "new-email@example.com",
    "phone": "+34912345678",
    ...
  }
}

Restrictions

Some resources have update restrictions:

  • Invoices: Can only update invoices in DRAFT status
  • Series: Cannot change the code once created
  • Customers: Cannot change NIF if they have associated invoices

DELETE — Remove Resources

DELETE methods are used to delete or deactivate resources.

Characteristics

  • ✅ Idempotent: Deleting an already deleted resource returns the same result
  • ⚠️ Soft delete: Most resources are marked as "deleted" but not physically removed
  • ⚠️ May have restrictions: Some resources cannot be deleted if they have dependencies

Basic Usage

curl -X DELETE "https://app.beel.es/api/v1/customers/{customer_id}" \
  -H "Authorization: Bearer beel_sk_xxx"

Successful Response

HTTP/1.1 204 No Content

Or with confirmation message:

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "message": "Customer deleted successfully"
  }
}

Soft Delete

Most resources use soft delete:

  • Resource is marked as inactive
  • Does not appear in default listings
  • Data is preserved for audit purposes
  • Cannot be restored via API (contact support)

Common Restrictions

You cannot delete:

  • Customers with associated invoices
  • Invoice series with invoices
  • The default series
  • Issued invoices (use void instead)

HTTP Status Codes

Success (2xx)

  • 200 OK: Successful request (GET, PUT, DELETE)
  • 201 Created: Resource created successfully (POST)
  • 204 No Content: Successful deletion with no response content

Client Errors (4xx)

  • 400 Bad Request: Invalid data
  • 401 Unauthorized: Missing or invalid API Key
  • 403 Forbidden: You don't have permissions for this operation
  • 404 Not Found: Resource not found
  • 409 Conflict: Conflict (e.g., duplicate, business rule restriction)
  • 422 Unprocessable Entity: Business validation failed
  • 429 Too Many Requests: Rate limit exceeded

Server Errors (5xx)

  • 500 Internal Server Error: Internal server error
  • 503 Service Unavailable: Service temporarily unavailable

Important Headers

Requests

Authorization: Bearer beel_sk_xxx                    # Authentication (required)
Idempotency-Key: unique-key-123         # Idempotency (recommended for POST/PUT)
Content-Type: application/json            # Content type (for POST/PUT)

Responses

Idempotency-Replay: true                # Indicates cached response
X-RateLimit-Limit: 100                    # Request limit
X-RateLimit-Remaining: 95                 # Remaining requests
X-RateLimit-Reset: 1642089600             # Reset timestamp

Examples by Resource

Invoices

# Create
POST /v1/invoices

# List
GET /v1/invoices

# Get one
GET /v1/invoices/{invoice_id}

# Update (DRAFT only)
PUT /v1/invoices/{invoice_id}

# Delete (DRAFT only)
DELETE /v1/invoices/{invoice_id}

# Issue
POST /v1/invoices/{invoice_id}/issue

# Void
POST /v1/invoices/{invoice_id}/void

Customers

# Create
POST /v1/customers

# List
GET /v1/customers

# Get one
GET /v1/customers/{customer_id}

# Update
PUT /v1/customers/{customer_id}

# Deactivate
DELETE /v1/customers/{customer_id}

Products

# Create
POST /v1/products

# List
GET /v1/products

# Search (autocomplete)
GET /v1/products/search?q=consulting

# Get one
GET /v1/products/{product_id}

# Update
PUT /v1/products/{product_id}

# Delete
DELETE /v1/products/{product_id}

Next Steps

Idempotency

How to use idempotency keys to prevent duplicate operations in the BeeL. API.

Glossary

Spanish-English glossary of fiscal and business terms used in the BeeL. API.

On this page

SummaryGET — Read DataCharacteristicsBasic UsageFiltering and PaginationCommon ParametersTypical ResponsePOST — Create ResourcesCharacteristicsBasic UsageSuccessful ResponseBest PracticesPUT — Update ResourcesCharacteristicsBasic UsagePartial UpdateSuccessful ResponseRestrictionsDELETE — Remove ResourcesCharacteristicsBasic UsageSuccessful ResponseSoft DeleteCommon RestrictionsHTTP Status CodesSuccess (2xx)Client Errors (4xx)Server Errors (5xx)Important HeadersRequestsResponsesExamples by ResourceInvoicesCustomersProductsNext Steps