Invoices

Get invoice by ID

Retrieves complete details of a specific invoice

GET
/v1/invoices/{invoice_id}

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

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000"

Single invoice retrieved with full details including VeriFactu signature and PDF URL

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "invoice_number": "A/2025/0042",
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "A"
    },
    "number": 42,
    "type": "STANDARD",
    "status": "ISSUED",
    "issue_date": "2025-01-20",
    "due_date": "2025-02-20",
    "issuer": {
      "legal_name": "Tu Empresa SL",
      "nif": "B12345678",
      "address": {
        "street": "Calle Ejemplo",
        "number": "123",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España"
      },
      "email": "info@tuempresa.es",
      "phone": "+34912345678"
    },
    "recipient": {
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "legal_name": "Cliente Ejemplo SL",
      "nif": "B87654321",
      "email": "cliente@ejemplo.com",
      "address": {
        "street": "Avenida Cliente",
        "number": "456",
        "postal_code": "28013",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España"
      }
    },
    "lines": [
      {
        "description": "Corporate website development",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 37.5,
        "discount_percentage": 0,
        "taxable_base": 1500,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "irpf_rate": 15,
        "line_total": 1590
      }
    ],
    "totals": {
      "taxable_base": 1500,
      "total_vat": 315,
      "total_irpf": 225,
      "total_equivalence_surcharge": 0,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 1500,
          "amount": 315
        }
      ],
      "irpf_breakdown": [
        {
          "type": 15,
          "base": 1500,
          "amount": 225
        }
      ],
      "invoice_total": 1590
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES9121000418450200051332",
      "payment_term_days": 30
    },
    "notes": "Payment via bank transfer",
    "verifactu": {
      "enabled": true,
      "invoice_hash": "a7f3c9e2b1d4f8a6c3e9b2d5f1a8c4e7b9d2f5a1c8e4b7d3f9a2c6e1b5d8f4a7",
      "chaining_hash": "c9e2b1d4f8a6c3e9b2d5f1a8c4e7b9d2f5a1c8e4b7d3f9a2c6e1b5d8f4a7b3c1",
      "qr_url": "https://verifactu.agenciatributaria.gob.es/v?id=a7f3c9e2b1d4f8a6",
      "registration_date": "2025-01-20T10:35:00Z",
      "submission_status": "ACCEPTED"
    },
    "pdf_download_url": "/v1/invoices/f47ac10b-58cc-4372-a567-0e02b2c3d479/pdf",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:35:00Z"
  },
  "meta": {
    "timestamp": "2025-01-20T11:00:00Z",
    "request_id": "f4a5b6c7-d8e9-4f0a-1b2c-3d4e5f6a7b8c"
  }
}
{
  "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": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Get invoice PDF download URL GET

Generates a temporary pre-signed URL to download the invoice PDF. **Security:** - URL expires automatically in 5 minutes - HMAC signature prevents tampering - Only allows download (GET), no modification **Benefits:** - Direct download from storage (bypasses backend) - Better performance and lower server load - Compatible with browser cache and CDN - Ideal for large files **Frontend usage:** ```javascript const response = await fetch('/v1/invoices/{id}/pdf'); const { download_url } = await response.json(); window.open(download_url, '_blank'); // Direct download ``` **Format:** PDF is generated according to Spanish tax regulations.

Issue invoice (DRAFT → ISSUED) POST

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