HTTP API Endpoints — North Shore Handpiece Repair

Base URL: https://www.northshorehandpiecerepair.com

All endpoints are implemented in velo_code/http_functions.js using Wix HTTP Functions. Endpoints are live when the site is published or in Preview mode.

Authentication

These endpoints are public (no API key required). Wix HTTP Functions do not support custom auth headers — security is handled via:

• Validation: Required-field checks on each request
• suppressAuth: true: Backend functions bypass collection permissions to read/write data on behalf of external callers
• Obscurity: Endpoint URLs are not publicly listed; only integration partners (Zapier, UPS, etc.) should know them
• Possible Enhancement:adding a shared secret token to the request body and validating it in the endpoint handler.

---

Endpoints Overview

Method	Path	Function	Purpose
GET	/_functions/health	get_health	Health check / connectivity test
POST	/_functions/jotform-intake	post_jotformIntake	Create a repair record from a JotForm submission
POST	/_functions/ups-tracking-update	post_upsTrackingUpdate	Update repair status from a UPS tracking event
POST	/_functions/sync-contact-address	post_syncContactAddress	Sync a Wix contact's address

Note: Endpoint URLs use the function name suffix (e.g. jotformIntake → jotform-intake). Wix converts camelCase to kebab-case in the URL.

---

1. Health Check

Use this to verify the backend is reachable and endpoints are registered before wiring up integrations.

Request

No body required.

Response — 200 OK

{
  "status": "ok",
  "timestamp": "2026-06-25T14:30:00.000Z"
}

Response — 500 Server Error

{
  "success": false,
  "error": "Error message"
}

cURL Example

curl https://www.northshorehandpiecerepair.com/_functions/health

---

2. JotForm Intake — Create Repair

Creates a new repair record in the RepairJobs collection. Intended to be called by Zapier (triggered by a JotForm submission) or directly by JotForm's webhook integration.

Request Headers

Content-Type: application/json

Request Body

Field	Type	Required	Description
customerEmail	string	Yes	Customer's email — used to match repairs to Wix member accounts
customerName	string	Yes	Customer's full name
deviceMake	string	Yes	Device brand (e.g., "Dremel", "Foredom")
customerPhone	string	No	Phone number
deviceModel	string	No	Device model (e.g., "4000")
serialNumber	string	No	Device serial number
issueDescription	string	No	Customer's description of the problem
trackingNumberOutbound	string	No	UPS tracking number for outbound shipment
shippingAddress	string	No	Full return shipping address

Auto-Set Fields

These fields are set automatically by the endpoint (do not send them):

Field	Value
repairId	Auto-generated: RPR-YYYY-NNNN
intakeMethod	"UPS_JotForm"
carrierOutbound	"UPS"
status	"Label Created"
dateSubmitted	Current timestamp
isActive	true
createdBy	"Zapier"

Request Example

{
  "customerEmail": "customer@example.com",
  "customerName": "Jane Smith",
  "customerPhone": "555-123-4567",
  "deviceMake": "Dremel",
  "deviceModel": "4000",
  "serialNumber": "SN-12345",
  "issueDescription": "Motor not spinning, smells like burning",
  "trackingNumberOutbound": "1Z999AA10123456784",
  "shippingAddress": "123 Main St, Anytown, ST 12345"
}

Response — 200 OK

{
  "success": true,
  "repairId": "RPR-2026-9081",
  "message": "Repair record created successfully"
}

Response — 400 Bad Request

{
  "success": false,
  "error": "Missing required fields: customerEmail, customerName, deviceMake"
}

Response — 500 Server Error

{
  "success": false,
  "error": "Error message"
}

cURL Example

curl -X POST \
  https://www.northshorehandpiecerepair.com/_functions/jotform-intake \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "customer@example.com",
    "customerName": "Jane Smith",
    "deviceMake": "Dremel",
    "deviceModel": "4000",
    "trackingNumberOutbound": "1Z999AA10123456784"
  }'

Integration Notes

Zapier setup:

1. Trigger: JotForm → New Submission
2. Action: Webhooks by Zapier → POST
3. URL: https://www.northshorehandpiecerepair.com/_functions/jotform-intake
4. Payload type: JSON
5. Map JotForm fields to the request body fields above

JotForm direct webhook:

1. In JotForm → Settings → Integrations → Webhooks
2. Add the endpoint URL
3. JotForm will POST submission data — ensure field names match the request body

---

3. UPS Tracking Update — Status Progression [Enhancement]

As far as I know you aren't currently doing in-transit tracking, but provided you have access to that data we could automate this.

Updates a repair's status based on a UPS tracking event. Finds the repair by its outbound tracking number and maps the UPS event to a repair status.

Request Headers

Content-Type: application/json

Request Body

Field	Type	Required	Description
trackingNumber	string	Yes	UPS tracking number to look up
event	string	No	UPS event name (see mapping below)

Event → Status Mapping

UPS Event	Repair Status Set	Description
"In Transit"	"Shipped to Shop"	Item is on its way to the shop
"Delivered"	"Received"	Shop has received the item
(any other)	No change	Status remains unchanged

Request Example

{
  "trackingNumber": "1Z999AA10123456784",
  "event": "Delivered"
}

Response — 200 OK (status changed)

{
  "success": true,
  "repairId": "RPR-2026-9081",
  "newStatus": "Received"
}

Response — 200 OK (no matching repair)

{
  "success": false,
  "error": "No repair found for this tracking number"
}

Response — 400 Bad Request

{
  "success": false,
  "error": "Missing trackingNumber"
}

Response — 500 Server Error

{
  "success": false,
  "error": "Error message"
}

cURL Example

curl -X POST \
  https://www.northshorehandpiecerepair.com/_functions/ups-tracking-update \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1Z999AA10123456784",
    "event": "Delivered"
  }'

Integration Notes

Zapier setup (if using UPS → Zapier):

1. Trigger: UPS → New Tracking Event
2. Action: Webhooks by Zapier → POST
3. URL: https://www.northshorehandpiecerepair.com/_functions/ups-tracking-update
4. Map trackingNumber and event from the UPS trigger

Limitations:

• Only handles In Transit and Delivered events. Other events (e.g., Out for Delivery, Exception) do not change the status.
• Statuses beyond Received (e.g., In Repair, Repaired, Shipped Back) must be set manually via the admin dashboard.
• The createStatusEntry call records the change in RepairStatusHistory for audit/timeline purposes.

---

---

Testing

Use the Python test script to create a test repair and simulate status progression:

# Basic — creates a repair with "Label Created" status
python test_webhook.py member@example.com

# With status progression — simulates UPS tracking events
python test_webhook.py member@example.com transit,received

See test_webhook.py for details.

---

Troubleshooting

Symptom	Likely Cause	Fix
404 FUNCTION_NOT_FOUND	Endpoint not live	Publish the site; verify code is in http_functions.js (not a .jsw file)
500 Server Error with WDE0027	Missing suppressAuth: true	Add { suppressAuth: true } to the wixData call
400 Bad Request	Missing required fields	Check request body includes all required fields
Endpoint works in preview, not live	Site not published	Publish the site from the Wix editor
"Body is an invalid JSON format"	Malformed response object	Use ok({ body: {...} }) not raw objects; avoid ok as a property name

---

Notes for future enhancement

Adding a New Endpoint

1. Add a new exported function to http_functions.js:

   export async function post_myEndpoint(request) {
       try {
           const body = await request.body.json();
           // ... logic ...
           return ok({ body: { success: true } });
       } catch (error) {
           return serverError({ body: { success: false, error: error.message } });
       }
   }

2. The URL becomes: POST /_functions/my-endpoint
3. Use { suppressAuth: true } on all wixData calls
4. Parse the body with await request.body.json() (not JSON.parse)
5. Publish the site to make the endpoint live
6. Update this document with the new endpoint specification