🔗 Order Data Webhook API

Custom Integration Documentation

📋 Overview

This API allows 3rd party systems to sync order data into our system. When orders are created or updated in your system, you can send the order data to our webhook endpoint to keep our system in sync.

🚀 Getting Started

1. Get Your Webhook URL

Contact your system administrator to obtain your unique webhook URL. It will look like:

https://admin.jarabot.com/webhooks/custom_data/{your-webhook-key}

2. Webhook Endpoint

📝 Request Format

Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

{
  "webhook": {
    "event": "order:update",
    "payload": {
      "code": "2024000123",
      "external_id": "VS2024000123",
      "invoice_number": "INV-2024-000123",
      "created_at": "2024-01-15T10:30:00+0100",
      "total_amount": 1299.00,
      "currency": "CZK",
      "email": "customer@example.com",
      "status_id": 2,
      "status_name": "processing",
      "completed": false,
      "tracking_url": "https://tracking.example.com/TR123456789",
      "admin_url": "https://admin.example.com/orders/2024000123",
      "payment_type": "bank_transfer",
      "payment_date": "2024-01-15 14:25:00",
      "package_numbers": [
        { "external_id": 123456789, "status": "delivered" },
        { "external_id": 987654321, "status": "in_transit" }
      ],
      "delivery": {
        "id": "shipping-guid-456",
        "name": "Express Delivery",
        "provider": "DPD",
        "expected_date_of_delivery": "2024-01-18",
        "date_of_delivery": "2024-01-18",
        "expedition_date": "2024-01-16"
      },
      "customer": {
        "id": "customer-guid-123",
        "name": "John Doe",
        "email": "customer@example.com",
        "phone": "+420123456789",
        "location": "Main Street 123, Prague",
        "country_code": "CZ",
        "admin_url": "https://admin.example.com/customers/customer-guid-123"
      },
      "items": [
        {
          "code": "PROD-001",
          "name": "Example Product",
          "quantity": 2,
          "price": 599.00,
          "currency": "CZK"
        },
        {
          "code": "PROD-002",
          "name": "Another Product",
          "quantity": 1,
          "price": 700.00,
          "currency": "CZK"
        }
      ]
    }
  }
}

📊 Payload Structure

The payload should contain order data in the following format:

Field	Type	Required	Description
code	String	Yes	Unique order identifier
external_id	String	No	Any external identifier like variable symbol
invoice_number	String	No	Invoice number for the order
created_at	String	No	Order creation timestamp (ISO 8601 format)
total_amount	Number	No	Total order amount including VAT
currency	String	No	Currency code (e.g., "CZK", "EUR")
email	String	No	Customer email address
status_id	Integer	No	Order status ID
status_name	String	No	Human-readable status name
completed	Boolean	No	Whether the order is completed
tracking_url	String	No	Package tracking URL
admin_url	String	No	Admin panel URL for the order
payment_type	String	No	Payment method (e.g., "bank_transfer", "card", "cash_on_delivery")
payment_date	DateTime	No	Date and time when payment was received (format: YYYY-MM-DD hh:mm:ss)
package_numbers	Array	No	Array of package tracking objects
package_numbers[].external_id	Number	No	Package tracking number
package_numbers[].status	String	No	Package status (e.g., "in_transit", "delivered")
delivery	Object	No	Delivery/shipping information
delivery.id	String	No	Delivery method ID
delivery.name	String	No	Delivery method name
delivery.provider	String	No	Delivery provider/carrier (e.g., "DPD", "PPL", "Zásilkovna")
delivery.expected_date_of_delivery	Date	No	Expected delivery date
delivery.date_of_delivery	Date	No	Actual delivery date
delivery.expedition_date	Date	No	Date when the package was dispatched
customer	Object	No	Customer information
customer.name	String	No	Customer full name
customer.email	String	No	Customer email address
customer.phone	String	No	Customer phone number
customer.id	String	No	Customer unique identifier/GUID
customer.location	String	No	Customer address (formatted as "Street Number, City")
customer.country_code	String	No	Customer country code (e.g., "CZ", "SK")
customer.admin_url	String	No	Admin panel URL for the customer
items	Array	No	Array of order items
items[].code	String	No	Product code/SKU
items[].name	String	No	Product name
items[].quantity	Integer	No	Quantity ordered
items[].price	Number	No	Item unit price including VAT
items[].currency	String	No	Item currency code

📤 Response Codes

🔄 Update vs Create Behavior

Our system automatically handles both new orders and order updates:

• New Orders: If an order with the given code doesn't exist, a new record is created
• Existing Orders: If an order with the given code already exists, the existing record is updated with new data

💡 Example Implementations

cURL Example

curl -X POST https://admin.jarabot.com/webhooks/custom_data/your-webhook-key \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "event": "order:update",
      "payload": {
        "code": "ORD-2024-001",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "status_id": 3,
        "status_name": "shipped"
      }
    }
  }'

---

Last updated: