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.

AttributeDetails
API NameCreate Multiple / Bulk Terminals
HTTP MethodPOST
Endpoint/api/v1/tms/terminals/csv
Access LevelsSUPER_ADMIN, PARTNER
Content-Typemultipart/form-data
Success Response200 OK
Error Response400 Bad Request

2. Base URL

Production

https://app-api.edfapay.com

Full Endpoint

POST https://app-api.edfapay.com/api/v1/tms/terminals/csv

3. Authorization

This endpoint is accessible to the following roles:

  • SUPER_ADMIN
  • PARTNER

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

ParameterTypeRequiredDefaultDescription
businessUnitIdUUIDYes—Identifies the business unit under which the terminals will be created.
tmsVersionStringNoTMS1Specifies the TMS version used for the bulk operation. Allowed values: TMS1, TMS2.

4.2 Request Body

The request body must use multipart/form-data.

FieldTypeRequiredDescription
fileBinary fileYesCSV file containing the terminal records to be processed.

4.3 Request Headers

HeaderValueDefaultDescription
X-API-KEYYOUR_API_KEY—Authenticates the API request.
X-LangStringenSpecifies 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:

Download Sample CSV

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_UUID with a valid business unit UUID.
  • Replace YOUR_API_KEY with a valid API key.
  • Ensure that terminals.csv exists at the specified local path.
  • Use TMS1 or TMS2 for the TMS version, or omit tmsVersion to use the documented default of TMS1.
  • Do not manually set the Content-Type header 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

FieldTypeDescription
codeNumberApplication-level response code.
messageStringResponse message.
errorCodeStringApplication error identifier, where applicable.
dataObjectBulk processing summary and file information.
data.totalNumberTotal number of records reported by the operation.
data.addedNumberNumber of records reported as successfully added.
data.failedNumberNumber of records reported as failed.
data.tmsVersionStringTMS version used for the operation.
data.fileObjectInformation associated with the uploaded file.
data.file.fileNameStringFile name returned by the API.
data.file.fileDataStringFile-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:

  1. Verify that businessUnitId is present and contains a valid UUID.
  2. Confirm that tmsVersion is either TMS1 or TMS2, if supplied.
  3. Ensure that the file field contains a CSV upload.
  4. Validate the CSV structure against the official sample.
  5. Confirm that the caller has the required access level.
  6. Verify that the X-API-KEY header contains a valid API key.
  7. Inspect message and errorCode for 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

  1. Authenticate using a valid API key and an authorized SUPER_ADMIN or PARTNER account.
  2. Obtain the target business unit UUID.
  3. Select the appropriate TMS version.
  4. Download and inspect the official sample CSV.
  5. Prepare the CSV containing the terminal records.
  6. Submit the request using multipart/form-data, including the required file field.
  7. Read the response and evaluate total, added, and failed.
  8. Investigate unsuccessful records using any available error details.
  9. Verify that the expected terminal records were created.

10. Important Considerations

  • The endpoint supports bulk terminal creation through CSV upload.
  • businessUnitId is a required query parameter.
  • tmsVersion defaults to TMS1; the documented options are TMS1 and TMS2.
  • The uploaded file must be supplied in the file multipart field.
  • Authentication uses the X-API-KEY header.
  • 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.

Did this page help you?