Invoices

Create corrective invoice

Creates a corrective invoice to correct or void an issued invoice. **Rectification types:** - **TOTAL**: Completely voids the original invoice (original status → VOIDED) - **PARTIAL**: Partially corrects the original invoice (original status → RECTIFIED) **VeriFactu codes:** - R1: Legal error and Art. 80 One, Two and Six LIVA - R2: Article 80 Three LIVA (Bankruptcy) - R3: Article 80 Four LIVA (Bad debts) - R4: Other causes - R5: Simplified invoices (only for simplified) **Validations:** - Original invoice must be in status ISSUED, SENT, PAID, OVERDUE or RECTIFIED - Cannot rectify a DRAFT invoice (must be issued first) - Cannot rectify a VOIDED invoice (final status) - For TOTAL rectification: Another total corrective cannot already exist - For PARTIAL rectification: Multiple partial correctives are allowed **Lines:** - TOTAL: Optional (if not provided, original lines are copied with negated amounts) - PARTIAL: REQUIRED (adjustment lines with positive or negative amounts)

POST
/v1/invoices/{invoice_id}/corrective

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

Invoice ID to rectify

Formatuuid

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Must be a unique UUID generated by the client
  • If the same key is sent twice, the result of the first operation is returned
  • Keys expire after processing
Formatuuid

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 uses the original invoice's series)

Formatuuid
options?

Controls how the invoice is processed after creation. All fields default to false if not specified.

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

application/json

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/corrective" \  -H "Content-Type: application/json" \  -d '{    "rectification_type": "TOTAL",    "rectification_code": "R1",    "reason": "Cancellation of invoice issued due to a legally founded error under Art. 80 Uno LIVA. The transaction was not completed due to project cancellation before commencement.",    "notes": "Original invoice F/2025/0042 fully cancelled. Customer notified."  }'
{
  "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": "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": "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"
  }
}

Change status of multiple invoices POST

Changes the status of multiple invoices in a single operation. **Supported status changes:** - **SENT:** Mark multiple invoices as sent (from ISSUED) - **PAID:** Mark multiple invoices as paid (from ISSUED, SENT, or OVERDUE) **Partial success:** If some invoices cannot be updated, the operation continues with the others. The response includes details of failures. **Limits:** - Maximum 50 invoices per request **Validations:** - All invoices must belong to the authenticated user - Each invoice must be in a valid status for the requested transition - For PAID: payment_date is required

Create invoice POST

Creates a new invoice. **Idempotency:** Supports `Idempotency-Key` header to prevent duplicates.