Customers

Create or validate multiple customers

Creates multiple customers 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 customer (same rules as single customer 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`: Customer valid, ready to create - `WARNING`: Customer valid but with warnings (e.g., missing email) - `ERROR`: Customer 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 customer fails, ALL customers are rejected (full atomicity)

POST
/v1/customers/bulk

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

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

dry_run?boolean

Operation mode:

  • true: Validation only without persistence (recommended for frontend preview)
  • false: Validation + actual creation (atomic operation)
Defaultfalse

Request Body

customers
Items1 <= items <= 500

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/customers/bulk" \  -H "Content-Type: application/json" \  -d '{    "customers": [      {        "legal_name": "string",        "address": {          "street": "Calle Mayor, 123",          "number": "123",          "postal_code": "28001",          "city": "Madrid",          "province": "Madrid",          "country": "España"        }      }    ]  }'
{
  "success": true,
  "data": {
    "metadata": {
      "total_customers": 10,
      "is_dry_run": true,
      "processing_time_ms": 450,
      "source_type": "CSV_IMPORT",
      "filename": "clientes_enero.csv",
      "file_size_bytes": 1048576,
      "total_rows": 250
    },
    "customers_validation": [
      {
        "index": 0,
        "customer": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "legal_name": "Empresa Cliente SL",
          "trade_name": "EmpresaCliente",
          "nif": "12345678A",
          "address": {
            "street": "Calle Mayor, 123",
            "number": "123",
            "floor": "2º A",
            "door": "A",
            "postal_code": "28001",
            "city": "Madrid",
            "province": "Madrid",
            "country": "España",
            "country_code": "ES"
          },
          "phone": "+34 612 345 678",
          "email": "user@example.com",
          "web": "string",
          "billing_emails": [
            "user@example.com"
          ],
          "contact_person": "María García",
          "notes": "string",
          "preferred_payment_method": {
            "method": "BANK_TRANSFER",
            "iban": "ES1234567890123456789012",
            "swift": "ABCDESMMXXX",
            "payment_term_days": 30
          },
          "general_discount": 0,
          "active": true,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "alternative_id": {
            "type": "NIF_IVA",
            "number": "string",
            "country_code": "st"
          }
        },
        "status": "VALID",
        "errors": [
          {
            "field": "nif",
            "value": "12345678X",
            "message": "NIF not found in AEAT census"
          }
        ],
        "warnings": [
          {
            "field": "email",
            "message": "Email not provided, NIF will be used for invoicing"
          }
        ],
        "row_number": 15
      }
    ],
    "statistics": {
      "total_processed": 10,
      "valid": 6,
      "with_warnings": 2,
      "with_errors": 2,
      "duplicates": 1,
      "invalid_nifs": 1,
      "imported": 0,
      "success_rate": 0.8,
      "importable": 8,
      "not_importable": 2
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "legal_name": "Empresa Cliente SL",
        "trade_name": "EmpresaCliente",
        "nif": "12345678A",
        "address": {
          "street": "Calle Mayor, 123",
          "number": "123",
          "floor": "2º A",
          "door": "A",
          "postal_code": "28001",
          "city": "Madrid",
          "province": "Madrid",
          "country": "España",
          "country_code": "ES"
        },
        "phone": "+34 612 345 678",
        "email": "user@example.com",
        "web": "string",
        "billing_emails": [
          "user@example.com"
        ],
        "contact_person": "María García",
        "notes": "string",
        "preferred_payment_method": {
          "method": "BANK_TRANSFER",
          "iban": "ES1234567890123456789012",
          "swift": "ABCDESMMXXX",
          "payment_term_days": 30
        },
        "general_discount": 0,
        "active": true,
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "alternative_id": {
          "type": "NIF_IVA",
          "number": "string",
          "country_code": "st"
        }
      }
    ],
    "total_created": 5
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BULK_VALIDATION_ERROR",
    "message": "string",
    "details": {
      "field": "specific error message"
    },
    "errors": [
      {
        "index": 0,
        "field": "string",
        "message": "string"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Create customer POST

Creates a new customer. **Idempotency:** Supports `Idempotency-Key` header to prevent duplicates when a request is retried (network timeout, double-click, etc.).

Deactivate customer DELETE

Deactivates (marks as deleted) a customer. **Soft delete:** The customer is not physically deleted, only marked as inactive. **Restriction:** Cannot deactivate a customer with associated invoices.