# ATC Integration Discovery

## Status
- Stage: discovery
- Ballbox implementation status: no ATC integration in repo yet
- Current purpose: understand how ATC can support the Ballbox coach workflow wedge and what access would be required

## Strategic Position
- ATC is the current strategic moat hypothesis behind the Ballbox thesis.
- Ballbox's likely unfair advantage comes from ATC-connected court/club context plus the relationship path through Seba.
- The open question is not whether ATC matters strategically; it is how much ATC access Ballbox needs for the first valuable loop.

## What The Public Docs Show
- Docs URL: `https://alquilatucancha.gitlab.io/node-apis/`
- Environments:
  - beta: `https://beta.alquilatucancha.com/api/v3`
  - production: `https://alquilatucancha.com/api/v3`
- Auth is JWT bearer with RS256.
- JWKS endpoint exists at `/auth/oauth/certs`.
- OAuth docs explicitly mention `password` and `refresh_token` grants.
- Some auth/API details still look ambiguous or partially documented.

## Relevant Endpoint Areas For Ballbox

### Sportclubs and courts
- `GET /atlas/sportclubs`
- `GET /atlas/sportclubs/{id}`
- `GET /atlas/courts`
- `GET /atlas/courts/{id}`

Potential value for Ballbox:
- identify clubs and courts
- inspect sports, timezone, business hours, amenities, pricing, and availability rules
- understand whether a coach workflow wedge can be club-aware and court-aware

### Availability and bookings
- `GET /availability/sportclubs`
- `GET /availability/sportclubs/{id}`
- `GET /availability/bookings`
- `POST /availability/bookings`
- `PATCH /availability/bookings/{id}`
- `DELETE /availability/bookings/{id}`
- `GET /availability/booking-instances`
- `POST /availability/booking-instances`
- `PATCH /availability/booking-instances/{id}`
- `POST /availability/booking-instances/{id}/cancel`
- `GET /availability/booking-instances/check-overlap`
- participant endpoints under `/availability/booking-instances/{id}/participants`

Potential value for Ballbox:
- see real court availability
- inspect existing bookings and overlaps
- test whether reprogramming or class coordination workflows are feasible
- support a future wedge around scheduling, rebooking, or occupancy fill

### Activities / open matches
- endpoints under `/activities` for available slots, open matches, match creation, inscriptions, nivelation, and whitelist checks

Potential value for Ballbox:
- understand whether ATC already exposes primitives for open-play or group activity flows
- evaluate whether Ballbox should layer on top of activities instead of inventing a parallel model

### Players and users
- `/atlas/sportclubs/{sportclub_id}/players`
- `/atlas/users`
- `/atlas/sportclubs/{sportclub_id}/users`
- `/connect/profile`
- player booking/debt/history endpoints under `/connect`

Potential value for Ballbox:
- map players and staff identities
- inspect whether Ballbox could use ATC players as an external source of truth for some workflows

## What Ballbox Can Likely Learn Early
- whether availability data is rich enough for a coach workflow wedge
- whether bookings expose enough data for class planning, rescheduling, or participant management
- whether clubs/courts metadata is useful enough to support scheduling decisions
- whether ATC activities overlap with any future Ballbox sports wedge

## Access Reality
- Public docs are enough to understand endpoint shape, auth model, and candidate use cases.
- Public docs alone are not enough to explore real data.
- To actually hit ATC endpoints and inspect live/beta data, Ballbox will need valid credentials and likely some manual setup from ATC.
- From docs alone, likely minimum access needs are:
  - a valid `client_id`
  - a username/password flow or equivalent credential flow for a real account
  - clarity on whether access should target beta or production
  - clarity on what sportclubs/data the provided account can read
- CEO verbal approval is useful organizationally, but technically Ballbox still needs working credentials and any required ATC-side provisioning.

## Practical Recommendation
- Ballbox can start now with docs-first integration discovery and endpoint prioritization.
- Ballbox probably cannot meaningfully "play with the API" until ATC provides at least one credentialed path into beta or production.
- Best next step is to ask ATC for a minimal beta sandbox setup:
  - one `client_id`
  - one test user/account
  - one or more sportclubs/courts with safe test data
  - confirmation of allowed scopes/permissions
  - confirmation of whether booking write operations are allowed in beta

## Public Read Validation
- Live probing against the documented beta API host suggests Ballbox can already validate some useful public-read surfaces without a user/token.

### Validated working without auth
- `GET /availability/sportclubs`
  - requires query params like `date_time`, `geohash_9`, and `sport_id`
  - returns nearby sportclubs plus public availability, court ids, slot times, durations, and prices
- `GET /availability/sportclubs/{id}`
  - works without auth for a specific club id
  - can return per-court inventory and `available_slots[]`
- `GET /activities/whitelist/courts/check?id=<courtId>`
  - works without auth
  - returns whether a court is whitelisted for activities flows

### Validated blocked or unreliable without auth
- `GET /atlas/sportclubs` -> `401`
- `GET /atlas/sportclubs/{id}` -> `401`
- `GET /atlas/courts` -> `401`
- `GET /atlas/sports` -> `401`
- `GET /availability/bookings` -> `401`
- `GET /activities/public-matches/{id}` -> `401`
- `GET /activities/public-matches` with valid-looking params behaved unreliably in testing and is not safe to treat as public-read

### What This Unlocks Right Now
- Ballbox can validate real public club/court/slot/price availability without waiting for admin credentials.
- Ballbox can start testing location + sport + datetime search behavior and understand real supply shape.
- Ballbox still cannot rely on unauthenticated access for booking details, admin-grade club data, or teacher/admin workflows.

## Risks / Unknowns From Docs Alone
- auth flow details are partially ambiguous
- required permissions per endpoint are not clearly documented
- no visible webhook/event model for booking changes
- no documented rate limits, SLAs, or idempotency guidance
- some docs appear thin or inconsistent, especially around activities
- recurring bookings, coach-specific metadata, and attendance semantics are still unclear

## Ballbox Decision Rule
- Do not write an ATC MVP integration spec as if access were ready.
- First confirm:
  - real credentials exist
  - target environment exists
  - Ballbox can read the club/court/availability data needed for the chosen wedge
- Only then should Ballbox move from integration discovery to integration spec.
- Ballbox should still keep ATC central in product strategy docs even before access is live.