Bulk Terminal Creation — API
Creates multiple terminal records by uploading a CSV file. Requires a businessUnitId, supports TMS1 and TMS2, and returns a summary of total, added, and failed records. Accessible to SUPER_ADMIN and PARTNER roles using API Key authentication through the X-API-KEY header.
1. Endpoint Summary
The Bulk Terminal Creation API creates multiple terminal records through a CSV file upload. The API processes the submitted file and returns a summary of the total, successfully added, and failed records.
| Attribute | Details |
|---|---|
| API Name | Create Multiple / Bulk Terminals |
| HTTP Method | POST |
| Endpoint | /api/v1/tms/terminals/csv |
| Access Levels | SUPER_ADMIN, PARTNER |
| Content-Type | multipart/form-data |
| Success Response | 200 OK |
| Error Response | 400 Bad Request |
2. Base URL
Production
https://app-api.edfapay.comFull Endpoint
POST https://app-api.edfapay.com/api/v1/tms/terminals/csv3. Authorization
This endpoint is accessible to the following roles:
SUPER_ADMINPARTNER
Authentication uses an API key supplied through the X-API-KEY request header.
4. Request Parameters
The endpoint accepts two query parameters and one file in the multipart request body.
4.1 Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
businessUnitId | UUID | Yes | — | Identifies the business unit under which the terminals will be created. |
tmsVersion | String | No | TMS1 | Specifies the TMS version used for the bulk operation. Allowed values: TMS1, TMS2. |
4.2 Request Body
The request body must use multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
file | Binary file | Yes | CSV file containing the terminal records to be processed. |
4.3 Request Headers
| Header | Value | Default | Description |
|---|---|---|---|
X-API-KEY | YOUR_API_KEY | — | Authenticates the API request. |
X-Lang | String | en | Specifies the language used for API messages. |
Accept | */* | — | Specifies the response media types accepted by the client. |
The request body must contain the CSV file in the file multipart field.
5. Sample CSV File
The Swagger documentation provides a sample CSV file at the following URL:
Use the sample file to verify the expected column structure before preparing the bulk upload.
Important: The exact CSV column names, field order, validation rules, and required values must be confirmed from the downloadable sample. Do not assume a CSV schema that is not documented.
6. cURL Example
curl --request POST \
--url 'https://app-api.edfapay.com/api/v1/tms/terminals/csv?businessUnitId=BUSINESS_UNIT_UUID&tmsVersion=TMS1' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-Lang: en' \
--header 'Accept: */*' \
--form '[email protected];type=text/csv'Before execution:
- Replace
BUSINESS_UNIT_UUIDwith a valid business unit UUID. - Replace
YOUR_API_KEYwith a valid API key. - Ensure that
terminals.csvexists at the specified local path. - Use
TMS1orTMS2for the TMS version, or omittmsVersionto use the documented default ofTMS1. - Do not manually set the
Content-Typeheader when using cURL's--form; cURL generates the multipart boundary automatically.
7. Response Specification
7.1 HTTP 200 — OK
The endpoint returns a response containing an operation summary and file information.
Example response:
{
"code": 0,
"message": "string",
"errorCode": "string",
"data": {
"total": 0,
"added": 0,
"failed": 0,
"tmsVersion": "TMS1",
"file": {
"fileName": "string",
"fileData": "string"
}
}
}The values above are Swagger example placeholders and do not represent actual processing results.
7.2 Response Fields
| Field | Type | Description |
|---|---|---|
code | Number | Application-level response code. |
message | String | Response message. |
errorCode | String | Application error identifier, where applicable. |
data | Object | Bulk processing summary and file information. |
data.total | Number | Total number of records reported by the operation. |
data.added | Number | Number of records reported as successfully added. |
data.failed | Number | Number of records reported as failed. |
data.tmsVersion | String | TMS version used for the operation. |
data.file | Object | Information associated with the uploaded file. |
data.file.fileName | String | File name returned by the API. |
data.file.fileData | String | File-related data returned by the API. Its exact representation is not specified in the available definition. |
7.3 Interpreting the Processing Summary
The response includes three record-count fields:
total— the total number of records reported.added— the number reported as successfully added.failed— the number reported as failed.
For example, if a response reports total: 100, added: 95, and failed: 5, the API reports 95 records added and 5 failed.
An HTTP 200 OK response should not be interpreted as confirmation that every terminal was created successfully. Inspect the returned processing counts and any available failure details.
8. Error Handling
HTTP 400 — Bad Request
The endpoint documents 400 Bad Request as a possible response.
Example response:
{
"code": 0,
"message": "string",
"errorCode": "string",
"data": {}
}Troubleshooting checklist:
- Verify that
businessUnitIdis present and contains a valid UUID. - Confirm that
tmsVersionis eitherTMS1orTMS2, if supplied. - Ensure that the
filefield contains a CSV upload. - Validate the CSV structure against the official sample.
- Confirm that the caller has the required access level.
- Verify that the
X-API-KEYheader contains a valid API key. - Inspect
messageanderrorCodefor additional error details.
These are general troubleshooting recommendations. The complete validation rules and error mappings are not specified in the available definition.
9. Integration Workflow
- Authenticate using a valid API key and an authorized
SUPER_ADMINorPARTNERaccount. - Obtain the target business unit UUID.
- Select the appropriate TMS version.
- Download and inspect the official sample CSV.
- Prepare the CSV containing the terminal records.
- Submit the request using
multipart/form-data, including the requiredfilefield. - Read the response and evaluate
total,added, andfailed. - Investigate unsuccessful records using any available error details.
- Verify that the expected terminal records were created.
10. Important Considerations
- The endpoint supports bulk terminal creation through CSV upload.
businessUnitIdis a required query parameter.tmsVersiondefaults toTMS1; the documented options areTMS1andTMS2.- The uploaded file must be supplied in the
filemultipart field. - Authentication uses the
X-API-KEYheader. - The response distinguishes between total, added, and failed records.
- The maximum upload size, CSV encoding, duplicate handling, transaction behavior, and detailed per-row error reporting are not specified in the available definition.
- Confirm these constraints before using the endpoint for large production uploads.
Updated 25 days ago