# Upscrape TalabatMart LLM Integration Prompt

Give this to an LLM or coding agent. It must fetch the OpenAPI spec first and use this brief only for orientation.

## First Step

Fetch and read this OpenAPI spec before writing code:

https://data.upscrape.com/catalog/platforms/talabatmart/openapi.json?token=SFMyNTY.g2gDdAAAAAFtAAAAC3BsYXRmb3JtX2lkbQAAAAt0YWxhYmF0bWFydG4GAMSO3UqfAWIAAVGA.fg2jyjT0V7KVlEfbDViEkF-hxiiT6Pgi6XVwxiXEBe0
This signed OpenAPI URL is valid for approximately 7 days.

## Hard Rules

- Use the OpenAPI spec as the source of truth for endpoints, request bodies, response bodies, errors, and JSON schemas.
- Do not infer fields from capability descriptions; fetch the spec and use its component schemas.
- Authenticate every request with `Authorization: Bearer YOUR_API_KEY`.
- Start runs with `POST /execute`; do not invent platform-specific execute endpoints.
- Poll `GET /jobs/{id}` or `GET /jobs/{id}/result` until `state` is `completed` or `failed`.
- Optionally send `Prefer: wait=N` on `POST /execute` to wait up to N seconds for inline results.
- If the response is `200`, the job completed — read `results[0].data`. If `202`, poll `GET /jobs/{id}`.
- `stream` is public-facing but must remain `false` today.

## API Base

- Base URL: `https://data.upscrape.com`
- OpenAPI spec: `https://data.upscrape.com/catalog/platforms/talabatmart/openapi.json?token=SFMyNTY.g2gDdAAAAAFtAAAAC3BsYXRmb3JtX2lkbQAAAAt0YWxhYmF0bWFydG4GAMSO3UqfAWIAAVGA.fg2jyjT0V7KVlEfbDViEkF-hxiiT6Pgi6XVwxiXEBe0`
- Execute endpoint: `POST /execute`
- Job poll endpoint: `GET /jobs/{id}`
- Result alias: `GET /jobs/{id}/result`
- Content-Type: `application/json`
- Optional header: `Idempotency-Key`
- Optional header: `Prefer: wait=N` (hold connection up to N seconds for synchronous result)

## Execution Flow

1. Send `POST /execute` with a platform capability ID and its `input` object.
2. The API responds with a queued `job_id`.
3. Poll the job endpoint until `state` becomes `completed` or `failed`.
4. If completed, read `results[0].data`; its exact shape is defined by the OpenAPI component schema for the selected capability.

## Normalized Products

For these capabilities the completed response also carries a top-level `normalized` object alongside `results` — use it as the cross-platform product feed instead of parsing `results[0].data` per platform:

- `talabatmart.products.list`

- `normalized.products[]`: one canonical record per sellable unit (`product_id`, `name`, `brand`, `price`/`price_minor` in halalas, `original_price_minor`, `on_promo`, `discount_pct`, `in_stock`, `stock_quantity`, `size_value`/`size_unit`, `image_url`, `barcode`, `store_id`, `category_id`, `subcategory_id`/`subcategory_name` where the platform splits a category into shelves). See the `NormalizedProduct` component schema.
- `normalized.schema_version`: integer; pin to it and treat new fields as additive.
- `normalized.dropped`: count of raw records skipped because identity or name was missing.
- `normalized` is additive and best-effort: if it is absent or `dropped` is high, fall back to `results[0].data` (always the source of truth).

## Example Execute Request

```json
{
  "capability": "talabatmart.categories.list",
  "input": {
    "area_id": 4001,
    "lat": 25.2938803,
    "lng": 55.4288672,
    "page": 0,
    "vendor_id": "650917"
  }
}
```

## Optional Request Fields

- `network.session_id`: explicit reusable session identifier
- `network.session_key`: stable key used to derive a reusable session
- `network.sticky`: reuse the resolved session when `true`
- `timeout_ms`: per-capability timeout override up to the capability maximum listed below
- `stream`: must be `false`

## Supported Capabilities

- `talabatmart.categories.list` - Categories List. List TalabatMart categories for a vendor. Max `timeout_ms`: 30000. Streaming: disabled.
- `talabatmart.globalid.get` - Global ID Get. Resolve the TalabatMart global identifier for a vendor. Max `timeout_ms`: 30000. Streaming: disabled.
- `talabatmart.products.list` - Products List. List TalabatMart products for a category and global identifier. Max `timeout_ms`: 30000. Streaming: disabled.
- `talabatmart.userlocation.get` - User Location Get. Resolve the TalabatMart area and city identifiers for a user location. Max `timeout_ms`: 30000. Streaming: disabled.
- `talabatmart.vendor.get` - Vendor Get. Resolve the TalabatMart vendor for an area and city. Max `timeout_ms`: 30000. Streaming: disabled.