7.7. Creating a new package

The following process explains how a new BL package is created on the platform. Before the package is created, the user must be authenticated against the platform using OAuth.

All the examples below expect the Authorization: Bearer header, as explain elsewhere in this document.

POST /document-upload/

Call this method first. Use it to upload the file attachment and start preparing the batch. Call multiple times if you need to upload multiple files. Record the JSON object of each returned document.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
   -F file_field=@test.pdf \
   -F force_pdf=true \
   -F bl_type=1 \
   https://sandbox.smartbl.io/api/v1/document-upload/

Response:

[
   {
      "name":"test.pdf",
      "uuid":"04b59579-9618-46e5-8381-056eb5e9ae62",
      "type":"application/pdf",
      "bl_type": 1
   }
]

POST /document-upload/change-bl-type/

This method allows you to change the type of the file attachment, if needed. Works only on files in packages not already sealed.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -F uuid=04b59579-9618-46e5-8381-056eb5e9ae62 \
   -F bl_type=1 \
   https://sandbox.smartbl.io/api/v1/document-upload/change-bl-type/

And the response:

[
   {
      "type":"application/pdf",
      "uuid":"04b59579-9618-46e5-8381-056eb5e9ae62",
      "name":"test.pdf",
      "bl_type":1
   }
]

POST /smart-bl-drafts/

Use this method to actually create a new package – a draft of the document and include all the uploaded files in the later phase.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -F 'bl_number=BL-123' \
   -F 'documents_upload=[{"uuid": "04b59579-9618-46e5-8381-056eb5e9ae62", "name": "test.pdf", "type": "application/pdf", "bl_type": 1}]' \
   -F 'shipper=10' \
   -F 'delivery_agent=11' \
   -F 'document_template_id=3' \
   -F '[email protected]' \
   -F 'terms_and_conditions_included_in_file=false' \
   https://sandbox.smartbl.io/api/v1/smart-bl-drafts/ \

And the response:

{
    "bl_number": "BL-123",
    "shipper": 10,
    "consignee": null,
    "consignee_type": 0,
    "delivery_agent": 11,
    "notify_party_email": "[email protected]",
    "notify_party_info": null,
    "documents": [
        {
            "uuid": "04b59579-9618-46e5-8381-056eb5e9ae62",
            "name": "test.pdf",
            "type": "application/pdf",
            "bl_type": 1,
            "manually_generated": false
        }
    ],
    "ipfs_document_group": null,
    "manual_document": null,
    "additional_issuer_info_text": "",
    "additional_shipper_info_text": "",
    "additional_consignee_info_text": "",
    "additional_delivery_info_text": "",
    "document_template": 3,
    "contract": "GenericSmartBL",
    "terms_and_conditions_included_in_file": false,
    "id": 98,
    "affiliate": null
}

POST /seal-bl/

Next step is to SEAL the package. Sealing the package makes it immutable and prepared for signing, committing to the blockchain and transferring.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -F 'destination=0' \
   -F 'id=smartbldraft:98' \
   -F 'keep_ipfd_document_hashes=[]' \
   -F 'recipient=shipper' \
   -F 'transfer_note=This is a sample transfer note.' \
   https://sandbox.smartbl.io/api/v1/seal-bl/

And the response:

{
    "status": "ok"
}

POST /save-documents-to-ipfs/

After the package is sealed, you are ready to push the files to IPFS. IPFS is a distributed file system which guarantees redundancy, and failover. Call this endpoint to move all the file attachments from temporary storage onto the IPFS.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -F 'id=smartbldraft:98' \
   https://sandbox.smartbl.io/api/v1/save-documents-to-ipfs/

And the response:

{
    "ipfs_hash": "QmYA6eR8Z94aND54zbBaWLuXTBd5yHZMftqtNn7LKZbYJt",
    "amend": true
}

POST /blockchain/hashes/issue/

After the documents are saved on the IPFS you are ready to sign a special message so that the smart contract will know that you are the one creating the package. To get the proper hash that needs to be signed you need to use this endpoint, which will fetch the hash from the smart contract.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -F 'draft_id=98' \
   https://sandbox.smartbl.io/api/v2/blockchain/hashes/issue/

And the response:

{
    "draft_id": 98,
    "issue_hash": "0xe6e293cf2d4d0e679a21262ce4e1a55d239cccd6f0a16145c12e6f92cfd0dc85"
}

POST /sign-bl/

This is the last method that needs to be called that actually executes the transfer and commits the token on the blockchain. The signature is the signature of the signed hash from the previous call.

Example request:

curl -X POST \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -F 'id=98' \
   -F 'signature=0x617de5b80b44579afc18f28f36e7b8beb28c2a18e12a6850e40f1e4de3f6d57428fb8bce2b8403eb70018b009b66be5809e970e8fc2ed30f282008e437be52221c' \
   https://sandbox.smartbl.io/api/v1/sign-bl/

And the response:

{
    "status":"ok"
}