Skip to content

authentic.network API documentation v2.4.0

Documentation for the REST api access of authentic.api

Item

Create Hook

Back to top

This endpoint adds a hook to an item.

POST /api/v2/items/:id/hooks

Headers - Header

Name Type Description
content-type String

Request content type
an-api-key-owner String

API producer key

Parameters - Parameter

Name Type Description
id String

The item id

Parameters examples

json - Request-Example:

{
  "events": "itemScanned",
  "url": "https://wh-echo.dev.authentic.network/webhook-endpoint",
  "data": {
    "key": "value"
  }
}

Success response example

Success response example - Success-Response:

{ "id": hookid, "data": { hook data }}

Error response

Error response - Errors

Name Type Description
400

Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Create Item

Back to top

Create a new item. Method is usually called when a hook is physically connected to a product. The fields _created, _updated and _producer are set automatically by the backend. These fields cannot be overwritten.

POST /api/v2/items

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters examples

json - Request-Example:

{
  "identifier": "0123456789",
  "image": "/images/identifiers/0123456789/11877002.jpg",
  "verificationinfos": [
    {
      "visible": "verified",
      "label": "Manufacturer",
      "value": "HelpPharma"
    }
  ],
  "title": "Test Item"
}

Success response example

Success response example - Success-Response:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "_producer": "authentic-test",
    "data": {
      "keyA": "a",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "_updated": 1595189641190,
    "_created": 1595189639871,
    "verificationinfos": [
      {
        "key": "a",
        "value": "ItemValue for A",
        "visible": "verified",
        "label": "A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "141bb8334543c2f1a4711832f5c5fd0c5272d7f0"
  }
}

Error response

Error response - Errors

Name Type Description
400

Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
409

Conflict - Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Delete Hook

Back to top

This endpoint delete an existing hook on an item.

DELETE /api/v2/items/:id/hooks/:idwebhook

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id
idwebhook String

The hook id

Success response example

Success response example - Response:

HTTP/1.1 200 OK

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Delete Item

Back to top

Deletes an item according to its id. Only the producer can delete an item.

DELETE /api/v2/items/:id

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id

Success response example

Success response example - Response:

HTTP/1.1 200 OK

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Get Hooks

Back to top

Get a list of configured hooks for a item

GET /api/v2/items/:id/hooks

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id

Success response example

Success response example - Success-Response:

{
  "id": "0001",
  "type": "item",
  "hooks": [
    {
      "id": "Fgs4kG0bORWyfiI71hkV",
      "data": {
        "_updated": 1592991983387,
        "url": "https://wh-echo.dev.authentic.network/webhook-endpoint",
        "_created": 1592991983387,
        "type": "httprequest",
        "events": "itemScanned",
        "executed": 0,
        "data": {
          "key": "value"
        }
      }
    }
  ]
}

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Get Item

Back to top

This endpoints returns the data for a given identifier. If the producer does not make the request, the following fields are removed from the response: _created, _updated, _scans, _fakes, _producer, image.

GET /api/v2/items/:id

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id
merged Boolean

If item in group, both entitys will merged by default. merged=false prevent this. Result contains item and group as own objects. Merge rules:

  1. Group values have higher priority than identifier values
  2. Identifier values are overwritten by identical group values
  3. Verificationinfos are merged. Overwriting takes place using the same key.
  4. Verificationinfos are finally sorted. Sorting is based on the pos specification, if not specified, pos is assumed to be 0.

Success response example

Success response example - Response unmerged+token:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "_group": "Hv2rqTnZbRoWvrW7SiWF",
    "_producer": "authentic-test",
    "data": {
      "keyA": "a",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "_updated": 1595189641190,
    "_created": 1595189639871,
    "_scans": 3,
    "_fakes": 1,
    "verificationinfos": [
      {
        "key": "a",
        "value": "ItemValue for A",
        "visible": "verified",
        "label": "A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "141bb8334543c2f1a4711832f5c5fd0c5272d7f0"
  },
  "group": {
    "id": "Hv2rqTnZbRoWvrW7SiWF",
    "data": {
      "_updated": 1595189629114,
      "_owner": "authentic-test",
      "title": "79d4f866e5e8cfb2f7356a755a33592fb3d527f8",
      "data": {
         "keyA": "A"
      },
      "_created": 1595189629114,
      "verificationinfos": [
        {
          "key": "a",
          "label": "A",
          "visible": "verified",
          "value": "GroupValue for A"
        }, {
          "visible": "verified",
           "value": "GroupValue for B",
           "label": "B"
        }, {
           "pos": -1,
           "label": "C",
           "visible": "verified",
           "value": "GroupValue for C"
        }
      ]
    }
  }
}

Success response example - Response merged+token:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "_group": "Hv2rqTnZbRoWvrW7SiWF",
    "_producer": "authentic-test",
    "data": {
      "keyA": "A",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "_updated": 1595189641190,
    "_created": 1595189639871,
    "_scans": 3,
    "_fakes": 1,
    "verificationinfos": [
      {
        "pos": -1,
        "label": "C",
        "visible": "verified",
        "value": "GroupValue for C"
      }, {
        "key": "a",
        "label": "A",
        "visible": "verified",
        "value": "GroupValue for A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "visible": "verified",
        "value": "GroupValue for B",
        "label": "B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "79d4f866e5e8cfb2f7356a755a33592fb3d527f8"
  }  
}

Success response example - Response merged:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "data": {
      "keyA": "A",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "verificationinfos": [
      {
        "pos": -1,
        "label": "C",
        "visible": "verified",
        "value": "GroupValue for C"
      }, {
        "key": "a",
        "label": "A",
        "visible": "verified",
        "value": "GroupValue for A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "visible": "verified",
        "value": "GroupValue for B",
        "label": "B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "79d4f866e5e8cfb2f7356a755a33592fb3d527f8"
  }  
}

Success response example - Success-Response:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "_producer": "authentic-test",
    "data": {
      "keyA": "a",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "_updated": 1595189641190,
    "_created": 1595189639871,
    "verificationinfos": [
      {
        "key": "a",
        "value": "ItemValue for A",
        "visible": "verified",
        "label": "A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "141bb8334543c2f1a4711832f5c5fd0c5272d7f0"
  }
}

Error response

Error response - Errors

Name Type Description
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Get Item History

Back to top

Important: Method not implemented yet! Get a list with manipulation and scan events for a given identifier.

GET /api/v2/items/:id/history

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Get Item History Entry

Back to top

Important: Method not implemented yet! Get identifier history item by id.

GET /api/v2/items/:itemid/history/:entryid

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
itemid String

The item id
entryid String

The history entry id

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Get List of Scans

Back to top

This endpoints returns a list of last scans in descand order

GET /api/v2/items/:id/scans

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id
timestamp Number

Only scans that are older than the specified time stamp. If not set, the result starts with the most recent.
limit Number

Number of expected entries

Success response example

Success response example - Success-Response:

{
  "identifier": {
    "id": "0001",
    "data": {
      "_producer": "authentic-test",
      "_scans": 2062,
      "image": "/images/identifiers/0001/drug.png",
      "_fakes": 1528,
      "title": "Paracetamol 600mg",
      "_updated": 1593081282544,
      "verificationinfos": [
        {
          "value": "HelpPharma",
          "visibility": "verified",
          "label": "Manufactor"
        }
      ],
      "_created": 1586439433831
    }
  },
  "scans": [
    {
      "id": "oYhV39z5SQCDJ5AqybAC",
      "data": {
        "os": "ios",
        "_owner": "authentic-test",
        "continent": "Africa",
        "location": {
          "_lat": 12.452351967343938,
          "_long": -7.986657239304272
        },
        "identifier": "0001",
        "timestamp": 1593081281892,
        "device": "sfdsfds32234546",
        "copyclassification": "original",
        "country": "ML",
        "creator": "unknown"
      }
    }
  ]
}

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Get Thumbnail

Back to top

This endpoints returns a thumbnail of an item if an image configured and available.

GET /api/v2/items/:id/thumbnail/:width

Parameters - Parameter

Name Type Description
id String

The item id
width Number

Width of thumbnail

Success response example

Success response example - Success-Response:

HTTP/2 200 
content-type: image/png
content-length: 202433

Error response

Error response - Errors

Name Type Description
400

Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Invalidate Item

Back to top

Invalidate an existing item. The fields _created, _updated and _producer are set automatically by the backend. These fields cannot be overwritten. Invalidate is a final state, after them no more modifications are possible.

POST /api/v2/items/:id/invalidate

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id

Parameters examples

json - Request-Example:

{
}

Success response example

Success response example - Success-Response:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "_producer": "authentic-test",
    "data": {
      "keyA": "a",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "_updated": 1595189641190,
    "_created": 1595189639871,
    "verificationinfos": [
      {
        "key": "a",
        "value": "ItemValue for A",
        "visible": "verified",
        "label": "A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "141bb8334543c2f1a4711832f5c5fd0c5272d7f0"
  }
}

Error response

Error response - Errors

Name Type Description
400

Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Update Item

Back to top

Update an existing item. The fields _created, _updated and producer are set automatically by the backend. These fields cannot be overwritten.

POST /api/v2/items/:id

Headers - Header

Name Type Description
content-type String

Request content type, musst set to application/json
an-api-token String

API token

Parameters - Parameter

Name Type Description
id String

The item id

Parameters examples

json - Request-Example:

{
  "image": "/images/identifiers/0123456789/11877002.jpg",
  "verificationinfos": [
    {
      "visible": "verified",
      "label": "Manufacturer",
      "value": "HelpPharma"
    }
  ],
  "title": "Test Item"
}

Success response example

Success response example - Success-Response:

{
  "id": "9f3646e190f97a4dbe1854e056d178113e641c7e",
  "data": {
    "_producer": "authentic-test",
    "data": {
      "keyA": "a",
      "keyB": "b"
    },
    "identifier": "9f3646e190f97a4dbe1854e056d178113e641c7e",
    "_updated": 1595189641190,
    "_created": 1595189639871,
    "verificationinfos": [
      {
        "key": "a",
        "value": "ItemValue for A",
        "visible": "verified",
        "label": "A"
      }, {
        "visible": "verified",
        "label": "B",
        "value": "ItemValue for B"
      }, {
        "label": "C",
        "visible": "verified",
        "value": "ItemValue for C",
        "pos": 5
      }
    ],
    "title": "141bb8334543c2f1a4711832f5c5fd0c5272d7f0"
  }
}

Error response

Error response - Errors

Name Type Description
403

Forbidden - The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication via the an-api-token header field, but the server did not accept that authentication. The request should not be repeated.
404

NotFound - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500

Internal server error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.