# SmartPay Invoices for WooCommerce

Connects a WooCommerce store to the [SmartPay.co.il](https://www.smartpay.co.il/)
platform to create documents (receipts, tax invoices, tax-invoice/receipts and
proforma invoices) 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 (קבלה)`, `Tax Invoice / Receipt (חשבונית מס קבלה)`, `Tax Invoice (חשבונית מס)` or `Proforma Invoice (חשבונית עסקה)`. |
| Automatic document creation | `No`, `For paid orders`, or — for payment demands only (tax invoice, proforma invoice) — `For created orders`. |
| Attach Invoice as PDF to emails | Attach the PDF to the "Completed order" email. |
| Document notes | Free text printed in the notes area of every document (e.g. your website address); links are clickable. Sent upstream as `notes`. |
| 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. |

**Payment methods tab** — maps each registered WooCommerce payment gateway to
the SmartPay payment method recorded on the document's transactions (printed in
the payments section of receipts and invoice-receipts). WooCommerce core
gateways (`bacs`, `cheque`, `cod`, `paypal`) and the SmartPay Payments gateways
have built-in defaults; any other gateway defaults to credit card. Stored under
`smartpayinvoices_options[payment_methods]` as `gateway id => method`.

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** / **Generate Tax Invoice** / **Generate Proforma Invoice**. Orders
  that already have that document are skipped; the notice reports created /
  skipped / blocked / unpaid / failed counts.
- **Coexistence:** a combined tax-invoice/receipt excludes a separate receipt or
  tax invoice (and vice versa); receipt + tax invoice may coexist; a proforma
  invoice may precede any of them; no type is issued twice per order.
- **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 )
- `smartpayinvoices_transaction_payment_method` ( string $method, WC_Order $order, array|null $order_payment )
- `smartpayinvoices_default_payment_methods` ( array $gateway_id_to_method )
- `smartpayinvoices_payment_method_options` ( array $method_to_label )
- `smartpay_payments_order_payments` ( array $payments, WC_Order $order ) — entries
  `{ amount, transaction_id, label?, payment_method? }`; a valid `payment_method`
  overrides the gateway mapping for that payment

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.