Clientes

List clients

Returns a paginated list of clients with optional filters

GET
/clientes

Authorization

X-API-Key<token>

API Key authentication.

Format: X-API-Key: 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

Query Parameters

page?integer

Page number (starts at 1)

Default1
Range1 <= value
limit?integer

Number of items per page

Default20
Range1 <= value <= 100
activo?boolean

Filter by active/inactive status

search?string

Global search by name, NIF or email

nombre_fiscal?string

Filter by legal name (partial search case-insensitive)

nif?string

Filter by NIF (partial search)

email?string

Filter by email (partial search)

telefono?string

Filter by phone (partial search)

poblacion?string

Filter by city

provincia?string

Filter by province

sort_by?string

Field to sort by (eg. nombre_fiscal, nif, created_at)

sort_order?string

Sort order direction

Default"asc"
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/clientes"

Client list with pagination and summary (active/inactive count, total billed)

{
  "success": true,
  "data": {
    "clientes": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "nombre_fiscal": "Tech Solutions SL",
        "nif": "B12345678",
        "email": "admin@techsolutions.com",
        "telefono": "+34912345678",
        "activo": true,
        "total_facturas": 15,
        "total_facturado": 28500
      },
      {
        "id": "789abc12-34de-56f7-8901-234567890abc",
        "nombre_fiscal": "María García López",
        "nif": "12345678Z",
        "email": "maria.garcia@email.com",
        "telefono": "+34654321987",
        "activo": true,
        "total_facturas": 8,
        "total_facturado": 12400
      },
      {
        "id": "456def78-90gh-12ij-3456-78klmn901234",
        "nombre_fiscal": "Distribuidora Levante SA",
        "nif": "A22222222",
        "email": "contabilidad@distribuidoralevante.es",
        "telefono": "+34963456789",
        "activo": false,
        "total_facturas": 3,
        "total_facturado": 4500
      }
    ],
    "paginacion": {
      "pagina_actual": 1,
      "items_por_pagina": 20,
      "total_items": 3,
      "total_paginas": 1,
      "tiene_siguiente": false,
      "tiene_anterior": false
    },
    "resumen": {
      "total_clientes_activos": 2,
      "total_clientes_inactivos": 1,
      "total_facturado": 45400
    }
  },
  "meta": {
    "timestamp": "2025-01-20T12:00:00Z",
    "request_id": "req_list_clientes_001"
  }
}

Missing, invalid, or expired API key in X-API-Key header

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is invalid or has expired",
    "details": {
      "header": "X-API-Key",
      "reason": "Invalid API key format or key not found"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_001"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Import contacts from Holded Excel POST

Imports multiple clients from an Excel file exported from Holded. **Key features**: - **Specific parsing**: Reads exact structure of Holded contacts Excel (29 columns) - **Automatic mapping**: Converts Holded contacts to Client entities automatically - **Full validation**: Validates NIFs, addresses and required data - **Preview mode**: Allows viewing parsed data before importing **Recommended flow**: 1. **Initial upload**: Call with `preview=true` to get preview 2. **Display data**: Frontend shows parsed Holded contacts 3. **Final import**: Call with `preview=false` to import definitively **Expected Excel structure** (contacts exported from Holded): - Sheet: "Holded" - Rows to skip: 2 (header + empty) - Headers in row 2: Created, Name, ID, Email, Phone, Mobile, etc. (29 columns) - Footer: "Report created automatically with Holded..." **Security limits**: - Max size: 10MB - Max 5,000 records per file - Rate limiting: 5 imports per hour **Automatic Holded → Client mapping**: - Name → nombreFiscal - ID → identifier (NIF/CIF) - Email → email - Phone/Mobile → phone (prioritizes mobile) - Full address → address - Tags → notes

Get client by ID GET

Retrieves complete details of a specific client