comecerodocs
Concepts

API endpoint and requests

The base URL of the Comecero API, why every call must use HTTPS, and the headers and JSON body format that every request and response uses.

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

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).

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.

{
  "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

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

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" }'

See Create a customer for every field.

Methods

MethodWhat it does
GETReads an object or a list.
POSTCreates an object, or updates one. Updates send only the fields you change (see Partial updates).
DELETEDeletes an object.
PUTUsed only to replace a role, see Replace a role.

JSON in, JSON out

  • Request bodies are JSON. Send Content-Type: application/json.
  • The two upload endpoints are the only exception: Create a file and Create an image take multipart/form-data.
  • Every response body is JSON, errors included (see Errors).
  • A body that is not valid JSON is refused with 400 (code invalid_syntax).

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.

{
  "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

On this page