createCardImport

Overview

This method uploads a CSV file of cards for a supplier and validates every row. Each row is classified as create, update, invalid, duplicate or unauthorized, and the results are stored against a new import batch. No cards are created or updated until the batch is processed.

This API is part of the card import process:

createCardImport – upload and validate the CSV file.
getCardImportErrors – download the rows that failed validation (optional).
processCardImport – create and update the valid cards.
getCardImportResult – download the final outcome for every row.

Validation rules

supplier_id must be supplied and must be a card-services supplier.
Each row must contain either contract_id or reg_no.
If reg_no matches more than one active contract, the row is invalid.
If a card with the same supplier_id and card_number already exists, the row is an update; otherwise it is a create.
Rows in the same file with the same supplier_id and card_number are duplicate.
status_flag must be active or inactive; deleted is rejected.
A missing Cards:Create permission does not invalidate update rows, and a missing Cards:Update permission does not invalidate create rows.

This method only requires an authenticated user. Permissions are checked for each row: create rows need the Cards:Create permission and update rows need the Cards:Update permission. Rows you are not authorised to process are classified as unauthorized rather than blocking the request.

Permissions

The permissions for this api are stored in [gb_api_permissions]permission as 'Cards:Create' and 'Cards:Update'.

Only roles with a stored link to these permissions in [gb_role_api_permissions] can create or update cards through this api.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/fm/cards/imports https://api.{{environment}}.catch-e.com/fm/cards/imports https://api.test.catch-e.com/fm/cards/imports

Input Fields (Header)

Key	Format	Notes	Mandatory
Audit-User-Id	string	(Optional) User Id to use for audit purposes. Up to 5 digits. Requires the Audit:UserIdOverride permission.	No

Input Fields (Form Data)

The request body is sent as multipart form data (multipart/form-data).

Key	Format	Notes	Mandatory
supplier_id	string	The supplier for this import batch. Must be a supplier of type card-services. A positive whole number, up to 10 digits.	Yes
data	file	The CSV file to import. Must include a header row. See CSV columns below.	Yes

CSV columns

Column	Mandatory	Notes
card_number	Yes	Up to 40 characters.
contract_id	Conditional	Required if `reg_no` is not supplied.
reg_no	Conditional	Required if `contract_id` is not supplied. Must match exactly one active contract.
account_number	No	Up to 40 characters.
status_flag	No	`active` or `inactive`. Blank on update leaves the existing value unchanged.
expiry_date	No	yyyy-MM-dd. Blank on update leaves the existing value unchanged.
activated_date	No	yyyy-MM-dd. Blank on update leaves the existing value unchanged.
inactivated_date	No	yyyy-MM-dd. Blank on update leaves the existing value unchanged.
recharge_flag	No	`yes` or `no`. Blank on update leaves the existing value unchanged.
client_id_recharge	No	Blank on update leaves the existing value unchanged.

Response Details

Success

201 - Created

The batch was created and all rows validated. Check import_allowed to see whether the batch can be processed.

Field	Format	Notes
import_batch_id	string	The id of the new import batch. Use it in the process, errors and result requests.
summary.total	integer	Total number of data rows in the file, excluding the header row.
summary.valid	integer	Rows classified as create or update that passed all validation.
summary.invalid	integer	Rows that failed one or more validation rules.
summary.duplicate	integer	Rows rejected because the same supplier_id and card_number appeared more than once in the file.
summary.unauthorized	integer	Otherwise valid rows the user does not have permission to process.
import_allowed	boolean	`true` if at least one create or update row can be processed. `false` if every row is invalid, duplicate or unauthorized.
error_report_available	boolean	`true` if there is at least one invalid, duplicate or unauthorized row, so an error report can be downloaded with getCardImportErrors.

{ "import_batch_id": "1234", "summary": { "total": 10, "valid": 8, "invalid": 1, "duplicate": 1, "unauthorized": 0 }, "import_allowed": true, "error_report_available": true }

Error Response Details

Validation Message	Comments
401 - Unauthorized	1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }

Validation Message	Comments
403 - Forbidden	- You do not have permissions for this request. - Go to System Roles and enter 'web_services' - Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" }

Validation Message	Comments
406 - Not Acceptable	The Accept header of the request does not match a response format this API supports.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Not Acceptable" }

Validation Message	Comments
415 - Unsupported Media Type	The Content-Type of the request is not supported by this API.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unsupported Media Type", "status": 415, "detail": "Not Acceptable" }

Validation Message	Comments
422 - Unprocessable Entity	One or more input fields failed validation. The field name and message are returned in `validation_messages`.

{ "warning_messages": {}, "validation_messages": { "fieldName": { "validationExceptionCode": "A textual description of the validation exception" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Validation Message	Comments
500 - Internal Error	An unexpected error occurred on the server.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }

Validation Message	Comments
default - Unexpected Error	Any other unexpected error.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }