Creating Cards

This service allows you to create new card records.

It performs the same function as creating a card in the Cards / Card Details tab does.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/fm/cards

Input Fields (Header)

Key

Format

Notes

Mandatory

Audit-User-Id

Number

User ID that you want to show as the user in audit records. To use this Key, the authorised role must have the permission Audit:UserIdOverride enabled.

No

Input Fields (Body)

JSON Field

Format

Notes

Mandatory

contract_id

Number

The Contract ID the card should be linked to.

Yes

card_number

Number

Card number provided by the supplier.

Yes

supplier_id

Number

The supplier the card is linked to. * .

Yes

account_number

Number

Account number of the card

No

posting_flag

Text

This updates and defaults to 'yes' if it is not specified.

No

recharge_flag

Text

This updates . If this Key is not specified the value will default from the linked Contract Types / Expense-Approvals "R" fild for the ‘F - Fuel’ record.

No

clientidrecharge

Number

This updates . If this Key is not specified, the Client ID that is attached to the Contract will be used. Cannot be blank if “Posting Enabled” flag = ‘yes’.

No

history Only

Text

( – This defaults from Clients / Contract Defaults "History Only".

No

date Activated

Text

(*.

No

date Inactivated

Text

(*.

No

expiry Date

Text

(*.

No

cardsubstatus_id

Number

Pass the sub status you want for the card. I.e. .

No

status_flag

Text

Pass the status of the card. The default entry is 'active'.

No

notes

Text

Notes to be stored with the attachment

No

Audit-User-Id

Number

User Id to use for audit purposes. This header requires the Audit: UserIdOverride permission to be associated with your role.

No

Successful Response Example

{
  "_links": {
    "self": {
      "href": "https://api.test.catch-e.com/fm/cards/"
    }
  },
  "_embedded": {
    "fm_cards": [
      {
        "card_id": "100312",
        "contract_id": "104274",
        "card_number": "081412438765",
        "account_number": "4354365",
        "supplier_id": "100515",
        "posting_flag": "yes",
        "recharge_flag": "no",
        "client_id_recharge": "100240",
        "history_only_flag": "no",
        "activated_date": "2021-09-26",
        "inactivated_date": "2022-09-03",
        "expiry_date": "2023-09-03",
        "card_sub_status_id": "100001",
        "status_flag": "active",
        "notes": "kavyatest",
        "_links": {
          "self": {
            "href": "https://api.test.catch-e.com/fm/cards/100312"
          }
        }
      }
    ]
  },
  "total_items": 1
}

Error Response Details

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

}, "target_table": { "notInArray": "Unsupported target table" },|
 "contract_id": { "isEmpty": "Value is required and can't be empty"

 "card_number": { "duplicateCardNumber": "The specified card number already exists"
 "card_sub_status_id": { "noRecordFound": "No record matching the input was found"

 "client_id_recharge": { "noRecordFound": "No record matching the input was found"
 "expiry_date": { "dateFalseFormat": "The input does not fit the date format 'Y-m-d'", "dateInvalidDate": "The input does not appear to be a valid date"

 "posting_flag": { "rechargeClientRequired": "Recharge A/c be blank if 'Posting Enabled' is checked on"
 "supplier_id": { "noRecordFound": "No record matching the input was found"

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

Create mappings for a card interface

Qualifiers

  1. You want to use a new card interface

  2. You have linked a supplier to the interface

  3. You have reviewed the supplied product list and have noted which Class and VMRS Code you want to map each product to.

  4. See also the Card Interface Set-up page that contains Useful Queries

Manual Process

  1. Go to Fleet / Controls / Interfaces / Card Services

  2. Card Interface - enter or lookup the required code

  3. Navigate to Card Services / Mappings

  4. Click on **

  5. Product Code - enter the suppliers product code

  6. Description - enter the suppliers product description

  7. Class - enter or ?Search for the right class to link this product to

  8. VMRS - enter or ?Search for the right vmrs code to link this product to

  9. Fee - if required, enter a fee amount

  10. Click on **

Bulk Process

  1. Go to Fleet / Controls / Interfaces / Card Services

  2. Card Interface - enter or lookup the required code - note the Interface ID

  3. Navigate to Card Services / Mappings - note any pre-existing mappings

  4. Prepare an upload file for the table fminterfacevmrs_mappings - exclude any pre-existing mapping records

  5. The required fields for each record are listed below

  6. interfacevmrsmapping_id - enter the suppliers product code

  7. interface_id - enter the suppliers product code

  8. product_code - enter the suppliers product code

  9. postingclassid - enter the right postingclassid to link this product to

  10. vmrscodeid - enter the right vmrscodeid to link this product to

  11. description - enter the suppliers product description

  12. internalfeenet - if required, enter a fee amount

  13. Go to Setup / Import Table Data to import the file

Link a supplier to a card interface

Qualifiers

  1. You want to use a new card interface

  2. You have set-up a supplier for the card transactions

Process

  1. Go to Fleet / Controls / Interfaces / Card Services

  2. Card Interface - enter or lookup the required code

  3. 'Supplier' - enter the supplier code you want to use for this interface

  4. Click on ** to update the record

Update a list of cards

This method allows you to update card records in bulk.

This method requires the Cards:Update permission to be associated with your role.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on ** Cards:Update **.

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate

https://api.test.catch-e.com/fm/cards

Input Fields (Body)

JSON Field

Format

Notes

card_number

Number

Optional Card Number. This field supports the wildcard % operator (See Wildcard % operator notes below).

contract_id

Number

contract_id - Optional Contract Id

supplier_id

Number

Optional Supplier Id, Supplier must be of type 'card-services'

expiry_date

Date

Optional Expiry Date

page

integer($int32)

Optional page number

page_size

integer($int32)

Optional page size

Wildcard % operator notes:

If you are using "Postman" app, with the wildcard operator, the search string of either %ab% or %ba%, will give this response:

"field_name": {"isEmpty": "Value is required and can't be empty"}.

If you need to search either %ab% or %ba%, please use %25ab%25 or %25ba%25 as required to return results as expected.

Successful Response Example

{
  "_links": {
    "self": {
      "href": "https://api.test.catch-e.com/fm/cards/?page=1"
    },
    "first": {
      "href": "https://api.test.catch-e.com/fm/cards/"
    },
    "last": {
      "href": "https://api.test.catch-e.com/fm/cards/?page=12"
    },
    "next": {
      "href": "https://api.test.catch-e.com/fm/cards/?page=2"
    }
  },
  "_embedded": {
    "fm_cards": [
      {
        "card_id": "100000",
        "contract_id": "100237",
        "card_number": "12377734",
        "account_number": "",
        "supplier_id": "100459",
        "posting_flag": "no",
        "recharge_flag": "yes",
        "client_id_recharge": "100007",
        "history_only_flag": "no",
        "activated_date": "2005-07-01",
        "inactivated_date": "0000-00-00",
        "expiry_date": "2008-12-01",
        "card_sub_status_id": "0",
        "status_flag": "inactive",
        "notes": null,
        "_links": {
          "self": {
            "href": "https://api.test.catch-e.com/fm/cards/100000"
          }
        }
      }

Error Response Details

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}|
{ "validation_messages": { "contract_id": { "isEmpty": "Value is required and can't be empty" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"

}, "target_table": { "notInArray": "Unsupported target table" },|
{ "validation_messages": [ { "card_number": { "duplicateCardNumber": "The specified card number already exists" } }, { "card_number": { "duplicateCardNumber": "The specified card number already exists" } } ],|

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}
{ "validation_messages": { "posting_flag": { "rechargeClientRequired": "Recharge A/c be blank if 'Posting Enabled' is checked on" } },}|

{ "validation_messages": { "expiry_date": { "dateFalseFormat": "The input does not fit the date format 'Y-m-d'", "dateInvalidDate": "The input does not appear to be a valid date" } },}}
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 0, "detail": "string"}

Update card

This method allows you to update card details based on the selected card_id.

It performs the same function as editing a card in the Cards / Card Details tab.

This method requires the Cards:Update permission to be associated with your role.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate

https://api.test.catch-e.com/fm/cards/100313

Input Fields (Body)

JSON Field

Format

Notes

Mandatory

card_number

Number

Card number

Yes

card_id

Number

Card id

Yes

contract_id

Number

contract_id - Optional Contract Id

supplier_id

Number

Optional Supplier Id, Supplier must be of type 'card-services'

expiry_date

Date

Optional Expiry Date

page

integer($int32)

Optional page number

page_size

integer($int32)

Optional page size

Successful Response Example

{
  "card_id": "100313",
  "contract_id": "100313",
  "card_number": "10098799",
  "account_number": "123456",
  "supplier_id": "100514",
  "posting_flag": "yes",
  "recharge_flag": "no",
  "client_id_recharge": "100077",
  "history_only_flag": "no",
  "activated_date": "0000-00-00",
  "inactivated_date": "0000-00-00",
  "expiry_date": "0000-00-00",
  "card_sub_status_id": "0",
  "status_flag": "inactive",
  "notes": "",
  "_links": {
    "self": {
      "href": "https://api.test.catch-e.com/fm/cards/100313"
    }
  }
}

Error Response Details

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}|
{ "validation_messages": { "contract_id": { "isEmpty": "Value is required and can't be empty" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}
{ "validation_messages": { "attachment_id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}}

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