Add examples for feed task management and inventory publishing workflows
This commit is contained in:
parent
2c6bd35ebb
commit
904f4e487e
3 changed files with 363 additions and 6 deletions
|
|
@ -115,6 +115,20 @@ Use the generated model packages for request and response types:
|
|||
|
||||
This section maps typical seller workflows to wrapper methods.
|
||||
|
||||
Quick source jumps:
|
||||
|
||||
- facade: [ebay_client/client.py](../ebay_client/client.py)
|
||||
- notification wrapper: [ebay_client/notification/client.py](../ebay_client/notification/client.py)
|
||||
- inventory wrapper: [ebay_client/inventory/client.py](../ebay_client/inventory/client.py)
|
||||
- fulfillment wrapper: [ebay_client/fulfillment/client.py](../ebay_client/fulfillment/client.py)
|
||||
- account wrapper: [ebay_client/account/client.py](../ebay_client/account/client.py)
|
||||
- feed wrapper: [ebay_client/feed/client.py](../ebay_client/feed/client.py)
|
||||
- media wrapper: [ebay_client/media/client.py](../ebay_client/media/client.py)
|
||||
- FastAPI webhook example: [examples/fastapi_notification_webhook.py](../examples/fastapi_notification_webhook.py)
|
||||
- media workflows example: [examples/media_workflows.py](../examples/media_workflows.py)
|
||||
- inventory publish example: [examples/inventory_publish_flow.py](../examples/inventory_publish_flow.py)
|
||||
- feed task example: [examples/feed_task_flow.py](../examples/feed_task_flow.py)
|
||||
|
||||
### Notification: manage webhook subscriptions
|
||||
|
||||
Typical flow:
|
||||
|
|
@ -143,7 +157,7 @@ Recommended server flow:
|
|||
3. verify the POST body with `WebhookSignatureValidator`
|
||||
4. dispatch the parsed `WebhookEventEnvelope`
|
||||
|
||||
Reference implementation: `examples/fastapi_notification_webhook.py`.
|
||||
Reference implementation: [examples/fastapi_notification_webhook.py](../examples/fastapi_notification_webhook.py).
|
||||
|
||||
### Inventory: read listings and inventory records
|
||||
|
||||
|
|
@ -305,9 +319,157 @@ Helpers:
|
|||
- `VideoWorkflowResult`
|
||||
- `DocumentWorkflowResult`
|
||||
|
||||
Reference implementation: `examples/media_workflows.py`.
|
||||
Reference implementation: [examples/media_workflows.py](../examples/media_workflows.py).
|
||||
|
||||
## 5. Working With Generated Models
|
||||
## 5. End-to-End Recipes
|
||||
|
||||
These are the shortest practical paths through the client for the most common seller tasks.
|
||||
|
||||
### Recipe: read existing listed inventory data
|
||||
|
||||
Use this when you mainly want to inspect what is already listed or staged in eBay.
|
||||
|
||||
```python
|
||||
from ebay_client import EbayClient
|
||||
from ebay_client.core.auth.models import EbayOAuthConfig
|
||||
|
||||
client = EbayClient(
|
||||
EbayOAuthConfig(
|
||||
client_id="your-client-id",
|
||||
client_secret="your-client-secret",
|
||||
default_scopes=["https://api.ebay.com/oauth/api_scope/sell.inventory.readonly"],
|
||||
)
|
||||
)
|
||||
|
||||
items = client.inventory.get_inventory_items(limit=50)
|
||||
offers = client.inventory.get_offers(limit=50)
|
||||
```
|
||||
|
||||
Methods involved:
|
||||
|
||||
- `get_inventory_items()`
|
||||
- `get_offers()`
|
||||
- optionally `get_inventory_item()` and `get_offer()` for detail reads
|
||||
|
||||
### Recipe: create an inventory item, create an offer, and publish it
|
||||
|
||||
Use this when you want the standard listing flow through the Inventory API.
|
||||
|
||||
```python
|
||||
from ebay_client import EbayClient
|
||||
from ebay_client.core.auth.models import EbayOAuthConfig
|
||||
from ebay_client.generated.inventory.models import InventoryItem, OfferDetailsWithKeys
|
||||
|
||||
client = EbayClient(
|
||||
EbayOAuthConfig(
|
||||
client_id="your-client-id",
|
||||
client_secret="your-client-secret",
|
||||
default_scopes=["https://api.ebay.com/oauth/api_scope/sell.inventory"],
|
||||
)
|
||||
)
|
||||
|
||||
client.inventory.create_or_replace_inventory_item(
|
||||
"SKU-123",
|
||||
InventoryItem(),
|
||||
content_language="en-US",
|
||||
)
|
||||
|
||||
offer = client.inventory.create_offer(OfferDetailsWithKeys())
|
||||
client.inventory.publish_offer(offer.offerId)
|
||||
```
|
||||
|
||||
Operational notes:
|
||||
|
||||
- you typically need business policy IDs and location data in place before the offer is valid
|
||||
- the wrapper requires `content_language` for the item write call because eBay expects it on several write endpoints
|
||||
- the exact request model fields depend on your marketplace and listing format
|
||||
|
||||
### Recipe: receive Notification webhook events in FastAPI
|
||||
|
||||
Use the built-in webhook helpers instead of hand-parsing the signature format.
|
||||
|
||||
Flow:
|
||||
|
||||
1. create a normal `EbayClient`
|
||||
2. build `WebhookPublicKeyResolver` from `client.notification.get_public_key`
|
||||
3. build `WebhookSignatureValidator`
|
||||
4. use `WebhookRequestHandler` for both GET challenge and POST notification handling
|
||||
|
||||
Working example: [examples/fastapi_notification_webhook.py](../examples/fastapi_notification_webhook.py).
|
||||
|
||||
### Recipe: upload a document or video asset for listings
|
||||
|
||||
Use the Media wrapper helpers when you want the client to handle the create, upload, and polling loop for you.
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
from ebay_client import EbayClient
|
||||
from ebay_client.core.auth.models import EbayOAuthConfig
|
||||
from ebay_client.generated.media.models import CreateDocumentRequest
|
||||
|
||||
client = EbayClient(
|
||||
EbayOAuthConfig(
|
||||
client_id="your-client-id",
|
||||
client_secret="your-client-secret",
|
||||
default_scopes=["https://api.ebay.com/oauth/api_scope/sell.inventory"],
|
||||
)
|
||||
)
|
||||
|
||||
result = client.media.create_upload_and_wait_document_from_path(
|
||||
CreateDocumentRequest(
|
||||
documentType="USER_GUIDE_OR_MANUAL",
|
||||
languages=["en-US"],
|
||||
),
|
||||
Path("./manual.pdf"),
|
||||
timeout_seconds=60.0,
|
||||
)
|
||||
|
||||
print(result.document_id)
|
||||
print(result.document.documentStatus)
|
||||
```
|
||||
|
||||
Working example: [examples/media_workflows.py](../examples/media_workflows.py).
|
||||
|
||||
### Recipe: create a Feed task, upload its file, and download the result
|
||||
|
||||
Use this when the operation is file-based and asynchronous.
|
||||
|
||||
Flow:
|
||||
|
||||
1. create the task with `create_task()`
|
||||
2. extract the returned `resource_id`
|
||||
3. upload the task input file with `upload_file()`
|
||||
4. poll `get_task()` until the task reaches the state you expect
|
||||
5. download the result with `get_result_file()`
|
||||
|
||||
This wrapper already provides typed helpers for the file downloads through `FeedFileDownload`.
|
||||
|
||||
Working example: [examples/feed_task_flow.py](../examples/feed_task_flow.py).
|
||||
|
||||
### Recipe: dispute handling and evidence upload
|
||||
|
||||
Use the Fulfillment dispute methods only when you have the dispute-specific scope.
|
||||
|
||||
Flow:
|
||||
|
||||
1. read the dispute with `get_payment_dispute()`
|
||||
2. upload the binary evidence file with `upload_evidence_file()`
|
||||
3. attach or update the evidence metadata with `add_evidence()` or `update_evidence()`
|
||||
4. contest or accept with `contest_payment_dispute()` or `accept_payment_dispute()`
|
||||
|
||||
Caveat: these calls go through the alternate `apiz.ebay.com` fulfillment base URL inside the wrapper.
|
||||
|
||||
### Recipe: use the included examples directly
|
||||
|
||||
The repository now includes these runnable example scripts:
|
||||
|
||||
- [examples/inventory_publish_flow.py](../examples/inventory_publish_flow.py): create or replace an inventory item, create an offer, and publish it
|
||||
- [examples/feed_task_flow.py](../examples/feed_task_flow.py): create a feed task, upload an input file, poll its status, and optionally save the result file
|
||||
- [examples/media_workflows.py](../examples/media_workflows.py): image, document, and video asset workflows
|
||||
- [examples/fastapi_notification_webhook.py](../examples/fastapi_notification_webhook.py): FastAPI-based challenge and notification handling
|
||||
|
||||
## 6. Working With Generated Models
|
||||
|
||||
The wrappers are intentionally thin. Request payloads and response types come from the generated Pydantic model packages.
|
||||
|
||||
|
|
@ -337,14 +499,14 @@ result = client.media.create_upload_and_wait_document_from_path(
|
|||
|
||||
For any wrapper method that takes a payload, look up the corresponding generated request model in the matching `ebay_client.generated.<api>.models` package.
|
||||
|
||||
## 6. Operational Notes
|
||||
## 7. Operational Notes
|
||||
|
||||
- The default token store is process-local and in-memory only.
|
||||
- Empty `202` and `204` responses are normalized by the shared transport so wrapper methods can return `None` cleanly for no-body success cases.
|
||||
- Multipart uploads are already handled by the transport and wrappers for Media, Feed, and dispute evidence uploads.
|
||||
- Absolute URL handling is already built into the transport so wrappers can call alternate eBay hosts when required.
|
||||
|
||||
## 7. Validation and Regeneration
|
||||
## 8. Validation and Regeneration
|
||||
|
||||
Run tests:
|
||||
|
||||
|
|
@ -364,4 +526,4 @@ Generate just one API package:
|
|||
& .\.venv\Scripts\python.exe .\scripts\generate_clients.py --api media
|
||||
```
|
||||
|
||||
The generated models are written to `ebay_client/generated/<api>/models.py`.
|
||||
The generated models are written to `ebay_client/generated/<api>/models.py`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue