### Service Unavailable Error Examples Source: https://docs.gateway.harborlockers.com/create-a-transaction-28385288e0 Example JSON responses for 503 Service Unavailable errors, covering scenarios for no available lockers and assignment contention. ```json no_lockers: summary: No available lockers value: error: NO_AVAILABLE_LOCKERS message: No lockers currently available timestamp: '2024-01-15T10:30:00Z' ``` ```json locker_contention: summary: Temporary locker assignment contention (retry recommended) value: error: LOCKER_ASSIGNMENT_CONFLICT message: >- Selected locker was assigned to another transaction. Please retry the request. timestamp: '2024-01-15T10:30:00Z' details: lockerId: 42 retryAfter: 0.1 ``` -------------------------------- ### Define Error Response Examples Source: https://docs.gateway.harborlockers.com/update-locker-service-state-28385295e0 Examples of JSON error responses for 404 and 409 HTTP status codes. ```yaml '404': description: Locker not found content: application/json: schema: *ref_0 examples: lockerNotFound: summary: Locker not found value: error: LOCKER_NOT_FOUND message: 'Locker not found: 42' timestamp: '2024-01-15T10:30:00Z' details: lockerId: 42 headers: {} x-apidog-name: '' '409': description: >- Conflict (locker deleted by another request, or always-out-of-service type) content: application/json: schema: *ref_0 examples: lockerDeleted: summary: Locker was deleted (race condition) value: error: LOCKER_NOT_FOUND message: Locker 42 was deleted by another request timestamp: '2024-01-15T10:30:00Z' details: lockerId: 42 alwaysOutOfService: summary: Locker type must stay out of service value: error: LOCKER_ALWAYS_OUT_OF_SERVICE message: >- Locker 42 has a locker type that must always remain out of service timestamp: '2024-01-15T10:30:00Z' details: lockerId: 42 reason: Locker type requires permanent out-of-service status headers: {} x-apidog-name: '' ``` -------------------------------- ### GET /bank-types Source: https://docs.gateway.harborlockers.com/list-all-bank-types-28385300e0 Retrieve all defined bank type configurations. ```APIDOC ## GET /bank-types ### Description Retrieve all defined bank type configurations. ### Method GET ### Endpoint /bank-types ### Response #### Success Response (200) - **bankTypeId** (integer) - Unique identifier for the bank type - **friendlyName** (string) - Human-readable name - **description** (string) - Optional description of this bank configuration - **isDebug** (boolean) - Whether this bank type is for debugging/testing - **lockerCount** (integer) - Total number of lockers defined in this bank type - **createdAt** (string) - Timestamp of creation #### Error Response (500) - **error** (string) - Machine-readable error code - **message** (string) - Human-readable error message - **timestamp** (string) - When the error occurred ``` -------------------------------- ### GET /lockers/config Source: https://docs.gateway.harborlockers.com/get-locker-configuration-28385293e0 Retrieve static configuration for all lockers without state information. ```APIDOC ## GET /lockers/config ### Description Retrieve static configuration for all lockers without state information. Returns only the physical configuration (locker IDs, controller assignments, ports, types) without dynamic state like availability, operational status, transactions, or door state. ### Method GET ### Endpoint /lockers/config ### Response #### Success Response (200) - **lockerId** (integer) - Unique identifier for the locker - **lockControllerId** (integer) - ID of the lock controller managing this locker (null if not assigned) - **controllerName** (string) - Name of the controller (null if not assigned) - **controllerHostname** (string) - Network hostname of the controller (null if not assigned) - **lockPort** (integer) - Port number on the controller (1-20) for this locker (null if not assigned) - **bankId** (integer) - Which bank this locker belongs to - **bankName** (string) - Name of the bank - **bankLockerNumber** (integer) - Customer-facing locker number within the bank (e.g., 1-44) - **lockerTypeId** (integer) - ID of the locker type - **lockerTypeSlug** (string) - Machine-readable locker type identifier (e.g., "medium", "large") - **isLow** (boolean) - Whether the locker is low/wheelchair accessible #### Error Response (500) - **error** (string) - Machine-readable error code - **message** (string) - Human-readable error message - **timestamp** (string) - When the error occurred - **details** (object) - Additional error details ``` -------------------------------- ### GET /lockers Source: https://docs.gateway.harborlockers.com/list-all-lockers-28385292e0 Retrieve the status of all lockers in the system with optional filters. ```APIDOC ## GET /lockers ### Description Retrieve the status of all lockers in the system with optional filters. ### Method GET ### Endpoint /lockers ### Parameters #### Query Parameters - **controllerId** (integer) - Optional - Filter by controller ID - **available** (boolean) - Optional - Filter by availability status (computed field - locker has no transaction, not out of service, and operational) - **outOfService** (boolean) - Optional - Filter by out of service status - **transacted** (boolean) - Optional - Filter by transaction status (locker has an active transaction assigned) ### Response #### Success Response (200) - **lockerId** (integer) - Unique identifier for the locker - **bankId** (integer) - Which bank this locker belongs to - **bankLockerNumber** (integer) - Customer-facing locker number within the bank (e.g., 1-44) - **lockerType** (object) - Locker type summary - **isLow** (boolean) - Whether the locker is low/wheelchair accessible - **lockControllerId** (integer) - ID of the lock controller managing this locker (null if not assigned) - **lockPort** (integer) - Port number on the controller (1-20) for this locker (null if not assigned) - **transactionId** (string) - Associated transaction ID, null if not assigned - **available** (boolean) - Whether the locker is available for transaction assignment - **outOfService** (boolean) - Whether the locker is administratively disabled - **brokenLock** (boolean) - Whether the locker has a broken lock sensor ``` -------------------------------- ### GET / Source: https://docs.gateway.harborlockers.com/admin-interface-28385285e0 Serves the admin interface HTML frontend or returns service information if the static files are unavailable. ```APIDOC ## GET / ### Description Serves the admin interface HTML frontend. This is the primary web interface for managing the locker service. If static files are not available, it returns service information. ### Method GET ### Endpoint / ### Response #### Success Response (200) - **message** (string) - Service name - **version** (string) - Service version #### Response Example { "message": "Harbor Gateway", "version": "1.0.0" } ``` -------------------------------- ### GET /transactions Source: https://docs.gateway.harborlockers.com/list-all-transactions-28385287e0 Retrieve a list of all active transactions in the system. ```APIDOC ## GET /transactions ### Description Retrieve all active transactions in the system. ### Method GET ### Endpoint /transactions ### Response #### Success Response (200) - **transactionId** (string) - The transaction ID - **lockerId** (integer) - ID of the assigned locker. Use GET /lockers/{lockerId} to retrieve full locker details. - **createdAt** (string) - Timestamp when the transaction was created #### Error Response (500) - **error** (string) - Machine-readable error code - **message** (string) - Human-readable error message - **timestamp** (string) - When the error occurred ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/lockers/config Source: https://docs.gateway.harborlockers.com/locker-configuration-34155926e0 Retrieves the static configuration of lockers at a specified location. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/lockers/config ### Description Returns the static configuration of lockers at this location. This response is safe to cache client-side. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/lockers/config ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Header Parameters - **Prefer** (string) - Optional - RFC 7240 preference. Supports `wait=` to override server default or `respond-async` to return 202 immediately. ### Response #### Success Response (200) - **Configuration payload** (string) - The configuration data for the lockers. #### Success Response (202) - **PendingRequest** (object) - Returned if sync-wait is exhausted. Poll the URL in the `Location` header. #### Error Responses - **400** (Error) - Malformed body or bad query parameter. - **401** (Error) - Missing, invalid, or revoked API key. - **403** (Error) - Endpoint not in gateway's allow-list. - **404** (Error) - Location or locker not found. - **413** (Error) - Body exceeds 32 KB limit. - **429** (Error) - Rate limit exceeded. - **502** (Error) - Gateway reached but dispatch failed. ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/system Source: https://docs.gateway.harborlockers.com/gateway-system-info-34155919e0 Retrieves hardware and firmware metadata for a specific gateway location. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/system ### Description Proxies the gateway's `GET /system` endpoint to retrieve hardware and firmware metadata. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/system ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Header Parameters - **Prefer** (string) - Optional - RFC 7240 preference. Supports `wait=` to override server default (max 30s) or `respond-async` to return 202 immediately. ### Response #### Success Response (200) - **body** (string) - Gateway system info. #### Success Response (202) - **Location** (string) - URL to poll for the terminal response. - **X-Request-Id** (string) - Request identifier. #### Error Responses - **400** (InvalidRequest) - Malformed body or bad query parameter. - **401** (AuthRequired) - Missing, invalid, or revoked API key. - **403** (PermissionDenied) - Endpoint not in gateway's allow-list. - **404** (NotFound) - Location not found or outside organization scope. - **413** (PayloadTooLarge) - Body exceeds 32 KB limit. - **429** (RateLimited) - Rate limit exceeded. - **502** (BadGateway) - Gateway reached but dispatch failed. ``` -------------------------------- ### OpenAPI Specification for Locker Configuration Source: https://docs.gateway.harborlockers.com/get-locker-configuration-28385293e0 Defines the GET /lockers/config endpoint and the associated LockerConfig and Error schemas. ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /lockers/config: get: summary: Get locker configuration deprecated: false description: > Retrieve static configuration for all lockers without state information. Returns only the physical configuration (locker IDs, controller assignments, ports, types) without dynamic state like availability, operational status, transactions, or door state. Use this endpoint to understand the physical locker layout and assignments. operationId: getLockerConfig tags: - Harbor Gateway Local API/Lockers - Lockers parameters: [] responses: '200': description: Locker configuration list content: application/json: schema: type: array items: $ref: '#/components/schemas/LockerConfig' headers: {} x-apidog-name: '' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} x-apidog-name: '' security: [] x-apidog-folder: Harbor Gateway Local API/Lockers x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/1136893/apis/api-28385293-run components: schemas: LockerConfig: type: object description: Static locker configuration without state information properties: lockerId: type: integer description: Unique identifier for the locker lockControllerId: type: integer description: >- ID of the lock controller managing this locker (null if not assigned) nullable: true controllerName: type: string description: Name of the controller (null if not assigned) nullable: true controllerHostname: type: string description: Network hostname of the controller (null if not assigned) nullable: true lockPort: type: integer description: >- Port number on the controller (1-20) for this locker (null if not assigned) nullable: true bankId: type: integer description: Which bank this locker belongs to bankName: type: string description: Name of the bank bankLockerNumber: type: integer description: Customer-facing locker number within the bank (e.g., 1-44) lockerTypeId: type: integer description: ID of the locker type lockerTypeSlug: type: string description: Machine-readable locker type identifier (e.g., "medium", "large") isLow: type: boolean description: Whether the locker is low/wheelchair accessible required: - lockerId - bankId - bankName - bankLockerNumber - lockerTypeId - lockerTypeSlug - isLow x-apidog-orders: - lockerId - lockControllerId - controllerName - controllerHostname - lockPort - bankId - bankName - bankLockerNumber - lockerTypeId - lockerTypeSlug - isLow x-apidog-ignore-properties: [] x-apidog-folder: '' Error: type: object properties: error: type: string enum: - NO_AVAILABLE_LOCKERS - NO_AVAILABLE_LOCKERS_OF_TYPE - LOCKER_ASSIGNMENT_CONFLICT - TRANSACTION_NOT_FOUND - TRANSACTION_ALREADY_EXISTS - LOCKER_NOT_FOUND - LOCKER_NOT_AVAILABLE - LOCKER_OUT_OF_SERVICE - LOCKER_ALWAYS_OUT_OF_SERVICE - LOCK_MALFUNCTION - LOCKER_TYPE_NOT_FOUND - CONTROL_BOARD_UNREACHABLE - CONTROL_BOARD_TIMEOUT - CONTROL_BOARD_ERROR - CONTROLLER_NOT_FOUND - CONTROLLER_EXISTS - CONTROLLER_ALREADY_ASSIGNED - CONTROLLER_DELETED - ACTIVE_TRANSACTIONS - INVALID_LOCKER_COUNT - BANK_NOT_FOUND - BANK_TYPE_NOT_FOUND - BANK_DELETED - UNAUTHORIZED - INVALID_REQUEST - UPDATE_FAILED description: Machine-readable error code for programmatic handling message: type: string description: Human-readable error message timestamp: type: string format: date-time description: When the error occurred details: type: object ``` -------------------------------- ### OpenAPI Specification for List Lockers Source: https://docs.gateway.harborlockers.com/list-all-lockers-28385292e0 Defines the GET /lockers endpoint and the Locker schema for the Harbor Gateway Local API. ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /lockers: get: summary: List all lockers deprecated: false description: Retrieve the status of all lockers in the system with optional filters operationId: listLockers tags: - Harbor Gateway Local API/Lockers - Lockers parameters: - name: controllerId in: query description: Filter by controller ID required: false schema: type: integer - name: available in: query description: >- Filter by availability status (computed field - locker has no transaction, not out of service, and operational) required: false schema: type: boolean - name: outOfService in: query description: Filter by out of service status required: false schema: type: boolean - name: transacted in: query description: >- Filter by transaction status (locker has an active transaction assigned) required: false schema: type: boolean responses: '200': description: List of all lockers content: application/json: schema: type: array items: $ref: '#/components/schemas/Locker' headers: {} x-apidog-name: '' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} x-apidog-name: '' security: [] x-apidog-folder: Harbor Gateway Local API/Lockers x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/1136893/apis/api-28385292-run components: schemas: Locker: type: object properties: lockerId: type: integer description: Unique identifier for the locker bankId: type: integer description: Which bank this locker belongs to bankLockerNumber: type: integer description: Customer-facing locker number within the bank (e.g., 1-44) lockerType: $ref: '#/components/schemas/LockerTypeSummary' isLow: type: boolean description: Whether the locker is low/wheelchair accessible lockControllerId: type: integer description: >- ID of the lock controller managing this locker (null if not assigned) nullable: true lockPort: type: integer description: >- Port number on the controller (1-20) for this locker (null if not assigned) nullable: true transactionId: type: string description: Associated transaction ID, null if not assigned nullable: true available: type: boolean description: >- Whether the locker is available for transaction assignment. Computed as transactionId is null AND outOfService is false AND operational is true. outOfService: type: boolean description: Whether the locker is administratively disabled brokenLock: type: boolean description: > Whether the locker has a broken lock sensor (GPIO expander bug workaround). ``` -------------------------------- ### GET /bank-types/{bankTypeId} Source: https://docs.gateway.harborlockers.com/get-bank-type-with-associations-28385301e0 Retrieve detailed bank type configuration including locker number to type mappings. ```APIDOC ## GET /bank-types/{bankTypeId} ### Description Retrieve detailed bank type configuration including locker number to type mappings. ### Method GET ### Endpoint /bank-types/{bankTypeId} ### Parameters #### Path Parameters - **bankTypeId** (string) - Required - The unique identifier of the bank type. ### Response #### Success Response (200) - **associations** (array) - Mapping of locker numbers to locker types. #### Error Response (404) - Bank type not found #### Error Response (500) - Internal server error ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/health Source: https://docs.gateway.harborlockers.com/gateway-health-check-34155918e0 Proxies the gateway's GET /health request. This operation is cheap and idempotent. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/health ### Description Proxies the gateway's `GET /health`. Cheap, idempotent. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/health ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Header Parameters - **Prefer** (string) - Optional - RFC 7240 preference. Two forms are recognised: `Prefer: wait=` (override server default, max 30s) or `Prefer: respond-async` (return 202 immediately). ### Response #### Success Response (200) - **string** - Gateway is healthy. #### Success Response (202) - **PendingRequest** - Sync-wait exhausted before the gateway reached a terminal state. Poll the URL in `Location` until it returns the terminal response. ``` -------------------------------- ### GET /api/customer/v1/me Source: https://docs.gateway.harborlockers.com/identify-the-authenticated-api-key-34155915e0 Returns the key's label, prefix, and the organization it's scoped to. This is useful as a smoke test after provisioning a key. ```APIDOC ## GET /api/customer/v1/me ### Description Returns the key's label, prefix, and the organization it's scoped to. Handy smoke test after provisioning a key. ### Method GET ### Endpoint /api/customer/v1/me ### Response #### Success Response (200) - **api_key** (object) - Metadata about the API key including id, label, and prefix. - **organization** (object) - Metadata about the organization including id and name. - **rate_limit** (object) - Current rate limit status including limit, remaining, and reset_at timestamp. #### Error Response (401) - **error** (object) - Contains code and message indicating authentication failure. #### Error Response (429) - **error** (object) - Contains code and message indicating rate limit exceeded. ``` -------------------------------- ### Authentication Headers Source: https://docs.gateway.harborlockers.com/how-to-use-harbor-gateway-cloud-api-2110574m0 Use either the X-API-Key or Authorization header to provide your API key for every request. ```http X-API-Key: hgwm_<64 hex chars> ``` ```http Authorization: Bearer hgwm_<64 hex chars> ``` -------------------------------- ### GET /api/customer/v1/requests/{id} Source: https://docs.gateway.harborlockers.com/poll-a-pending-request-34155917e0 Polls the status of a pending request by its unique identifier. ```APIDOC ## GET /api/customer/v1/requests/{id} ### Description Returns the status of a pending request. When the request has reached a terminal state, the body contains the gateway's response. If the request is still in flight, it returns a 202 Accepted status. ### Method GET ### Endpoint /api/customer/v1/requests/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the request. ``` -------------------------------- ### POST /lockers/open-all Source: https://docs.gateway.harborlockers.com/open-all-lockers-28385297e0 Opens all lockers in the system. This operation is intended for maintenance or emergency use and does not check the operational status of the lockers. ```APIDOC ## POST /lockers/open-all ### Description Opens all lockers in the system. Each locker operation uses a 20-second timeout per attempt, up to 3 attempts with 1-second delays between retries. Retries occur on network/communication errors only; hardware malfunctions are not retried. This is an optimistic operation that does not check outOfService or operational status. ### Method POST ### Endpoint /lockers/open-all ### Response #### Success Response (200) - **success** (boolean) - Whether the operation completed (true even if some lockers failed) - **totalLockers** (integer) - Total number of lockers in the system - **successCount** (integer) - Number of lockers successfully opened - **failureCount** (integer) - Number of lockers that failed to open - **results** (array) - Array of results for each locker operation #### Error Response (500) - **error** (string) - Machine-readable error code - **message** (string) - Human-readable error message #### Error Response (503) - **error** (string) - Machine-readable error code (e.g., CONTROL_BOARD_UNREACHABLE) - **message** (string) - Human-readable error message ``` -------------------------------- ### POST /transactions Source: https://docs.gateway.harborlockers.com/create-a-transaction-34155921e0 Initiates a new transaction request in the Harbor Gateway system. ```APIDOC ## POST /transactions ### Description Creates a new transaction request. This endpoint accepts transaction details such as locker preferences and dimensions to initiate the process. ### Method POST ### Endpoint /transactions ### Request Body - **transactionId** (string) - Required - Unique identifier for the transaction (e.g., ORDER-8821) - **preferredLockerType** (string) - Optional - The preferred size or type of locker (e.g., medium) - **preferredAttributes** (array) - Optional - List of preferred attributes - **widthInches** (number) - Optional - Width of the item in inches - **heightInches** (number) - Optional - Height of the item in inches - **lengthInches** (number) - Optional - Length of the item in inches - **allowFallback** (boolean) - Optional - Whether to allow fallback options - **attributesRequired** (boolean) - Optional - Whether attributes are strictly required - **matchingStrategy** (string) - Optional - Strategy used for matching ### Response #### Success Response (200) - **request_id** (string) - UUID of the request - **status** (string) - Status of the request (pending) - **state** (string) - Latest observed non-terminal state - **poll_url** (string) - URL to poll for status updates - **message** (string) - Optional status message ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/transactions Source: https://docs.gateway.harborlockers.com/list-transactions-at-a-location-34155920e0 Retrieves a list of transactions for the specified location. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/transactions ### Description Retrieves a list of transactions for the specified location. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/transactions ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Query Parameters - **Prefer** (string) - Optional - RFC 7240 preference. Two forms are recognised: * `Prefer: wait=` — override the server default for this call (clamped to 30s max). * `Prefer: respond-async` — return `202` immediately without blocking. ### Response #### Success Response (200) - **transactions** (string) - List of transactions. #### Success Response (202) - **Location** (string) - Poll this URL until it returns the terminal response. - **X-Request-Id** (string) - Request identifier. ``` -------------------------------- ### GET /locker-types/{lockerTypeId} Source: https://docs.gateway.harborlockers.com/get-locker-type-details-28385299e0 Retrieve detailed information about a specific locker type. ```APIDOC ## GET /locker-types/{lockerTypeId} ### Description Retrieve detailed information about a specific locker type. ### Method GET ### Endpoint /locker-types/{lockerTypeId} ### Parameters #### Path Parameters - **lockerTypeId** (string) - Required - Unique identifier for the locker type. ### Response #### Success Response (200) - **lockerTypeId** (integer) - Unique identifier for the locker type. - **createdAt** (string) - Timestamp when the locker type was created. - **slug** (string) - Machine-readable identifier (e.g., "medium", "screen", "large"). - **lengthInches** (number) - Locker depth dimension in inches. - **widthInches** (number) - Locker width dimension in inches. - **heightInches** (number) - Locker height dimension in inches. - **description** (string) - Human-readable description. - **alwaysOos** (boolean) - Whether this locker type is permanently out of service. ``` -------------------------------- ### Locker Schema and Server Configuration Source: https://docs.gateway.harborlockers.com/locker-11234081d0 Defines the locker resource structure and the production API server endpoint. ```yaml operational: type: boolean description: >- Whether the locker hardware and communication are functioning properly reasonCode: type: string enum: - CONTROL_BOARD_UNREACHABLE - CONTROL_BOARD_TIMEOUT - CONTROL_BOARD_ERROR - LOCK_MALFUNCTION - MANUAL_DISABLE - HARDWARE_MALFUNCTION - DOOR_SENSOR_FAILURE - UNKNOWN description: >- Machine-readable reason code when operational is false or outOfService is true nullable: true reason: type: string description: >- Human-readable explanation when operational is false or outOfService is true nullable: true doorOpen: type: boolean description: >- Whether the door sensor detected the door as open. Updated automatically every 60 seconds via health checks (requires controller firmware v2.0.7+). Shows last known state from controller status polling or UNKNOWN if controller firmware doesn't support status reporting. lastOpened: type: string format: date-time description: Timestamp of when the locker was last opened nullable: true required: - lockerId - bankId - bankLockerNumber - lockerType - available - outOfService - operational - doorOpen x-apidog-orders: - lockerId - bankId - bankLockerNumber - lockerType - isLow - lockControllerId - lockPort - transactionId - available - outOfService - brokenLock - operational - reasonCode - reason - doorOpen - lastOpened x-apidog-folder: '' securitySchemes: {} servers: - url: https://prod.your-api-server.com description: Prod Env security: [] ``` -------------------------------- ### GET /locker-types Source: https://docs.gateway.harborlockers.com/list-all-locker-types-28385298e0 Retrieve all defined locker types (physical dimensions and characteristics). ```APIDOC ## GET /locker-types ### Description Retrieve all defined locker types (physical dimensions and characteristics). ### Method GET ### Endpoint /locker-types ### Response #### Success Response (200) - **lockerTypeId** (integer) - Unique identifier for the locker type - **createdAt** (string) - Timestamp when the locker type was created - **slug** (string) - Machine-readable identifier (e.g., "medium", "screen", "large") - **lengthInches** (number) - Locker depth dimension in inches - **widthInches** (number) - Locker width dimension in inches - **heightInches** (number) - Locker height dimension in inches - **description** (string) - Human-readable description - **alwaysOos** (boolean) - Whether this locker type is permanently out of service #### Response Example [ { "lockerTypeId": 1, "createdAt": "2025-01-15T10:30:00Z", "slug": "medium", "lengthInches": 12, "widthInches": 12, "heightInches": 18, "description": "Medium locker (default)", "alwaysOos": false } ] ``` -------------------------------- ### GET /health Source: https://docs.gateway.harborlockers.com/health-check-28385286e0 Verifies that the service is running and returns the current status and timestamp. ```APIDOC ## GET /health ### Description Quick health check endpoint to verify the service is running. ### Method GET ### Endpoint /health ### Response #### Success Response (200) - **status** (string) - Service status, must be "ok". - **timestamp** (string) - The date-time when the health check was performed. #### Response Example { "status": "ok", "timestamp": "2023-10-27T10:00:00Z" } ``` -------------------------------- ### GET /transactions/{transactionId} Source: https://docs.gateway.harborlockers.com/get-transaction-details-28385289e0 Retrieve information about a specific transaction and its associated locker. ```APIDOC ## GET /transactions/{transactionId} ### Description Retrieve information about a specific transaction and its associated locker. ### Method GET ### Endpoint /transactions/{transactionId} ### Parameters #### Path Parameters - **transactionId** (string) - Required - The transaction ID ### Response #### Success Response (200) - **transactionId** (string) - The transaction ID - **lockerId** (integer) - ID of the assigned locker. Use GET /lockers/{lockerId} to retrieve full locker details. - **createdAt** (string) - Timestamp when the transaction was created #### Response Example { "transactionId": "string", "lockerId": 0, "createdAt": "2023-01-01T00:00:00Z" } ``` -------------------------------- ### POST /api/customer/v1/locations/{locationId}/lockers/{lockerId}/open Source: https://docs.gateway.harborlockers.com/open-a-specific-locker-34155929e0 Triggers the hardware operation to open a specific locker. This is a non-idempotent operation; use an Idempotency-Key for safe retries. ```APIDOC ## POST /api/customer/v1/locations/{locationId}/lockers/{lockerId}/open ### Description Triggers the hardware operation to open a specific locker. Note that this is a non-idempotent operation; use an Idempotency-Key for safe retries. On abandoned requests, the side effect is unknown. ### Method POST ### Endpoint /api/customer/v1/locations/{locationId}/lockers/{lockerId}/open ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. - **lockerId** (string) - Required - Locker identifier (numeric or string; gateway-defined). #### Header Parameters - **Idempotency-Key** (string) - Optional - Safe-retry token. Use a fresh UUIDv4 per logical attempt. - **Prefer** (string) - Optional - RFC 7240 preference. Supports `wait=` or `respond-async`. ### Response #### Success Response (200) - **string** - Door opened. #### Success Response (202) - **PendingRequest** - Sync-wait exhausted. Poll the URL in the `Location` header until a terminal response is returned. ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/lockers Source: https://docs.gateway.harborlockers.com/list-lockers-34155925e0 Lists lockers at a location, optionally filtered by state. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/lockers ### Description Lists lockers at a location, optionally filtered by state. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/lockers ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Query Parameters - **available** (boolean) - Optional - If true, return only lockers currently available for assignment. If false, only unavailable ones. - **transacted** (boolean) - Optional - If true, return only lockers currently holding a transaction. If false, only empty ones. - **outOfService** (boolean) - Optional - If true, return only lockers marked out of service. If false, only in-service. - **controllerId** (string) - Optional - Return only lockers managed by this controller. ### Response #### Success Response (200) - **body** (string) - List of lockers. #### Success Response (202) - **Location** (string) - Poll the URL in Location until it returns the terminal response. - **X-Request-Id** (string) - Request identifier. ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/bank-types Source: https://docs.gateway.harborlockers.com/list-bank-types-34155932e0 Retrieves a list of bank types for the specified location. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/bank-types ### Description Retrieves a list of bank types for the specified location. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/bank-types ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Header Parameters - **Prefer** (string) - Optional - RFC 7240 preference. Two forms are recognised: 'wait=' to override server default or 'respond-async' to return 202 immediately. ### Response #### Success Response (200) - **body** (string) - List of bank types. #### Success Response (202) - **Location** (string) - URL to poll for terminal response. - **X-Request-Id** (string) - Request identifier. ``` -------------------------------- ### POST /lockers/{lockerId}/open Source: https://docs.gateway.harborlockers.com/open-locker-by-id-28385296e0 Opens a specific locker by its ID. This is a physical operation with a 20-second timeout per attempt, up to 3 attempts with 1-second delays. It is designed for maintenance and does not check transaction status or operational status. ```APIDOC ## POST /lockers/{lockerId}/open ### Description Opens a specific locker by its ID. This is a physical operation with a 20-second timeout per attempt, up to 3 attempts with 1-second delays. It is designed for maintenance and does not check transaction status or operational status. ### Method POST ### Endpoint /lockers/{lockerId}/open ### Parameters #### Path Parameters - **lockerId** (integer) - Required - The locker ID ### Response #### Success Response (200) - **success** (boolean) - Whether the operation was successful - **lockerId** (integer) - The locker ID that was operated on - **doorOpen** (boolean) - Whether the door sensor detected the door as open after the operation - **message** (string) - Human-readable message about the operation #### Error Response (404, 500, 503) - **error** (string) - Machine-readable error code - **message** (string) - Human-readable error message - **timestamp** (string) - When the error occurred - **details** (object) - Additional error context ``` -------------------------------- ### OpenAPI Specification Configuration Source: https://docs.gateway.harborlockers.com/open-locker-by-id-28385296e0 Defines the API server URL and security requirements for the HarborLockers gateway. ```yaml description: Same API key, sent as a bearer token. servers: - url: https://prod.your-api-server.com description: Prod Env security: [] ``` -------------------------------- ### GET /api/customer/v1/locations/{locationId}/locker-types Source: https://docs.gateway.harborlockers.com/list-locker-types-34155930e0 Retrieves a list of locker types for the specified location. ```APIDOC ## GET /api/customer/v1/locations/{locationId}/locker-types ### Description Retrieves a list of locker types available at the specified location. ### Method GET ### Endpoint /api/customer/v1/locations/{locationId}/locker-types ### Parameters #### Path Parameters - **locationId** (integer) - Required - Location ID. #### Header Parameters - **Prefer** (string) - Optional - RFC 7240 preference. Supports `wait=` to override server default or `respond-async` to return 202 immediately. ### Response #### Success Response (200) - **body** (string) - List of locker types. #### Success Response (202) - **Location** (string) - URL to poll for the terminal response. - **X-Request-Id** (string) - Request identifier. ``` -------------------------------- ### Define API Servers Source: https://docs.gateway.harborlockers.com/get-locker-type-details-28385299e0 Configuration for API server endpoints and environment definitions. ```yaml servers: - url: https://prod.your-api-server.com description: Prod Env security: [] ```