NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

Get an invoice

Scopeinvoices:read

Retrieves the full details of an invoice.

GET
/v1/invoices/{invoice_id}

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

invoice_idstring

Invoice ID

Formatuuid

Header Parameters

BeeL-Active-Company?string

Which company (tax ID) the request operates on.

An API key belongs to an account, and an account may hold several companies. Endpoints that read or write company-owned data — invoices, customers, products, series, tax and VeriFactu settings — resolve their target company from this header when the path does not already name one.

On a path that names the company, such as /v1/companies/{company_id}/invoices, the path is the target and this header is not read at all: it neither switches the target nor makes the request fail, so sending one that disagrees with the path is silently ignored rather than rejected. Prefer those paths whenever you need to be explicit about which tax ID you are operating on.

On an account holding a single company the header may be omitted — that company is used. On an account holding several it is required: the request fails with 403 ACTIVE_COMPANY_REQUIRED otherwise. A company-owned record always belongs to one tax ID, so operating on it without saying which one has no meaning.

The company does not have to belong to the API key's own account: one you manage works too, which is what makes the company_id returned by POST /v1/accounts usable here to invoice on a provisioned account's behalf. What you may do with it is then decided by your access level over that account, and issuing also requires a signed fiscal representation.

This header is how you operate on a company, never how you find one: a value you do not reach answers 403, the same as one that does not exist, so guessing reveals nothing. Get the company_id from the response that created the company.

Requires the companies:read scope. Returns 403 if the company is neither yours nor one you manage.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

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": "B12345674",
      "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/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/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": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "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": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "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"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Issue several draft invoices POST

Issues several draft invoices at once, each one assigned its definitive number. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices/batches` with `operation: ISSUE`, which issues the same drafts. - **Limits:** up to 50 invoices per call. - **Not atomic:** each invoice is issued in its own transaction, and since issuing is irreversible, the ones already issued stay issued if a later one fails.

List invoices GET

Returns a paginated list of invoices, with filters, sorting and pagination. - **Deprecated:** use `GET /v1/companies/{company_id}/invoices`, which returns the same list with the same filters. - **Difference:** the legacy alias `external_reference` is not carried over there. Use `external_ref`, which this route also accepts.