> ## Documentation Index
> Fetch the complete documentation index at: https://developer.quickei.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Odoo

> Synchronize payments, invoices, and accounting with Odoo ERP

Accept Quickei QR payments at your Odoo POS and auto-reconcile invoices. The Quickei module integrates with Odoo's Point of Sale and Accounting modules.

## Requirements

| Requirement | Version                        |
| ----------- | ------------------------------ |
| Odoo        | 18.0 (Community or Enterprise) |
| Modules     | `account`, `point_of_sale`     |
| Quickei     | Merchant account with API keys |

## Installation

<Steps>
  <Step title="Download the module">
    Download the `quickei_pos` module from your [Merchant Dashboard](https://quickei.io/merchant/integrations) under **Integrations > Odoo**.
  </Step>

  <Step title="Install in Odoo">
    Copy the `quickei_pos` folder to your Odoo addons directory:

    ```bash theme={null}
    cp -r quickei_pos /opt/odoo/addons/
    ```

    Then restart Odoo and activate **Developer Mode**. Go to **Apps > Update Apps List**, search for "Quickei" and install.
  </Step>

  <Step title="Configure API credentials">
    Navigate to **Settings > Quickei POS** and enter:

    * **Client ID** — Your merchant API client ID
    * **Client Secret** — Your merchant API secret
    * **API Base URL** — `https://quickei.io/merchant-api/pos/v1`
    * **Webhook Secret** — Auto-generated, used for signature verification

    Click **Test Connection** to verify.
  </Step>

  <Step title="Configure the webhook">
    Set your webhook URL in the Quickei Merchant Dashboard:

    ```
    https://your-odoo.com/quickei/webhook
    ```
  </Step>
</Steps>

## Features

### POS QR Payments

At the Odoo Point of Sale, select **Quickei QR** as the payment method. A dynamic QR code is generated for the customer to scan with the Quickei app. Payment confirmation appears in real-time.

### Invoice Auto-Reconciliation

When you validate (post) an invoice, the module automatically:

1. Creates a Quickei payment order linked to the invoice
2. Generates a payment link sent to the customer
3. On payment, receives a webhook and creates a **Payment Entry** in Odoo
4. Reconciles the invoice — no manual journal entries needed

### Webhook Events

| Quickei Event         | Odoo Action                             |
| --------------------- | --------------------------------------- |
| `pos.order.paid`      | Create Payment Entry, reconcile invoice |
| `pos.order.expired`   | Mark payment as expired                 |
| `pos.order.cancelled` | Mark payment as cancelled               |
| `pos.order.refunded`  | Create reverse Payment Entry            |

## Webhook Signature Verification

Every webhook includes an `X-Quickei-Signature` header. The module verifies it automatically:

```python theme={null}
import hmac, hashlib

def verify_signature(payload_bytes, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

## API Client

The module includes a built-in API client with these methods:

| Method              | Description                     |
| ------------------- | ------------------------------- |
| `create_order()`    | Create a POS order with QR code |
| `get_order()`       | Check order status              |
| `cancel_order()`    | Cancel a pending order          |
| `list_orders()`     | List all orders                 |
| `test_connection()` | Verify API credentials          |

### Create Order Example

```python theme={null}
order = self.env['quickei.api'].create_order(
    amount=150.00,
    currency='EUR',
    reference='INV/2026/0042',
    description='Invoice payment',
    payment_method='both',
    callback_url='https://your-odoo.com/quickei/webhook',
    expires_in=600,
    idempotency_key='INV-2026-0042',
)
# order['data']['qr_data'] → QR code content
# order['data']['payment_url'] → Payment page URL
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test Connection fails">
    Verify your Client ID and Client Secret are correct. Ensure your Odoo server can reach `https://quickei.io` (check firewall/proxy settings).
  </Accordion>

  <Accordion title="Webhooks not received">
    Ensure `https://your-odoo.com/quickei/webhook` is publicly accessible. Check Odoo logs for signature verification failures. Verify the webhook secret matches in both Quickei and Odoo settings.
  </Accordion>

  <Accordion title="Payment Entry not created">
    Check that the invoice reference in the webhook payload matches an existing invoice in Odoo. Verify the `account` module is installed and the default payment journal is configured.
  </Accordion>
</AccordionGroup>

<Note>
  The Odoo module currently supports Odoo 18. For older versions, [contact support](https://quickei.io/contact) for compatibility assistance.
</Note>