Page tree
Skip to end of metadata
Go to start of metadata

The FileMapping resource represents the data mapping schema from shipx-api to other systems when exporting data.

On this page

 

The FileMapping resource has the following attributes:

Attribute
Type
Description
hrefString

URI address to the resource.

nameString

Mapping file name.

formatString

Format of the file being sent.

format_parametersHash

Additional parameters related to conversion.

descriptionString

Description of the mapping file.

mappingHash

Object in the json format containing the mapping.

activeBoolean

The parameter determines whether the given mapping is active.

organization_idInteger

Organization's ID. In case it is not provided, the file mapping is global and should be visible in the context of all users.

Authentication

Access to the resource requires provision of the correct and valid access token for the Organization

List of mappings

GET v1/organizations/:id_organizacji/file_mappings

Search criteria

Parameter
Type
Actions
Example
nameString

Searches for mappings in which the name begins from the specified string.

?name=Nazwa
activeBoolean

Searches for active (true) and inactive (false) mappings.

?active=true

Sorting results

Search results can be sorted by the sort_by parameter provided, which can take the following values:

sort_by value
Action
Example
name

Sorts mappings by name.

?sort_by=name
active

Sorts mappings by activity.

?sort_by=active

Sorting can be done in two directions, using the sort_order parameter:

Value
Działanie
Example
asc

Action

?sort_order=asc&sort_by=name
desc

Sorts shipments descending

?sort_order=desc&sort_by=name


Sample request


GET /v1/organizations/1/file_mappings?active=true&sort_order=asc&sort_by=name HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json

Response


{
  "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/file_mappings?active=true&sort_by=name&sort_order=asc",
  "count": 3,
  "page": 1,
  "per_page": 30,
  "items": [
    {
      "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/file_mappings",
      "id": 1,
      "name": "wea",
      "format": "CSV",
      "format_parameters": {
    	"field_separator": ";",
    	"character_encoding": "UTF-8",
    	"text_qualifier": "\"",
    	"sheets_index": [0]
      },
      "description": "Opis",
      "mapping": {
        "custom_attributes": {
          "target_point": "target_point"
        },
        "insurance": {
          "amount": "insurance_amount",
          "currency": "insurance_currency"
        },
        "cod": {
          "amount": "cod_amount",
          "currency": "cod_currency"
        },
        "additional_services": [
          "email",
          "sms"
        ],
        "service": "service",
        "parcels": [
          {
            "weight": {
              "amount": "weight_amount",
              "unit": "weight_unit"
            },
            "dimensions": {
              "length": "length",
              "width": "width",
              "height": "height",
              "unit": "unit"
            }
          }
        ],
        "receiver": {
          "name": "receiver_name",
          "first_name": "receiver_first_name",
          "last_name": "receiver_last_name",
          "email": "receiver_email",
          "phone": "receiver_phone",
          "address": {
            "street": "receiver_address_street",
            "building_number": "receiver_address_building_number",
            "city": "receiver_address_city",
            "post_code": "receiver_address_post_code",
            "country_code": "receiver_address_country_code"
          }
        },
        "sender": {}
      },
      "active": true,
      "organization_id": null
    },
	...[ommited for brevity]...
  ]
}

Export a mapping to xfile

The data are sent through the API to the xfile system, which returns the mapped data according to the filtered formula.

POST /v1/organizations/:organization_id/file_mappings/export

Parameters

Param eter
Type
Description

Validation

nameString

Mapping file name.

The attribute is required

formatString 

Format of the file being sent. Available formats: csv, xls/xlsx, ods, xml.

The attribute is required

format_parameters

Hash

Format Parameters Form

Additional parameters related to conversion.

The attribute is required

contentString 

Encoded file with import data in Base64.

The attribute is required

descriptionString 

Description of the mapping file.

The attribute is not required

mapping_idInteger

Mapping ID which is saved in the database.

The attribute is required

•     The mapping_id parameter has a higher priority than the object provided in the mapping parameter

• By specifying mapping_id, the data are collected from the database and put automatically as mapping attribute

mapping

Hash

Mapping Form

Object in the json format containing the mapping. Required if

the mapping_id attribute is not provided.

Additional functions which can be used in the mapping:


• It is also possible to combine n columns into one, names of the columns to be separated by the string ###, e.g.:

"zlaczenie_dwoch_kolumn": "Account###Date of purchase" - returns the text collected from two columns, space-separated.

• The first name or surname can be distinguished when these are in one column: "first name ": "first name(Contact details)" - returns the text to the first space

"last name": "last name(Contact details)" - returns the text from the first space to the end

The attribute is required

• It becomes required when the mapping_id attribute is not provided

formHash

Additional parameters of the exported shipments.

The attribute is not required

organization_idInteger 

Organization's ID. In case it is not provided, the file mapping is global and should be visible in the context of all users.

The attribute is not required


Sample request

POST /v1/organizations/1/file_mappings/export HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
{
    "format" : "csv",
    "name" : "Name csv",
    "format_parameters" : {
    	"field_separator" : ";",
    	"character_encoding" : "UTF-8",
    	"text_qualifier" : "\"",
    	"sheets_index" : [0]
    },
    "form": {},
    "content" : "cmVjZWl2ZXJfZmlyc3RfbmFtZTtyZWNlaXZlcl9sYXN0X25hbWU7cmVjZWl2ZXJfbmFtZTtyZWNlaXZlcl9lbWFpbDtyZWNlaXZlcl9waG9uZTtyZWNlaXZlcl9hZGRyZXNzX3N0cmVldDtyZWNlaXZlcl9hZGRyZXNzX2J1aWxkaW5nX251bWJlcjtyZWNlaXZlcl9hZGRyZXNzX2NpdHk7cmVjZWl2ZXJfYWRkcmVzc19wb3N0X2NvZGU7cmVjZWl2ZXJfYWRkcmVzc19jb3VudHJ5X2NvZGU7dGFyZ2V0X3BvaW50O2luc3VyYW5jZV9hbW91bnQ7aW5zdXJhbmNlX2N1cnJlbmN5O2NvZF9hbW91bnQ7Y29kX2N1cnJlbmN5O3NlcnZpY2U7bGVuZ3RoO3dpZHRoO2hlaWdodDt1bml0O3dlaWdodF9hbW91bnQ7d2VpZ2h0X3VuaXQNCkphbjtLb3dhbHNraTtKYW47amFuQGtvd2Fsc2tpLnBsOzEyMzEyMzEyMztaYXdpxYJhOzY1bDtLcmFrw7N3OzMwLTMzMztQTDtBMTIzOzEwMDtQTE47MTAwO1BMTjtpbnBvc3RfbG9ja2VyX3N0YW5kYXJkOzI0MDA7MjQwMDszNTAwO21tOzMwO2tnDQpNYXJpYW47S293YWxza2k7TWFyaWFuO21hcmlhbkBrb3dhbHNraS5wbDsxMjMxMjMxMjM7UnluZWs7MTI7S3Jha8OzdzszMC0zMzM7UEw7QTEyMzsxMDtQTE47MTA7UExOO2lucG9zdF9sb2NrZXJfc3RhbmRhcmQ7MjQwMDsyNDAwOzM1MDA7bW07MjU7a2c",
    "mapping" : {
        "custom_attributes" : {
            "target_point" : "target_point"
        },
        "insurance" : {
            "amount" : "insurance_amount",
            "currency" : "insurance_currency"
        },
        "cod": {
            "amount" : "cod_amount",
            "currency" : "cod_currency"
        },
        "additional_services" : ["email", "sms"],
        "service" : "service",
        "parcels" : [
            {
                "dimensions": {
                    "length": "length",
                    "width": "width",
                    "height": "height",
                    "unit": "unit"
                },
               "weight": {
                   "amount": "weight_amount",
                   "unit": "weight_unit"
               }
           }
       ],
       "receiver": {
           "first_name": "receiver_ first_name",
           "last_name": "receiver_last_name",
           "name": "receiver_name",
           "email": "receiver_email",
           "phone": "receiver_phone",
           "address": {
               "street": "receiver_address_street",
               "building_number": "receiver_address_building_number",
               "city": "receiver_address_city",
               "post_code": "receiver_address_post_code",
               "country_code": "receiver_address_country_code"
           }
       },
       "sender": {}
    }
}

Response

 {
  "href": "https://api-shipx-pl.easypack24.net/v1/organizations/115/file_mappings",
  "id": 115,
  "name": "Name csv",
  "format": "csv",
  "format_parameters": {
    "field_separator": ";",
    "character_encoding": "UTF-8",
    "text_qualifier": "\"",
    "sheets_index": [0]
  },
  "description": null,
  "content": "cmVjZWl2ZXJfZmlyc3RfbmFtZTtyZWNlaXZlcl9sYXN0X25hbWU7cmVjZWl2ZXJfbmFtZTtyZWNlaXZlcl9lbWFpbDtyZWNlaXZlcl9waG9uZTtyZWNlaXZlcl9hZGRyZXNzX3N0cmVldDtyZWNlaXZlcl9hZGRyZXNzX2J1aWxkaW5nX251bWJlcjtyZWNlaXZlcl9hZGRyZXNzX2NpdHk7cmVjZWl2ZXJfYWRkcmVzc19wb3N0X2NvZGU7cmVjZWl2ZXJfYWRkcmVzc19jb3VudHJ5X2NvZGU7dGFyZ2V0X3BvaW50O2luc3VyYW5jZV9hbW91bnQ7aW5zdXJhbmNlX2N1cnJlbmN5O2NvZF9hbW91bnQ7Y29kX2N1cnJlbmN5O3NlcnZpY2U7bGVuZ3RoO3dpZHRoO2hlaWdodDt1bml0O3dlaWdodF9hbW91bnQ7d2VpZ2h0X3VuaXQNCkphbjtLb3dhbHNraTtKYW47amFuQGtvd2Fsc2tpLnBsOzEyMzEyMzEyMztaYXdpxYJhOzY1bDtLcmFrw7N3OzMwLTMzMztQTDtBMTIzOzEwMDtQTE47MTAwO1BMTjtpbnBvc3RfbG9ja2VyX3N0YW5kYXJkOzI0MDA7MjQwMDszNTAwO21tOzMwO2tnDQpNYXJpYW47S293YWxza2k7TWFyaWFuO21hcmlhbkBrb3dhbHNraS5wbDsxMjMxMjMxMjM7UnluZWs7MTI7S3Jha8OzdzszMC0zMzM7UEw7QTEyMzsxMDtQTE47MTA7UExOO2lucG9zdF9sb2NrZXJfc3RhbmRhcmQ7MjQwMDsyNDAwOzM1MDA7bW07MjU7a2c",
  "mapping": {
    "service": "service",
    "additional_services": [
      "email",
      "sms"
    ],
    "custom_attributes": {
      "target_point": "target_point"
    },
    "insurance": {
      "amount": "insurance_amount",
      "currency": "insurance_currency"
    },
    "cod": {
      "amount": "cod_amount",
      "currency": "cod_currency"
    },
    "parcels": [
      {
        "weight": {
          "amount": "weight_amount",
          "unit": "weight_unit"
        },
        "dimensions": {
          "length": "length",
          "width": "width",
          "height": "height",
          "unit": "unit"
        }
      }
    ],
    "receiver": {
      "name": "receiver_name",
      "first_name": "receiver_ first_name",
      "last_name": "receiver_last_name",
      "email": "receiver_email",
      "phone": "receiver_phone",
      "address": {
        "street": "receiver_address_street",
        "building_number": "receiver_address_building_number",
        "city": "receiver_address_city",
        "post_code": "receiver_address_post_code",
        "country_code": "receiver_address_country_code"
      }
    },
    "sender": {}
  },
  "xfile": [
    {
      "service": "inpost_locker_standard",
      "additional_services": [
        "",
        ""
      ],
      "custom_attributes": {
        "target_point": "A123"
      },
      "insurance": {
        "amount": "100",
        "currency": "PLN"
      },
      "cod": {
        "amount": "100",
        "currency": "PLN"
      },
      "parcels": [
        {
          "weight": {
            "amount": "30",
            "unit": "kg"
          },
          "dimensions": {
            "length": "2400",
            "width": "2400",
            "height": "3500",
            "unit": "mm"
          }
        }
      ],
      "receiver": {
        "name": "Jan",
        "first_name": "",
        "last_name": "Kowalski",
        "email": "jan@kowalski.pl",
        "phone": "123123123",
        "address": {
          "street": "Zawiła",
          "building_number": "65l",
          "city": "Kraków",
          "post_code": "30-333",
          "country_code": "PL"
        }
      },
      "sender": {}
    },
    {
      "service": "inpost_locker_standard",
      "additional_services": [
        "",
        ""
      ],
      "custom_attributes": {
        "target_point": "A123"
      },
      "insurance": {
        "amount": "10",
        "currency": "PLN"
      },
      "cod": {
        "amount": "10",
        "currency": "PLN"
      },
      "parcels": [
        {
          "weight": {
            "amount": "25",
            "unit": "kg"
          },
          "dimensions": {
            "length": "2400",
            "width": "2400",
            "height": "3500",
            "unit": "mm"
          }
        }
      ],
      "receiver": {
        "name": "Marian",
        "first_name": "",
        "last_name": "Kowalski",
        "email": "marian@kowalski.pl",
        "phone": "123123123",
        "address": {
          "street": "Rynek",
          "building_number": "12",
          "city": "Kraków",
          "post_code": "30-333",
          "country_code": "PL"
        }
      },
      "sender": {}
    }
  ],
  "form": {},
  "organization_id": 1,
  "created_at": "2017-06-09T11:41:10.737+02:00"
}

Export view

GET /v1/organizations/:organization_id/file_mappings/export/:id

Sample request


GET /v1/organizations/1/file_mappings/export/1 HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json

Response


{
    "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/file_mappings/export/1",
    "id": 1,
    "name": "Name csv",
    "format": "csv",
    "format_parameters": {
        "field_separator": ";",
        "character_encoding": "UTF-8",
        "text_qualifier": "\"",
        "sheets_index": [
            0
        ]
    },
    "description": null,
    "content": "cmVjZWl2ZXJfZmlyc3RfbmFtZTtyZWNlaXZlcl9sYXN0X25hbWU7cmVjZWl2ZXJfbmFtZTtyZWNlaXZlcl9lbWFpbDtyZWNlaXZlcl9waG9uZTtyZWNlaXZlcl9hZGRyZXNzX3N0cmVldDtyZWNlaXZlcl9hZGRyZXNzX2J1aWxkaW5nX251bWJlcjtyZWNlaXZlcl9hZGRyZXNzX2NpdHk7cmVjZWl2ZXJfYWRkcmVzc19wb3N0X2NvZGU7cmVjZWl2ZXJfYWRkcmVzc19jb3VudHJ5X2NvZGU7dGFyZ2V0X3BvaW50O2luc3VyYW5jZV9hbW91bnQ7aW5zdXJhbmNlX2N1cnJlbmN5O2NvZF9hbW91bnQ7Y29kX2N1cnJlbmN5O3NlcnZpY2U7bGVuZ3RoO3dpZHRoO2hlaWdodDt1bml0O3dlaWdodF9hbW91bnQ7d2VpZ2h0X3VuaXQNCkphbjtLb3dhbHNraTtKYW47amFuQGtvd2Fsc2tpLnBsOzEyMzEyMzEyMztaYXdpxYJhOzY1bDtLcmFrw7N3OzMwLTMzMztQTDtBMTIzOzEwMDtQTE47MTAwO1BMTjtpbnBvc3RfbG9ja2VyX3N0YW5kYXJkOzI0MDA7MjQwMDszNTAwO21tOzMwO2tnDQpNYXJpYW47S293YWxza2k7TWFyaWFuO21hcmlhbkBrb3dhbHNraS5wbDsxMjMxMjMxMjM7UnluZWs7MTI7S3Jha8OzdzszMC0zMzM7UEw7QTEyMzsxMDtQTE47MTA7UExOO2lucG9zdF9sb2NrZXJfc3RhbmRhcmQ7MjQwMDsyNDAwOzM1MDA7bW07MjU7a2c",
    "mapping_id": null,
    "mapping": {
        "service": "service",
        "additional_services": [
            "email",
            "sms"
        ],
        "custom_attributes": {
            "target_point": "target_point"
        },
        "insurance": {
            "amount": "insurance_amount",
            "currency": "insurance_currency"
        },
        "cod": {
            "amount": "cod_amount",
            "currency": "cod_currency"
        },
        "parcels": [
            {
                "weight": {
                    "amount": "weight_amount",
                    "unit": "weight_unit"
                },
                "dimensions": {
                    "length": "length",
                    "width": "width",
                    "height": "height",
                    "unit": "unit"
                }
            }
        ],
        "receiver": {
            "name": "receiver_name",
            "first_name": "receiver_ first_name",
            "last_name": "receiver_last_name",
            "email": "receiver_email",
            "phone": "receiver_phone",
            "address": {
                "street": "receiver_address_street",
                "building_number": "receiver_address_building_number",
                "city": "receiver_address_city",
                "post_code": "receiver_address_post_code",
                "country_code": "receiver_address_country_code"
            }
        },
        "sender": {}
    },
    "xfile": [
        {
            "service": "inpost_locker_standard",
            "additional_services": [
                "",
                ""
            ],
            "custom_attributes": {
                "target_point": "A123"
            },
            "insurance": {
                "amount": "100",
                "currency": "PLN"
            },
            "cod": {
                "amount": "100",
                "currency": "PLN"
            },
            "parcels": [
                {
                    "weight": {
                        "amount": "30",
                        "unit": "kg"
                    },
                    "dimensions": {
                        "length": "2400",
                        "width": "2400",
                        "height": "3500",
                        "unit": "mm"
                    }
                }
            ],
            "receiver": {
                "name": "Jan",
                "first_name": "",
                "last_name": "Kowalski",
                "email": "jan@kowalski.pl",
                "phone": "123123123",
                "address": {
                    "street": "Zawiła",
                    "building_number": "65l",
                    "city": "Kraków",
                    "post_code": "30-333",
                    "country_code": "PL"
                }
            },
            "sender": {}
        },
        {
            "service": "inpost_locker_standard",
            "additional_services": [
                "",
                ""
            ],
            "custom_attributes": {
                "target_point": "A123"
            },
            "insurance": {
                "amount": "10",
                "currency": "PLN"
            },
            "cod": {
                "amount": "10",
                "currency": "PLN"
            },
            "parcels": [
                {
                    "weight": {
                        "amount": "25",
                        "unit": "kg"
                    },
                    "dimensions": {
                        "length": "2400",
                        "width": "2400",
                        "height": "3500",
                        "unit": "mm"
                    }
                }
            ],
            "receiver": {
                "name": "Marian",
                "first_name": "",
                "last_name": "Kowalski",
                "email": "marian@kowalski.pl",
                "phone": "123123123",
                "address": {
                    "street": "Rynek",
                    "building_number": "12",
                    "city": "Kraków",
                    "post_code": "30-333",
                    "country_code": "PL"
                }
            },
            "sender": {}
        }
    ],
    "form": {},
    "organization_id": 1,
    "created_at": "2017-07-17T11:34:04.375+02:00"
}
  • No labels