Skip to content
API Reference
/
Transportations

iF returns - Inverse Logistic API (1.2.10)

API to allow the integration with merchants

Download OpenAPI description
returns.json
returns.yaml
Overview
E-mail

dev@ifreturns.com

Languages
Servers
Mock server

https://docs.ifreturns.com/_mock/apis/returns/

Development Server

https://api.dev.ifreturns.com/integration/v1/

Staging Server

https://api.stg.ifreturns.com/integration/v1/

Production Server

https://api.ifreturns.com/integration/v1/

iFreturns REST API

integration with merchants

Returns

Operations

Order Cancellation Returns

Operations

Store Returns

Operations

Gradings of Return

Operations

Transportations

Operations

Register tracking status

Request

It allows to update the tracking status of an active tranportation

Security
bearerAuth
Bodyapplication/json
shopCodestring

Shop code which belongs the shipment. In case this field is not informed, it will be obtained from security context. In case it is informed, it will be validated against the security context. This field is mandatory in case the token is associated with two or more merchants

Example: "marchelacolombine"
shipmentIdstringrequired

ID of the shipment. The ID must exist in the platform. API will use this value to search the shipment whose status will be updated.

Example: "R1-64231"
shipmentIdTypestringrequired

Type of ID that is being reported * RETURN_NAME - Name of the return. The last active shipment/transport will be searched. This value is generated by iF at the moment the return request is created. It has the format R#-{ORDER_NAME} (R1-64231)

Value"RETURN_NAME"
Example: "RETURN_NAME"
carrierNamestring

Carrier responsible for the shipment

Example: "UPS"
trackingNumberstring

Tracking number for the shipping

Example: "1Z4E61W19106005862"
trackingUrlstring

Tracking URL for the shipping

Example: "https://www.ups.com/tracknum=1Z4E61W19106005862"
trackingStatusstring(TransportationStatus)required

Status of the shipment/transport

Enum"REQUESTED""PICK_UP_IN_PROGRESS""PICK_UP_COMPLETED""SHIPPING_IN_PROGRESS""SHIPPING_COMPLETED""PICK_UP_FAILED""PICK_UP_CANCELLED""SHIPPING_FAILED""SHIPPING_CANCELLED"
Example: "SHIPPING_IN_PROGRESS"
trackingStatusDescriptionstring

Description of the status description

Example: "Package assigned to the driver"
trackingDatestring(date)

Date of the tracking event. In case is not present, the current date will be used

Example: "2011-08-12T20:17:46Z"
curl -i -X POST \
  https://docs.ifreturns.com/_mock/apis/returns/shipping_trackings \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shopCode": "marchelacolombine",
    "shipmentId": "R1-64231",
    "shipmentIdType": "RETURN_NAME",
    "carrierName": "UPS",
    "trackingNumber": "1Z4E61W19106005862",
    "trackingUrl": "https://www.ups.com/tracknum=1Z4E61W19106005862",
    "trackingStatus": "SHIPPING_IN_PROGRESS",
    "trackingStatusDescription": "Package assigned to the driver",
    "trackingDate": "2011-08-12T20:17:46Z"
  }'

Responses

Successful operation

Bodyapplication/json
statusCodestring
Example: "200"
descriptionstring
Example: "Your tracking have been registered correctly"
Response
application/json
{
  "statusCode": "200",
  "description": "Your tracking have been registered correctly"
}

Create shipping label

Request

Create a shipping label for the transportation of the items

Security
bearerAuth
Bodyapplication/json
shopCodestring

Shop code which belongs the shipment. In case this field is not informed, it will be obtained from security context. In case it is informed, it will be validated against the security context

Example: "marchelacolombine"
shipmentTypestring

Shiptment type

Enum"ORDER""RETURN"
Example: "RETURN"
clientShipmentIdstringrequired

ID of the shipment assigned by the merchant. It will be communicated to the carrier in order to be printed in the label

Example: "SHP123"
clientShipmentNamestring

Name of the shipment assigned by the merchant

Example: "S123"
carrierServiceCodestringrequired

Code of the carrier connection

Example: "IF-UPS-EXPRESS-SAVER"
labelFormatstring(LabelFormatInput)required

Allow to request a specific label format. In case is not informed, the default format for the carrier will be used. In case the carrier does not support the requested format, the default format for the carrier will be used. The final format will be included in the response

Enum"PDF""ZPL"
shipperobject

Shipper for the transportation

originobjectrequired

Origin address for the transportation

origin.​fullNamestringrequired

Full name associated to the origin

Example: "Juan Perez"
origin.​codestring

Code associated to the origin

Example: "Juan Perez"
origin.​emailstringrequired

Email associated to the origin

Example: "customer@if.com"
origin.​phonestringrequired

Phone associated to the origin

Example: 34666666666
origin.​addressobject(Address)
destinationobjectrequired

Destination address for the transportation

destination.​fullNamestringrequired

Full name of the destination

Example: "iF warehouse"
destination.​codestring

Code associated to the destination

destination.​emailstringrequired

Email associated to the destination

Example: "warehouse@if.com"
destination.​phonestringrequired

Phone associated to the destination

Example: 34666666666
destination.​addressobject(Address)
parcelsArray of objects(Parcel)
customsInfoArray of objects
curl -i -X POST \
  https://docs.ifreturns.com/_mock/apis/returns/shipping_labels \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shopCode": "marchelacolombine",
    "shipmentType": "RETURN",
    "clientShipmentId": "SHP123",
    "clientShipmentName": "S123",
    "carrierServiceCode": "IF-UPS-EXPRESS-SAVER",
    "labelFormat": "PDF",
    "shipper": {
      "fullName": "iF warehouse",
      "email": "warehouse@if.com",
      "phone": 34666666666,
      "address": {
        "line1": "Calle de Fortunata y Jacinta 12",
        "line2": "",
        "city": "Madrid",
        "postalCode": "28020",
        "region": "Madrid",
        "countryCode": "ES"
      }
    },
    "origin": {
      "fullName": "Juan Perez",
      "code": "Juan Perez",
      "email": "customer@if.com",
      "phone": 34666666666,
      "address": {
        "line1": "Calle de Fortunata y Jacinta 12",
        "line2": "",
        "city": "Madrid",
        "postalCode": "28020",
        "region": "Madrid",
        "countryCode": "ES"
      }
    },
    "destination": {
      "fullName": "iF warehouse",
      "code": "string",
      "email": "warehouse@if.com",
      "phone": 34666666666,
      "address": {
        "line1": "Calle de Fortunata y Jacinta 12",
        "line2": "",
        "city": "Madrid",
        "postalCode": "28020",
        "region": "Madrid",
        "countryCode": "ES"
      }
    },
    "parcels": [
      {
        "clientParcelId": "P001",
        "description": "Goods",
        "weight": 1000,
        "height": 10,
        "length": 10,
        "width": 10
      }
    ],
    "customsInfo": [
      {
        "description": "Goods",
        "hsCode": 40159000,
        "weight": 1,
        "quantity": 1,
        "unitPrice": 120,
        "currencyCode": "EUR",
        "originCountryCode": 120
      }
    ]
  }'

Responses

Successful operation

Bodyapplication/json
carrierCodestring

Carrier code associated to the shipment

Example: "ups"
carrierExternalCodestring

External carrier code associated to the shipment

Example: 20000008
carrierServiceCodestring

Carrier service associated to the shipment

Example: "IF-UPS-EXPRESS-SAVER"
clientShipmentIdstring

ID of the shipment assigned by the merchant

Example: "SHP123"
shippingLabelsArray of objects

List of shipping labels

Response
application/json
{
  "carrierCode": "ups",
  "carrierExternalCode": 20000008,
  "carrierServiceCode": "IF-UPS-EXPRESS-SAVER",
  "clientShipmentId": "SHP123",
  "shippingLabels": [
    { … }
  ]
}

Get a shipping label

Request

Get an existing shipping label

Security
bearerAuth
Query
client_shipment_idstringrequired

ID of the shipment assigned by the merchant

Example: client_shipment_id=SHP123
shopCodestring

Shop code which belongs the shipping label. In case this field is not informed, it will be obtained from security context. In case it is informed, it will be validated against the security context

Example: shopCode=marchelacolombine
curl -i -X GET \
  'https://docs.ifreturns.com/_mock/apis/returns/shipping_labels?client_shipment_id=SHP123&shopCode=marchelacolombine' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful operation

Bodyapplication/jsonArray [
carrierCodestring

Carrier code associated to the shipment

Example: "ups"
carrierExternalCodestring

External carrier code associated to the shipment

Example: 20000008
carrierServiceCodestring

Carrier service associated to the shipment

Example: "IF-UPS-EXPRESS-SAVER"
clientShipmentIdstring

ID of the shipment assigned by the merchant

Example: "SHP123"
shippingLabelsArray of objects

List of shipping labels

]
Response
application/json
[
  {
    "carrierCode": "ups",
    "carrierExternalCode": 20000008,
    "carrierServiceCode": "IF-UPS-EXPRESS-SAVER",
    "clientShipmentId": "SHP123",
    "shippingLabels": [ … ]
  }
]

Update the shipping label

Request

It allows to update the shipping label of an existing transportation in the platform

Security
bearerAuth
Bodyapplication/json
shopCodestring

Shop code which belongs the shipment. In case this field is not informed, it will be obtained from security context. In case it is informed, it will be validated against the security context. This field is mandatory in case the token is associated with two or more merchants

Example: "marchelacolombine"
shipmentIdstringrequired

ID of the shipment. The ID must exist in the platform. Platform will use this value to search the shipment whose status will be updated.

Example: "64231-R1"
shipmentIdTypestringrequired

Type of ID that is being reported * RETURN_NAME - Name of the return. The last active shipment/transport will be searched. This value is generated by iF at the moment the return request is created. It has the format R#-{ORDER_NAME} (R1-64231) * CLIENT_REFERENCE - Shipping reference assigned for the shipment/transport. This value is generated by iF at the moment the transport is created. It has the format P#R#{MERCHANT-SHORT-CODE}{ORDER_NAME} (P1R1maco64231) * MERCHANT_RETURN_NAME - Name of the return in the ecommerce platform. The last active shipment/transport will be searched. This value is generated by the merchant system when the return is registered. The format is defined by the merchant (e.g. in Shopify the return name is 64231-R1)

Enum"RETURN_NAME""CLIENT_REFERENCE""MERCHANT_RETURN_NAME"
Example: "MERCHANT_RETURN_NAME"
shippingLabelsArray of objectsrequired

List of shipping labels

shippingLabels[].​carrierTrackingCodestringrequired

Reference assigned by the carrier to the shipment

Example: "PARC0001"
shippingLabels[].​additionalTrackingCodesArray of strings
Example: ["S4848554544545"]
shippingLabels[].​carrierTrackingUrlstringrequired

URL for shipment tracking

Example: "https://carrier.com/tracking/S4848554544545"
shippingLabels[].​formatstring(LabelFormat)required

Format of the label or free-label code

Enum"PDF""ZPL""PNG"
shippingLabels[].​urlstringrequired

URL for getting the shipping label

Example: "https://if.com/shippping_label.pdf"
curl -i -X PUT \
  https://docs.ifreturns.com/_mock/apis/returns/shipping_labels \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shopCode": "marchelacolombine",
    "shipmentId": "64231-R1",
    "shipmentIdType": "MERCHANT_RETURN_NAME",
    "shippingLabels": [
      {
        "carrierTrackingCode": "PARC0001",
        "additionalTrackingCodes": [
          "S4848554544545"
        ],
        "carrierTrackingUrl": "https://carrier.com/tracking/S4848554544545",
        "format": "PDF",
        "url": "https://if.com/shippping_label.pdf"
      }
    ]
  }'

Responses

Successful operation

Bodyapplication/json
statusCodestring
Example: "200"
descriptionstring
Example: "Your shipping label have been updated correctly"
Response
application/json
{
  "statusCode": "200",
  "description": "Your shipping label have been updated correctly"
}

Calculate available PUDOs

Request

Calculate the PUDOs can be used to ship the items. The PUDOs are calculated based on a reference address. Before call this endpoint, the list of avaiable return methods should be calculated in order to obtain the carrier data. It is mandatory to inform either the address or the geolocation data

Security
bearerAuth
Bodyapplication/json
shopCodestring

Shop code which belongs the shipment. In case this field is not informed, it will be obtained from security context. In case it is informed, it will be validated against the security context

Example: "marchelacolombine"
carrierServicesArray of objects

List of carrier service connections from which the PUDOs will be obtained

Example: [{"code":"IF-UPS-EXPRESS-SAVER"},{"code":"IF-SEUR-HOME2SHOP"}]
limitnumber

Number of PUDOs to be listed

Example: 10
addressstring

Reference address information

Example: "C. Juan de Mena 8"
citystring

City of the reference address

Example: "Madrid"
postalCodestring

Postal code of the reference address

Example: "28010"
countryCodestring

Country code of the reference address

Example: "ES"
latitudenumber(float)

Latitude of the reference address. If this field is informed will have more priority than address

Example: 40.323132
longitudenumber(float)

Longitude of the reference address. If this field is informed will have more priority than address

Example: -3.434343
rangenumber

Range search area in km. Min 1 and Max 20

Example: 10
locationTypestring(LocationType)

Optional parameter used to filter PUDOs by location type. By default all location types are listed.

Enum"ALL""STORE_POINT""LOCKER_POINT"
curl -i -X POST \
  https://docs.ifreturns.com/_mock/apis/returns/pudos \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shopCode": "marchelacolombine",
    "carrierServices": [
      {
        "code": "IF-UPS-EXPRESS-SAVER"
      },
      {
        "code": "IF-SEUR-HOME2SHOP"
      }
    ],
    "limit": 10,
    "address": "C. Juan de Mena 8",
    "city": "Madrid",
    "postalCode": "28010",
    "countryCode": "ES",
    "latitude": 40.323132,
    "longitude": -3.434343,
    "range": 10,
    "locationType": "ALL"
  }'

Responses

Successful operation

Bodyapplication/jsonArray [
carrierCodestring

Carrier code associated with the PUDOs

Example: "ups"
carrierExternalCodestring

Carrier code associated with the PUDOs

Example: "20000008"
pudoPointsArray of objects(CalculatedPudo)

List of available PUDOs for the carrier

]
Response
application/json
[
  {
    "carrierCode": "ups",
    "carrierExternalCode": "20000008",
    "pudoPoints": [ … ]
  }
]

Return Methods

Operations