# SmartPay Invoices for WooCommerce

Connects a WooCommerce store to the [SmartPay.co.il](https://www.smartpay.co.il/)
platform to create tax documents (receipts and tax-invoice/receipts) for orders,
and lets staff and customers download them as PDFs.

Documents are created and numbered by SmartPay (the upstream Streamline API); the
plugin stores a reference (`smartpay_invoice_id`) on the order, caches the PDF,
and surfaces download / create / retry actions in the admin.

## Requirements

- WordPress 6.5+
- PHP 7.4+
- WooCommerce 7.1+ (HPOS compatible)
- SmartPay.co.il API credentials

## Installation

1. Copy this folder to `wp-content/plugins/smartpay-invoices` (or install the ZIP).
2. Ensure WooCommerce is active.
3. Activate **SmartPay Invoices for WooCommerce**.
4. Go to **WooCommerce → Smartpay Invoices** and configure it.

## Configuration

**WooCommerce → Smartpay Invoices**

| Setting | Description |
| --- | --- |
| Is Sandbox | Use the sandbox or production SmartPay endpoint. |
| Api Key / Api Secret / Company | SmartPay API credentials (Basic auth). |
| Connection status | On-demand **Test connection** button. |
| Produced Doc Type | `Receipt (קבלה)` or `Tax Invoice / Receipt (חשבונית מס קבלה)`. |
| Automatically Generate Invoices for paid orders | Create a document when an order becomes paid. |
| Attach Invoice as PDF to emails | Attach the PDF to the "Completed order" email. |
| Tax Rate / Tax Rate included on Pricing | Tax rate and mode (None / WooCommerce / Inclusive / Exclusive). |
| Log enabled | Record API requests/responses to the log table. |

Logs are viewable under **WooCommerce → Smartpay Invoices Logs**.

## Usage

- **Automatic:** with auto-generate on, a document is created once when an order
  becomes paid (via payment success or a transition to processing/completed).
  Issued documents are not auto-updated afterwards.
- **Manual (per order):** the **Smartpay Invoices** column on the Orders screen
  shows one of three actions — download an existing invoice, **Create invoice**
  for an order without one, or **Retry** for one whose creation failed.
- **Bulk:** select orders and use **Generate Receipt** / **Generate Tax Invoice /
  Receipt**. Orders that already have a document are skipped; the notice reports
  created / skipped / failed counts.
- **Customer:** a **Download Invoice PDF** button appears on the My Account order
  view once a document exists.

## Architecture

- `smartpay-invoices.php` — bootstrap, autoloader, activation, HPOS declaration,
  WooCommerce dependency guard.
- `includes/` — `-app` (hook wiring), `-order-observer` (create/retry),
  `-invoice-handler` (column, bulk, tax math), `-adapter`/`-client` (SmartPay
  API), `-pdf-handler`/`-invoice-file-handler` (PDF download + caching),
  `-admin-settings-page`, `-log-*`, `-checkout-vat-field`.
- `templates/` — admin field + PDF-button views.
- `assets/js/admin.js` — settings-page connection test.

The plugin talks only to the SmartPay API; it does not call the documents PDF
renderer directly.

## Developer hooks

Filters:

- `smartpayinvoices_can_sync_invoice` ( bool $enabled, WC_Order $order )
- `smartpayinvoices_customer_vat_number` ( string $vat, WC_Order $order )
- `smartpayinvoices_vat_required_threshold` ( int $amount )
- `smartpayinvoices_invoice_email_ids` ( array $email_ids, WC_Order $order )
- `smartpayinvoices_adapter_instance` ( Smartpayinvoices_Adapter $adapter )

Actions:

- `smartpayinvoices_document_failed` ( WC_Order $order, object|null $response )

## Development

```bash
php -l includes/class-smartpayinvoices-app.php   # syntax check a file
```

Full behaviour requires a running WordPress + WooCommerce environment.

## License

GPL-2.0-or-later.