Tutorial

From Internal Tool to API Product: The PunchConnect Story

How we turned an internal biometric device integration built for 24,000 employees into a cloud REST API product — and what we learned along the way.

PunchConnect Team·Mar 28, 2026·5 min read

Introduction

PunchConnect wasn't supposed to be a product. It was built out of frustration — and 4 months of production hell.

We were building AgriWise, a workforce management platform for agricultural companies in Morocco. 24,000+ employees across dozens of sites. Every site had ZKTeco biometric devices. And we needed to get attendance data from those devices into our cloud application in real time.

Nothing on the market worked. So we built our own. This is the story of how that internal tool became a standalone API product — and the engineering decisions that made it possible.

The Problem That Started Everything

AgriWise had a straightforward requirement: get punch data from biometric devices into a cloud application, reliably, in real time.

Sounds simple. It's not.

We tried every option. Open-source SDKs worked for a single device on a LAN. Vendor software was Windows-only with no API. Competitors in this space had opaque pricing, poor documentation, and architectures that assumed on-premise deployment.

So we spent 4 months building a protocol engine from scratch. It had to handle:

- 80+ devices across sites with varying connectivity (fiber to 3G cellular)
- Automatic reconnection and data sync after network outages
- Zero data loss — every punch had to arrive, eventually
- Real-time delivery — attendance data needed to flow within seconds, not minutes

From One Customer to a Platform

After running in production for 6 months with AgriWise, we kept hearing the same question from other companies: "How do you connect ZKTeco devices to the cloud?"

Developers on forums, Stack Overflow, GitHub issues — all hitting the same wall. The device protocol was undocumented. The open-source libraries were unmaintained. Cloud connectivity was an unsolved problem.

We didn't build a demo. We opened our production system. The same engine that handles AgriWise's 24,000+ employees now powers every PunchConnect API call.

The Engineering Decisions That Mattered

Turning an internal tool into an API product isn't just adding authentication. It's rethinking the entire architecture. Here's what we had to build:

1. Multi-Tenancy with Device Isolation

Every customer's devices are completely isolated. Customer A can never see Customer B's data, devices, or webhooks — even if they share the same physical server infrastructure.

python

# Every API request is scoped to the authenticated tenant
@app.route("/v1/devices", methods=["GET"])
@require_api_key
def list_devices():
    tenant_id = request.auth.tenant_id  # From API key
    
    devices = db.query(
        "SELECT * FROM devices WHERE tenant_id = %s",
        [tenant_id]
    )
    
    return jsonify({"devices": devices})

2. API Design: Lessons from Stripe

We studied Stripe, Twilio, and GitHub's APIs obsessively. The patterns that made them great:

- Consistent response format — every endpoint returns the same structure
- Clear error codes — not just HTTP status codes, but specific error identifiers
- Idempotency keys — retry-safe operations on every mutating endpoint
- Pagination — cursor-based, not offset-based (stable with real-time data)

bash

# Consistent error format across all endpoints
curl -X GET https://api.punchconnect.com/v1/devices/nonexistent \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "error": {
#     "code": "device_not_found",
#     "message": "No device found with ID 'nonexistent'",
#     "status": 404,
#     "doc_url": "https://docs.punchconnect.com/errors/device_not_found"
#   }
# }

3. Webhook Delivery System

The internal tool sent data directly to our database. An API product needs to send data to thousands of different endpoints, each with different reliability characteristics.

python

# Webhook delivery with exponential backoff
RETRY_DELAYS = [10, 60, 300, 1800, 7200]  # seconds

def deliver_webhook(webhook_url: str, payload: dict, secret: str):
    """Deliver webhook with signature and retries."""
    body = json.dumps(payload)
    signature = hmac.new(
        secret.encode(), body.encode(), hashlib.sha256
    ).hexdigest()
    
    for attempt, delay in enumerate(RETRY_DELAYS):
        try:
            resp = requests.post(
                webhook_url,
                data=body,
                headers={
                    "Content-Type": "application/json",
                    "X-PunchConnect-Signature": signature,
                    "X-PunchConnect-Delivery": str(uuid4()),
                },
                timeout=10
            )
            if resp.status_code < 300:
                return True  # Delivered
        except requests.RequestException:
            pass
        
        time.sleep(delay)
    
    # All retries exhausted — mark as failed
    log_delivery_failure(webhook_url, payload)
    return False

4. Rate Limiting Per Device

When an internal tool, you control the load. With an API product, you need to protect against abuse — both accidental and intentional.

bash

# Rate limit headers on every response
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 87
# X-RateLimit-Reset: 1711594800

curl -X GET https://api.punchconnect.com/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

5. Documentation as Product

For an internal tool, documentation is a wiki page nobody reads. For an API product, documentation is the product. If developers can't figure out your API in 5 minutes, they'll leave.

We built:
- Interactive API reference with try-it-now examples
- Quick-start guide (device to first webhook in under 5 minutes)
- Code samples in Python, JavaScript, cURL, PHP, Ruby
- Error code reference with solutions
- Webhook payload reference with full JSON schemas

What We Learned

After 18 months running both AgriWise (internal) and PunchConnect (product) on the same engine:

| Metric | Internal (AgriWise) | Product (PunchConnect) |
|--------|-------------------|----------------------|
| Devices | 80+ | Growing |
| Employees | 24,000+ | Varies per customer |
| Uptime | 99.7% | 99.7% (same engine) |
| Webhook latency | 340ms avg | 340ms avg |
| Lost records | Zero | Zero |
| Time to first integration | 4 months | Under 5 minutes |

The last row is the product. We spent 4 months integrating. Our customers spend 5 minutes. That's the value of an API product — you package your hard-won engineering into a simple interface.

The Lessons for Other Internal-to-Product Journeys

If you're sitting on an internal tool that solves a real problem, here's what we wish we'd known:

1. Don't build a demo — open your production system. Customers trust battle-tested infrastructure over polished landing pages.

2. Study the best APIs obsessively. Stripe's consistency, Twilio's error messages, GitHub's pagination. Copy the patterns, not the code.

3. Documentation is not an afterthought. Budget 30% of engineering time for docs. It's the first thing developers evaluate.

4. Multi-tenancy is harder than you think. Every query, every log, every webhook needs tenant scoping. Bolt this on from day one.

5. Price transparently. Our competitors hide pricing behind "contact sales." We put ours on the website: $200/device. Developers appreciate knowing the cost before they evaluate the product.

What's Next

PunchConnect is now serving customers across MENA, Sub-Saharan Africa, and Southeast Asia. The roadmap:

- Additional device protocols — beyond ZKTeco (Suprema, HID, ZKBioAccess)
- Device provisioning API — register and configure devices programmatically
- Real-time streaming — WebSocket connections for live attendance feeds
- Marketplace — pre-built integrations for popular ERP/HRMS platforms

We're building the Stripe of biometric device integration. The infrastructure layer that lets developers forget about device protocols and focus on their product.

FAQ

Is PunchConnect still used by AgriWise internally?

Yes. AgriWise runs on the exact same PunchConnect engine. Every improvement we make for external customers benefits AgriWise too — and vice versa. The production battle-testing never stops.

How long does it take to integrate PunchConnect?

Most developers get their first webhook within 5 minutes: register a device, configure the device in the dashboard, and start receiving real-time attendance data via your API endpoint.

What devices does PunchConnect support?

Currently, PunchConnect supports ZKTeco biometric devices — the most widely deployed brand globally. This includes SpeedFace, ProFace, UA860, K40, MB460, and most models with network connectivity. Support for additional brands is on the roadmap.

How is PunchConnect different from open-source libraries like pyzk?

Open-source libraries like pyzk connect to devices over LAN — one device at a time, on the same network. PunchConnect is a cloud service: devices connect outbound, work across any network, handle offline buffering, and deliver data via webhooks. It's the difference between a library and a platform.

Can I try PunchConnect before committing?

Yes. 7-day free trial with full API access, no credit card required. Connect a device and see it working before you decide.

---

Every API product starts as someone's internal problem. We spent 4 months solving biometric device connectivity for AgriWise. Now that solution is available to every developer who faces the same challenge.

Start your free 7-day trial — from zero to first webhook in under 5 minutes.