Facturas

Create multiple invoices

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.

POST
/facturas/bulk

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

Request Body

facturas
Items1 <= items <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/facturas/bulk" \  -H "Content-Type: application/json" \  -d '{    "facturas": [      {        "tipo": "ORDINARIA",        "serie_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",        "fecha_emision": "2025-01-15",        "fecha_vencimiento": "2025-02-14",        "receptor": {          "tipo_receptor": "EXISTENTE",          "cliente_id": "4f244735-980b-8d9c-80e8-6331fa0b1958"        },        "lineas": [          {            "descripcion": "Desarrollo de aplicación web - Sprint 1",            "cantidad": 40,            "unidad": "horas",            "precio_unitario": 50,            "impuesto_principal": {              "tipo": "IVA",              "porcentaje": 21,              "clave_regimen": "01"            },            "tipo_irpf": 15          }        ],        "forma_pago": {          "metodo": "TRANSFERENCIA",          "iban": "ES9121000418450200051332",          "plazo_dias": 30        },        "observaciones": "Pago mediante transferencia bancaria. Incluye soporte técnico durante 30 días.",        "metadatos": {          "project_code": "PROJ-123",          "client_reference": "REF-2025-001"        },        "verifactu_habilitado": false,        "enviar_automaticamente": false      }    ]  }'
{
  "success": true,
  "data": {
    "facturas": [
      {
        "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"
      }
    ],
    "total_creadas": 5
  },
  "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": "BULK_VALIDATION_ERROR",
    "message": "string",
    "details": {
      "campo": "specific error message"
    },
    "errors": [
      {
        "index": 0,
        "field": "string",
        "message": "string"
      }
    ]
  },
  "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 corrective invoice POST

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)

Delete invoice DELETE

Deletes (marks as deleted) an invoice. **Soft delete:** The invoice is not physically deleted, only marked as deleted. **Restriction:** Only invoices in `borrador` status can be deleted.