Facturas

Get invoice by ID

Retrieves complete details of a specific invoice

GET
/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

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/facturas/550e8400-e29b-41d4-a716-446655440000"

Single invoice retrieved with full details including VeriFactu signature and PDF URL

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "numero_factura": "A/2025/0042",
    "numero": 42,
    "tipo": "ORDINARIA",
    "estado": "EMITIDA",
    "fecha_emision": "2025-01-20",
    "fecha_vencimiento": "2025-02-20",
    "emisor": {
      "nombre_fiscal": "Tu Empresa SL",
      "nif": "B12345678",
      "direccion": {
        "calle": "Calle Ejemplo",
        "numero": "123",
        "codigo_postal": "28001",
        "poblacion": "Madrid",
        "provincia": "Madrid",
        "pais": "España"
      }
    },
    "serie": {
      "id": "serie-001",
      "codigo": "A",
      "nombre": "Serie Principal"
    },
    "receptor": {
      "cliente_id": "123e4567-e89b-12d3-a456-426614174000",
      "nombre_fiscal": "Cliente Ejemplo SL",
      "nif": "B87654321",
      "email": "cliente@ejemplo.com",
      "direccion": {
        "calle": "Avenida Cliente",
        "numero": "456",
        "codigo_postal": "28013",
        "poblacion": "Madrid",
        "provincia": "Madrid",
        "pais": "España"
      }
    },
    "lineas": [
      {
        "id": "line-001",
        "descripcion": "Desarrollo de página web corporativa",
        "cantidad": 40,
        "unidad": "horas",
        "precio_unitario": 37.5,
        "descuento_porcentaje": 0,
        "base_imponible": 1500,
        "impuesto_principal": {
          "tipo": "IVA",
          "porcentaje": 21,
          "clave_regimen": "01",
          "importe": 315
        },
        "total_linea": 1815
      }
    ],
    "totales": {
      "base_imponible": 1500,
      "total_iva": 315,
      "total_irpf": 0,
      "total_recargo_equivalencia": 0,
      "total_factura": 1815
    },
    "forma_pago": {
      "metodo": "TRANSFERENCIA",
      "plazo_dias": 30
    },
    "observaciones": "Pago mediante transferencia bancaria",
    "verifactu": {
      "estado": "FIRMADO",
      "huella": "a7f3c9e2b1d4f8a6c3e9b2d5f1a8c4e7b9d2f5a1c8e4b7d3f9a2c6e1b5d8f4a7",
      "qr_url": "https://verifactu.gob.es/verify?h=a7f3c9e2b1d4f8a6",
      "fecha_firma": "2025-01-20T10:35:00Z"
    },
    "pdf_url": "https://storage.beel.es/facturas/f47ac10b-58cc-4372-a567-0e02b2c3d479.pdf",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:35:00Z"
  },
  "meta": {
    "timestamp": "2025-01-20T11:00:00Z",
    "request_id": "req_get_factura_001"
  }
}

Missing, invalid, or expired API key in X-API-Key header

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is invalid or has expired",
    "details": {
      "header": "X-API-Key",
      "reason": "Invalid API key format or key not found"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_001"
  }
}

Requested resource does not exist or belongs to another user (RLS)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {
      "resource_type": "Factura",
      "resource_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_002"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Mark invoice as paid POST

Marks an invoice as paid. **Status change:** `enviada` → `pagada`

Validate NIF against AEAT registry POST

**Public endpoint** to validate a NIF/CIF against the AEAT registry using VeriFactu. This endpoint is useful for: - Pre-validation before registration (proactive feedback) - Validating client NIFs before creating invoices - Verifying that a NIF exists in the registry **Behavior:** - **VALID**: The NIF exists in the AEAT registry. Returns the fiscal name. - **INVALID**: The NIF has correct format but doesn't exist in the registry. - **PENDING**: VeriFactu API is temporarily unavailable. The NIF has valid syntax but couldn't be verified against the registry. - **ERROR**: Technical error during validation (invalid syntax, timeout, etc.) **Note about PENDING:** If you use this endpoint for pre-validation during registration, a PENDING status indicates that the NIF has valid format and the user can continue. The system will validate the NIF automatically when the service becomes available. **Rate limiting:** - With API Key: 100 requests/hour - With Session Cookie: 1000 requests/hour **Authentication:** This endpoint accepts both API Keys and Session Cookies.