Create a corrective invoice

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

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

company_idstring

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF 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)
If the same key is sent twice, the result of the first operation is returned
Keys 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.

Status	Code	When
`400`	`INVALID_IDEMPOTENCY_KEY`	The key breaks the format rules above.
`409`	`IDEMPOTENCY_KEY_PROCESSING`	The first request is still in flight. Wait and retry with the same key.
`409`	`IDEMPOTENCY_KEY_MISMATCH`	The key was already used with a different body. Use a new key.

Match^[a-zA-Z0-9_-]+$

Lengthlength <= 255

Request Body

rectification_typestring

Type of rectification applied to a corrective invoice:

TOTAL: Completely cancels the original invoice (status → VOIDED)
PARTIAL: Partially corrects the original invoice (status → RECTIFIED)

Value in"TOTAL" | "PARTIAL"

rectification_codestring

Rectification codes according to VeriFactu regulations (AEAT):

R1: Error founded in law and Art. 80 One, Two and Six LIVA
R2: Article 80 Three LIVA (Bankruptcy proceedings)
R3: Article 80 Four LIVA (Uncollectable debts)
R4: Other causes
R5: Simplified invoices (Art. 80 One and Two LIVA) - ONLY for simplified invoices

Value in"R1" | "R2" | "R3" | "R4" | "R5"

reasonstring

Detailed reason for rectification (minimum 10 characters)

Length10 <= length <= 1000

lines?

TOTAL: Optional (if not sent, original invoice lines are copied negated) PARTIAL: REQUIRED (adjustment lines with positive or negative amounts)

notes?string

Additional observations about the rectification

Lengthlength <= 1000

series_id?string

Series for the corrective invoice. Optional: if not specified, the company's default series for corrective invoices is used — not the original invoice's series, which is an ordinary or simplified one and cannot hold a corrective. If the company has no default corrective series the request fails with 422 SERIES_DEFAULT_NOT_FOUND; a series of the wrong type fails with 422 SERIES_INCOMPATIBLE_DOC_TYPE.

Formatuuid

external_ref?string

Client-supplied identifier from an external system (order, cart, contract…). Stored as-is, echoed back on read, and filterable via GET /v1/invoices?external_ref=. Optional. Enforced UNIQUE per issuer for live standard/simplified invoices: creating a second invoice with the same reference returns 409 (INVOICE_DUPLICATE_EXTERNAL_REFERENCE); deleting the existing one lets you recreate. Corrective invoices are exempt from that uniqueness: a corrective carries the same order reference as the invoice it corrects, so both can coexist. This is a business key, NOT the Idempotency-Key (which guards request retries).

Lengthlength <= 255

metadata?

Your own key/value pairs to cross-reference this invoice with records in your system (order ids, tenants, internal codes). Namespace them to avoid clashing with the system keys BeeL adds on payment-generated invoices.

options?

Controls how the invoice is processed after creation. All fields default to false if not specified, except verifactu_enabled, which falls back to the company's declared preference (see its description).

Common combinations:

Draft (default): omit options or set all to false
Issue immediately: { issue_directly: true }
Issue + wait for PDF: { issue_directly: true, wait_for_pdf: true }
Issue + send email: { issue_directly: true, send_automatically: true }
Full automation: { issue_directly: true, wait_for_pdf: true, send_automatically: true, email_config: { ... } }

Response Body

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000/corrective" \
  -H "Content-Type: application/json" \
  -d '{
    "rectification_type": "PARTIAL",
    "rectification_code": "R4",
    "reason": "Amount correction due to calculation error in hours worked during the project",
    "lines": [
      {
        "description": "Adjustment for hours error - Sprint 1",
        "quantity": -5,
        "unit": "hours",
        "unit_price": 50,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "irpf_rate": 15
      }
    ],
    "notes": "Rectification agreed with the customer on 2025-01-20",
    "external_ref": "ORD-2025-0042",
    "metadata": {
      "project_code": "PROJ-123"
    },
    "options": {
      "verifactu_enabled": false,
      "issue_directly": true,
      "send_automatically": false
    }
  }'

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000/corrective" \  -H "Content-Type: application/json" \  -d '{    "rectification_type": "PARTIAL",    "rectification_code": "R4",    "reason": "Amount correction due to calculation error in hours worked during the project",    "lines": [      {        "description": "Adjustment for hours error - Sprint 1",        "quantity": -5,        "unit": "hours",        "unit_price": 50,        "main_tax": {          "type": "IVA",          "percentage": 21,          "regime_key": "01"        },        "irpf_rate": 15      }    ],    "notes": "Rectification agreed with the customer on 2025-01-20",    "external_ref": "ORD-2025-0042",    "metadata": {      "project_code": "PROJ-123"    },    "options": {      "verifactu_enabled": false,      "issue_directly": true,      "send_automatically": false    }  }'

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "invoice_number": "2025/0001",
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "FAC"
    },
    "number": 1,
    "type": "STANDARD",
    "status": "SCHEDULED",
    "issue_date": "2025-01-15",
    "operation_date": "2025-01-10",
    "due_date": "2025-02-14",
    "valid_until": "2025-02-28",
    "payment_date": "2025-01-20",
    "sent_at": "2025-01-29T18:45:00Z",
    "paid_at": "2025-02-05T10:30:00Z",
    "auto_emit_after": "2025-03-20",
    "scheduled_for": "2025-02-15",
    "scheduled_action": "DRAFT",
    "issuer": {
      "legal_name": "Juan Pérez García",
      "trade_name": "JP Web Development",
      "nif": "12345678A",
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      },
      "phone": "+34 612 345 678",
      "email": "user@example.com",
      "website": "https://beel.es",
      "logo_url": "string",
      "additional_info": "Nº Colegiado: 12345"
    },
    "recipient": {
      "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
      "legal_name": "Empresa SL",
      "trade_name": "Empresa",
      "nif": "12345678A",
      "alternative_id": {
        "type": "NIF_IVA",
        "number": "string",
        "country_code": "st"
      },
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      },
      "phone": "+34 612 345 678",
      "email": "user@example.com"
    },
    "lines": [
      {
        "description": "Web application development",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 50,
        "discount_percentage": 10,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "equivalence_surcharge_rate": 5.2,
        "irpf_rate": 15,
        "exemption_reason": "EXENTA_ART_20",
        "exemption_reason_text": "string",
        "taxable_base": 1800,
        "line_total": 2178,
        "pricing_mode": "UNIT_PRICE",
        "total_excluding_tax": 1,
        "total_including_tax": 100,
        "line_type": "NORMAL",
        "source_invoice_reference": "string",
        "source_invoice_ids": [
          "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ]
      }
    ],
    "totals": {
      "taxable_base": 2000,
      "total_discounts": 0,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 2000,
          "amount": 420
        }
      ],
      "total_vat": 420,
      "surcharge_breakdown": [
        {
          "type": 0,
          "base": 0,
          "amount": 0
        }
      ],
      "total_equivalence_surcharge": 0,
      "irpf_breakdown": [
        {
          "type": 0,
          "base": 0,
          "amount": 0
        }
      ],
      "total_irpf": 300,
      "invoice_total": 2120,
      "total_disbursements": 0,
      "total_to_pay": 2120
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "notes": "string",
    "void_cause": "VOID_REQUEST",
    "void_reason": "string",
    "voided_at": "2025-01-20T09:12:44Z",
    "rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
    "source_proforma_id": "5f6c4143-c67e-4332-9fbc-f68d1420128f",
    "converted_invoice_id": "c85716fe-5512-4945-9dc8-daa0106a270b",
    "rectification_reason": "string",
    "recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
    "recurring_invoice_name": "string",
    "rectification_type": "TOTAL",
    "rectification_code": "R1",
    "external_ref": "ORD-2025-0042",
    "metadata": {
      "external_customer_id": "cus_ULGk8bzIr88aag",
      "external_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "payment_intent_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
      "payment_provider": "STRIPE_CONNECT",
      "external_order_id": "ORD-2025-0042"
    },
    "send_automatically": true,
    "email_config": {
      "recipients": [
        "client@example.com"
      ],
      "cc": [
        "accounting@example.com"
      ],
      "subject": "Invoice 2025/0001 - Development services",
      "message": "Please find attached the requested invoice. We remain at your disposal for any clarification."
    },
    "pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/550e8400-e29b-41d4-a716-446655440000/pdf",
    "verifactu": {
      "enabled": false,
      "invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
      "chaining_hash": "7F8E9D0C1B2A3F4E5D6C7B8A9F0E1D2C3B4A5F6E7D8C9B0A1F2E3D4C5B6A7F8",
      "registration_number": "VERIFACTU2025000001",
      "qr_url": "https://verifactu.agenciatributaria.gob.es/v?id=ABC123XYZ",
      "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
      "registered_at": "2019-08-24T14:15:22Z",
      "submission_status": "ACCEPTED",
      "skip_reason": "CONFIG_DISABLED",
      "error_code": "3000",
      "error_message": "Factura ya existe en el sistema"
    },
    "attachments": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "url": "string",
        "type": "string"
      }
    ],
    "sending_history": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "recipients": [
          "string"
        ],
        "cc": [
          "string"
        ],
        "subject": "string",
        "status": "SENT",
        "sent_at": "2025-01-29T18:45:00Z",
        "external_message_id": "string",
        "error": "string"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "deleted_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_JSON_FORMAT",
    "message": "The field 'due_date' has an invalid date format: '2026-03-04fds'. Expected format: YYYY-MM-DD.",
    "details": {
      "field": "due_date",
      "invalid_value": "2026-03-04fds",
      "expected_format": "YYYY-MM-DD"
    }
  },
  "meta": {
    "timestamp": "2026-03-05T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource 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": "La factura debe tener al menos una línea",
  "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"
  }
}

Create a corrective invoice

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json