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

Remove the scheduling of an invoice

Scopeinvoices:write

Removes the scheduling of an invoice, returning it to a plain draft. Idempotent: an invoice that is not scheduled answers 204 all the same. Unlike the PUT, it does not require the scheduled_invoices feature.


DELETE
/v1/companies/{company_id}/invoices/{invoice_id}/schedule
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

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

curl -X DELETE "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000/schedule"
Empty
{
  "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": "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"
  }
}

Get the scheduling of an invoice GET

Returns the date and generation mode currently scheduled for this invoice. An invoice with no scheduling answers `404`, since the sub-resource does not exist yet. To move only the date, read the current `generation_mode` here and send it back on the `PUT`.

Create a corrective invoice POST

Issues a corrective invoice that amends the invoice in the path. It is a new fiscal document with its own number, not an edit of the original. - **`rectification_type`:** `TOTAL` leaves the original `VOIDED` and rectifies what is still invoiced on it: every line of the original and of its live correctives (voided ones do not count), negated. It takes no `lines` — sending them fails with `422 RECTIFICATIVA_TOTAL_CON_LINEAS`. `PARTIAL` leaves the original `RECTIFIED` and requires the adjustment `lines`. - **Never more than was invoiced:** a `PARTIAL` may raise any amount, but may not take the taxable base of any rate (tax, rate and equivalence surcharge; `SUPLIDO` lines by their amount) below zero once the previous correctives are counted. That fails with `422 CORRECTIVE_EXCEEDS_INVOICED_AMOUNT`, and `error.details` (`CorrectiveInvoiceErrorDetails`) carries `tax_group` (for example `IVA 21%`) and `max_reduction`, how much of that rate is left to rectify. A `TOTAL` on an invoice that previous correctives already brought to zero fails with `422 CORRECTIVE_NOTHING_LEFT_TO_RECTIFY`. - **Not for the withholding alone:** a `PARTIAL` whose lines leave the taxable base of every rate unchanged and only change the withholding fails with `422 CORRECTIVE_WITHHOLDING_ONLY`. A withholding is not a cause for a corrective: void the invoice and issue a new one without it. - **The original's PDF:** unchanged by either type. The corrective has its own PDF; the original keeps the one that was delivered, and its new status is in `status`. - **Total of 0:** a corrective whose `total_to_pay` is 0 has nothing to refund or collect, so it is issued as `PAID`, with `payment_date` equal to `issue_date`. - **What can be rectified:** an ordinary or simplified invoice in `ISSUED`, `SENT`, `PAID`, `OVERDUE` or `RECTIFIED`. Rectifying a corrective fails with `422 CORRECTIVE_NOT_RECTIFIABLE` — to fix an erroneous corrective, issue another one against the original invoice. - **Repeat rectifications:** several `PARTIAL` correctives are allowed, but a `VOIDED` invoice is no longer rectifiable, so a second `TOTAL` against the same invoice fails with `422 INVOICE_NOT_CORRECTIBLE_IN_CURRENT_STATUS`. - **Correcting the recipient's data:** when the invoice recorded its recipient with a wrong name, tax ID or address, send the corrected `recipient` with `rectification_type` `PARTIAL`, `rectification_code` `R4` and no `lines`. The corrective carries the corrected recipient and does not change the amounts: its lines negate what is still invoiced and repeat it, so every rate nets to zero. A different person is not a data correction (`422 CORRECTIVE_RECIPIENT_IS_ANOTHER_PERSON`): correct the invoice in full and issue a new one to the right customer. - **Original rejected by the AEAT:** when VeriFactu rejected the original's record and it has not been resubmitted, the original is not in the AEAT's books: fix and resubmit it first. Until then the request fails with `422 CORRECTIVE_ORIGINAL_RECORD_REJECTED`. - **Exchange invoice recorded as F3:** correcting a full invoice issued in exchange for simplified invoices is not available yet: `422 EXCHANGE_INVOICE_NOT_CORRECTABLE`. Contact support. - **Deadline:** four years from when the tax accrued (the original's operation date) or, for a cause of article 80 of the VAT Act, from the `circumstance_date` you declare. Past it the request fails with `422 CORRECTIVE_OUT_OF_TIME`, with `deadline` and `counted_from` in `error.details` (`CorrectiveInvoiceErrorDetails`). - **What the reason code requires** (Ley 37/1992, art. 80): `R2` (insolvency) and `R3` (bad debt) need a recipient established in Spain, the Canary Islands, Ceuta or Melilla —an `R2` also accepts a recipient in another EU member state, for insolvency proceedings there— and fail otherwise with `422 CORRECTIVE_RECIPIENT_NOT_ESTABLISHED`. An `R3` needs at least six months since the original's operation date (`422 CORRECTIVE_BAD_DEBT_TOO_EARLY`, with `earliest_date`; one year when the previous year's turnover exceeded 6,010,121.04 €, which is the issuer's to apply), and on an operation with a base of 50 € or less it needs `recipient_is_business` (`422 CORRECTIVE_BAD_DEBT_BASE_TOO_LOW`). The other conditions of each code (claims, guarantees, related parties, filing with the AEAT) are the issuer's to meet. - **Fiscal inheritance on a `PARTIAL`:** a line that omits `irpf_rate` or `equivalence_surcharge_rate` takes it from the **original invoice** — the document being amended — and never from the company's current tax profile, so a profile that changed after the original was issued does not leak into the credit note. An explicit value always wins, `0` included. The surcharge inherits the *regime* (on/off), not the rate: the rate is re-derived from each corrective line's own VAT (21→5.2, 10→1.4, 5→0.62, 4→0.5), and an original outside the regime pins the line to `0`. `SUPLIDO` lines are out of it on both sides. When the original is not unambiguous BeeL does not pick for you: different IRPF rates per line fail with `422 CORRECTIVE_ORIGINAL_MIXED_IRPF`, and a surcharge applied on some lines but not others fails with `422 CORRECTIVE_ORIGINAL_MIXED_SURCHARGE`. Declare the figure on every line to get past either — both only fire when some line actually needs to inherit. - **`series_id`:** when omitted, the document is numbered in the company's default corrective series, never in the series of the original: corrective invoices go in a series of their own (RD 1619/2012, art. 6.1.a). If the company has none, it is created on first use (code `R`, or the next free one that cannot repeat another series' numbers). An explicit `series_id` must be a corrective series. - **Numbering conflict:** if the number the series would assign is already used by another invoice of the same company, in this series or in another one, the request fails with `400 SERIES_NUMBER_COLLISION` without issuing anything or consuming a number. The series needs review, so contact support.