# API endpoint and requests (/docs/basic-concepts/api-endpoint)

Every call to the Comecero API goes to one base URL, over HTTPS, with JSON in and JSON out. This page shows what a request looks like and what the API expects from it.

## Base URL [#base-url]

```text
https://api.comecero.com/api/v1
```

Add the resource path to it, for example `https://api.comecero.com/api/v1/products`. There is one base URL for test and live. The token you send decides which data you see (see [Authentication](/docs/basic-concepts/authentication)).

## HTTPS only [#https-only]

The API only answers over HTTPS. A call over plain `http://` is refused with `403` (code `tls_required`). The API does not redirect you to HTTPS, so fix the URL in your code.

```json
{
  "error": {
    "type": "forbidden",
    "code": "tls_required",
    "message": "The connection requires SSL/TLS. Try your request again using https:// as the protocol in the URL.",
    "reference": "Vx4OVmb",
    "status": 403,
    "meta": null
  }
}
```

## A request [#a-request]

Each request has a token in the `Authorization` header. A request with a body also sends `Content-Type: application/json`.

<Tabs items={['curl', 'Node.js']}>
<Tab value="curl">

```bash
curl https://api.comecero.com/api/v1/customers \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "John Doe", "email": "john@example.com" }'
```

</Tab>
<Tab value="Node.js">

```js
const response = await fetch('https://api.comecero.com/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COMECERO_TEST_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'John Doe', email: 'john@example.com' }),
});
const customer = await response.json();
```

</Tab>
</Tabs>

See [Create a customer](/api/customers/create-customer) for every field.

## Methods [#methods]

| Method | What it does |
| --- | --- |
| `GET` | Reads an object or a list. |
| `POST` | Creates an object, or updates one. Updates send only the fields you change (see [Partial updates](/docs/basic-concepts/partial-updates)). |
| `DELETE` | Deletes an object. |
| `PUT` | Used only to replace a role, see [Replace a role](/api/roles/update-role). |

## JSON in, JSON out [#json-in-json-out]

- Request bodies are JSON. Send `Content-Type: application/json`.
- The two upload endpoints are the only exception: [Create a file](/api/files/create-file) and [Create an image](/api/images/create-image) take `multipart/form-data`.
- Every response body is JSON, errors included (see [Errors](/docs/basic-concepts/error-handling)).
- A body that is not valid JSON is refused with `400` (code `invalid_syntax`).

## Objects and URLs [#objects-and-urls]

Every object in a response has an `object` field that names its type (`cart`, `order`, `payment`) and a `url` field with its full address in the API. Links to related objects are URLs too, which you can follow or [expand](/docs/basic-concepts/expanding-objects).

```json
{
  "object": "order",
  "url": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858",
  "order_id": "6622-NXKHE-858",
  "customer": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4"
}
```

A call that creates an object answers `201 Created` with the new object in the body.

## Next steps [#next-steps]

<Cards>
  <Card title="Authentication" href="/docs/basic-concepts/authentication" />
  <Card title="Errors" href="/docs/basic-concepts/error-handling" />
</Cards>
