# Intrasistema REST API - Extended LLM Technical Reference

> Full machine-readable reference specification of the Intrasistema Omnichannel eCommerce & WMS REST API for AI Agents, autonomous developer tools, and API clients.

- **Title**: Intrasistema REST API v1
- **Specification**: OpenAPI 3.0.0b
- **Base Host**: `https://api.intrasistema.com`
- **Documentation**: `https://api.intrasistema.com/doc`
- **OpenAPI JSON**: `https://api.intrasistema.com/v1/swagger.json`
- **Authentication**: Header `X-API-KEY: <string>`
- **Content-Type**: `application/json`

---

## 1. Authentication & Security Model
All requests require the `X-API-KEY` HTTP header.
- The API key is scoped per tenant / business entity.
- If the header is missing, invalid, or belongs to an unauthorized business, the API returns:
```json
{
  "error": 1,
  "code": 401,
  "message": "Invalid or missing API key."
}
```

---

## 2. Global Conventions
- All timestamps are formatted in ISO 8601 / RFC 3339 (`YYYY-MM-DDTHH:MM:SSZ`).
- Numeric monetary amounts use standard decimal floating numbers or strings formatted with two decimal digits.
- Geographic coordinates utilize standard decimal latitude and longitude (WGS 84).

---

## 3. Key Endpoint Groups

### Automation & Pricing Rules (`/v1/automation`)
Manages programmatic pricing rules, channel margin calculators, and automated rules.
- `GET /v1/automation/{business_id}/items/pricing/rules/list`: Lists all pricing automation rules.
- `POST /v1/automation/{business_id}/items/pricing/rules/create`: Creates a new pricing rule.
  - Body params: `name` (string), `type` (percentage|fixed), `value` (number), `channels` (array), `conditions` (object).
- `PUT /v1/automation/{business_id}/items/pricing/rules/{rule_id}/edit`: Updates an existing rule.
- `DELETE /v1/automation/{business_id}/items/pricing/rules/{rule_id}/delete`: Deletes a rule.

### Orders & Sales (`/v1/orders`)
Central order management for omnichannel sales channels.
- `GET /v1/orders/{business_id}/list`: Search and retrieve orders by status, date range, channel, or customer.
- `GET /v1/orders/{business_id}/{order_id}`: Retrieve detailed order payload, line items, buyer info, shipping address, payments.
- `POST /v1/orders/{business_id}/create`: Ingest an external order directly into the fulfillment pipeline.
- `PUT /v1/orders/{business_id}/{order_id}/status`: Transition order status (pending, confirmed, picking, packed, dispatched, delivered, cancelled).

### Inventory & Items (`/v1/inventory`, `/v1/items`)
Stock levels, reservations, locations, and catalog master items.
- `GET /v1/inventory/{business_id}/items/list`: Current physical and available-to-promise (ATP) stock per warehouse.
- `POST /v1/inventory/{business_id}/adjust`: Manual or cycle-count stock adjustments with audit reason codes.
- `GET /v1/items/{business_id}/list`: Retrieve catalog items, barcodes, SKUs, brand, category, dimensions, weight.
- `POST /v1/items/{business_id}/create`: Register a new SKU in the system.
- `PUT /v1/items/{business_id}/{item_id}/edit`: Update SKU attributes, prices, and publication links.

### Shipments, Carriers & Logistics (`/v1/shipments`, `/v1/tracking`)
Carrier integration, package metrics, dispatch runs, and real-time tracking.
- `GET /v1/shipments/{business_id}/list`: List outgoing shipments by status, carrier, dispatch date.
- `POST /v1/shipments/{business_id}/generate-label`: Request carrier shipping label (PDF/ZPL).
- `GET /v1/tracking/{tracking_number}`: Public tracking endpoint returning chronological shipment milestones and estimated delivery date.

### Warehouse Management (WMS) (`/v1/inbounds`, `/v1/outbounds`, `/v1/picking`, `/v1/packing`)
Core warehouse workflows for logistics centers and fulfillment hubs.
- `GET /v1/inbounds/{business_id}/orders/list`: Purchase orders awaiting receipt.
- `POST /v1/inbounds/{business_id}/reception`: Scan-based blind receiving and quality inspection.
- `GET /v1/picking/{business_id}/waves/list`: Active picking waves and pick-lists.
- `POST /v1/picking/{business_id}/item/scan`: Validate barcode scan during picking round.
- `POST /v1/packing/{business_id}/pack-order`: Validate line items at packing station and produce packing slip.
- `GET /v1/outbounds/{business_id}/dispatch-runs`: Manifest dispatch runs grouped by carrier.

### Thermal Printers & Hardware (`/v1/printers`)
Direct printing to networked thermal label and document printers.
- `GET /v1/printers/{business_id}/list`: List registered thermal printers and their online status.
- `POST /v1/printers/jobs/{business_id}/{printer_id}`: Dispatch a raw ZPL or PDF print job to a designated warehouse workstation.

### Documents & Fiscal Compliance (`/v1/documents`)
Fiscal electronic invoices, delivery notes (remitos), and ONVIF verification attachments.
- `GET /v1/documents/{business_id}/categories`: Document categories and tax types.
- `GET /v1/documents/{business_id}/{entity_type}/{entity_id}/list`: Retrieve documents associated with an order, shipment, or purchase.
- `POST /v1/documents/{business_id}/{entity_type}/{entity_id}`: Upload and attach signed fiscal documents or delivery proof.

---

## 4. Error Handling Contract
When an operation cannot be completed, the HTTP status code indicates the category (400 Client Error, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 500 Server Error).
The JSON response always includes:
- `error` (integer): 1 indicates an error.
- `message` (string): Error description.
- `code` (integer, optional): Detailed business error code.
- `errors` (array, optional): Granular field validation violations when applicable.