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

Issue an invoice

Scopeinvoices:write

Finalizes a draft invoice of this company: assigns its definitive number from the configured series and makes it immutable.

  • Irreversible: an issued invoice is corrected with a corrective invoice (POST …/{invoice_id}/corrective) or voided (POST …/{invoice_id}/void), never edited.
  • Asynchronous: PDF generation and submission to the AEAT happen after the response, so a 200 means the invoice was accepted for submission, not that the AEAT has registered it. Use wait_for_pdf to wait for the PDF.
  • Nothing to collect: a STANDARD or SIMPLIFIED invoice whose total_to_pay is 0 is issued as PAID, with payment_date equal to issue_date. It is registered with the AEAT like any other invoice, with a total of 0.
POST
/v1/companies/{company_id}/invoices/{invoice_id}/issue

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

Query Parameters

wait_for_pdf?boolean

If true, waits for PDF generation and returns the URL in the response. Adds ~1-2s of latency but guarantees the PDF is immediately available.

Defaultfalse
attach_source_invoices?boolean

Only applies when the invoice has automatic email sending enabled. If true, the email sent after issuing also attaches a ZIP (suplidos_<invoice-number>.zip) with the PDFs of the source invoices referenced by the invoice's SUPLIDO consolidation lines. Access to sources owned by managed accounts is re-checked with the same rules as issuing, and the request fails synchronously with an actionable error — never a partial ZIP — if the invoice has no consolidation sources (ATTACH_SOURCE_INVOICES_NO_SOURCES), a source is not reachable (ATTACH_SOURCE_INVOICE_UNAVAILABLE) or a source has no generated PDF (ATTACH_SOURCE_PDF_MISSING).

Defaultfalse

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000/issue"

State changed to ISSUED. Final number assigned, VeriFactu record generated with its hash, PDF generated

{
  "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"
      }
    },
    "recipient": {
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "legal_name": "Cliente Ejemplo SL",
      "nif": "B87654321"
    },
    "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"
        },
        "line_total": 1815
      }
    ],
    "totals": {
      "taxable_base": 1500,
      "total_vat": 315,
      "total_irpf": 0,
      "total_equivalence_surcharge": 0,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 1500,
          "amount": 315
        }
      ],
      "invoice_total": 1815
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES9121000418450200051332",
      "payment_term_days": 30
    },
    "verifactu": {
      "enabled": true,
      "invoice_hash": "A7F3C9E2B1D4F8A6C3E9B2D5F1A8C4E7B9D2F5A1C8E4B7D3F9A2C6E1B5D8F4A7",
      "qr_url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A%2F2025%2F0042&fecha=20-01-2025&importe=1815.00",
      "registered_at": "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-20T10:35:00Z",
    "request_id": "e3f4a5b6-c7d8-4e9f-0a1b-2c3d4e5f6a7b"
  }
}
{
  "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": "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": "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": "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": "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"
  }
}

Delete a draft invoice DELETE

Deletes a draft invoice of this company. The record is marked as deleted rather than removed. - **Issued invoices:** never deleted. They are voided with `POST …/{invoice_id}/void`, which leaves the fiscal trail. - **`source_proforma_id`:** when the draft came from converting a proforma, deleting it returns that proforma from `CONVERTED` to `ACTIVE`, editable and convertible again. Voiding or rectifying an issued invoice does not return its proforma; only deleting the draft does.

Apply one operation to a set of invoices POST

Applies one operation to a set of invoices of this company and reports, invoice by invoice, which succeeded and which failed. - **Operations:** `ISSUE` issues the draft invoices; `STATUS` moves them to the `new_status` given in the body. - **Limit:** up to 50 invoices per request (`invoice_ids`). - **Not atomic:** each invoice is processed on its own, and since issuing is irreversible, the ones already issued stay issued if a later one fails. - **Related:** downloading PDFs, sending email and exporting are not operations of this batch — use `…/invoices/pdf-archive`, `…/invoices/deliveries` and `…/invoices/exports`.