Ordering System Reference

This section will give a further explantation on Tychron's ordering APIs and provides examples of how to request numbers for messaging and other features.

Ordering Overview

The client is expected to make several HTTP requests to the system in order to request provisioning numbers for messaging or to setup TCR campaigns on existing numbers.

A general overview of the workflow would be the following:

POST /api/v1/carts once
POST /api/v1/carts/:cart_id/requests one or more times
POST /api/v1/carts/:cart_id/checkout once per cart

The ordering system is based around the concept of carts.

A cart is an order before checkout, within that cart are various requests that can be made (e.g. enable this number for CNAM, enable this number for messaging, remove this number, etc...), an order can contain multiple requests, and some requests allow multiple numbers within them to perform batch processing.

WARNING A request with multiple numbers is treated as a single unit for processing, each stage in the processing of a request will wait for the completion of all numbers, if a number in the batch experiences any difficulties (e.g. upstream conflicts with registry) it may stall the entire enablement until it is resolved, therefore it is recommended for critical numbers a request with only that number is issued, for non-critical numbers batching is recommended.

When in doubt, use a single number per request.

Requests are processed asynchronously, therefore checkout will return immediately with the order id (which will be the same as the cart, as it is the same record just being transitioned to a new state).

Carts

At the very start of a new request process a new cart must be created (or if one was created before, it can be used instead).

Type

The type string for carts is cart

Data Structures

RequestData

{
  "name": "A unique name",
  "notes": "Optional notes"
}

Name	Type	Description
`name` *	`String`	A unique name for the cart
`notes`	`String`	Optional notes about the cart

For creating or updating an existing cart, only the name and notes can be supplied.

ResponseData

{
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-04T10:00:00.000000Z",
  "name": "An unique order name",
  "notes": "Optional notes, describing what this order is for",
  "updated_at": "2021-08-04T10:00:00.000000Z"
}

Name	Type	Description
`id` *	`ULID`	A unique identfier for the cart
`inserted_at` *	`Datetime`	An ISO8601 formatted timestamp, representing when the cart was created
`updated_at` *	`Datetime`	An ISO8601 formatted timestamp, representing when the cart was last updated
`name` *	`String`	A unique name for the cart
`notes`	`String`	Optional notes about the cart

Creating A New Cart

POST /api/v1/carts HTTP/1.1

Create a new cart

Request application/json

POST /api/v1/carts HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 81

{
  "data": {
    "name": "string",
    "notes": "string"
  },
  "type": "cart"
}

Response 201

application/json

HTTP/1.1 201
Content-Type: application/json
Content-Length: 226

{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 422

application/json

HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Updating An Existing Cart

PATCH /api/v1/carts/{id} HTTP/1.1

Update an existing account

Path Parameters

Name	Type	Description
id	String(format:ulid)!	Cart ID

Request application/json

PATCH /api/v1/carts/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 81

{
  "data": {
    "name": "string",
    "notes": "string"
  },
  "type": "cart"
}

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 226

{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json

HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

application/json

HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Deleting An Existing Cart

DELETE /api/v1/carts/{id} HTTP/1.1

Delete an existing cart, if the cart contains any requests this action will fail, if the purge flag is provided the cart will be deleted along with all of its requests.

The default action is to prevent accidental deletions with requests present.

Path Parameters

Name	Type	Description
id	String(format:ulid)!	Cart ID

Query Parameters

Name	Type	Description
purge	Boolean	Query Desc. purge

Query Desc. purge

Typically a Cart cannot be removed if it has any requests still associated with it.

With the purge option, the cart and its associated requests can all be removed at once.

Request

DELETE /api/v1/carts/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 226

{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json

HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

application/json

HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Checkout Cart

POST /api/v1/carts/{cart_id}/checkout HTTP/1.1

Finalize a given cart and process it as an order, the cart and its requests can no longer be modified after this.

Path Parameters

Name	Type	Description
cart_id	String(format:ulid)!	Cart ID

Request

POST /api/v1/carts/{cart_id}/checkout HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 303

{
  "data": {
    "error_code": "OK",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "Add Messaging to 10 Numbers",
    "notes": "Order for Client XYZ\n",
    "status": "NEW",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "order"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json

HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

application/json

HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

List Existing Carts

GET /api/v1/carts HTTP/1.1

Retrieve a list of carts

Query Parameters

Name	Type	Description
first	Integer	Query Desc. first
last	Integer	Query Desc. last
after	String	Query Desc. after
before	String	Query Desc. before

Query Desc. first

The number of items to return starting from the 'after' cursor

Query Desc. last

The number of items to return behind the 'before' cursor

Query Desc. after

The cursor representing the starting point of a 'first' based paging

Query Desc. before

The cursor representing the starting point of a 'last' based paging

Request

GET /api/v1/carts HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 427

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "My New Order",
        "notes": "string",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "cart"
    }
  ]
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Get Cart

GET /api/v1/carts/{id} HTTP/1.1

Lookup cart by id

Path Parameters

Name	Type	Description
id	String(format:ulid)!	Cart ID

Request

GET /api/v1/carts/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 226

{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json

HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}