Create or validate multiple clients
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)
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
Operation mode:
true: Validation only without persistence (recommended for frontend preview)false: Validation + actual creation (atomic operation)
false1 <= items <= 100Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.beel.es/api/v1/clientes/bulk" \ -H "Content-Type: application/json" \ -d '{ "clientes": [ { "nombre_fiscal": "string", "direccion": { "calle": "Calle Mayor, 123", "numero": "123", "codigo_postal": "28001", "poblacion": "Madrid", "provincia": "Madrid", "pais": "España" } } ] }'{
"success": true,
"data": {
"metadata": {
"total_clientes": 10,
"is_dry_run": true,
"processing_time_ms": 450,
"source_type": "CSV_IMPORT",
"filename": "clientes_enero.csv",
"file_size_bytes": 1048576,
"total_rows": 250
},
"clientes_validation": [
{
"index": 0,
"cliente": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"nombre_fiscal": "Empresa Cliente SL",
"nombre_comercial": "EmpresaCliente",
"nif": "12345678A",
"direccion": {
"calle": "Calle Mayor, 123",
"numero": "123",
"piso": "2º A",
"puerta": "A",
"codigo_postal": "28001",
"poblacion": "Madrid",
"provincia": "Madrid",
"pais": "España",
"codigo_pais": "ES"
},
"telefono": "+34 600 123 456",
"email": "user@example.com",
"emails_facturacion": [
"usuario@ejemplo.com"
],
"persona_contacto": "María García",
"notas": "string",
"forma_pago_preferida": {
"metodo": "NINGUNO",
"iban": "ES1234567890123456789012",
"swift": "ABCDESMMXXX",
"plazo_dias": 30
},
"descuento_general": 0,
"activo": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"id_otro": {
"tipo": "02",
"numero": "string",
"codigo_pais": "st"
}
},
"status": "VALID",
"errores": [
{
"campo": "nif",
"valor": "12345678X",
"mensaje": "NIF no encontrado en censo AEAT"
}
],
"warnings": [
{
"campo": "email",
"mensaje": "Email no proporcionado, se usará el NIF para facturación"
}
],
"row_number": 15
}
],
"statistics": {
"total_procesados": 10,
"validos": 6,
"con_warnings": 2,
"con_errores": 2,
"duplicados": 1,
"nifs_invalidos": 1,
"importados": 0,
"tasa_exito": 0.8,
"importables": 8,
"no_importables": 2
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": true,
"data": {
"clientes": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"nombre_fiscal": "Empresa Cliente SL",
"nombre_comercial": "EmpresaCliente",
"nif": "12345678A",
"direccion": {
"calle": "Calle Mayor, 123",
"numero": "123",
"piso": "2º A",
"puerta": "A",
"codigo_postal": "28001",
"poblacion": "Madrid",
"provincia": "Madrid",
"pais": "España",
"codigo_pais": "ES"
},
"telefono": "+34 600 123 456",
"email": "user@example.com",
"emails_facturacion": [
"usuario@ejemplo.com"
],
"persona_contacto": "María García",
"notas": "string",
"forma_pago_preferida": {
"metodo": "NINGUNO",
"iban": "ES1234567890123456789012",
"swift": "ABCDESMMXXX",
"plazo_dias": 30
},
"descuento_general": 0,
"activo": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"id_otro": {
"tipo": "02",
"numero": "string",
"codigo_pais": "st"
}
}
],
"total_creados": 5
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"error": {
"code": "BULK_VALIDATION_ERROR",
"message": "string",
"details": {
"campo": "specific error message"
},
"errors": [
{
"index": 0,
"field": "string",
"message": "string"
}
]
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "123e4567-e89b-12d3-a456-426614174000"
}
}