Invoices

Issue invoice (DRAFT → ISSUED)

Finalizes a draft invoice and marks it as issued. **Status change:** `DRAFT` → `ISSUED` **Actions performed:** - Assigns definitive invoice number according to configured series - Marks invoice as finalized (not modifiable) - Prepares invoice for sending to customer **Validations:** - Invoice must be in DRAFT status - All invoice data must be complete and valid **Note:** After issuing, the invoice can be sent to the customer via the `/invoices/{id}/send` endpoint

POST
/v1/invoices/{invoice_id}/issue

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

Path Parameters

invoice_idstring

Invoice ID

Formatuuid

Query Parameters

wait_for_pdf?boolean

If true, waits for PDF generation and returns the URL in the response. Adds ~1-2s latency but guarantees PDF is immediately available. If false (default), PDF is generated asynchronously.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/issue"
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoice_number": "2025/0001",
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "FAC"
    },
    "number": 1,
    "type": "STANDARD",
    "status": "SCHEDULED",
    "issue_date": "2025-01-15",
    "operation_date": "2025-01-10",
    "due_date": "2025-02-14",
    "payment_date": "2025-01-20",
    "sent_at": "2025-01-29T18:45:00Z",
    "paid_at": "2025-02-05T10:30:00Z",
    "auto_emit_after": "2025-03-20",
    "scheduled_for": "2025-02-15",
    "scheduled_action": "DRAFT",
    "issuer": {
      "legal_name": "Juan Pérez García",
      "trade_name": "JP Web Development",
      "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": "https://beel.es",
      "logo_url": "string",
      "additional_info": "Nº Colegiado: 12345"
    },
    "recipient": {
      "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
      "legal_name": "Empresa SL",
      "trade_name": "Empresa",
      "nif": "12345678A",
      "alternative_id": {
        "type": "NIF_IVA",
        "number": "string",
        "country_code": "st"
      },
      "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"
    },
    "lines": [
      {
        "description": "Web application development",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 50,
        "discount_percentage": 10,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "equivalence_surcharge_rate": 5.2,
        "irpf_rate": 15,
        "exemption_reason": "EXENTA_ART_20",
        "exemption_reason_text": "string",
        "taxable_base": 1800,
        "line_total": 2178
      }
    ],
    "totals": {
      "taxable_base": 2000,
      "total_discounts": 0,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 2000,
          "amount": 420
        }
      ],
      "total_vat": 420,
      "surcharge_breakdown": [
        {
          "type": 0,
          "base": 0,
          "amount": 0
        }
      ],
      "total_equivalence_surcharge": 0,
      "irpf_breakdown": [
        {
          "type": 0,
          "base": 0,
          "amount": 0
        }
      ],
      "total_irpf": 300,
      "invoice_total": 2120
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "notes": "string",
    "rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
    "rectification_reason": "string",
    "recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
    "recurring_invoice_name": "string",
    "rectification_type": "TOTAL",
    "rectification_code": "R1",
    "metadata": {
      "stripe_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "stripe_charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
      "external_order_id": "ORD-2025-0042",
      "payment_platform": "stripe"
    },
    "send_automatically": true,
    "email_config": {
      "recipients": [
        "client@example.com"
      ],
      "cc": [
        "accounting@example.com"
      ],
      "subject": "Invoice 2025/0001 - Development services",
      "message": "Please find attached the requested invoice. We remain at your disposal for any clarification."
    },
    "pdf_download_url": "/v1/invoices/550e8400-e29b-41d4-a716-446655440000/pdf",
    "verifactu": {
      "enabled": false,
      "invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
      "chaining_hash": "7F8E9D0C1B2A3F4E5D6C7B8A9F0E1D2C3B4A5F6E7D8C9B0A1F2E3D4C5B6A7F8",
      "registration_number": "VERIFACTU2025000001",
      "qr_url": "https://verifactu.agenciatributaria.gob.es/v?id=ABC123XYZ",
      "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
      "registration_date": "2019-08-24T14:15:22Z",
      "submission_status": "PENDING",
      "error_code": "3000",
      "error_message": "Factura ya existe en el sistema"
    },
    "attachments": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "url": "string",
        "type": "string"
      }
    ],
    "sending_history": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "date": "2019-08-24T14:15:22Z",
        "recipient": "user@example.com",
        "status": "SENT",
        "error": "string"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "deleted_at": "2019-08-24T14:15:22Z"
  },
  "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": "NOT_FOUND",
    "message": "Resource not found"
  },
  "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"
  }
}

Get invoice by ID GET

Retrieves complete details of a specific invoice

List invoices GET

Returns a paginated list of invoices with optional filters