Invoices

Duplicate invoice as draft

Creates a copy of an existing invoice as a new draft. **Use case:** Quickly create a new invoice based on an existing one, useful for recurring invoices to the same customer. **What is copied:** - Customer data (recipient) - Invoice lines (descriptions, quantities, prices, taxes) - Payment method - Series (if specified, otherwise uses default) - Observations **What is NOT copied (reset to defaults):** - Invoice number (null - assigned when issued) - Status (always DRAFT) - Issue date (defaults to today, can be overridden) - Due date (recalculated based on new issue date) - VeriFactu data - PDF - Payment date - Sent date **Result:** A new draft invoice ready for review and emission. **Note:** Send `Content-Type: application/json` even when body is empty.

POST
/v1/invoices/{invoice_id}/duplicate

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

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

invoice_idstring

ID of the invoice to duplicate

Formatuuid

Request Body

issue_date?string

Issue date for the new invoice. If not provided, defaults to today.

Formatdate
series_id?string
notes?string

Observations for the new invoice. If not provided, copies from the original invoice.

Lengthlength <= 2000

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/duplicate" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoice_number": "2025/0001",
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "FAC"
    },
    "number": 1,
    "type": "STANDARD",
    "status": "SCHEDULED",
    "issue_date": "2025-01-15",
    "due_date": "2025-02-14",
    "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",
      "web": "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": "02",
        "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,
        "taxable_base": 1800,
        "line_total": 2178
      }
    ],
    "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
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "notes": "string",
    "rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
    "rectification_reason": "string",
    "recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
    "recurring_invoice_name": "string",
    "rectification_type": "TOTAL",
    "rectification_code": "R1",
    "metadata": {
      "stripe_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "stripe_charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
      "external_order_id": "ORD-2025-0042",
      "payment_platform": "stripe"
    },
    "pdf_download_url": "/v1/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...",
      "registration_date": "2019-08-24T14:15:22Z",
      "submission_status": "PENDING",
      "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",
        "date": "2019-08-24T14:15:22Z",
        "recipient": "user@example.com",
        "status": "SENT",
        "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": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10: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"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Download multiple invoice PDFs as ZIP POST

Downloads multiple invoice PDFs as a single ZIP file. **Limits:** - Maximum 20 invoices per request - Maximum 50MB total ZIP size **Partial success:** If some PDFs are not available (not generated, not found), the response will include a `failures` array with details. The ZIP will still be generated with the available PDFs. **Error handling:** - If NO PDFs are available, returns 400 Bad Request - If some PDFs are unavailable, returns 200 with partial ZIP + failures list

Export invoices to Excel POST

Exports invoices to an Excel file (XLSX format). **Two modes of operation:** - **By IDs:** Export specific invoices by providing `invoice_ids` - **By filters:** Export all invoices matching filter criteria **Two export formats (like Holded):** - **SUMMARY:** One row per invoice with aggregated totals (default) - **ITEMS:** One row per invoice line item, ideal for import compatibility **Columns for SUMMARY format:** - Date, Number, Due Date, Customer, NIF - Description, Subtotal, IVA, Withholding, Equivalence Surcharge - Total, Collected, Pending, Status, Payment Method **Columns for ITEMS format:** - Invoice Number, Date, Due Date, Draft, Contact, Contact NIF - Address, Postal Code, City, Province, Country - SKU, Item, Units, Unit Price, Discount % - Subtotal, Tax Type, Tax %, Tax Amount - Surcharge %, Surcharge Amount, IRPF %, IRPF Amount, Total **Limits:** - Maximum 5000 invoices per export - All invoices must belong to the authenticated user (RLS enforced) **Usage example (Frontend):** ```javascript const response = await fetch('/v1/invoices/export/excel', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ invoice_ids: [...], format: 'ITEMS' }) }); const blob = await response.blob(); // Download the blob as file ```