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>

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