[1.23.0] File mapping

Warning!

The resource is available only in the following countries: PL

FileMapping resource represents data mapping schema from shipx-api to other systems on data export.


On this page

Structure

FileMapping resource has the following attributes:

Attribute
Type
Description
Availability
hrefStringResource URI address.PL
nameStringMapping file name.PL
formatStringFormat of the file being sent.PL
format_parametersHashAdditional parameter related to conversion.PL
descriptionStringMapping file description.PL
mappingHashJSON format object containing the mapping.PL
activeBooleanParameter deciding whether or not the mapping is active.PL
organization_idIntegerOrganisation ID. In case it is not provided, the file mapping is global and should be visible in the context of all users.PL



Authentication

Access to the resource requires a valid access token.



List of File Mappings

GET v1/organizations/:organization_id/file_mappings

Search criteria

Parameter
Type
Description
Example
Availability
nameStringSearches for mappings for which the name starts with the given string.?name=NazwaPL
activeBooleanSearches for active mappings when true, inactive mappings when false?active=truePL

Result sorting

Search result sorting can be facilitated using the sort_by attribute, which can take the following values:

sort_by value
Description
Example
Availability
nameSorts by name?sort_by=namePL
activeSorts by active?sort_by=activePL

Sort ordering can be set using sort_order  attribute.

sort_order value
Description
Example
Availability
ascSorts in ascending order?sort_order=asc&sort_by=namePL
descSorts in descending order?sort_order=desc&sort_by=namePL

Example request

curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/file_mappings?active=true&sort_order=asc&sort_by=name -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Response

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "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
    },
	{...},
	{...}
  ]
}



Xfile mapping export

Data is sent through the API to the xfile system, which returns the data mapped according to the sent form.

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

Parameters

Parameter
Type
Description

Validation

Availability
nameStringNazwa pliku mapowania.The attribute is requiredPL
formatString Format przesyłanego pliku. Dostępne formaty: csv, xls/xlsx, ods, xml.The attribute is requiredPL
format_parameters

Format Parameters

Dodatkowe parametry związane z konwersja.The attribute is requiredPL
contentString Zakodowany plik z danymi z importu w Base64.The attribute is requiredPL
descriptionString Opis pliku mapowania.

The attribute is not required

PL
mapping_idInteger

Identyfikator mapowania który jest zapisany w bazie.

The attribute is required

  • mapping_id has a higher priority than the mapping object parameter
  • By specifying mapping_id , the data are collected from the database and put automatically as mapping attribute
PL
mapping

Mapping

JSON format object containing the mapping. Required if  mapping_id is not provided.
Additional function which can be used in the mapping:

  • It is possible to combine n columns into one, names of the columns should be separated by ###, eg.:
    "columb_combination" : "Account###Date of purchase" -returns the text from both columns separated by space.
  • First name and surname can be separated if they 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
PL
formHashAdditional parameters of the exported shipments.

The attribute is not required

PL
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 requiredPL

Example request

curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/file_mappings/export -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
    "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

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "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

Example request

curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/file_mappings/export/10 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Response

HTTP/1.1 200 OK 
Content-Type: application/json
{
    "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"
}