{ "openapi": "3.1.0", "info": { "title": "EasyPick E-shop API", "description": "Serverové API pro rezervaci a sledování zásilek ve výdejových boxech EasyPick.", "version": "1.1.0" }, "servers": [ { "url": "https://api.easypick.cz/v1", "description": "EasyPick production" }, { "url": "https://sandbox-api.easypick.cz/v1", "description": "EasyPick sandbox" } ], "paths": { "/boxes": { "get": { "tags": [ "Boxes" ], "summary": "Vypsat boxy", "description": "Vrátí aktivní boxy patřící klientovi API klíče.", "operationId": "listBoxes", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBoxListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } }, "security": [ { "EasyPickApiKey": [] } ] } }, "/shipments": { "post": { "tags": [ "Shipments" ], "summary": "Vytvořit zásilku", "description": "Atomicky rezervuje zákaznickou schránku a vygeneruje šestimístný PIN.", "operationId": "createShipment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShipmentCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShipmentCreateResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "409": { "description": "Business rule conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } } }, "security": [ { "EasyPickApiKey": [] } ] } }, "/shipments/{shipment_id}": { "get": { "tags": [ "Shipments" ], "summary": "Načíst zásilku", "description": "Vrátí aktuální veřejný stav a termíny vyzvednutí.", "operationId": "getShipment", "security": [ { "EasyPickApiKey": [] } ], "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Shipment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShipmentRead" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shipments/{shipment_id}/pickup-pin": { "get": { "tags": [ "Shipments" ], "summary": "Zobrazit PIN", "description": "Vrátí PIN zásilky a zapíše auditní událost.", "operationId": "revealPickupPin", "security": [ { "EasyPickApiKey": [] } ], "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Shipment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPickupPinRead" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "409": { "description": "Business rule conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shipments/{shipment_id}/cancel": { "post": { "tags": [ "Shipments" ], "summary": "Zrušit zásilku", "description": "Zruší rezervovanou nebo naskladněnou zásilku. Opakované zrušení je idempotentní.", "operationId": "cancelShipment", "security": [ { "EasyPickApiKey": [] } ], "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Shipment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShipmentRead" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "409": { "description": "Business rule conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shipments/{shipment_id}/retry": { "post": { "tags": [ "Shipments" ], "summary": "Opakovat chybovou zásilku", "description": "Po fyzickém uvolnění původní schránky vytvoří nový rezervovaný pokus s novým PINem. Opakovaný požadavek vrátí stejný náhradní pokus.", "operationId": "retryShipment", "security": [ { "EasyPickApiKey": [] } ], "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Shipment Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShipmentCreateResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "409": { "description": "Business rule conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "PublicBoxListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PublicBoxRead" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "PublicBoxListResponse" }, "PublicBoxRead": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stabilní identifikátor boxu používaný při vytváření zásilky." }, "name": { "type": "string", "title": "Name", "description": "Název boxu určený pro zákazníka." }, "location_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location Name", "description": "Krátký název lokace." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address", "description": "Poštovní nebo jinak čitelná adresa lokace." } }, "type": "object", "required": [ "id", "name", "location_name", "address" ], "title": "PublicBoxRead" }, "PublicCompartmentState": { "enum": [ "reserved", "occupied", "awaiting_removal", "cooldown", "available" ], "title": "PublicCompartmentState", "type": "string" }, "PublicErrorDetail": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "request_id": { "type": "string", "title": "Request Id" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details" } }, "type": "object", "required": [ "code", "message", "request_id" ], "title": "PublicErrorDetail" }, "PublicErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/PublicErrorDetail" } }, "type": "object", "required": [ "error" ], "title": "PublicErrorResponse" }, "PublicPickupPinRead": { "properties": { "shipment_id": { "type": "string", "title": "Shipment Id" }, "pickup_pin": { "type": "string", "pattern": "^[0-9]{6}$", "title": "Pickup Pin" } }, "type": "object", "required": [ "shipment_id", "pickup_pin" ], "title": "PublicPickupPinRead" }, "PublicShipmentCreate": { "properties": { "box_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Box Id", "description": "Identifikátor boxu vrácený endpointem GET /boxes." }, "external_order_id": { "type": "string", "maxLength": 160, "minLength": 1, "title": "External Order Id", "description": "Unikátní číslo objednávky v rámci klienta. Současně slouží jako idempotency key." }, "customer_name": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ], "title": "Customer Name", "description": "Volitelné jméno zákazníka zobrazené obsluze klienta." }, "reservation_ttl_minutes": { "anyOf": [ { "type": "integer", "maximum": 10080.0, "minimum": 15.0 }, { "type": "null" } ], "title": "Reservation Ttl Minutes", "description": "Volitelné přepsání doby rezervace v minutách." }, "pickup_ttl_minutes": { "anyOf": [ { "type": "integer", "maximum": 43200.0, "minimum": 60.0 }, { "type": "null" } ], "title": "Pickup Ttl Minutes", "description": "Volitelné přepsání doby na vyzvednutí v minutách, počítané od naskladnění." } }, "additionalProperties": false, "type": "object", "required": [ "box_id", "external_order_id" ], "title": "PublicShipmentCreate", "examples": [ { "box_id": "box_a1b2c3d4", "customer_name": "Jan Novak", "external_order_id": "ORDER-2026-1042" } ] }, "PublicShipmentCreateResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Identifikátor zásilky v EasyPick." }, "external_order_id": { "type": "string", "title": "External Order Id", "description": "Číslo objednávky dodané e-shopem." }, "attempt_number": { "type": "integer", "title": "Attempt Number", "description": "Číslo pokusu o výdej dané externí objednávky, počítané od jedné." }, "retry_of_shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retry Of Shipment Id", "description": "Předchozí chybová zásilka nahrazená tímto pokusem." }, "box_id": { "type": "string", "title": "Box Id", "description": "Identifikátor přiřazeného boxu." }, "compartment_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compartment Code", "description": "Čitelný kód schránky, například A2." }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Name", "description": "Jméno zákazníka dodané při vytvoření." }, "status": { "$ref": "#/components/schemas/PublicShipmentStatus", "description": "Aktuální veřejný stav zásilky." }, "compartment_state": { "$ref": "#/components/schemas/PublicCompartmentState", "description": "Aktuální fyzický stav přidělení schránky." }, "pickup_enabled": { "type": "boolean", "title": "Pickup Enabled", "description": "Hodnota true pouze po skončení ochranné lhůty, kdy už může začít zákaznický výdej." }, "reservation_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Reservation Expires At", "description": "Konec rezervace v UTC." }, "loaded_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Loaded At", "description": "Čas prvního potvrzeného naskladnění v UTC." }, "pickup_available_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Pickup Available At", "description": "Nejdřívější čas zákaznického vyzvednutí v UTC." }, "pickup_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Pickup Expires At", "description": "Konec lhůty pro zákaznické vyzvednutí v UTC." }, "picked_up_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Picked Up At", "description": "Čas potvrzeného vyzvednutí v UTC." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Čas poslední změny zásilky v UTC." }, "pickup_pin": { "type": "string", "pattern": "^[0-9]{6}$", "title": "Pickup Pin", "description": "Šestimístný PIN pro naskladnění a zákaznický výdej." } }, "type": "object", "required": [ "id", "external_order_id", "attempt_number", "retry_of_shipment_id", "box_id", "compartment_code", "customer_name", "status", "compartment_state", "pickup_enabled", "reservation_expires_at", "loaded_at", "pickup_available_at", "pickup_expires_at", "picked_up_at", "updated_at", "pickup_pin" ], "title": "PublicShipmentCreateResponse" }, "PublicShipmentRead": { "properties": { "id": { "type": "string", "title": "Id", "description": "Identifikátor zásilky v EasyPick." }, "external_order_id": { "type": "string", "title": "External Order Id", "description": "Číslo objednávky dodané e-shopem." }, "attempt_number": { "type": "integer", "title": "Attempt Number", "description": "Číslo pokusu o výdej dané externí objednávky, počítané od jedné." }, "retry_of_shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retry Of Shipment Id", "description": "Předchozí chybová zásilka nahrazená tímto pokusem." }, "box_id": { "type": "string", "title": "Box Id", "description": "Identifikátor přiřazeného boxu." }, "compartment_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compartment Code", "description": "Čitelný kód schránky, například A2." }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Name", "description": "Jméno zákazníka dodané při vytvoření." }, "status": { "$ref": "#/components/schemas/PublicShipmentStatus", "description": "Aktuální veřejný stav zásilky." }, "compartment_state": { "$ref": "#/components/schemas/PublicCompartmentState", "description": "Aktuální fyzický stav přidělení schránky." }, "pickup_enabled": { "type": "boolean", "title": "Pickup Enabled", "description": "Hodnota true pouze po skončení ochranné lhůty, kdy už může začít zákaznický výdej." }, "reservation_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Reservation Expires At", "description": "Konec rezervace v UTC." }, "loaded_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Loaded At", "description": "Čas prvního potvrzeného naskladnění v UTC." }, "pickup_available_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Pickup Available At", "description": "Nejdřívější čas zákaznického vyzvednutí v UTC." }, "pickup_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Pickup Expires At", "description": "Konec lhůty pro zákaznické vyzvednutí v UTC." }, "picked_up_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Picked Up At", "description": "Čas potvrzeného vyzvednutí v UTC." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Čas poslední změny zásilky v UTC." } }, "type": "object", "required": [ "id", "external_order_id", "attempt_number", "retry_of_shipment_id", "box_id", "compartment_code", "customer_name", "status", "compartment_state", "pickup_enabled", "reservation_expires_at", "loaded_at", "pickup_available_at", "pickup_expires_at", "picked_up_at", "updated_at" ], "title": "PublicShipmentRead" }, "PublicShipmentStatus": { "enum": [ "reserved", "loaded", "picked_up", "cancelled", "expired", "fault" ], "title": "PublicShipmentStatus", "type": "string" }, "SandboxTransitionRequest": { "properties": { "event": { "type": "string", "enum": [ "loaded", "picked_up", "door_available", "expired", "fault", "removed" ], "title": "Event" } }, "type": "object", "required": [ "event" ], "title": "SandboxTransitionRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "PublicWebhookData": { "properties": { "shipment_id": { "title": "Shipment Id", "type": "string" }, "external_order_id": { "title": "External Order Id", "type": "string" }, "attempt_number": { "title": "Attempt Number", "type": "integer" }, "retry_of_shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retry Of Shipment Id" }, "box_id": { "title": "Box Id", "type": "string" }, "box_name": { "title": "Box Name", "type": "string" }, "compartment_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compartment Code" }, "status": { "$ref": "#/components/schemas/PublicShipmentStatus" }, "compartment_state": { "$ref": "#/components/schemas/PublicCompartmentState" }, "pickup_available_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Pickup Available At" }, "pickup_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Pickup Expires At" } }, "required": [ "shipment_id", "external_order_id", "attempt_number", "retry_of_shipment_id", "box_id", "box_name", "compartment_code", "status", "compartment_state", "pickup_available_at", "pickup_expires_at" ], "title": "PublicWebhookData", "type": "object" }, "PublicWebhookEvent": { "properties": { "api_version": { "const": "1", "default": "1", "title": "Api Version", "type": "string" }, "id": { "title": "Id", "type": "string" }, "type": { "enum": [ "reserved", "loaded", "picked_up", "expired", "cancelled", "fault", "removed", "door_available" ], "title": "Type", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "data": { "$ref": "#/components/schemas/PublicWebhookData" } }, "required": [ "id", "type", "occurred_at", "data" ], "title": "PublicWebhookEvent", "type": "object" } }, "securitySchemes": { "EasyPickApiKey": { "type": "http", "description": "API key issued in the EasyPick tenant administration.", "scheme": "bearer" } } }, "tags": [ { "name": "Boxes", "description": "Získání boxů dostupných přihlášenému e-shopu." }, { "name": "Shipments", "description": "Rezervace schránek a čtení nebo rušení zásilek." }, { "name": "Sandbox", "description": "Deterministická simulace životního cyklu dostupná pouze v sandboxu." } ], "webhooks": { "shipmentEvent": { "post": { "summary": "Webhook zásilky", "description": "Podepsaná notifikace o události zásilky doručovaná alespoň jednou.", "parameters": [ { "in": "header", "name": "EasyPick-Event-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "EasyPick-Timestamp", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "EasyPick-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookEvent" } } } }, "responses": { "200": { "description": "Webhook přijat" } } } } } }