HTTP Methods

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

Summary

Method	Purpose	Idempotent	Modifies data
GET	Read/query	✅ Yes	❌ No
POST	Create resources	❌ No	✅ Yes
PUT	Update resources	✅ Yes	✅ Yes
DELETE	Remove 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/facturas/factura-123" \
  -H "X-API-Key: beel_sk_xxx"

Filtering and Pagination

Query parameters are passed in the URL:

# List invoices with filters
curl "https://app.beel.es/api/v1/facturas?estado=EMITIDA&limit=10&page=1" \
  -H "X-API-Key: beel_sk_xxx"

Common Parameters

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

Typical Response

{
  "data": [
    {
      "id": "factura-123",
      "numero": "FACT-2025-001",
      ...
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

POST — Create Resources

POST methods are used to create new resources.

Characteristics

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

Basic Usage

curl -X POST "https://app.beel.es/api/v1/facturas" \
  -H "X-API-Key: beel_sk_xxx" \
  -H "X-Idempotency-Key: create-invoice-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "ORDINARIA",
    "clienteId": "cliente-123",
    "fecha_emision": "2025-01-15",
    "lineas": [
      {
        "descripcion": "Web development consulting",
        "cantidad": 40,
        "unidad": "hours",
        "precio_unitario": 50.00
      }
    ]
  }'

Successful Response

HTTP/1.1 201 Created
Location: /api/v1/facturas/factura-abc123

{
  "data": {
    "id": "factura-abc123",
    "numero": "FACT-2025-001",
    "estado": "BORRADOR",
    ...
  }
}

Best Practices

Always use X-Idempotency-Key for resource creation
Validate data before sending the request
Handle 4xx and 5xx errors appropriately
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/clientes/cliente-123" \
  -H "X-API-Key: beel_sk_xxx" \
  -H "X-Idempotency-Key: update-client-456" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-email@example.com",
    "telefono": "+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

{
  "data": {
    "id": "cliente-123",
    "nombre_fiscal": "Company SL",
    "email": "new-email@example.com",
    "telefono": "+34912345678",
    ...
  }
}

Restrictions

Some resources have update restrictions:

Invoices: Can only update invoices in BORRADOR status
Series: Cannot change the code once created
Clients: 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/clientes/cliente-123" \
  -H "X-API-Key: beel_sk_xxx"

Successful Response

HTTP/1.1 204 No Content

Or with confirmation message:

HTTP/1.1 200 OK

{
  "data": {
    "message": "Client deleted successfully"
  }
}

Soft Delete

Most resources use soft delete:

Resource is marked as deleted: true or activo: false
Does not appear in default listings
Data is preserved for audit purposes
Cannot be restored via API (contact support)

Common Restrictions

You cannot delete:

Clients 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

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

Responses

X-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 /facturas

# List
GET /facturas

# Get one
GET /facturas/{id}

# Update (BORRADOR only)
PUT /facturas/{id}

# Delete (BORRADOR only)
DELETE /facturas/{id}

# Issue
POST /facturas/{id}/emitir

# Void
POST /facturas/{id}/anular

Clients

# Create
POST /clientes

# List
GET /clientes

# Get one
GET /clientes/{id}

# Update
PUT /clientes/{id}

# Deactivate
DELETE /clientes/{id}

Products

# Create
POST /productos

# List
GET /productos

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

# Get one
GET /productos/{id}

# Update
PUT /productos/{id}

# Delete
DELETE /productos/{id}

Next Steps

Idempotency — Implement idempotency keys
Create invoice — Practical POST example
List invoices — Practical GET example

HTTP Methods

On this page