Facturas

Create corrective invoice

Creates a corrective invoice (factura rectificativa) to correct or void an issued invoice. **Rectification types:** - **TOTAL**: Completely voids the original invoice (original status → ANULADA) - **PARCIAL**: Partially corrects the original invoice (original status → RECTIFICADA) **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 EMITIDA, ENVIADA, PAGADA, VENCIDA or RECTIFICADA - Cannot rectify a BORRADOR invoice (must be issued first) - Cannot rectify an ANULADA invoice (final status) - For TOTAL rectification: Another total corrective cannot already exist - For PARCIAL rectification: Multiple partial correctives are allowed **Lines:** - TOTAL: Optional (if not provided, original lines are copied with negated amounts) - PARCIAL: REQUIRED (adjustment lines with positive or negative amounts)

POST
/facturas/{factura_id}/rectificativa

Authorization

X-API-Key<token>

API Key authentication.

Format: X-API-Key: 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

factura_idstring

Invoice ID to rectify

Formatuuid

Header Parameters

X-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

tipo_rectificacionstring

Type of rectification applied to a corrective invoice:

  • TOTAL: Completely cancels the original invoice (status → ANULADA)
  • PARCIAL: Partially corrects the original invoice (status → RECTIFICADA)
Value in"TOTAL" | "PARCIAL"
codigo_rectificacionstring

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"
motivostring

Detailed reason for rectification (minimum 20 characters)

Length20 <= length <= 1000
lineas?

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

observaciones?string

Additional observations about the rectification

Lengthlength <= 1000
serie_id?string

Series for the corrective invoice (optional, if not specified uses the original invoice's series)

Formatuuid
verifactu_habilitado?boolean

Whether VeriFactu information should be generated for this corrective invoice

Defaultfalse
enviar_automaticamente?boolean

If true, sends the corrective invoice by email after creation. IMPORTANT: If true, requires that:

  • The recipient has a configured email, OR
  • email_config is provided with valid recipients
Defaultfalse
emitir_directamente?boolean

If true, the corrective invoice is created directly in EMITIDA status with an assigned number. If false, it's created as BORRADOR without an invoice number.

Defaulttrue
email_config?

Custom email sending configuration (optional). If not provided and enviar_automaticamente=true, uses the recipient's email.

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/facturas/550e8400-e29b-41d4-a716-446655440000/rectificativa" \  -H "Content-Type: application/json" \  -d '{    "tipo_rectificacion": "TOTAL",    "codigo_rectificacion": "R1",    "motivo": "Anulación de factura emitida por error fundado en derecho según Art. 80 Uno LIVA. La operación no llegó a realizarse debido a cancelación del proyecto antes de su inicio.",    "observaciones": "Factura original F/2025/0042 anulada completamente. Cliente notificado."  }'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "numero_factura": "2025/0001",
    "serie": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "codigo": "FAC"
    },
    "numero": 1,
    "tipo": "ORDINARIA",
    "estado": "BORRADOR",
    "fecha_emision": "2025-01-15",
    "fecha_vencimiento": "2025-02-14",
    "fecha_pago": "2025-01-20",
    "emisor": {
      "nombre_fiscal": "Juan Pérez García",
      "nombre_comercial": "Desarrollo Web JP",
      "nif": "12345678A",
      "direccion": {
        "calle": "Calle Mayor, 123",
        "numero": "123",
        "piso": "2º A",
        "puerta": "A",
        "codigo_postal": "28001",
        "poblacion": "Madrid",
        "provincia": "Madrid",
        "pais": "España",
        "codigo_pais": "ES"
      },
      "telefono": "+34 600 123 456",
      "email": "usuario@ejemplo.com",
      "web": "https://beel.es",
      "logo_url": "string"
    },
    "receptor": {
      "cliente_id": "e0a8fb7f-2aba-4d25-a71d-cd7478e5bbcb",
      "nombre_fiscal": "Empresa SL",
      "nombre_comercial": "Empresa",
      "nif": "12345678A",
      "direccion": {
        "calle": "Calle Mayor, 123",
        "numero": "123",
        "piso": "2º A",
        "puerta": "A",
        "codigo_postal": "28001",
        "poblacion": "Madrid",
        "provincia": "Madrid",
        "pais": "España",
        "codigo_pais": "ES"
      },
      "telefono": "+34 600 123 456",
      "email": "usuario@ejemplo.com"
    },
    "lineas": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "descripcion": "Desarrollo de aplicación web",
        "cantidad": 40,
        "unidad": "horas",
        "precio_unitario": 50,
        "descuento_porcentaje": 10,
        "impuesto_principal": {
          "tipo": "IVA",
          "porcentaje": 21,
          "clave_regimen": "01"
        },
        "tipo_recargo_equivalencia": 5.2,
        "tipo_irpf": 15,
        "base_imponible": 1800,
        "total_linea": 2178
      }
    ],
    "totales": {
      "base_imponible": 2000,
      "total_descuentos": 0,
      "desglose_iva": [
        {
          "tipo": 21,
          "base": 2000,
          "cuota": 420
        }
      ],
      "total_iva": 420,
      "desglose_recargo": [
        {
          "tipo": 0,
          "base": 0,
          "cuota": 0
        }
      ],
      "total_recargo_equivalencia": 0,
      "desglose_irpf": [
        {
          "tipo": 0,
          "base": 0,
          "cuota": 0
        }
      ],
      "total_irpf": 300,
      "total_factura": 2120
    },
    "forma_pago": {
      "metodo": "NINGUNO",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "plazo_dias": 30
    },
    "observaciones": "string",
    "factura_rectificada_id": "57fbc95a-ac09-4eb3-b224-bea2471dfa9d",
    "motivo_rectificacion": "string",
    "tipo_rectificacion": "TOTAL",
    "codigo_rectificacion": "R1",
    "metadatos": {
      "stripe_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "stripe_charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
      "external_order_id": "ORD-2025-0042",
      "payment_platform": "stripe"
    },
    "pdf_url": "invoices/550e8400-e29b-41d4-a716-446655440000/550e8400-e29b-41d4-a716-446655440001.pdf",
    "pdf_download_url": "/api/v1/facturas/550e8400-e29b-41d4-a716-446655440000/pdf",
    "verifactu": {
      "habilitado": false,
      "huella_factura": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
      "huella_encadenamiento": "7F8E9D0C1B2A3F4E5D6C7B8A9F0E1D2C3B4A5F6E7D8C9B0A1F2E3D4C5B6A7F8",
      "numero_registro": "VERIFACTU2025000001",
      "qr_url": "https://verifactu.agenciatributaria.gob.es/v?id=ABC123XYZ",
      "fecha_registro": "2019-08-24T14:15:22Z",
      "estado_envio": "pendiente"
    },
    "archivos_adjuntos": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "nombre": "string",
        "url": "string",
        "tipo": "string"
      }
    ],
    "historial_envios": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "fecha": "2019-08-24T14:15:22Z",
        "destinatario": "usuario@ejemplo.com",
        "estado": "enviado",
        "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": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "campo": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "campo": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "campo": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "campo": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Create invoice POST

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

Create multiple invoices POST

Creates multiple invoices in a single operation. **Idempotency:** Each invoice can have its own `idempotency_key`. **Atomicity:** If any invoice fails, ALL invoices are rejected.