Documents API

The IBM Blockchain Transparent Supply Documents API allows authorized users to upload, view, and share your organization's supply chain documents, such as facility certificates and audit reports.

Prerequisites

To use the IBM Blockchain Transparent Supply Documents API, you must meet the following prerequisites:

  1. Your organization is subscribed to Documents.
  2. Your data integration experts are familiar with using REST APIs to send data programmatically. Automation of data upload is an ultimate goal to facilitate data sharing.
  3. For IBM Blockchain Transparent Supply organizations to share supply chain data, each organization must have defined the appropriate level of data access control. For details on restricting and sharing your data, see Data entitlement mode and Data access control.

Getting started

Take the following steps to get started with the IBM Blockchain Transparent Supply Documents API:

  1. Obtain an authentication token, as described in Authentication.
  2. Submit a Documents API request by including the authentication token in the authorization header, as shown in the example request. For manual testing, human users can use Swagger to call the API endpoints.
  3. For help with understanding the API response model, refer to the documentation in the following sections.

Swagger

To use the Documents API manually, use the Swagger interface for the following environments:

You must first provide a valid IBM Blockchain Transparent Supply authorization token (human user token) on Swagger, by using the Authorize button in the upper right section of the page.

Endpoints

All Documents API endpoints are documented in Documents API. With the required authorization, users can create, share, search, download, and view documents.

For example, to create a new document, an authorized user calls the following endpoints:

  • GET /templates/{documentType} - Retrieves a document type template for rendering and validating a document.
  • POST /documents - Creates and uploads a new document, with access permissions.

Request body

Use the following attributes to create and upload a new document (POST /documents endpoint):

  • properties - Information about the document (uploaded in JSON).
  • content - A content file in PDF, PNG, JPEG, or GIF format.
  • entitlement - Document access permissions. See Data entitlement mode and Data access control for details.

Parameters

The following parameters are used when calling applicable endpoints:

  • id - The system-generated document ID.
  • version - The document version. Versions of the same document have an equivalent id.

Example Query

See Documents API for example requests and responses for each endpoint.