Skip to content

Instantly share code, notes, and snippets.

@mgates

mgates/Partage API README.md

Last active August 29, 2015 14:01
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mgates/6b6dfc7a6852c03a5496 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mgates/6b6dfc7a6852c03a5496 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Partage API README.md

Partage API

The Partage API provides a simple and limited interface to the Partage brokerage system.

The latest version of this document can always be reached at http://gopartage.com/api.

Authentication

For now, authentication is done with an API token that is connected to your company.

If you do not have an API token for your company, send an email to seandevine@gopartage.com with a very brief description of what you plan to build.

Staging

The staging server is staging.gopartage.com. Once you are able to successfully integrate with the staging system, we'll move you over. We do sometimes use the staging server for internal testing, so it has a bit more downtime than production. Let us know if you think there is a problem.

Content Types

You must send an accept header the includes application/json; */* is fine.

You must send a content type of application/json when posting JSON.

Create Quote

POST http://www.gopartage.com/api/quotes will create a new quote from the parameters passed.

Acceptable equipment types are van, flatbed, and refrigerated.

Request

{
  "api_token":"your_api_token",
  "quote":{
    "equipment":"van",
    "origin_postal_code":"60612",
    "destination_postal_code":"12186"
  }
}

If you would like to receive only full truckload rates, you may add '"ftl_only": true' inside the quote section.

Response

In addition to echoing the some of the request parameters, the response includes:

  • Number: Used to reference the quote with Partage.
  • URL: Location of the quote in the Partage system.
  • Options: One for each mode that is offered (truckload, partial_truckload and intermodal).
{
  "quote":{
    "destination_postal_code":"60612",
    "equipment":"van",
    "origin_postal_code":"12186",
    "pallet_spots":null,
    "weight":null,
    "miles": 888,
    "number":"2012-12-25-1",
    "url":"http://www.gopartage.com/companies/.../quotes/...",
    "options":[
      {
        "mode":"truckload",
        "total":1575
      },
      {
        "mode":"intermodal",
        "total":1212
      }
    ]
  }
}

If you'd like a partial truckload option as well, include the weight and pallet spots.

{
  "api_token":"your_api_token",
  "quote":{
    "equipment":"van",
    "origin_postal_code":"60612",
    "destination_postal_code":"12186",
    "weight": 10000,
    "pallet_spots": 10
  }
}

If your company has sub-companies (branches, franchises, etc) in the Partage system, you can create the quotes for them by supplying an external_id parameter.

{
  "api_token":"your_api_token",
  "external_id":"sub-company id",
  "quote":{
    "equipment":"van",
    "origin_postal_code":"60612",
    "destination_postal_code":"12186",
    "weight": 10000,
    "pallet_spots": 10
  }
}

You can set the unique external_ids for your sub-companies on http://www.gopartage.com by editing the their profile. See below for info on how to create them.

If you provide an external_id, you will receive an error if a child company is not found for your company with the external_id.

For an exact rate, or if you intend to book the quote through the API, you can add the origin and the destination address. This is in addition to the zipcodes, but must match.

{
    "api_token": "your_api_token",
    "external_id": "sub-company id",
    "own_credit: true,
    "quote": {
        "origin_postal_code": "60615",
        "destination_postal_code": "60612",
        "pallet_spots": 10,
        "weight": 10000
        "equipment": "van",
        "origin_address": {
            "name": "Pet Party Planners",
            "address_one": "5046 S Greenwood Ave",
            "address_two": "",
            "phone": "9879879876",
            "postal_code": "60615"
        },
        "destination_address": {
            "name": "Partage, LLC",
            "address_one": "333 North Oakley Blvd",
            "address_two": "Suite 200",
            "phone": "123-123-1234",
            "postal_code": "60612"
        }
    }
}

You must include the phone number, the address one, the name and the postal code. Address two is optional.

If you intend to book through the API, you will need to include commodity(a string), value and pieces(both numerics), too. You may add pallets.

Sub-companies

To keep track of different customers you can use sub-companies. You can add them by contacting Partage, or by making a request with the API. If you want seperate financial liability, we'll need enough information and time to assign a credit limit. We'll start with a small limit, to allow them to book the first load. You should not book a load with a new company that has to move in less that one buisness day, to allow time for the credit check.

You can see your main company and sub-companies:

GET /api/companies?api_token=...

  [
    {"name": "parent company"
     "external_id": null,
     "credit_limit": 10000,
     "credit_utilization": 6543,
    },
    {"name": "independent company"
     "external_id": "approved_independent_sub_company_sub_company",
     "credit_limit": 8000,
     "credit_utilization": 6000,
    },
    {"name": "dependent company"
     "external_id": "dependent_sub_company_sub_company",
     "credit_limit": null,
     "credit_utilization": 6000,
    }
  ]

You can create a new sub-company: POST /api/companies

{
  "api_token":"your_api_token",
  "company":{
    "external_id": "the id",
    "same_credit": false,
    "name": "A Subcompany Name",
    "duns_number": "Optional, free-form text",
    "location": {
      "address_one":"333 N Oakley",
      "address_two": "Suite 200",
      "postal_code":"60612"
    },
    "accounts_payable": {
      "first_name": "AP Contact Last Name",
      "last_name": "AP Contact First Name",
      "email": "ap@example.com",
      "phone": "123 123 1234"
    }
  }
}

Or, if you just need subcompanies for organizational reasons:

{
  "api_token":"your_api_token",
  "company":{
    "external_id": "the id",
    "same_credit": true,
    "name": "A Subcompany Name"
  }
}

Timing

You should add timing information if you intend to book the load, or want to know prices for weekend delivery, etc. All dates are local to the stop, and expressed in ISO 8601 notation, with no time zone indicator, like "1983-11-02".

You may be charged a close-in delivery fee if the pickup date is less than 24 hours away.

{
  "api_token":"your_api_token",
  "quote":{
    "equipment":"van",
    "origin_postal_code":"60612",
    "destination_postal_code":"12186"
    "timing": {
      "origin": "2014-07-27",
      "destination": "2014-07-31"
      }
    }
  }
}

You may add stop timing information, or use the defaults(8:00 open, 14:00 close) for any section. Use 24 hour time:

{
  "api_token":"your_api_token",
  "quote":{
    "equipment":"van",
    "origin_postal_code":"60612",
    "destination_postal_code":"12186"
    "timing": {
      "origin": "2014-07-27",
      "destination": "2014-07-31",
      "origin_open": "6:00",
      "destination_open": "6:30",
      "origin_close": "18:00",
      "destination_close": "18:30"
      }
    }
  }
}

You may omit the destination timing. We'll choose dates that won't incur extra fees.

Services

Services can be be attached on the load, origin, or destination. All of the load-level services happen automatically.

You can specify a services block:

"services": {
  "origin": {
    "Liftgate": 1,
    "Lumper": 30
  },
  "destination":{
    "Pallet Jack": 1
  }
}

These will be included in the prices you receive.:

You can specify the following services:

  • Coil Rack - $250 / stop
  • Drop Trailer - $300 / day
  • Dunnage - 2"x4" - $10.00
  • Extra Stop - $75.00 / stop
  • Layover - $350 / day
  • Liftgate - $250 / stop (LTL ONLY)
  • Lumper - Pass through + $10.00
  • Pallet Jack - $250 / stop
  • Same Day Booking - $100 / shipment
  • Tarps (4 ft) - $50 / stop
  • Tarps (6 ft) - $100 / stop
  • Tarps (8 ft) - $150 / stop
  • Warehousing - $350 / day

Show Quote

Request

GET http://www.gopartage.com/api/quotes/:id?api_token=... will get you the data of the quote for the passed id. You can use the number or pl_id fields as :id

Response

The response includes:

  • Number: Used to reference the quote with Partage.
  • Length
  • Weight
  • Pallets
  • Pallet Spots
  • Equipment Type
  • Rate: The booked rate with its total, who booked it, its charges, notes and the invoice
  • Carrier: Information about the booked carrier and who booked it
  • Shipments: The shipments containing the load with its information and notes
  • Stops: The stops of the quote with information about which shipment is involved in the stop, what type it is (pickup, drop), the location, window, schedule, notes and proof of delivery (only drop stop)
  • Special Services: Show all special services booked to the load
{
  "quote":{
    "pl_id":"PLWSC6",
    "number":"2012-08-22-100",
    "length":8,
    "weight":6792,
    "pallet_spots":4,
    "pallets":4,
    "equipment_type":"Van",
    "rate":{
      "booked_at":"2012-08-22T18:20:21Z",
      "booked_by":{
        "name":"Name of Customer User",
        "email":"Email of Customer User"
      },
      "total":300,
      "charges":[
        {
          "name":"Linehaul",
          "total":582,
          "unit_of_measure":"Mile",
          "units":534.7
        },
        {
          "name":"Consolidation",
          "total":-555,
          "unit_of_measure":"Dollar",
          "units":855
        },
        {
          "name":"Fuel",
          "total":273,
          "unit_of_measure":"Mile",
          "units":534.7
        },
        {
          "name":"Delay Time",
          "total":800,
          "unit_of_measure":"Day",
          "units":4.0
        }
      ],
      "notes":[
        {
          "content":"Call For Appointment",
          "user":{
            "name":"Name of User",
            "company":"Name of Company"
          },
          "attachment_url":null,
          "created_at":"2012-08-22T18:20:19Z"
        }
      ],
      "invoice":{
        "due_date":"2012-11-12",
        "adjustment":0,
        "total":300.0,
        "balance":300.0,
        "created_at":"2012-08-29T17:10:55Z",
        "approved_by":{
          "name":"Name of Partage User"
        },
        "approved_at":"2012-11-06T22:33:19Z",
        "notes":[
          {
            "content":"W220999016",
            "user":{
              "name":"Name of User",
              "company":"Name of Company"
            },
            "attachment_url":null,
            "created_at":"2012-11-06T22:33:13Z"
          }
        ]
      }
    },
    "carrier":{
      "name":"Name of Carrier",
      "mc_number":"MC...",
      "dot_number":"...",
      "covered_at":"2012-08-23T16:04:09Z",
      "booked_by":{
        "name":"Name of Partage User",
        "email":"Email of Partage User"
      }
    },
    "shipments":[
      {
        "id":20377,
        "weight":6792,
        "pallet_spots":4,
        "pallets":4,
        "commodity":"BBQ Sauce",
        "notes":[]
      }
    ],
    "stops":[
      {
        "shipments":[
          {
            "id":20377
          }
        ],
        "type":"pick",
        "location":{
          "street":"920 cable road",
          "city":"kansas city",
          "state":"mo",
          "postal_code":"64116"
        },
        "window":{
          "start_at":"2012-08-23T13:00:00Z",
          "end_at":"2012-08-23T20:00:00Z"
        },
        "schedule":{
          "arrived_at":"2012-08-23T17:00:00Z",
          "departed_at":"2012-08-23T19:00:00Z"
        },
        "notes":[
          {
            "content":"PICK UP #023EKC414514",
            "user":{
              "name":"Name of User",
              "company":"Name of Company"
            },
            "attachment_url":null,
            "created_at":"2012-08-23T16:21:09Z"
          }
        ]
      },
      {
        "shipments":[
          {
            "id":20377
          }
        ],
        "type":"drop",
        "location":{
          "street":"5151 AMERICAN WAY ",
          "city":"MEMPHIS",
          "state":"TN",
          "postal_code":"38115"
        },
        "window":{
          "start_at":"2012-08-29T16:00:00Z",
          "end_at":"2012-08-29T16:00:00Z"
        },
        "schedule":{
          "arrived_at":"2012-08-29T12:10:00Z",
          "departed_at":"2012-08-29T16:00:00Z"
        },
        "notes":[
          {
            "content":"Call For Appointment",
            "user":{
              "name":"Name of User",
              "company":"Name of Company"
            },
            "attachment_url":null,
            "created_at":"2012-08-22T18:20:10Z"
          }
        ],
        "proof_of_delivery": {
          "attachment_url": "https://s3.amazonaws.com/a_pod_file.pdf?AWSParams=some",
          "created_at": "2013-10-25T15:54:19Z"
        }
      }
    ],
    "special_services":[]
  }
}

Note: The Proof of Delivery is attached in its own proof_of_delivery field only for loads created after 09-18-2013. For prior loads it is attached as a note attachment on the drop stop.

Add A Note

You may add a note to a load.

Simply post to http://www.gopartage.com/api/quotes/:id/notes

{
  "api_token":"your_api_token",
  "note": {
    "content": "This is a note."
  }
}

Book Quote

If your company is set up to book via the api, you can book a quote you made via the api.

Post the choosen option to http://www.gopartage.com/api/quotes/:id/book.

{
  "api_token":"your_api_token",
  "mode":"intermodal",
}

If all goes well, you will get the same thing as the view action, of the booked quote.

Bill Of Lading

You can get the bill of lading after the load has been booked:

curl http://www.gopartage.com/api/quotes/<<QuoteNumber/bol.pdf?api_token=token

Obviously, you should be pulling down and caching the document to ensure that you don't expose the API token to the end user.

Cancel Quote

To cancel a quote that will not get a TONU fee (one that has either not been covered, or doesn't start today), post to http://www.gopartage.com/api/quotes/:id/cancel:

{
  "api_token":"your_api_token",
}

You will recive a 406 status with an explanatory message if a TONU fee might be incured.

Exception Handling

If there are any exceptions encountered, you will receive a status code in the 400 of 500 range, depending on the problem.

  • Authorization: 401
  • Invalid Request Format: 412
  • Invalid Quote: 406
  • Internal Application Error: 500

You will also receive a response describing the exception in the following format.

{
  "errors":["Invalid token. Company not found."]
}

Curl Examples

Anxious to get something working? Just add your api_token to these curl requests and you should receive a successful response.

curl http://www.goapartage.com/api/quotes -v -H "Content-type: application/json" -X POST -d '{"api_token":"valid_api_token","quote":{"destination_postal_code":"60654","equipment":"refrigerated","origin_postal_code":"12186"}}'

curl http://www.goapartage.com/api/quotes -v -H "Content-type: application/json" -X POST -d '{"api_token":"valid_api_token","quote":{"destination_postal_code":"60654","equipment":"van","origin_postal_code":"12186","weight":10000,"pallet_spots":10}}'

Retrieving a quote

Add the quote's number as :id to fetch your quote curl http://www.gopartage.com/api/quotes/:id?api_token=... -v -H "Content-type: application/json"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment