Creating a Guarantee

Creating a guarantee within the Cauzioni Smart platform involves a two-step process. First, the relevant document, such as a bail act, must be securely uploaded using the presigned URL obtained from the /api/v1/presigned-url endpoint. Following the successful upload, the guarantee can be created by making a POST request to the /api/v1/guarantees endpoint, referencing the uploaded document’s unique key.

Step 1: Securely Uploading a Bail Act

Before creating a guarantee, the bail act or relevant document must be uploaded securely. Obtain a presigned URL as detailed in the previous section and use it to upload your document. Ensure you keep the key returned in the response, as it will be required to create the guarantee.
Securely Uploading .p7m file(s)

Step 2: Creating the Guarantee

Once the document is uploaded, you can proceed to create the guarantee. This involves sending a POST request to the /api/v1/guarantees endpoint with a JSON payload that references the key of the uploaded document.

Request

In its simplestform guarantee can be created by just providing the bail act’s key in the payload. You can also specify any other field you find relevant.

In partical the field guaranteeNumber can host your own internal id. This field must be unique for each guarantee across your organization.

• Method: POST
• Endpoint: /api/v1/guarantees
• Headers:
• Content-Type: application/json
• Authorization: Bearer YOUR_API_KEY

Payload

{
  "guarantee": {
    "details": {
        "policyNumber": "text",
        "actType": "BAIL_ACT",
        "checkCode": "text",
    },
    "docs": [
      {
        "type": "BAIL_ACT",
        "key": "<file_key>"
      }
    ]
  }
}

• type: Specifies the type of document. In this case, "BAIL_ACT" indicates that the document is a bail act.
• key: The unique identifier for the uploaded document. This should match the key received from the presigned URL upload process.

Example Request

Here’s an example of how to make the request using curl:

curl -X POST '{base_endpoint}/api/v1/guarantees' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  --data-raw '{
    "guarantee": {
      "details": {
        "policyNumber": "text",
        "actType": "BAIL_ACT",
        "checkCode": "text",
      },
      "docs": [
        {
          "type": "BAIL_ACT",
          "key": "org_2a2sA4RGsRKUXvSrtW4Nhy90itl/60597ba2-a9b7-4fcd-b334-dd17c7f2a140.p7m"
        }
      ]
    }
  }'

Response Structure

Upon successfully creating a guarantee, the API responds with a JSON object detailing the newly created guarantee. The response structure is as follows:

{
 "guarantees": {
      "details": {
        "policyNumber": "text",
        "actType": "BAIL_ACT",
        "checkCode": "text",
        "emittedAt": "2024-06-20T14:34:13.295Z",
        "effectiveAt": "2024-06-20T14:34:13.295Z",
        "expiresAt": "2024-06-20T14:34:13.295Z",
        "isFixedExpiry": false,
        "cig": "text",
        "batchCode": "text"
      },
      "economics": {
        "garantedAmount": 0,
        "contractAmount": 0,
        "isAutomaticRenewal": false
      },
      "note": {
        "shared": "text"
      },
      "sign": {
        "emissionAt": "2024-06-20T14:34:13.295Z"
      },
      "txHash": "text",
      "notarizationStatus": "PENDING",
      "docs": [
        {
          "type": "BAIL_ACT",
          "key": "text",
          "checksum": "text"
        }
      ],
      "createdAt": "now",
      "id": "text",
      "orgId": "text"
    }
}

Notes:

• Notarization Status: The notarizationStatus will initially be set to PENDING. A guarantee should not be considered notarized by default. To verify the notarization status of a guarantee, a separate check should be conducted using the guarantee ID. This step is crucial to ensure that the guarantee has been fully processed and is recognized on the distributed ledger.\
  Possible values:

  - PENDING
  - NOTARIZED
  - REJECTED

This structured response provides all necessary details about the created guarantee, including the transaction hash (txHash), notarization status, and associated documents. Ensure to conduct a follow-up verification of the notarization status to confirm the guarantee’s final state.