Integrating invoicing systems with Jumpseller

Why Integrate

Automatic invoicing improves your sales process by reducing manual work, minimizing human errors, and making order management easier.
With Jumpseller, integrating an external invoicing system is straightforward.

Merchants can choose between:

• Comprehensive Integration
  Build and publish a full invoicing App that connects with Jumpseller using webhooks, OAuth2, and the complete API. This method offers maximum flexibility and supports advanced business logic.

• Lightweight Integration
  Provide a single invoicing endpoint that Jumpseller calls directly when a merchant chooses to generate an invoice for an order. This method is quick to set up and ideal for simple invoicing workflows.

Requirements

To integrate an invoicing system with your store, you will need:

• A Jumpseller store
• An invoicing software with an API (XML or JSON) and valid API credentials
• Technical knowledge to connect both systems
• Integration code hosted on your own server (for Comprehensive Integration) or just an endpoint URL (for Lightweight Integration)

Workflow

Typical flow between Jumpseller and the invoicing system:

1. The merchant clicks “Create Invoice” for an order in Jumpseller.
2. Jumpseller sends order data differently to the invoicing system depending on the integration type:
   • Comprehensive Integration: via the Order Created webhook
   • Lightweight Integration: direct POST to the selected endpoint
3. The invoicing system creates the invoice.
4. The invoice is attached to the order in Jumpseller so it’s accessible to both the merchant and customer.
5. (Optional) If the invoicing system manages stock, update inventory accordingly.
6. (Optional) When order statuses change (Pending, Paid, Canceled), update the invoicing system — essential for issuing credit notes on cancellations.

Where the “Create Invoice” Button Appears

The “Create Invoice” option will appear inside the order view in the Jumpseller Admin.

API Endpoint (Lightweight Integration)

Method: POST
URL: https://your-service.com/invoices

Request Example

{
  "order": {
    "id": 1020,
    "created_at": "2024-11-05T11:26:30Z",
    "currency": "USD",
    "subtotal": 10.0,
    "total": 10.0,
    "status": "paid",
    "customer": {
      "email": "customer@example.com",
      "fullname": "John Smith",
      "tax_id": "US123456789"
    },
    "products": [
      {
        "name": "Premium T-Shirt",
        "price": 10.0,
        "quantity": 1,
        "sku": "TSHIRT-01"
      }
    ],
    "billing_address": {
      "country": "US",
      "zip": "10001"
    }
  }
}

Success Response Example

{
  "url": "https://your-service.com/invoices/INV-1020",
  "public_id": "INV-1020",
  "message": "Your invoice was created successfully"
}

Error Response Example

{
  "message": "Customer tax ID is required for invoice generation"
}

Field Reference

Order Object

• order.id (integer) – Unique order ID
• order.total (float) – Grand total amount
• order.customer.tax_id (string) – Tax identification number

Response Requirements

• url – Required – Browser-viewable invoice URL
• public_id – Required – Invoice reference ID
• message – Optional – Message to display to merchant after success

Comprehensive Integration Steps

1. Create a test store (14-day free trial; contact support for extensions).
2. Add a webhook that triggers on “Order Update” events when the merchant clicks “Create Invoice” and sends POST data to your integration.
   You can read more on how to do this here.
3. Use RequestBin to inspect webhook data.
4. Read the request’s body and headers in your integration code.
5. Send order data to your invoicing system’s API to create the invoice.

6. Attach invoice details to the Jumpseller order:

   POST /orders/{id}/documents.json
   

   Include document type, ID, and URL.

7. (Optional) Add custom checkout fields for additional invoice data.
8. (Optional) Use JavaScript Apps for field validation.
9. (Optional) Schedule API calls to invoice orders without an invoice_id.
10. Publish your integration in the Jumpseller App Store.

Authentication (Recommended for Comprehensive Integration)

Use HMAC-SHA256 signatures to verify that requests are from Jumpseller.
This requires implementing OAuth2 to obtain a hooks_token.

Request Headers

• Content-Type: application/json (Required)
• Jumpseller-Store-Code: Store identifier (Required)
• Jumpseller-Hmac-Sha256: Base64-encoded signature (Required)

Verification Code Examples

Ruby

def verify_request(request)
  hooks_token = store.webhook_verification_token
  return false unless hooks_token
  
  hmac_header = request.headers['Jumpseller-Hmac-Sha256']
  digest = OpenSSL::Digest.new('sha256')
  hmac = Base64.encode64(
    OpenSSL::HMAC.digest(digest, hooks_token, request.raw_post)
  ).strip
  
  hmac == hmac_header
end

Node.js

const verifyRequest = (rawBody, hooks_token, headerSig) => {
  const hmac = crypto.createHmac('sha256', hooks_token);
  hmac.update(rawBody);
  return hmac.digest('base64') === headerSig;
};

Python

def verify_request(raw_body: str, hooks_token: str, header_sig: str) -> bool:
    digest = hmac.new(
        hooks_token.encode(), 
        raw_body.encode(), 
        hashlib.sha256
    ).digest()
    return base64.b64encode(digest).decode() == header_sig

Invoicing with Gift Cards

• Products with type = 'gift_card' should have 0% VAT.
• If a gift card is redeemed (order.gift_cards_amount > 0), note it in the invoice.

Application Form for Lightweight Integration

If you are implementing the Lightweight Integration, fill out this form so our team can review and approve your endpoint:
Lightweight Integration Application Form

FAQ

1. How are roundings handled?
   On an item-by-item basis, not on the total.
2. What date/time format is used?
   UTC format: "YYYY-MM-DD HH:MM:SS UTC". Convert to your desired timezone.

Resources

• Jumpseller Webhooks Documentation
• Jumpseller API Documentation
• Jumpseller Apps Documentation
• Ngrok (for local tunneling during development)
• Postman (to inspect webhook POST requests)

Support

If you have questions or feedback about this guide, please contact our support team. We’re here to help.