CompanyInvoiceLifecycle
Exchange simplified invoices for a full invoice
Issues a full invoice in exchange for one or more simplified invoices already issued, when the customer asks for an invoice with their details. It is not a corrective invoice: it documents the same operations again with the recipient identified (RD 1619/2012, art. 15.6).
- What it issues: a STANDARD invoice with the lines of the simplified invoices and the recipient sent, numbered in series_id or in the company's default standard series. It lists the invoices it replaces in replaced_invoice_ids.
- The simplified invoices: each becomes VOIDED with void_cause EXCHANGED, in the same act: their records are not cancelled, the exchange replaces them. They must be simplified invoices (422 EXCHANGE_REQUIRES_SIMPLIFIED), issued and not voided, exchanged or corrected before (422 SIMPLIFIED_NOT_EXCHANGEABLE), and each one listed once in simplified_invoice_ids (422 EXCHANGE_DUPLICATED_SIMPLIFIED, before anything is read or numbered).
- The exchange invoice cannot be voided afterwards (422 EXCHANGE_INVOICE_NOT_VOIDABLE), and when it is recorded as F3 it cannot be corrected yet (see the corrective operation).
- VeriFactu: the exchange invoice is recorded as F3, identifying each simplified invoice it replaces by number and issue date. Each of them must already be accepted by the AEAT, or nothing is issued: one issued without VeriFactu fails with 422 SIMPLIFIED_EXCHANGE_NOT_RECORDABLE; one whose record is still pending fails with 422 EXCHANGE_SIMPLIFIED_NOT_YET_ACCEPTED (wait until the AEAT accepts it and retry); one whose record was rejected fails with 422 EXCHANGE_SIMPLIFIED_RECORD_REJECTED (fix or resubmit it first).
post/v1/companies/{company_id}/invoices/simplified-exchanges
Request
- Base URL: https://app.beel.es/api
- URL: https://app.beel.es/api/v1/companies/{company_id}/invoices/simplified-exchanges
- Auth: HTTP bearer
Headers
Idempotency-Keystring
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.
| 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 for the Retry-After seconds (2) and retry with the same key. |
| 409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
Request body
Example request
{
"simplified_invoice_ids": [
"550e8400-e29b-41d4-a716-446655440010"
],
"recipient": {
"customer_id": "4f244735-980b-8d9c-80e8-6331fa0b1958"
},
"options": {
"issue_directly": true,
"wait_for_pdf": false,
"send_automatically": false
}
}Response
Full invoice issued in exchange for the simplified invoices
Example response
{
"success": true,
"data": {
"invoice_number": "2025/0001",
"series": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "FAC"
},
"number": 1,
"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",
"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",
"additional_info": "Nº Colegiado: 12345"
},
"recipient": {
"legal_name": "Empresa SL",
"trade_name": "Empresa",
"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"
},
"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",
"taxable_base": 1800,
"line_total": 2178,
"total_excluding_tax": 1,
"total_including_tax": 100,
"line_type": "NORMAL"
}
],
"totals": {
"taxable_base": 2000,
"vat_breakdown": [
{
"type": 21,
"base": 2000,
"amount": 420,
"regime_key": "18"
}
],
"total_vat": 420,
"total_irpf": 300,
"invoice_total": 2120,
"total_to_pay": 2120
},
"payment_info": {
"method": "BANK_TRANSFER",
"iban": "ES1234567890123456789012",
"swift": "ABCDESMMXXX",
"payment_term_days": 30
},
"voided_at": "2025-01-20T09:12:44Z",
"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"
},
"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": {
"invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
"registration_number": "4f8c2a1e-9b3d-4e7a-8c5f-1d2e3f4a5b6c",
"qr_url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A%2F2025%2F0042&fecha=20-01-2025&importe=1590.00",
"qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
"submission_status": "ACCEPTED",
"skip_reason": "CONFIG_DISABLED",
"error_code": "3000",
"error_message": "Factura ya existe en el sistema"
},
"sending_history": [
{
"sent_at": "2025-01-29T18:45:00Z"
}
],
"email_delivery": {
"status": "REJECTED",
"reason": "error.email.envio_no_permitido"
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"custom_fields": [
{
"key": "store",
"label": "Store",
"value": "Gran Vía 12"
}
]
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.