VeriFactu

Update VeriFactu configuration

Updates the user's VeriFactu configuration. **Business rules:** - If `enabled` is false, `apply_by_default` must also be false - If `apply_by_default` is true, `enabled` must be true

PUT
/v1/configuration/verifactu

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

Request Body

enabledboolean

Whether VeriFactu is enabled for this user. When enabled, the user can submit invoices to AEAT. Freelancers who don't need to submit invoices to AEAT can leave it disabled.

Defaultfalse
apply_by_defaultboolean

Whether VeriFactu should be automatically applied to new invoices. Requires 'enabled' to be true.

Defaultfalse
nif_status?string|null

VeriFactu registration status (can be null if VeriFactu was never enabled):

  • PENDING: Initial registration in progress
  • ACTIVATED: NIF validated and user created in the corresponding environment
  • DEACTIVATED: Deactivated (data retained for 30 days)
  • ERROR: Some step of the process failed
Value in"PENDING" | "ACTIVATED" | "DEACTIVATED" | "ERROR"
nif_registered_at?string|null

Successful activation date in VeriFactu production

Formatdate-time

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://app.beel.es/api/v1/configuration/verifactu" \  -H "Content-Type: application/json" \  -d '{    "enabled": false,    "apply_by_default": false  }'
{
  "success": true,
  "data": {
    "enabled": false,
    "apply_by_default": false,
    "nif_status": "PENDING",
    "nif_registered_at": "2019-08-24T14:15:22Z"
  },
  "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": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "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"
  }
}

Get VeriFactu configuration GET

Retrieves the current VeriFactu configuration

Create webhook subscription POST

Register an HTTPS endpoint to receive real-time event notifications. Every delivery is signed with BeeL-Signature (HMAC-SHA256). The secret is returned once on creation — store it securely. Maximum 10 active webhook subscriptions per account.