# Bob Shop Tools API

The Bob Shop Tools API lets your own system manage your Bob Shop listings
through an API source on Bob Sync.

A **product** in this API becomes a **listing** on Bob Shop. A product can have
several **variants**, for example sizes or colours of the same shirt.

What you can do with it:

- **Send products to us**, one at a time or in bulk from a JSON file.
- **Remove listings** by deleting a product.
- **Receive orders.** We send each paid order to a webhook URL you give us.

Products are pushed by you to us. We never call your system to fetch them. The
only request we make to you is the order webhook.

## How to read these docs

| Section | What it covers |
| --- | --- |
| **[Authentication](../2_Authentication/README.md)** | Getting your token, sending it, and keeping it safe. |
| **[Workflow](../3_Workflow/README.md)** | The integration in order. Start here. |
| **[What makes a product go live](../4_What%20makes%20a%20product%20go%20live/README.md)** | Why a `200` is not a listing, and the category rule that catches most integrations out. Read it before you write code. |
| **[Important concepts](../5_Important%20concepts/README.md)** | How products are identified, and the product, image, variant and option objects. |
| **[Products](../6_Products/README.md)** | One product at a time: create, update, fetch, delete. |
| **[Bulk upload](../7_Bulk%20upload/README.md)** | Many products in one JSON file. |
| **[Webhooks](../8_Webhooks/README.md)** | How a paid order reaches you, and what we expect back. |

## Base URLs

| Environment | Base URL |
| --- | --- |
| Sandbox | `https://api.tools.qa.bobshop.co.za/api/bobsync` |
| Production | `https://api.tools.bobshop.co.za/api/bobsync` |

Sandbox is our QA environment. The two are separate systems with separate
tokens: a token for one does not work on the other. Going live means changing
the base URL and the token.

## Getting set up

An administrator installs an API source on Bob Sync for you, which generates
your token. Contact [support](https://help.bobshop.co.za/) to get set up, then
follow the [Workflow](../3_Workflow/README.md) section.

## Conventions

- Requests and responses are JSON. Send `Content-Type: application/json` with
  a body.
- Field names are `snake_case`. Prices are numbers in rands, for example
  `199.99`. Weights are kilograms.
- A delete returns `204 No Content` with an empty body.
- A failed request returns a plain-text message, not JSON, with the reason in
  the body and the meaning in the status code. For example `400` with
  `Invalid id.`
- A field you leave out takes its type's default: `0`, `""`, `false` or `null`.

## Support

Contact [help.bobshop.co.za](https://help.bobshop.co.za/) or email
[techsupport@bobshop.co.za](mailto:techsupport@bobshop.co.za). When reporting a
problem with a request, quote the `X-Request-ID` response header. For a
webhook, quote either ID header from the request we sent you.