Developer API Guide

This guide explains how to integrate with the Juvonno API reliably in real-world implementations.

Getting Started

• Use this guide for integration rules and behavior patterns.
• Start with the first successful call: 5-Minute First API Call
• Then implement the end-to-end flow: Golden Path Integration Example
• If you can successfully complete the Golden Path example, you are ready to build production integrations.

Authentication

• Use header auth on requests: `X-API-Key: <your_api_key>`.
• Authentication is required for all requests unless an endpoint explicitly states otherwise.
• Common mistakes:
  • missing `X-API-Key` header
  • typo in header name (`X-Api-Key`, `x-api-key`, etc.)
  • using API key in query parameters instead of headers
• Special case: customer document upload uses a token flow (`upload_token` then upload with `api_token`) and is documented to avoid exposing your API key in client applications.

Base URL and Environment

• Base URL pattern: `https://{subdomain}.juvonno.com`
• API routes are under `/api` (for example: `$BASE_URL/api/branches`).
• Subdomain is tenant-specific.
• Public sandbox/staging environment is not documented. [Needs Juvonno confirmation]

Request and Response Conventions

• Most create/update/search requests use JSON (`Content-Type: application/json`).
• Common request headers:
  • `Accept: application/json`
  • `Content-Type: application/json` (when sending body data)
  • `X-API-Key: <your_api_key>`
• Response shape is not uniform:
  • some endpoints return arrays directly (for example `GET /branches`)
  • some return wrapped objects with paging fields and a `list` payload
  • some return wrappers with different keys (for example `count` + `data` on staff list responses)
  • some return single resource objects
• Do not assume response formats are consistent across endpoints.
• Inspect and validate each endpoint’s response structure before finalizing parsing logic.
• Gotcha: endpoint summaries/descriptions do not always match actual schema shape; parse responses defensively and validate against runtime.

Pagination and Search Behavior

• Common paged wrapper pattern uses:
  • `total`
  • `page`
  • `count`
  • `list` 
• Example endpoints using wrapped list responses:
  • `POST /customers/search`
  • `GET /customers/list`
  • `POST /appointments/search`
• Pagination and query styles are inconsistent across endpoints:
  • some use `page`
  • others use `start` and `results`
• Endpoint pagination patterns:
  • `GET /customers/list`: `page`
  • `POST /customers/search`: wrapped response with `total` / `page` / `count` / `list`
  • `GET /appointments/list/{branchCode}`: `start` + `results`
  • `GET /commissions`: `start` + `results`
  • `GET /staff`: `page`, with `count` + `data` response keys
• Simple implementation pattern:
  • start with each endpoint's documented pagination parameters
  • process the endpoint's actual response keys (`list` or `data`)
  • continue requesting additional pages until no results are returned

Identifiers in Juvonno

• Identifier handling is critical; most integration issues come from using the wrong identifier type for a specific endpoint.
• `customer_id` vs `customer_num`:
  • some endpoints accept either, but not always with identical naming
  • prefer `customer_id` after first lookup/create when available
• `branch_code` vs `branch_id`:
  • both appear across endpoints
  • prefer `branch_code` when available; keep `branch_id` as fallback
• `staff_num`:
  • used for appointment attendants/practitioner references
  • must be valid for appointment creation flows
• See concrete ID capture and reuse in [Golden Path Integration Example](../_shared/workflows/00-golden-path.md).
• Gotcha: naming is inconsistent in the API (`customerId` vs `customer_id` in different endpoints).
• Before shipping, confirm accepted identifier fields per endpoint in runtime tests.

Error Handling

• Typical error body format:
  • `status` (integer)
  • `message` (string)
• Common scenarios to handle:
  • auth errors (missing/invalid API key)
  • validation errors (invalid IDs, missing required fields)
  • not found (invalid resource identifiers)
• Implementation guidance:
  • log request path, status, and response body
  • fail fast on validation errors
  • retry only where safe and idempotent [Needs Juvonno confirmation]
  • use backoff for transient/network failures [Needs Juvonno confirmation]

Common Integration Patterns

• Customer sync:
  • search or list customers, then upsert in your system
• Appointment creation:
  • resolve customer + clinic + staff identifiers, then create and confirm appointment
• Document upload:
  • token-based upload flow under customer documents endpoints
• Webhook usage:
  • configure webhook endpoints to receive event notifications
• Related workflows:
  • Golden Path Integration Example

Known Inconsistencies and Gotchas

• These issues come from differences between the OpenAPI description and observed runtime behavior.
• Parameter naming inconsistencies across endpoints (`customerId` vs `customer_id`, mixed id/code/num naming).
• Response shape differences require endpoint-specific parsing (array vs wrapped list vs single object).
• Keep a dedicated inconsistencies document and update it as runtime behavior is verified.
• Validate integrations against actual API responses, not documentation text alone.

Common Integration Mistakes

• Using the wrong identifier type for an endpoint (`*_id` vs `*_num` vs `*_code`).
• Forgetting the `/api` path prefix.
• Assuming every endpoint returns the same response structure.
• Treating empty results as hard errors instead of valid no-match cases.
• Sending unvalidated values for required fields (date/time, staff/branch/customer identifiers).

Support and Responsibilities

• Juvonno provides:
  • API endpoints
  • OpenAPI definition
  • integration documentation
• Integrators are responsible for:
  • secure key handling and secret storage
  • request/response validation
  • retries, monitoring, and alerting
  • business logic correctness in their own system
• Before escalating issues, isolate and reproduce with a minimal `curl` request and response payload.
• Support limitations:
  • implementation details in your internal systems are out of scope

FAQ

Which guide should I start with?

• Start with the 5-Minute First API Call, then follow the Golden Path Integration Example.

Do all endpoints require `X-API-Key`?

• Treat as yes by default; account for documented endpoint exceptions (for example token-based document upload behavior).

Should I use `customer_id` or `customer_num`?

• Prefer `customer_id` after you have it; use `customer_num` only where needed by endpoint behavior.

Should I use `branch_code` or `branch_id`?

• Prefer `branch_code` when accepted; keep `branch_id` as fallback.

Why does list parsing work for one endpoint but fail for another?

• Some endpoints return wrappers with `list`, others return arrays or single objects.

Is an empty list response an error?

• Usually no; treat as no matching records unless endpoint docs say otherwise.

Glossary

• customer: a client/patient record in Juvonno
• branch: a clinic/location record
• staff: practitioner/employee record (often referenced via `staff_num`)
• appointment: scheduled visit record tied to customer, branch, and staff
• identifiers: fields used to reference records (`id`, `num`, `code`) that vary by endpoint