Clientes

Create client

Creates a new client

POST
/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

Request Body

nombre_fiscalstring

Customer legal name (required)

Match^\S.*$
Length1 <= length <= 120
nombre_comercial?string|null

Customer trade name (optional)

Lengthlength <= 120
nif?string
id_otro?|null

Alternative identifier for customers without Spanish Tax ID

direccion
telefono?string
email?string|null

Email address

Formatemail
Length0 <= length <= 255
emails_facturacion?|null

Additional emails for invoice delivery (optional)

persona_contacto?string|null

Contact person name (optional)

Lengthlength <= 200
notas?string|null

Additional notes about the customer (optional)

forma_pago_preferida?
descuento_general?number|null

General discount percentage (optional)

Formatdecimal
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/clientes" \  -H "Content-Type: application/json" \  -d '{    "nombre_fiscal": "Tech Solutions SL",    "nif": "B12345678",    "email": "admin@techsolutions.com",    "telefono": "+34912345678",    "direccion": {      "calle": "Calle Mayor",      "numero": "123",      "piso": "2º B",      "codigo_postal": "28013",      "poblacion": "Madrid",      "provincia": "Madrid",      "pais": "España"    },    "observaciones": "Cliente prioritario - Pago puntual"  }'

Client created successfully with generated ID and initial statistics

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "nombre_fiscal": "Tech Solutions SL",
    "nif": "B12345678",
    "email": "admin@techsolutions.com",
    "telefono": "+34912345678",
    "direccion": {
      "calle": "Calle Mayor",
      "numero": "123",
      "piso": "2º B",
      "codigo_postal": "28013",
      "poblacion": "Madrid",
      "provincia": "Madrid",
      "pais": "España"
    },
    "observaciones": "Cliente prioritario - Pago puntual",
    "activo": true,
    "created_at": "2025-01-20T10:00:00Z",
    "updated_at": "2025-01-20T10:00:00Z"
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_cliente_001"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

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"
  }
}

Duplicate resource exists (NIF, email, invoice number, series code)

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Resource already exists",
    "details": {
      "conflict_type": "DUPLICATE_NIF",
      "field": "nif",
      "value": "B12345678",
      "existing_resource_id": "123e4567-e89b-12d3-a456-426614174000",
      "message": "A client with NIF B12345678 already exists"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_004"
  }
}

Request data fails validation (missing fields, invalid format, business rules)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "nif",
          "message": "Invalid NIF format. Expected 9 characters (8 digits + letter or letter + 8 digits)",
          "value": "B123INVALID"
        },
        {
          "field": "lineas",
          "message": "At least one line item is required",
          "value": []
        },
        {
          "field": "receptor.direccion.codigo_postal",
          "message": "Invalid postal code format. Expected 5 digits",
          "value": "280"
        },
        {
          "field": "lineas[0].precio_unitario",
          "message": "Unit price must be greater than or equal to 0",
          "value": -10.5
        }
      ]
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_003"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Update client PUT

Updates an existing client

Create or validate multiple clients POST

Creates multiple clients in a single operation or validates data without persisting. **Validation flow:** 1. `dry_run=true`: Full validation only (NIFs, duplicates, format) without persistence 2. `dry_run=false`: Validation + actual creation **Validations performed:** - Individual validation of each client (same rules as single client creation) - Detection of duplicate NIFs within the batch - Detection of duplicate NIFs against existing database - Parallel NIF validation against AEAT registry (VeriFactu) - Field format verification (email, phone, etc.) **Result statuses:** - `VALID`: Client valid, ready to create - `WARNING`: Client valid but with warnings (e.g., missing email) - `ERROR`: Client invalid, cannot process - `DUPLICATE`: Duplicate NIF (in batch or existing DB) - `NIF_INVALID`: NIF not valid in AEAT registry **Atomicity:** - `dry_run=true`: Validation only, no persistence - `dry_run=false`: If any client fails, ALL clients are rejected (full atomicity)