Report Management

This document details the endpoints for retrieving reports and their metadata via the Certificall API.

The reportToken is an identifier used to correlate multiple certificates to a third-party context (such as a CRM system or another application) when specified in a deeplink with the reportId parameter.

Retrieving Report Metadata

Endpoint: `GET /reports/:reportToken`

Description

This API endpoint allows users to retrieve detailed metadata of a specific report using a report token. This endpoint is public and does not require authentication.

The reportToken is transmitted directly in the URL as a parameter and serves as a key to access all information about certificates associated with a report.

Request

URL: /reports/:reportToken
HTTP Method: GET
Path parameters:
- reportToken: string - The unique token that identifies the report.
Required headers: No authentication is required for this public endpoint.

Responses

Successful response:

Status: 200 OK
Description: Returns an array of JSON objects containing the detailed metadata of the report.
Type: Array<CaseForApiResponseDto>

Response example:

[
  {
    "cfRef": "CAS-7264_CMP-1",
    "companyName": "Company XYZ",
    "createdAt": "2023-11-09T13:24:40+01:00",
    "closingDate": "2023-11-10T15:30:00+01:00",
    "reportId": "12345",
    "frame": "Visual Inspection",
    "closed": true,
    "caseUrl": "https://certificall.app/certificall/share/case/shareToken123",
    "items": [
      {
        "createdAt": "2023-11-09T13:25:00+01:00",
        "cfRef": "ITEM-001",
        "description": "Equipment photo",
        "geolocLatitude": "48.8566",
        "geolocLongitude": "2.3522",
        "data": "General condition satisfactory",
        "imageUrl": "https://certificall.app/images/photo1.jpg",
        "stepAction": "Photography",
        "stepTitle": "Equipment photo",
        "stepDescription": "Take a photo of the equipment to inspect",
        "imageHash": "abc123def456",
        "tspTokenHash": "xyz789uvw012"
      }
    ]
  }
]

Error response:

Status: 400 Bad Request
Description: The request is invalid, for example if the reportToken is incorrect or missing.

{
  "statusCode": 400,
  "message": "Invalid report token",
  "error": "Bad Request"
}

Status: 404 Not Found
Description: No report found for this reportToken.

{
  "statusCode": 404,
  "message": "Report not found",
  "error": "Not Found"
}

Data Model

CaseForApiResponseDto:

cfRef: string - Unique case reference (example: "CAS-7264_CMP-1")
companyName: string - Name of the company associated with the certificate
createdAt: Date (ISO 8601) - Certificate creation date
closingDate: Date (ISO 8601) - Certificate closing date
reportId: string - Unique report identifier (reportToken)
frame: string - Name of the frame used
closed: boolean - Status indicating whether the certificate is closed
caseUrl: string - Public URL for downloading the certificate PDF
items: Array<ItemDto> - Detailed list of certificate items

ItemDto:

createdAt: Date (ISO 8601) - Item creation date
cfRef: string - Unique item reference
description: string - Item description
geolocLatitude: string - Geolocation latitude
geolocLongitude: string - Geolocation longitude
data: string - Data associated with the item
imageUrl: string (optional) - Image URL if the item is a photo
stepAction: string - Step action type (Photography, Text, etc.)
stepTitle: string - Step title
stepDescription: string - Step description
imageHash: string (optional) - Image hash for integrity verification
tspTokenHash: string (optional) - Timestamp token hash

Use Cases

Use this endpoint to:

Retrieve all detailed metadata of a report's certificates
View information without authentication (public endpoint)
Obtain download URLs for individual certificates via the caseUrl field
Access details of each item (photos, texts, geolocation, etc.)
Verify file integrity via the provided hashes

Retrieving a Complete Report (ZIP or URLs)

Endpoint: `POST /reports/report/:reportToken`

Description

This API endpoint allows authenticated users to retrieve a complete report (set of certificates) associated with a specific report token. Depending on the requested format, you can obtain either a ZIP file containing all certificate PDFs, or the download URLs of the certificates.

Request

URL: /reports/report/:reportToken
HTTP Method: POST
Path parameters:
- reportToken: string - The unique token that identifies the report.

Required headers:

Authorization: Bearer <Your_JWT_Token>
Content-Type: application/json

Request Body (Payload)

format (Enum, optional): Response format (zip or metadata).
- zip: Returns a ZIP file containing all certificate PDFs
- metadata: Returns the download URLs of the certificates
hours (Number, optional): Filter certificates created in the last X hours.

Request example to get a ZIP:

{
  "format": "zip",
  "hours": 48
}

Request example to get metadata:

{
  "format": "metadata"
}

Responses

Successful response (format: zip):

Status Code: 200 OK
Content Type: application/zip
Description: Returns a ZIP file containing all certificate PDFs of the report.

Response headers:

Content-Type: application/zip
Content-Disposition: attachment; filename="reportToken.zip"

The response body contains the binary ZIP file.

Successful response (format: metadata):

Status Code: 200 OK
Content Type: application/json
Description: Returns an object containing download URLs.

Response example:

{
  "reportToken": "REPORT-2024-001",
  "caseUrls": [
    "https://certificall.app/certificall/share/case/shareToken1",
    "https://certificall.app/certificall/share/case/shareToken2",
    "https://certificall.app/certificall/share/case/shareToken3"
  ]
}

Error response:

Status Code: 400 Bad Request
Description: The request is invalid (missing reportToken or invalid format).

{
  "statusCode": 400,
  "message": "Invalid report token or format",
  "error": "Bad Request"
}

Status Code: 403 Forbidden
Description: You do not have the necessary permissions to access this report.
Status Code: 404 Not Found
Description: No certificates found for this reportToken.

{
  "statusCode": 404,
  "message": "No certificates found for this report token",
  "error": "Not Found"
}

Required Permissions

You must be authenticated via a valid JWT token.
The certificates must belong to your company.

Use Cases

Use this endpoint to:

Download all certificates of a report at once (ZIP format)
Obtain individual download links for each certificate (metadata format)
Retrieve certificates created within a specific time window (hours parameter)
Integrate certificates into a third-party system via sharing URLs

Differences Between the Two Endpoints

Criteria	GET /reports/:reportToken	POST /reports/report/:reportToken
Authentication	Not required (public)	Required (JWT)
Data type	Detailed metadata (JSON)	ZIP or simple URLs
Item information	Yes (full details)	No
ZIP download	No	Yes (if format=zip)
Time filtering	No	Yes (hours parameter)
Typical usage	Viewing details	Downloading PDFs

Recommendation:

Use GET /reports/:reportToken to get all detailed metadata of certificates (items, geolocation, hash, etc.)
Use POST /reports/report/:reportToken to download PDFs in bulk (ZIP) or get download URLs

Security and Best Practices

The GET endpoint is public but only provides access to metadata, not sensitive files
Use the zip format to download multiple certificates in a single request
Use the metadata format to get URLs and download them individually or share them
The hours parameter allows limiting results to recent certificates
The returned sharing URLs are public and do not require authentication
Interactions with the Certificall API must always be performed via a secure connection (HTTPS)
Store and manage the authentication token securely

By following these instructions, you will be able to securely retrieve complete reports via the Certificall API.

Retrieving Report Metadata​

Endpoint: GET /reports/:reportToken​

Description​

Request​

Responses​

Data Model​

Use Cases​

Retrieving a Complete Report (ZIP or URLs)​

Endpoint: POST /reports/report/:reportToken​

Description​

Request​

Request Body (Payload)​

Responses​

Required Permissions​

Use Cases​

Differences Between the Two Endpoints​

Security and Best Practices​

Retrieving Report Metadata

Endpoint: `GET /reports/:reportToken`

Description

Request

Responses

Data Model

Use Cases

Retrieving a Complete Report (ZIP or URLs)

Endpoint: `POST /reports/report/:reportToken`

Description

Request

Request Body (Payload)

Responses

Required Permissions

Use Cases

Differences Between the Two Endpoints

Security and Best Practices