Invoices

Change status of multiple invoices

Changes the status of multiple invoices in a single operation. **Supported status changes:** - **SENT:** Mark multiple invoices as sent (from ISSUED) - **PAID:** Mark multiple invoices as paid (from ISSUED, SENT, or OVERDUE) **Partial success:** If some invoices cannot be updated, the operation continues with the others. The response includes details of failures. **Limits:** - Maximum 50 invoices per request **Validations:** - All invoices must belong to the authenticated user - Each invoice must be in a valid status for the requested transition - For PAID: payment_date is required

POST
/v1/invoices/bulk/status

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

invoice_idsarray<UUID>

List of invoice IDs to update

Items1 <= items <= 50
new_statusstring

Target status for the invoices

Value in"SENT" | "PAID"
payment_date?string

Payment date (required when new_status is PAID)

Formatdate

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/bulk/status" \  -H "Content-Type: application/json" \  -d '{    "invoice_ids": [      "550e8400-e29b-41d4-a716-446655440001",      "550e8400-e29b-41d4-a716-446655440002"    ],    "new_status": "SENT"  }'
{
  "success": true,
  "data": {
    "total": 5,
    "successful": 4,
    "failed": 1,
    "failures": [
      {
        "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
        "reason": "Cannot change from PAID to SENT"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "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": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "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"
  }
}

Update invoice series PUT

Updates an existing invoice series. Can only update: - Description - Active/inactive status - Whether it is default Cannot modify: code, prefix, number_format (to maintain consistency with existing invoices). Business rules: - Cannot deactivate a default series (must set another as default first) - Cannot mark an inactive series as default

Create corrective invoice POST

Creates a corrective invoice to correct or void an issued invoice. **Rectification types:** - **TOTAL**: Completely voids the original invoice (original status → VOIDED) - **PARTIAL**: Partially corrects the original invoice (original status → RECTIFIED) **VeriFactu codes:** - R1: Legal error and Art. 80 One, Two and Six LIVA - R2: Article 80 Three LIVA (Bankruptcy) - R3: Article 80 Four LIVA (Bad debts) - R4: Other causes - R5: Simplified invoices (only for simplified) **Validations:** - Original invoice must be in status ISSUED, SENT, PAID, OVERDUE or RECTIFIED - Cannot rectify a DRAFT invoice (must be issued first) - Cannot rectify a VOIDED invoice (final status) - For TOTAL rectification: Another total corrective cannot already exist - For PARTIAL rectification: Multiple partial correctives are allowed **Lines:** - TOTAL: Optional (if not provided, original lines are copied with negated amounts) - PARTIAL: REQUIRED (adjustment lines with positive or negative amounts)