Get PCSID Generation Status

Gets status of the PCSID generation activity.

Request Method

GET

Request URL

{{BASE_URL}}/onboarding/{ActivityId}/pcsid-status

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	Cannot be empty.	Mandatory. User auth token.
vat	String	Cannot be empty	Mandatory. VAT or Group VAT of the entity.

Request Path Params

Parameter	Data Type	Field Validations	Description
ActivityId	String	UUID	Mandatory. The PcsidGenerationActivityId received in the previous API.

Request Query Params

There are no query parameters for this API.

Request Body

There is no request body for this API.

Sample Request

https://api-sandbox.cleartax.com/middle-east/ksa/einvoicing/onboarding/628f37b61ed71a6638b848e4/pcsid-status

Response Status Codes

HTTP Status Code	Description
200	For a successful status retrieval.
400	For any kind of validation issues.
401	If the user is not authenticated for the operation.
403	If the user is not authorized for the operation.

Response Schema

Parameter	Data Type	Field Validations	Description
ActivityType	String	NA	Mandatory. Activity type of the async activity. This will always be ZATCA_COMPLIANCE_INVOICE.
Status	String	Enum: IN_PROGRESS, SUCCEEDED, FAILED	Mandatory. The status of the entire asnc activity. IN_PROGRESS - PCSID generation is in progress. SUCCEEDED - PCSID generation is complete. FAILED - PCSID generation failed.
CreatedAt	String	Timestamp (UTC)	Mandatory. When the async activity was created.
UpdatedAt	String	Timestamp (UTC)	Mandatory. When the async activity was last updated.
CompletedAt	String	Timestamp (UTC)	Mandatory. When the async activity was completed. If the state is IN_PROGRESS, the value will be null.
RequestMetaInfo	Object	NA	Request Meta Info Object.
ResponseInfo	Object	NA	Response Info Object.
ErrorList	Array	NA	Optional. Array of Error Details objects.

Request Meta Info Object

Parameter	Data Type	Field Validations	Description
TotalCount	Number	NA	Mandatory. Always 6. 6 indicates the number of compliance checks done.
SuccessCount	Number	Will be less than or equal to TotalCount	Mandatory. Number of compliance checks, mentioned above, that passed. This will be updated only after the entire activity is completed.
FailureCount	Number	Will be less than or equal to TotalCount	Mandatory. Number of compliance checks, mentioned above, that failed. This deals with all errors (zatca/CT server 5xx failure + compliance checks or 4xx failures). This will be updated only after the entire activity is completed.

Response Info Object

Parameter	Data Type	Field Validations	Description
ResponseMetaData	Object	NA	Optional. ResponseMetaData Object. This will be NULL when activity is IN_PROGRESS

Response Metadata Object

Parameter	Data Type	Field Validations	Description
PcsidGenerated	String	Enum: GENERATED, FAILED	Mandatory. Final PCSID generation status. This is dependent on the 6 compliance checks listed below.
StandardTaxInvoice	String	SUCCEEDED/ comma separated error messages	Optional. State of compliance check for Standard Tax Invoice.
StandardTaxInvoiceCredit	String	SUCCEEDED/ comma separated error messages	Optional. State of compliance check for Standard Tax Invoice - Credit Note.
StandardTaxInvoiceDebit	String	SUCCEEDED/ comma separated error messages	Optional. State of compliance check for Standard Tax Invoice - Debit Note.
SimplifiedTaxInvoice	String	SUCCEEDED/ comma separated error messages	Optional. State of compliance check for Simplified Tax Invoic
SimplifiedTaxInvoiceCredit	String	SUCCEEDED/ comma separated error messages	Optional. State of compliance check for Simplified Tax Invoice - Credit Note.
SimplifiedTaxInvoiceDebit	String	SUCCEEDED/ comma separated error messages	Optional. State of compliance check for Simplified Tax Invoice - Debit Note.

Sample Response

In Progress State - HTTP Status Code - 200

{
    "ActivityType": "ZATCA_COMPLIANCE_INVOICE",
    "Status": "IN_PROGRESS",
    "CreatedAt": "2022-05-20 18:56:11",
    "UpdatedAt": "2022-05-20 18:56:11",
    "CompletedAt": null,
    "RequestMetaInfo": {
        "TotalCount": 6,
        "SuccessCount": null,
        "FailureCount": null
    },
    "ResponseInfo": {
        "ResponseMetaData": null
    }
}

Succeeded State - HTTP Status Code - 200

{
    "ActivityType": "ZATCA_COMPLIANCE_INVOICE",
    "Status": "SUCCEEDED",
    "CreatedAt": "2022-05-20 18:56:11",
    "UpdatedAt": "2022-05-20 18:56:20",
    "CompletedAt": "2022-05-20 18:56:20",
    "RequestMetaInfo": {
        "TotalCount": 6,
        "SuccessCount": 6,
        "FailureCount": 0
    },
    "ResponseInfo": {
        "ResponseMetaData": {
            "PcsidGenerated": "GENERATED",
            "StandardTaxInvoice": "SUCCEEDED",
            "StandardTaxInvoiceCredit": "SUCCEEDED",
            "StandardTaxInvoiceDebit": "SUCCEEDED",
            "SimplifiedTaxInvoice": "SUCCEEDED",
            "SimplifiedTaxInvoiceCredit": "SUCCEEDED",
            "SimplifiedTaxInvoiceDebit": "SUCCEEDED"
        }
    }
}

Failed state - HTTP Status Code - 500

{
    "ActivityType": "ZATCA_COMPLIANCE_INVOICE",
    "Status": "FAILED",
    "CreatedAt": "2022-06-01 14:46:49",
    "UpdatedAt": "2022-06-01 14:46:49",
    "CompletedAt": "2022-06-01 14:46:49",
    "RequestMetaInfo": {
        "TotalCount": 6,
        "SuccessCount": 0,
        "FailureCount": 6
    },
    "ResponseInfo": {
        "ResponseMetaData": null
    }
}

Error - HTTP Status Code - 400

{
    "Status": "FAILED",
    "ErrorList": [
        {
            "ErrorCode": "6003",
            "ErrorMessage": "The async activity was not found",
            "ErrorSource": "CLEARTAX"
        }
    ]
}

API Validations

1. The ActivityId should be valid and must be related to PCSID generation only.

API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.

2. If the auth token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular VAT used in the request.