CertFusion API End Points

Endpoint: `GET /api/lists`

Description:
Retrieve a list of all certificate lists associated with the authenticated user.

Method: GET

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Parameters:

page (optional):
The page number for pagination. Default is 1.
per_page (optional):
Number of results per page. Default is 15. Max is configurable depending on your application.

Request Headers:

Authorization: Bearer <token>
A valid API token must be included in the request header to authenticate the user.

Response:

Status Code: 200 OK

Response Body:

{
  "data": [
    {
      "id": 1,
      "name": "Certificate List 1",
      "created_at": "2023-10-01T12:00:00.000000Z",
      "updated_at": "2023-10-02T12:00:00.000000Z"
    },
    {
      "id": 2,
      "name": "Certificate List 2",
      "created_at": "2023-10-02T12:30:00.000000Z",
      "updated_at": "2023-10-03T14:00:00.000000Z"
    }
  ],
  "links": {
    "first": "http://example.com/api/lists?page=1",
    "last": "http://example.com/api/lists?page=5",
    "prev": null,
    "next": "http://example.com/api/lists?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}

Response Fields:

data: A collection of certificate lists.
- id: The unique identifier of the list.
- name: The name of the certificate list.
- created_at: The date and time when the certificate list was created.
- updated_at: The date and time when the certificate list was last updated.
links: Pagination links.
- first: URL to the first page of results.
- last: URL to the last page of results.
- prev: URL to the previous page of results, if applicable.
- next: URL to the next page of results, if applicable.
meta: Pagination metadata.
- current_page: The current page number.
- from: The starting index of the current page of results.
- last_page: The last page number.
- per_page: The number of items per page.
- to: The ending index of the current page of results.
- total: The total number of available certificate lists.

Errors:

401 Unauthorized: If the user is not authenticated.
500 Internal Server Error: If there is an issue with retrieving the certificate lists.

Endpoint: `GET /api/recipients`

Description:
Retrieve a list of all recipients associated with certificate lists belonging to the authenticated user.

Method: GET

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Parameters:

page (optional):
The page number for pagination. Default is 1.
per_page (optional):
Number of results per page. Default is 15. Max is configurable depending on your application.

Request Headers:

Authorization: Bearer <token>
A valid API token must be included in the request header to authenticate the user.

Response:

Status Code: 200 OK

Response Body:

{
  "data": [
    {
      "id": 1,
      "list_id": 1,
      "email": "recipient@example.com",
      "name": "John Doe",
      "status": "issued",
      "uuid": "abcd-1234-efgh-5678",
      "issued_date": "2023-10-01T12:00:00+00:00",
      "created_at": "2023-10-01T12:00:00+00:00",
      "updated_at": "2023-10-02T12:00:00+00:00"
    },
    {
      "id": 2,
      "list_id": 2,
      "email": "another@example.com",
      "name": "Jane Smith",
      "status": "draft",
      "uuid": "ijkl-5678-mnop-1234",
      "issued_date": "2023-09-28T10:00:00+00:00",
      "created_at": "2023-09-28T10:00:00+00:00",
      "updated_at": "2023-09-29T10:00:00+00:00"
    }
  ],
  "links": {
    "first": "http://example.com/api/recipients?page=1",
    "last": "http://example.com/api/recipients?page=5",
    "prev": null,
    "next": "http://example.com/api/recipients?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}

Response Fields:

data: A collection of recipient records.
- id: The unique identifier of the recipient.
- list_id: The ID of the certificate list the recipient is associated with.
- email: The email address of the recipient.
- name: The name of the recipient.
- status: The current status of the recipient (e.g., draft, issued).
- uuid: A unique identifier for the recipient (e.g., a GUID).
- issued_date: The date when the certificate was issued to the recipient. If not set, null will be returned.
- created_at: The timestamp when the recipient was created.
- updated_at: The timestamp when the recipient was last updated.
links: Pagination links.
- first: URL to the first page of results.
- last: URL to the last page of results.
- prev: URL to the previous page of results, if applicable.
- next: URL to the next page of results, if applicable.
meta: Pagination metadata.
- current_page: The current page number.
- from: The starting index of the current page of results.
- last_page: The last page number.
- per_page: The number of items per page.
- to: The ending index of the current page of results.
- total: The total number of available recipients.

Errors:

401 Unauthorized: If the user is not authenticated.
500 Internal Server Error: If there is an issue with retrieving the recipients.

Endpoint: `POST /api/recipients`

Description:
Add a new recipient to a certificate list associated with the authenticated user.

Method: POST

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Parameters (Body):

{
  "list_id": 1,
  "email": "recipient@example.com",
  "name": "John Doe"
}

list_id (required, integer):
The ID of the certificate list the recipient will be added to. This list must exist and belong to the authenticated user.
email (required, string):
The email address of the recipient. It must be a valid email format.
name (required, string):
The full name of the recipient. Maximum length is 255 characters.

Request Headers:

Authorization: Bearer <token>
A valid API token must be included in the request header to authenticate the user.

Response:

Status Code: 201 Created (on success)
When the recipient is successfully created, the response will include the recipient’s details.

Response Body (Success):

{
  "id": 1,
  "list_id": 1,
  "email": "recipient@example.com",
  "name": "John Doe",
  "status": "active",  
  "uuid": "abcd-1234-efgh-5678",
  "issued_date": null,
  "created_at": "2023-10-01T12:00:00+00:00",
  "updated_at": "2023-10-01T12:00:00+00:00"
}

id: The unique identifier of the recipient.
list_id: The ID of the certificate list the recipient is associated with.
email: The email address of the recipient.
name: The name of the recipient.
status: The status of the recipient (e.g., active, inactive).
uuid: A unique identifier for the recipient (UUID).
issued_date: The date when the certificate was issued to the recipient. If not issued yet, null.
created_at: The timestamp when the recipient was created.
updated_at: The timestamp when the recipient was last updated.

Response (Errors):

400 Bad Request:
If required parameters are missing or invalid, such as an invalid email format.

Response Example:

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "email": ["The email must be a valid email address."]
  }
}

404 Not Found:
If the specified list_id does not exist, or if the list does not belong to the authenticated user.

Response Example:
```
{
  "status": false,
  "message": "The list you are trying to access does not exist."
}
```
403 Forbidden:
If the authenticated user does not have permission to access the specified list.

Response Example:
```
{
  "status": false,
  "message": "You are not authorized to perform this action."
}
```

422 Unprocessable Entity:
If the input validation fails (e.g., missing required fields).

Response Example:

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "name": ["The name field is required."]
  }
}

500 Internal Server Error:
If there is an unexpected server error during recipient creation.

Response Example:

{
  "status": false,
  "message": "An error occurred while creating the recipient.",
  "error": "Error details here"
}

Endpoint: `DELETE /api/recipients/{id}`

Description:
Delete a recipient from a certificate list associated with the authenticated user.

Method: DELETE

Authentication:
Requires user authentication via token (e.g., Bearer Token).

URL Parameters:

id (required, integer):
The unique ID of the recipient that you want to delete.

Request Headers:

Authorization: Bearer <token>
A valid API token must be included in the request header to authenticate the user.

Response:

Status Code: 200 OK (on success)
When the recipient is successfully deleted, the response will include a success message.

Response Body (Success):

{
  "status": true,
  "message": "Recipient deleted successfully."
}

Response Fields:

status: Indicates whether the operation was successful (true or false).
message: A message describing the result of the operation.

Response (Errors):

404 Not Found:
If the recipient does not exist or is not associated with the authenticated user.

Response Example:
```
{
  "status": false,
  "message": "Recipient not found or not associated with your account."
}
```

500 Internal Server Error:
If an unexpected error occurs during the deletion process.

Response Example:

{
  "status": false,
  "message": "An error occurred while deleting the recipient.",
  "error": "Error details here"
}

Endpoint: `POST /api/recipients/{id}/issue`

Description:
Issue a certificate to a specific recipient in the authenticated user's certificate list.

Method: POST

Authentication:
Requires user authentication via token (e.g., Bearer Token).

URL Parameters:

id (required, integer):
The unique ID of the recipient for whom the certificate is to be issued.

Request Headers:

Authorization: Bearer <token>
A valid API token must be included in the request header to authenticate the user.

Response:

Status Code: 200 OK (on success)
When the certificate is successfully issued, the response will include the recipient's details.

Response Body (Success):

{
  "status": true,
  "recipient": {
    "id": 1,
    "list_id": 1,
    "email": "recipient@example.com",
    "name": "John Doe",
    "status": "issued",  
    "uuid": "abcd-1234-efgh-5678",
    "issued_date": "2023-10-01T12:00:00+00:00",
    "created_at": "2023-10-01T12:00:00+00:00",
    "updated_at": "2023-10-01T12:00:00+00:00"
  }
}

status: Indicates whether the operation was successful (true).
recipient: Contains the updated recipient details including the issued_date and other recipient-related information.

Response (Errors):

404 Not Found:
If the recipient does not exist or is not associated with the authenticated user.

Response Example:

{
  "status": false,
  "message": "Recipient not found or you do not have access to this recipient."
}

500 Internal Server Error:
If an unexpected error occurs while issuing the certificate.

Response Example:

{
  "status": false,
  "message": "An error occurred while issuing the certificate.",
  "error": "Error details here"
}

Endpoint: `POST /api/recipients/issue`

Description:
Issue certificates to a group of recipients belonging to the authenticated user's certificate lists.

Method: POST

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Body:

{
  "recipient_ids": [1, 2, 3]
}

recipient_ids (required, array of integers):
An array of recipient IDs for whom the certificates will be issued.

Request Headers:

Authorization: Bearer <token>
A valid API token must be included in the request header to authenticate the user.

Response:

Status Code: 200 OK (on success)
When the certificates are successfully issued to the group of recipients, the response will include the list of updated recipients.

Response Body (Success):

{
  "status": true,
  "recipients": [
    {
      "id": 1,
      "list_id": 1,
      "email": "recipient1@example.com",
      "name": "John Doe",
      "status": "issued",
      "uuid": "abcd-1234-efgh-5678",
      "issued_date": "2023-10-01T12:00:00+00:00",
      "created_at": "2023-10-01T12:00:00+00:00",
      "updated_at": "2023-10-01T12:00:00+00:00"
    },
    {
      "id": 2,
      "list_id": 1,
      "email": "recipient2@example.com",
      "name": "Jane Doe",
      "status": "issued",
      "uuid": "ijkl-2345-mnop-6789",
      "issued_date": "2023-10-01T12:00:00+00:00",
      "created_at": "2023-10-01T12:00:00+00:00",
      "updated_at": "2023-10-01T12:00:00+00:00"
    }
  ]
}

status: Indicates whether the operation was successful (true).
recipients: A collection of recipient objects, each containing the updated details such as issued_date and other recipient-related information.

Response (Errors):

422 Unprocessable Entity (Validation Error):
If the recipient_ids array is invalid or the IDs do not exist in the database.

Response Example:

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "recipient_ids": [
      "The selected recipient_ids is invalid."
    ]
  }
}

404 Not Found:
If no valid recipients are found or the authenticated user does not have access to them.

Response Example:
```
{
  "status": false,
  "message": "No valid recipients found or you do not have access to them."
}
```

500 Internal Server Error:
If an unexpected error occurs while issuing the certificates.

Response Example:

{
  "status": false,
  "message": "An error occurred while issuing certificates.",
  "error": "Error details here"
}

Endpoint: GET /api/lists

Endpoint: GET /api/recipients

Endpoint: POST /api/recipients

Endpoint: DELETE /api/recipients/{id}

Endpoint: POST /api/recipients/{id}/issue

Endpoint: POST /api/recipients/issue

Endpoint: `GET /api/lists`

Endpoint: `GET /api/recipients`

Endpoint: `POST /api/recipients`

Endpoint: `DELETE /api/recipients/{id}`

Endpoint: `POST /api/recipients/{id}/issue`

Endpoint: `POST /api/recipients/issue`