NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoices

List the VeriFactu records of an invoice

Scopeinvoices:read

Returns the VeriFactu records of this invoice, each with its own status, ordered by registered_at ascending: the registration first and, if the invoice was voided, its cancellation after it. A record rejected before reaching the AEAT is listed too, as REJECTED, until the invoice is submitted again: the new record then replaces it.

  • No records: an invoice that was never submitted (a draft, or one outside VeriFactu) answers 200 with an empty list.

Closed catalogue. This collection is fixed and bounded: it carries no pagination, it takes no page/limit, and every response holds the whole set.

GET
/v1/companies/{company_id}/invoices/{invoice_id}/verifactu-records

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

company_idstring

Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid
invoice_idstring

Invoice ID

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/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000/verifactu-records"
{
  "success": true,
  "data": {
    "records": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "operation": "REGISTRATION",
        "submission_status": "ACCEPTED",
        "invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
        "registration_number": "4f8c2a1e-9b3d-4e7a-8c5f-1d2e3f4a5b6c",
        "registered_at": "2019-08-24T14:15:22Z",
        "qr_url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A%2F2025%2F0042&fecha=20-01-2025&importe=1590.00",
        "error_code": "3000",
        "error_message": "Factura ya existe en el sistema"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice 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"
  }
}

Void an issued invoice POST

Voids an issued invoice of this company. The document is kept and its number is never reused. - **When to use it:** the invoice was issued by mistake — the operation never took place, it was a test, or it is an accidental duplicate. If the operation did take place but the invoice is wrong, issue a corrective invoice instead (`POST …/{invoice_id}/corrective`). The exception is a withholding that should not have been applied: it is not a cause for a corrective, so void the invoice and issue a new one without it. - **Sent or paid:** voiding an invoice that was already sent or paid requires `issued_in_error: true`, confirming it was issued by mistake; without it the request fails with `422 VOID_REQUIRES_ISSUED_IN_ERROR`. - **Corrected invoices:** an invoice with live corrective invoices cannot be voided — it was corrected, so the operation took place; issue another corrective (`422 INVOICE_HAS_LIVE_CORRECTIVES`). A `TOTAL` corrective cannot be voided either: the invoice it rectifies would stay voided with nothing to offset it (`422 TOTAL_CORRECTIVE_NOT_VOIDABLE`). - **`reason`:** required, at least 10 characters — it is fiscal data. - **`void_date`:** deprecated. A date earlier than the invoice's issue date is rejected with `422 VOID_DATE_BEFORE_ISSUE_DATE`. - **VeriFactu:** when it is enabled for the invoice, a cancellation record is submitted to the AEAT. - **PDF:** unchanged. The PDF of the invoice stays the one that was delivered; the void is reported by the invoice's `status` and the `invoice.voided` webhook. - **Proformas:** voiding an `ACTIVE` proforma is a plain status change with no fiscal effect — no corrective invoice, nothing submitted to the AEAT. The voided proforma is kept as the record of a rejected or withdrawn offer and stays listed.

Create an invoice (deprecated) POST

Creates an invoice, optionally numbered and issued in the same call with `options.issue_directly: true`. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices`, which behaves identically. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.