Facturas

Update invoice

Updates an existing draft invoice. **Restriction:** Only invoices in `borrador` status can be modified.

PUT
/facturas/{factura_id}

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

Formatuuid

Request Body

fecha_emision?string
Formatdate
fecha_vencimiento?string
Formatdate
receptor?||
lineas?
forma_pago?
observaciones?string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://app.beel.es/api/v1/facturas/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{    "fecha_emision": "2025-01-25",    "lineas": [      {        "descripcion": "Desarrollo de página web corporativa - Actualizado",        "cantidad": 45,        "unidad": "horas",        "precio_unitario": 40,        "descuento_porcentaje": 5,        "impuesto_principal": {          "tipo": "IVA",          "porcentaje": 21,          "clave_regimen": "01"        }      },      {        "descripcion": "Mantenimiento web - 3 meses",        "cantidad": 3,        "unidad": "mes",        "precio_unitario": 150,        "descuento_porcentaje": 0,        "impuesto_principal": {          "tipo": "IVA",          "porcentaje": 21,          "clave_regimen": "01"        }      }    ],    "forma_pago": {      "metodo": "DOMICILIACION",      "iban": "ES9121000418450200051332"    },    "observaciones": "Factura actualizada con nueva línea de mantenimiento. Pago mediante domiciliación bancaria."  }'
{
  "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": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "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": "NOT_FOUND",
    "message": "Resource not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "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"
  }
}

Get complete tax types catalog GET

Retrieves the complete catalog of available tax types with structured information for tax configuration in Spain: - **Tax regimes**: VAT (Peninsula), IGIC (Canary Islands), IPSI (Ceuta/Melilla), OTHERS - **Percentages per regime**: Valid percentages for each tax type - **Regime codes**: VeriFactu codes for each tax type - **IRPF**: Available withholding percentages - **Equivalence surcharge**: Automatic mappings based on VAT percentage - **Utilities**: Validation functions and geographic auto-detection This endpoint provides all necessary information for the frontend without duplicating tax validation logic.

Void invoice POST

Voids an invoice by changing its status to `anulada`. **Status change:** `borrador` or `enviada` → `anulada` **Validations:** - Cannot void invoices with status `pagada` - Requires a void reason **Note:** For Spanish tax compliance, consider creating a corrective invoice (rectificativa) instead of voiding.