diff --git a/GetInvoices/README.md b/GetInvoices/README.md new file mode 100644 index 0000000..835adcc --- /dev/null +++ b/GetInvoices/README.md @@ -0,0 +1,4 @@ +GetInvoices +=========== + +EDI (API) Documentation for the Standard, XML-Based, Invoice Information for Customers diff --git a/GetInvoices/Sample.xml b/GetInvoices/Sample.xml new file mode 100644 index 0000000..7e63869 --- /dev/null +++ b/GetInvoices/Sample.xml @@ -0,0 +1,259 @@ + + + + 781912826 + 2007-01-04T10:23:11-06:00 + 2007-01-04T16:23:11Z + + Clarity2UserName + 0xC8CCDC91AB2DF9EC8D449E987E727CB8A67E1330 + + + + 6543210 + 0123456IN + 2013-04-04T17:00:00 + CustID + Customer Name + + 1 + 3 + 426 + 553.80 + + + + + 1234567 + H1234567 + RefNum + PONum + RMANum + SONum + 0123456IN + + + CustomControlNumber + 12345 + + + + Acknowledged + + R + Ground + WG + White Glove + + + + + Test Shipper + TestShip1 + ShipperEmail@example.com +
+ Test Shipper + Test Shipper Contact + 123 Main Street + + Mendota Heights + MN + + 55120 + US +
+ +
651-994-7500
+ + + + + + + + + Test Consignee + TestCons1 + ConsigneeEmail@example.com +
+ Test Consginee + Test Consignee Contact + 555 Any Street + + Eagan + MN + + 55123 + US +
+ +
651-905-7560
+ + + + + + + + + ABC Shipper + ABCCO + ABCShipper@example.com +
+ ABC Shipper, Inc. + Jane Doe + 900 9th Avenue + + Los Angeles + CA + + 90210 + US +
+ +
555-123-4567
+ + + + + + + + + ABC Shipper + ABCCO + ABCShipper@example.com +
+ ABC Shipper, Inc. + Jane Doe + 900 9th Avenue + + Los Angeles + CA + + 90210 + US +
+ +
555-123-4567
+ + + + + + + + + + 2013-04-01T00:00:00 + 2013-04-04T23:59:00 + + + + 2013-04-04T17:00:00 + + + + MSP + MSP + + + + 2975663 + 2 + 29 + 35 + 36 + 116.0000 + 146.1600 + 0.00 + + ProdABC + ABC Big Box + + + 2975664 + 1 + 36 + 29 + 32 + 94.0000 + 133.6320 + 0.00 + + ProdCDE + CDE Different Big Box + + + + 3 + 326 + 426 + 326 + + + + 100 + INSH + Inserted + 2013-04-01T10:47:31.093 + + + + 120 + CLUP + Clarity Update + 2013-04-01T10:50:22.167 + + + + + 1030 + Service Issue - Home + 2013-04-04T08:52:58 + Dog bit driver. + + + + + 63438902 + A1 + Freight Charge + Freight + S + System + 100.0000 + 426.0000 + 100.0000 + 426.00 + + + 63438903 + C022 + Fuel Surcharge + + U + Fuel Sensitive + 0.3000 + 426.0000 + 0.0000 + 127.80 + + + + 426.00 + 127.80 + 0.00 + 0.00 + 0.00 + 0.00 + 0.00 + 553.80 + + + Test special instructions. + + + + + \ No newline at end of file diff --git a/GetManifests/ManifestXMLOutbound-Response-Failure-Sample.xml b/GetManifests/ManifestXMLOutbound-Response-Failure-Sample.xml new file mode 100644 index 0000000..5074e05 --- /dev/null +++ b/GetManifests/ManifestXMLOutbound-Response-Failure-Sample.xml @@ -0,0 +1,23 @@ + + + + 781912826 + + + 13d133489f + + + 2012-10-18T21:02:17.300Z + + + 2012-10-18T16:02:17.300-05:00 + + + + + 1234 + + + Invalid service. + + \ No newline at end of file diff --git a/GetManifests/ManifestXMLOutbound-Response-Success-Sample.xml b/GetManifests/ManifestXMLOutbound-Response-Success-Sample.xml new file mode 100644 index 0000000..15c7f22 --- /dev/null +++ b/GetManifests/ManifestXMLOutbound-Response-Success-Sample.xml @@ -0,0 +1,22 @@ + + + + 781912826 + + + 13d133489f + + + 2012-10-18T21:02:17.300Z + + + 2012-10-18T16:02:17.300-05:00 + + + ABC8181j238a + + + + + + \ No newline at end of file diff --git a/GetManifests/ManifestXMLOutbound-Sample.xml b/GetManifests/ManifestXMLOutbound-Sample.xml new file mode 100644 index 0000000..f46149e --- /dev/null +++ b/GetManifests/ManifestXMLOutbound-Sample.xml @@ -0,0 +1,200 @@ + + + + 781912826 + + + 2007-04-01T13:39:00 + + + 2007-04-01T08:39:00 + + + MFSUserName + MFSPassword + + + + + ABC123 + + + Carrier + + + MAWB + + WR + White Glove Assembly and Removal + White Glove + Assembly + Removal + 2-person service plus light assembly required; bring inside to client-specified location, unpack, follow specified assembly instructions and remove requested commodity & dunnage (unless otherwise directed). + Consingee has rabid dog. + + + M1234568 + 1234568 + 1234 + + + + 2007-01-02T14:00:00 + + + 2007-01-04T16:00:00 + + + 2007-01-04T12:00:00 + + + 2007-01-04T16:00:00 + + + + + Terminal + + + MSP + + + Local Cartage Company + + + Joe Trucker + + + 123-456-6890 + + + 123-456-6891 + + + 123-456-6892 + + + 123-456-6893 + + + + + Address + + + XYZ Company + + + Jane Dandy + + + 4321 Any Avenue + + + Bldg 4444 + + + AnyTown + + + CA + + + + + + 90210 + + + US + + + Residential + + + 223-456-7890 + + + 223-456-7891 + + + 223-456-7892 + + + 223-456-7893 + + + + 4 + 370 + 576 + 576 + 6150 + + + + + H1234567 + 1234567 + Reference Number Sample + PO Number Sample + RMA Number Sample + SO Number Sample + + + + + 8887212 + 2 + 50 + 20 + 70 + 150 + 2000 + PDP-042 + TVABCD123 + Big ABCD TV - 42 Inch Plasma + + + 8887213 + 1 + 10 + 40 + 5 + 50 + 150 + Stand + TVABCD123S + TV Stand + + + Plan on bringing the stand in first as you'll need to set the TV on that. + 2 separate pieces banded to one pallet. + + + + H1234569 + 1234569 + Reference Number Sample 2 + PO Number Sample 2 + RMA Number Sample 2 + SO Number Sample 2 + + + + 8887222 + 1 + 10 + 10 + 10 + 10 + 1000 + Speaker + Expensive Small Speaker + Expensive Small Speaker with Great Sound 102 + + + Be careful when opening box as knife could scratch top of unit. + Triple-layer corrugated blue box. + + + + \ No newline at end of file diff --git a/GetManifests/README.md b/GetManifests/README.md new file mode 100644 index 0000000..5ae3afd --- /dev/null +++ b/GetManifests/README.md @@ -0,0 +1,234 @@ +GetManifests +============ + +EDI (API) Documentation for the Standard, XML-Based, Vendor Shipment Data Transfer + +Overview +-------- + +Manna Freight Systems, Inc. can be configured to generate specially-formatted XML documents which contain shipment information for our suppliers. This information can be transferred to an HTTP endpoint or put into a file which can be transferred via FTP-- either uploaded to an FTP server hosted by the supplier or made available for download on an FTP server hosted by us. + +We recommend beginning the integration by creating a system to receive our transmissions and then requesting that we enable them. You would start to collect real-world examples for your development and testing. Make your request by emailing Support@MFSCorporate.com. + +Transmission +------------ + +The transmissions are generated by our system based on various triggers. Each transmission contains the complete shipment information as of the time of generation. The system does not filter out transmissions which would be practically identical to previous transmissions. The triggering mechanism also does not ensure that a change actually took place-- rather, it triggers based on an activity which might result in a change of shipment information. Also, the system does not, by default, stop transmissions for a particular shipment based on its life cycle. It will continue to send transmissions for a shipment whenever relevant activity occurs, even if the shipment has long since been completed. + +When the data is transferred via HTTP, the XML itself will appear in the body of an HTTP POST request. It will not be like a normal web form POST from a browser, which would have name-value pairs with a media type of `application/x-www-form-urlencoded`. Rather, it will be raw XML, with an effective media type of `application/xml`. + +When the data is transferred via HTTP, our system can be configured to expect an HTTP response with specially-formatted XML content which describes whether your interpretation of our transmission was successful. This allows our system to inform our operations staff if there is a problem with you receiving the information. + +Business Concepts +----------------- + +When our customers request that we move product (see also [SendUsShipments](/SendUsShipments)), we create a new shipment in our system. (That shipment is also called a Bill of Lading.) We then aggregate these shipments into groups which are appropriate for a single engagement with a supplier. We call that grouping a manifest. From a contractual or legal perspective, we relate to our suppliers at that aggregate level. We expect to be charged in aggregate, and we expect that the entire group move together and be treated as a single set of pieces. In effect, officially, it is not a group at all but simply a larger "shipment". + +That said, the operational reality is that it is still a group, and it's valuable for our suppliers to understand the nature of the group-- to have information about the shipments inside the manifest. Toward that end, our XML format includes both aggregate, manifest-level information and information about each shipment within the manifest. The most important piece of shipment-level information is the shipment identifier (ID). It is also known as the tracking number or BOL number. It's generally the number our customers use to refer to the shipment, and it's the number generally used by suppliers when interacting with shippers and consignees. + +Example Files +------------- + +* [Sample Outbound Transmission](ManifestXMLOutbound-Sample.xml) (From Us to You) +* Sample Response (You Responding to Us) + * [Success](ManifestXMLOutbound-Response-Success-Sample.xml) + * [Failure](ManifestXMLOutbound-Response-Failure-Sample.xml) + +Transmission Content +-------------------- + +The root XML element is `ManifestTransmission`; it contains header information and the manifest information itself. Each transmission will contain information about *only one* manifest. + +### Header Information + +The header elements are grouped into a header element, but rather hang off the root. They consist of: + +* `TransmissionID` - A unique integer for the current transmission. Multiple transmissions of the same manifest information would each have a different transmission ID. The value is unique across all of our transmissions, not just transmissions for a particular supplier. This value is useful for debugging transmission problems. +* `TransmissionGeneratedUTC` and `TransmissionGeneratedLocal` - The date the transmission was generated in UTC and our time (US Central time zone, where daylight savings is observed). +* `Authentication` - This section can be populated with a `UserName` and `Password` of your choosing. This could be used by you to authenticate our transmission. Instead of a password, a `PasswordHash` can be sent, which is a dynamically salted MD5 or SHA1 hash of this constructed value: + > `UserName` + `|` + `TransmissionID` + `|` + `TransmissionGeneratedUTC` + `|` + `Password` + +### Manifest Information + +The manifest information is hangs off the root inside of `Manifest` and is broken into various sections: + +* `ManifestInfo` +* `ManifestControlNumbers` +* `ManifestKeyDates` +* `ManifestOrigin` +* `ManifestDestination` +* `ManifestPieceSummary` +* `Shipments` + +#### ManifestInfo + +* `ManifestVendorID` - This is our primary, unique textual identifier for the company responsible for the manifest. The identifier is only unique for a particular Vendor Type. +* `ManifestVendorType` - We generally categorize our suppliers as either a "Carrier" or "Agent". A MAWB must have a "Carrier" as the responsible company. Carriers are generally used to move freight from one market to another (often called a "line haul"). An "Agent" typically operates within a market and is the responsible entity on Pickup Manifests, Delivery Manifests, and most Transfer Manifests (though a Carrier can be the responsible company on a Transfer Manifest). +* `ManifestType` - The primary Manifest Types are "Pickup", "Delivery", "MAWB", and "Transfer". + * A Pickup Manifest involves our supplier retrieving products from our customer's designated shipping location and then transferring that product to another supplier, typically the Carrier on one or more MAWBs. Usually, all of the shipments on the Pickup Manifest will belong to the same customer of ours, though it is possible that a variety of our customers might have shipments originating at the same distribution center or "drop shipper". While a Pickup manifest should always have a single origin location, various groups of the underlying shipments might have different Carriers for their next manifest. Therefore, the Pickup Manifest supplier (a.k.a. "Pickup Agent") might need to drop groups of the products at multiple Carriers. Unfortunately, this XML EDI system does not provide detail beyond the first drop location at this time. + * A MAWB can be thought of as a Line-Haul Manifest. The term MAWB stands for Master Air WayBill which is how the air freight industry typically refers to shipments of cargo on air carriers. Typically, Carriers receive shipments at their terminals (which is usually at or near an airport and therefore represented by 3-character IATA airport codes such as MSP) and hold them for pickup at the destination terminal. Some carriers perform more complete service, retrieving product from or delivering product to a location. Whether the carrier is bound to their terminals or travel to an address to pickup or drop off the orders varies by MAWB and is indicated in the `ManifestOrigin\ManifestOriginType` and `ManifestDestination\ManifestDestType` elements. + * A Delivery Manifest typically involves our supplier retrieving products from a carrier terminal and dropping products off at our customer's designated destination location; that destination location is known as the BOL Consignee. The vast majority of Delivery Manifests are of a single shipment; they are often destined for a residence. However, some are "returns", that is, a collection of shipments of damaged or broken products being "returned" to our customer's warehouse. In those cases, multiple shipments will be combined onto the same Delivery Manifest, and often they will need to be retrieved from multiple carriers. Unfortunately, this XML EDI system does not provide detail beyond the first retrieval location at this time. + * A Transfer Manifest is a designed to accommodate those supplier engagements which do not fit one of the primary patterns (Pickup, MAWB, Delivery). The responsible company is permitted to be either an Agent or Carrier. It could represent a responsible company moving product from one supplier to another, or it could involve performing an installation or assembly service at a residence. Unfortunately because of the wide variety of use cases, the XML EDI system probably will not provide sufficient detail on the handling of these manifests at this time. +* `ManifestSpecialSide` - Many manifests involve simply moving product from one business with a dock to another. However, Delivery Manifests (especially) often involve special services such as "White Glove" treatment (where the supplier brings product inside a residence, often with two people, unpacks the product, and removes the shipping materials). For Delivery Manifests, this should always be on the destination side. For Pickup Manifests, this should always be on the origin side. For MAWBs, it could be the origin or destination. It is not a well-defined concept for Transfer Manifests. If a special side is indicated on a MAWB, that side should not be an `ManifestOriginType` or `ManifestDestinationType` of Terminal; rather, it should be address. Internally, Pickup manifests where the special side is on the origin and Delivery manifests where the special side is on the destination are referred to as the "operative" shipment segments. +* `ManifestShipType` - This is the textual ID of the special services to be performed on the side specified in `ManifestSpecialSide`. Examples include "WG" for "White Glove" and "TP" for "Threshold Plus". Additional services required will be listed in the `ExtraServices` element under the `Shipment` element referenced below. +* `ManifestShipTypeName` - This is the textual name related to the special services ID specified in `ManifestShipType`. +* `ManifestShipTypeBilling` - Not all suppliers have defined rates for all special services. This billing description text is designed to explain the special services in more standardized terms for which the supplier is more likely to have rates. +* `ManifestShipTypeDesc` - This is a more lengthy description of the special services to be performed on the side specified in `ManifestSpecialSide`. +* `ManifestSpecInst` - These are custom instructions from our operations staff to our suppliers. + +#### ManifestControlNumbers + +* `ManifestID` - This is the textual transaction identifier for the manifest in our system. + * In the case of a MAWB, it is referred to as the "MAWB number". For Pickups, Deliveries, and Transfers, it is generally referred to as the "PRO Number". + * The intent of this field is to house the supplier's primary reference number for the manifest. This is not generally known at time of manifest creation, so a default value is constructed. The default is a letter ("P" for a Pickup, "M" for a MAWB, "D" for a Delivery, and "T" for a Transfer) followed by the numeric transaction identity (see `ManifestTranID`). + * If the supplier provides this number, it replaces the default number in our system and in future transmissions. The supplier can provide the number in the response to this transmission-- in the `VendorManifestControlNumber` element-- and the system will perform the replacement automatically. Alternatively, the supplier could communicate the value for our Ops staff to manually update. + * For some Carrier suppliers, we have secured ranges of valid numbers to use for this identifier on their MAWB manifests. We draw from this pool upon creation of the manifest, so even the earliest transmissions of that MAWB manifest will contain the valid, pre-assigned supplier reference number. + * In order for any transmission to us of [status](https://github.com/MFSTech/SendStatuses/) or [invoice](https://github.com/MFSTech/SendInvoices/) information to succeed, it must contain a `ManifestID` or `ManifestTranID` which matches a manifest transaction to which the transmitter is authorized. +* `ManifestTranID` - This is the unique numeric transaction identity for the manifest in our system. It is inviolate for a particular transaction, unlike the textual `ManifestID`. +* `ManifestSecCode` - This is a code used for primitive security, primarily for document retrieval. For example, in order to access some printable representations of manifest information, the security code must be provided in the URL. They are typically a four-digit random number which does not usually change through the live of a manifest. The security system is designed for prevention of casual snooping of other suppliers' documents simply by trying other `ManifestTranID` values in the document retrieval URLs. + +#### ManifestKeyDates + +* `ManifestReadyDateTime` + * For MAWB manifests with a `ManifestOriginType` of "Terminal", the Ready Date is the date and time we expect the shipment to be available for the carrier to begin transportation; internally, we refer to this as the ETD (estimated time of departure). We use that date together with the carrier's transit time matrix (if we have it in our system) to determine the Deliver Date, which we refer to internally as the ETA (estimated time of arrival). + * For other manifests, the Ready Date has less official meaning. It is labeled as "Open Time" in our system and was originally intended to store the start of the allowable window for the agent supplier to perform the pickup or delivery. It defaults to the morning of the shipment's ready date for Pickup manifests and the morning of the shipment's delivery date (the date by which we are obligated to our customer to deliver the freight) for Delivery manifests. When the manifest is the "operative segment" (that is, a Pickup manifest with a "Pickup" `ManifestSpecialSide` or a Delivery manifest with a "Delivery" `ManifestSpecialSide`) and an associated shipment is scheduled, this date and time will be set to the start of the scheduled window. +* `ManifestDeliverDateTime` + * For MAWB manifests with a `ManifestDestinationType` of "Terminal", the Deliver Date is the date and time we expect the carrier to have made the shipment available for the next supplier; internally, we refer to this as the ETA (estimated time of arrival). + * For other manifests, the Deliver Date has less official meaning. It is labeled as "Close Time" in our system and was originally intended to store the end of the allowable window for the agent supplier to perform the pickup or delivery. It defaults to the evening of the shipment's ready date for Pickup manifests and the evening of the shipment's delivery date (the date by which we are obligated to our customer to deliver the freight) for Delivery manifests. When the manifest is the "operative segment" (that is, a Pickup manifest with a "Pickup" `ManifestSpecialSide` or a Delivery manifest with a "Delivery" `ManifestSpecialSide`) and an associated shipment is scheduled, this date and time will be set to the end of the scheduled window. +* `ManifestScheduleDateTimeStart` - For a manifest with a specified `ManifestSpecialSide`, the represents the start of the allowable window for performance of the services identified by `ManifestShipType`. +* `ManifestScheduleDateTimeStop` - For a manifest with a specified `ManifestSpecialSide`, the represents the start of the allowable window for performance of the services identified by `ManifestShipType`. + +#### ManifestOrigin + +Most of these elements are self-explanatory. + +* `ManifestOriginType` - This is either "Terminal" or "Address". "Terminal" is only used for MAWB manifests. When the carrier receives the manifest at their origin terminal rather than retrieving it from an address, the "Terminal" origin type is used. Similarly, when the carrier holds the manifest for pickup at their destination terminal, rather than delivering it to an address, the "Terminal" destination type is used. +* `ManifestOriginCode` - When the `ManifestOriginType` or `ManifestDestType` is "Terminal", this will contain the terminal's code (often an airport code such as "MSP"). When the `ManifestType` is "Pickup" this will be the terminal code for the origin of the adjoining MAWB. When the `ManifestType` is "Delivery", this will be the terminal code for the destination of the adjoining MAWB. +* `ManifestOriginLocationType` - This is one of an enumerated list of location types. + * Business + * Convention + * Hospital + * Hotel + * MilitaryBase + * Residential + * School +* `ManifestOriginName` - This is the primary name. It could be a business name or an individual's name. It generally should not be blank. The system will automatically move the contact name to the primary name if the primary name is left blank and the contact name is non-blank. Occasionally, customers will enter the same name in the primary and contact name fields. +* `ManifestOriginContact` +* `ManifestOriginAdd1` +* `ManifestOriginAdd2` +* `ManifestOriginCity` +* `ManifestOriginState` +* `ManifestOriginRegion` +* `ManifestOriginZIP` +* `ManifestOriginCountryCode` +* `ManifestOriginPhone` +* `ManifestOriginFax` +* `ManifestOriginHomePhone` +* `ManifestOriginOtherPhone` + +#### ManifestDestination + +Most of these elements are self-explanatory. See the analogous origin element above for any special notes. + +* `ManifestDestType` +* `ManifestDestCode` +* `ManifestDescLocationType` +* `ManifestDestName` +* `ManifestDestContact` +* `ManifestDestAdd1` +* `ManifestDestAdd2` +* `ManifestDestCity` +* `ManifestDestState` +* `ManifestDestRegion` +* `ManifestDestZIP` +* `ManifestDestCountryCode` +* `ManifestDestPhone` +* `ManifestDestFax` +* `ManifestDestHomePhone` +* `ManifestDestOtherPhone` + +#### ManifestPieceSummary + +* `ManifestPieceCount` - This represents the total number of pieces on the manifest as a whole (across all of our customers' shipments). + * While seemingly obvious, it isn't always clear what constitutes a piece. Generally, we view it as a separable, labeled box. Several boxes piled on (but not secured to) a pallet are generally considered separate pieces. However, if they are banded to a pallet and surrounded with black shrink wrap, then the pallet itself is considered a single piece. It's less clear for configurations in between. + * Usually, this will be the sum of the number of pieces listed in each of our customers' shipments. However, sometimes the freight is reconfigured (e.g. banded to pallets) and shipped as larger, bulk units instead of the individual pieces supplied by the customer. In those cases, the adjusted piece count (known internally as "override pieces") will be displayed here. +* `ManifestWeightActual` - This represents the total actual weight of all pieces on the manifest. It is not the "dimensional weight". + +#### Shipments + +This element contains one or more `Shipment` elements for each of our customers' shipments on the manifest. + +##### ControlNumbers + +* `ShipmentID` - This is the primary textual identifier for a customer shipment. Duplicates in our system are discouraged but not impossible. This can change over time for an individual shipment, though that is quite rare. It is also known as the BOL (Bill of Lading) number and the tracking number. As a shorthand, for manifests with only a single BOL, our operations staff will generally refer to the manifest using the `ShipmentID`. +* `ShipmentTranID` - This is the unique numeric transaction identity for the shipment in our system. It is inviolate for a particular transaction, unlike the textual `ShipmentID`. It is in the same numeric scope as `ManifestTranID` values, meaning no `ShipmentTranID` can be used as a `ManifestTranID`, and vice versa. +* `Ref` - Reference Number. This is one of four primary textual control numbers customers are allowed to specify. It is merely informational. +* `PO` - Purchase Order Number. This is one of four primary textual control numbers customers are allowed to specify. It is merely informational. +* `RMA` - Return Merchandise Authorization Number. This is one of four primary textual control numbers customers are allowed to specify. It is merely informational. +* `SO` - Sales Order Number. This is one of four primary textual control numbers customers are allowed to specify. It is merely informational. +* `ShipperManifest` - A shipper might place a group of shipments together on a Shipper Manifest. Each shipment will share the same `ShipperManifest` number. This element is only present if authorized. + +##### Pieces + +One or more `Piece` elements with the following information. + +A `Piece` represents a piece record in our system. Typically, multiple, like pieces are grouped together in a single piece record, though that is not required. Therefore, a shipment might have multiple pieces but only one piece line. A shipment with two different types of pieces (TVs and stands) will usually have multiple piece lines. + +* `PieceID` - This is the unique numeric identity for the piece line in our shipment. It would allow you to specify updated dimension information for a particular piece. However, there is no correlation between this number and a physical piece (it doesn't appear on any label), so that system is not ready for use. +* `PieceCount` - If there are multiple pieces of the type represented by this piece line, that will be represented here by a quantity greater than 1. A quantity of 0 indicates that a piece has been converted into a pallet with other pieces (the pallet being represented by a different piece line). +* `PieceLength` - The length, in inches, of a a piece represented by this line. +* `PieceWidth` - The width, in inches, of a a piece represented by this line. +* `PieceHeight` - The height, in inches, of a a piece represented by this line. +* `PieceWeightActual` - The weight, in pounds, of a piece represented by this line. This is the *per piece* weight. A piece line with 5 TVs weighing 100 pounds each would have the value 100 in this element. +* `PieceDecVal` - The value, in US dollars, of a piece represented by this line. This is the *per piece* value. A piece line with 5 TVs valued at $1000 each would have the value 1000 in this element. This element is only present with special authorization. +* `ProdType` - One of a list of official product type IDs. Technically, these vary by customer, though there is general consistency across customers. Examples include TV product types (such as "PDP-042", "LED-050", which stand for 42" Plasma TV and 50" LED LCD TV, respectively); mattress sizes (such as "Queen-M"); and generally classifications (such as "Case" and "Soft" for "Case goods" and "Soft goods", in the context of furniture). +* `ProdID` - This is a customer-specified product ID which is often a model or SKU number. +* `ProdName` - This is a customer-specified product name. +* `PieceCommodity` - This is one of an specific list of commodity types. This element is available upon request. + * Appliances + * Exercise Equipment + * Furniture + * Mattress/Foundation + * Misc Freight + * Other + * TV + * TV Accessories +* `PieceSubCommodity` - This is one of a specific list of commodity types, with a different list for each commodity type. Examples include "Range" and "Grill" for "Appliances"; "LCD" and "Plasma" for "TV"; "Bookcase" and "Buffet" for "Furniture"; and "Mattress" and "Boxspring" for "Mattress/Foundation". This element is available upon request. +* `PieceNMFC` - The National Motor Freight Classification for the pieces represented by this line, if known. This is mostly for future expansion as it is rarely populated. This element is available upon request. + +##### Other Elements + +* `SpecInst` - Special instructions provided by the customer such as "beware of dog". +* `PkgDesc` - Package description provided by the customer such as "dining room set with table and chairs". + +#### ExtraServices + +This element falls under the `Manifest` element. All of the extra services required by the various customer shipment requests are aggregated into a single, unified manifest list of "extra services" such as Deluxing (where the provider removes packaging, inspects contents, and ensures product is pristine for delivery). The `ExtraServices` element has one or more `ExtraService` elements beneath it with the below contents. + +* `ExtraServiceTypeID` - A textual identifier for the extra service. (e.g. "Deluxing" for Deluxing) +* `ExtraServiceTypeName` - A name for the required extra service. +* `ExtraServiceTypeDesc` - A description of the required extra service. (e.g. "At Local Delivery Carrier location, remove product from packaging, inspect and process the product so that it is delivered in a pristine condition.") + +Response Content +---------------- + +When using synchronous HTTP transmission as a transport, we recommend responding with XML as defined below. We are able to mine this response for errors and your preferred control number. This is most useful when you synchronously, fully process the transmission-- that is, you actually create shipment records in your system-- so we confirm a semantic comprehension rather than a mere receipt acknowledgment. + +At this time, we do not support response handling for asynchronous transport such as FTP. + +The root element is `ManifestTransmissionResponse`. + +* `MFSTransmissionID` - This should be used to echo back our transmission ID. This would not be strictly necessary for synchronous communication, as it must correspond with the active transmission, but we include this as an extra check for validity and for future expansion to asynchronous processing. +* `VendorTransmissionID` - This should be a unique number you create for this transmission-- not for the shipment we are transmitting (as we might transmit the same shipment multiple times in the case of updates). This number is valuable for troubleshooting the result of particular transmissions. +* `ResponseGeneratedUTC` - This is a time stamp in UTC time. +* `ResponseGeneratedLocal` - This is a time stamp in your local time. +* `VendorManifestControlNumber` - This should be used for your preferred primary identifier for this shipment. We will set our `ManifestID` to this value and use it in future update transmissions. +* `ErrorID` - This should contain a numeric representation of any processing error. It is not currently used, but for future expansion, we envision it to be used to classify problems for better reporting and potential automatic remediation. +* `ErrorText` - This should be human comprehensible text describing any issues you had interpreting or handling the data we provided. It is made available for our operations staff and can be used by them to fix any data issues for future transmissions. + +Miscellany +---------- + +* Vendor and Supplier are used interchangeably in this documentation. Generally, the terms refer to any company which we pay to provide us service. Typically, they are transportation providers (truck fleet operators) or assembly and installation service providers. +* The term "element" is used to refer to an XML node. +* The presence of elements which are "available upon request" or otherwise restricted are controlled by EDI configuration settings which should be coordinated with our technical staff. \ No newline at end of file diff --git a/GetStatuses/README.md b/GetStatuses/README.md new file mode 100644 index 0000000..eadf4f3 --- /dev/null +++ b/GetStatuses/README.md @@ -0,0 +1,220 @@ +Get Statuses +============ + +EDI (API) Documentation for the Standard, XML-Based, Shipment Status Information for Customers + +Overview +-------- + +A status is an event that occurs in the life of a shipment. Examples include physical events such as the original pickup and final delivery, along with with administrative event such as a scheduling call or invoicing. Exceptions such as weather delays and damage are also represented. + +Our standard format uses XML. Rather than limit our format to a specific, triggering event, each status transmission contains all of the available events which have occurred relevant to the shipment. So the XML is a comprehensive collection of all events and BOL information. + +We support both "Push" and "Pull" triggering mechanisms. That is, you can retrieve the status transmission from us on demand, without any prior configuration on our part ("Pull"), or we can configure our system to send you the status transmission based on various events ("Push"). + +We have a "Full" and "Slim" version of the status format. The "Slim" version of the status format contains only that information which is available on our public status page-- basically, the normal physical statuses and a scheduling call history. The "Full" version contains everything the "Slim" format does, and much more, including address information, estimated charges, notes to the customer, and various administrative events such as invoicing. + +"Push" statuses-- where our system is sending the data using an established link to your server-- always use the "Full" version of the status format. Also, because every transmission contains all of the shipment's events, you never have to decide which events you want us to tell you about. You just have to decide which events should trigger transmissions. + +When using the "Pull" method, you will be accessing a particular web endpoint. By default, you will get the the "Slim" version. However, if you specify a Security Code, you will be able to receive the "Full" version of the status transmission. + +Transmission +------------ + +### Pull + +"Pull" statuses can be retrieved via HTTP GET from or POST to these URLs: + +* Production: [http://EDI.MFSClarity.com/EDI/Cust/Status.aspx](http://EDI.MFSClarity.com/EDI/Cust/Status.aspx). +* Test: [http://Demo.MFSClarity.com/EDI/Cust/Status.aspx](http://Demo.MFSClarity.com/EDI/Cust/Status.aspx) + +It must be fed either (1) the BOL number (aka tracking number) in the `BOL` parameter or (2) our internal transaction number (aka Trans ID) in the `Tran` parameter. It can be supplied in either the query string or in the HTTP body (when POST is used) in "application/x-www-form-urlencoded". (This is the standard encoding used by browsers when submitting an HTML form.) + +The HTTP response will have a content type of "text/xml". It will contain the XML status format directly. + +Sending only the BOL number or Trans ID will result in the "Slim" version of the transmission. In order to receive the "Full" version, the Security Code must be specified in the `SecCode` parameter (again, either via query string or form content). + +The Security Code is a random, typically 4-digit numeric code automatically by our system for the shipment. It is a rudimentary security mechanism to prevent casual snooping for status transmissions for shipments which are not relevant to you. The security code is returned in the [our standard XML acknowledgment](https://github.com/MFSTech/SendUsShipments/blob/master/ShipAck-Commented.xml "Shipment Acknowledgment XML Example") to [your XML shipment transmission](https://github.com/MFSTech/SendUsShipments/blob/master/Shipment-Commented.xml "Shipment XML Example"). See our [SendUsShipments repository](https://github.com/MFSTech/SendUsShipments "SendUsShipments Repository") for more information. + +At this time, secure transmission using HTTPS (SSL) is not available. + +These status transmissions are always available. No prior configuration by us is required. You may implement on your own schedule. + +### Push + +We are able to generate status transmissions based on a large number of triggers in our shipment tracking application. All of the following types of events are able to generate a status transmission: + +1. Freight or Service Statuses +2. Exceptions +3. Scheduling Calls +4. Scheduling +5. Administrative Activity +6. Shipment Closure +7. Customer-Facing Shipment Note Entry +8. Extra Service Adjustments + +We run a process every few minutes which generates the transmissions. The status transmissions generated from these events always use the "Full" version of the content. The content can delivered directly to an HTTP or HTTPS endpoint as an HTTP POST request. The body of the HTTP POST will contain the XML in "text/xml" format (*not* "application/x-www-form-urlencoded" format). + +Alternatively, our system can generate files containing the XML content. Another process which runs every few minutes can sweep these files to an FTP site we host, or it can send the files via FTP to a site hosted elsewhere. We believe it's best practice for the receiver to host the FTP site. Typically, it is more convenient and uses fewer system resources to poll a local FTP site than a remote FTP site. Also, receiver FTP host software can often trigger processing events. + +You can request that we establish Push status transmissions to you by emailing Support@MFSCorporate.com. + +Content +------- + +Each status transmission has information about a single shipment. The root XML element is `StatusTransmission`. It has some transmission-related header information and then a large `Shipment` section, which contains the statuses, call log, and other items. The Full format contains more information inside the Shipment section. + +### Header Elements + +These elements are direct descendants of the root `StatusTransmission` node. + +* `TransmissionID` - This is a unique integer created by our system to represent this particular transmission. It can be useful for debugging purposes. +* `TransmissionDate` - This is the date and time (in ISO 8601 format) the transmission content was generated, in the local time of our server. +* `TransmissionDateUTC` - This is the date and time (in ISO 8601 format) the transmission content was generated, in Coordinated Universal Time (also known as UTC or GMT). +* `Shipment` - This houses the shipment information; it is the bulk of the transmission. + +### Shipment Element + +Within the `Shipment` element are sections containing general shipment information along with each of the lists of various the event types. The following elements are direct descendants of the `Shipment` element. + +* `ControlNumbers` +* `Milestone` +* `ServiceInfo` +* `Parties` +* `Dates` +* `Airports` +* `Pieces` +* `PieceSummary` +* `CurrentStatus` +* `StatusList` +* `CommEvents` +* `Activities` +* `Exceptions` +* `Charges` +* `ChargesSummary` +* `TextInfo` + +#### ControlNumbers + +This section contains the main tracking numbers for the shipment, along with some other relevant identification numbers. It is sparsely populated in the Slim format, containing only the primary BOL number (our main tracking number) and our internal transaction ID for the shipment. In the Full format, it contains the other standard customer tracking numbers, such as PO number and Reference number. It also includes the invoice number, if the customer has been invoiced for the shipment. + +* `TranID` - Unique, inviolate, integer, internal transaction ID for the shipment. +* `BOL` - Bill of Lading number. This is our primary textual tracking number. +* `Ref` - Reference number. +* `PO` - Purchase Order number. +* `RMA` - Return Merchandise Authorization number. +* `SO` - Sales Order number. +* `Invoice` - Invoice number. Only populated if the customer has been invoiced for the shipment. +* `CustomCtrlNums` - See below. + +##### CustomCtrlNums + +Custom Control numbers are special control numbers defined for particular processes or customers. (Technically, most standard control numbers and custom control numbers are the same from the system's perspective. We simply expose the standard numbers differently.) The type of control number and the value are supplied as follows. + +* `CtrlNumType` +* `CtrlNumValue` + +#### Milestone + +The Milestone status is designed to provide a high level, simple summary of the status of the shipment. It corresponds with with the broad categories defined in our Clarity web tracking application. Those categories are as follows. + +* Acknowledged - We have the shipment information, and some activity might have taken place, but we have not yet picked up the freight (and no later activity has occurred). +* In Transit - We have picked up the freight and it is moving to the destination market. We have not yet placed it on the final delivery vehicle. +* Out For Delivery - We have placed the freight on the final delivery vehicle. +* Delivered - The freight has been delivered to the final recipient (aka consignee). +* Exceptions - The shipment has been closed for a reason other than a normal delivery. For example, the shipment might have been refused by the recipient. + +These milestone explanations (and many of our other status explanations) are written from the perspective of freight movement, but they often have analogous steps in a service-only transaction. For example, "Delivered" would really mean "Installed" if we were only performing installation services. + +When the Milestone is an Exception, additional information will be included about the Exception. The additional information is actually the shipments closure type (when not closed as Delivered). An example is "Exception: Damaged - Refused", where a recipient refused a delivery because it was damaged. + +The `Milestone` element is available in the Slim and Full formats. + +#### ServiceInfo + +The `ServiceInfo` element contains information about the type of services we are to perform, along with the speed in transit the customer has selected. + +* `ServiceTypeID` - A textual code representing the speed in transit requested for the shipment. Examples include Ground (R) and Next Day (1). +* `ServiceType` - The name of the speed in transit selection. See also `ServiceTypeID`. +* `ShipmentTypeID` - A textual code representing the collection of services we are to perform on the special side of a shipment. Most shipments are direction Delivery and the services will be performed at destination. Some shipments are direction Pickup and the services should be performed at origin. Example service bundles include Threshold Plus (TP), White Glove (WG), and White Glove with Assembly (WA). +* `ShipmentType` - The name of the collection of services we are to perform on the special side of the shipment. See also `ShipmentTypeID`. +* `CloseType` - If the shipment is complete, this will explain the final disposition. Most of the time, it will be closed as "POD", indicating it has been delivered (or that the installation has been completed). When there has been an Exception, this will show the specific issue (such as "Damaged - Refused"). For incomplete shipments, this will read "Not Closed". + +Note the shipment Direction is not currently included, but likely will be in the future, and it will likely be an element in this `ServiceInfo` section. + +The `Serviceinfo` section is available in the Slim and Full formats. + +#### Parties + +There are four primary parties to a shipment-- Shipper, Consignee, Bill-To, and Controller. For some Service Types (e.g. True Last Mile), the Delivery Agent will also be present. + +* `Shipper` - This is the origin of shipment and generally represents the location at which we took possession of it. +* `Consignee` - This is the destination of the shipment and generally represents the location at which we transfer possession to another party. +* `BillTo` - This is the party paying for the shipment. Typically, it is the same as the `Controller`, but sometimes there are different rate agreements with a customer and the specific rates which apply are based on this party. +* `Controller` - This is the party which controls the shipment. From a system perspective, it also drives the selection of available Shipment Types, Service Types, etc. +* `DeliveryAgent` - This is the supplier we have selected to perform the final delivery to the `Consignee`. It is only present for True Last Mile shipments. + +In some cases, the shipment does not involve actual movement of goods (e.g. an installation only service), in which case either the origin or destination address will be largely irrelevant. + +All of the parties share the same data structure. + +The parties are only available in the Full format. + +##### Party Structure + +* `Name` - This is the primary name of the party. It is equivalent to the `Address`\`BusinessName` element. +* `ID` - This is the unique textual identifier of the party. For the `BillTo`, `Controller`, and `DeliveryAgent`, this is set by us. For the `Shipper` and `Consignee`, it can be set by the customer, but it is generally defaulted. It is also only unique across all addresses for the customer not across all customers. +* `Email` - This is the email of the primary contact for the party. +* `Address` - This contains the address (street, city, state, and zip) for the party. `Region` is generally only relevant for non-US addresses. +* `Phones` - This contains the various phone numbers for the primary contact referenced in `Address`. + +#### Dates + +* `ETD` - This is date the shipment is available for pickup. It is also known as the Ready Date. It drives rate selection (in case there are different rates for different time periods). For True Last Mile shipment, this is the date the shipment will begin its journey to us. +* `ETA` - This is date the shipment is required to be available for delivery to the consignee in order to honor the `ServiceType`. +* `Schedule` - This is the date on which the services bundled in `ShipmentType` are to be performed. In that sense, it is sensitive to Direction. The time represents the end of the window as defined by `WindowStop`. +* `WindowStart` - This is the time on the `Schedule` date which represents the start of the window in which the delivery and/or services are to be performed. +* `WindowStop` - This is the time on the `Schedule` date which represents the end of the window in which the delivery and/or services are to be performed. +* `Invoice` - This is the date on which the shipment was invoiced. This is only available in the Full format. +* `Closed` - This was the date on which the shipment was closed. When the `CloseType` is "POD", it will correspond with the `StatusDateTime` of the "Delivery" status. + +#### Airports + +The `Origin` and `Destination` airport codes represent the nearest service terminals to the `Shipper` and `Consignee`, based on some proprietary routing logic. They were historically used for customer rating, but are now generally just informational. They are also available only in the Full format. + +#### Pieces + +`Pieces` encloses the list of `Piece` nodes. It is available only in the Full format. + +A Piece is a separately identified shipping unit, which definition leaves a gray area. Two separate cartons sitting on the floor near each other are clearly two separate Pieces. Slide those boxes together; surround them with black shrink wrap; attach a "Do Not Break Down" sign; and use metal banding to adhere them to a pallet; and they would usually be considered one Piece. + +The configuration of Pieces often has a pricing impact. Smaller, independently mobile Pieces allow more efficient vehicle loading. Bundled cartons, treated as a single piece, are less efficient. Those bundled cartons are considered to have dimensions equal to the cube formed by the maximum height, length, and width of the combination. + +When multiple cartons are grouped into a single shipping Piece, it's often useful to identify the number of cartons contained in the Piece, in case the package integrity is compromised during transit. Customers can specify this in the `PieceSTC` (Piece Said to Contain) element of the [Shipment transmission](https://github.com/MFSTech/SendUsShipments "SendUsShipments Repository"). That quantity is not currently represented in the below Piece information, but it likely will be in the future. + +We do not serialize to down to the Piece level. We allow customers to group like Pieces. All Pieces of the same product type with the same dimensions and weight can be grouped into a single Piece Line. Each Piece Line is separately stored in our system. A Piece Line is represented here as a `Piece` element. + +As a practical matter, it is unusual to have multiple, identically configured carton bundles, so generally if multiple cartons are shipping as a single Piece, it will be represented with its own Piece Line. + +`Piece` sub-nodes: + +* `PieceID` - This is our unique numeric identifier for the Piece Line record. +* `PieceCount` - This is the number of like Pieces represented by this Piece Line. +* `PieceLength` - This is the length-- in inches-- of Pieces in this Piece Line. +* `PieceWidth` - This is the width-- in inches-- of Pieces in this Piece Line. +* `PieceHeight` - This is the height-- in inches-- of Pieces in this Piece Line. +* `PieceWeightActual` - This is the actual (as opposed to dimensional) weight-- in pounds-- of *each* Piece in this Piece Line. The `PieceCount` should be multiplied by the `PieceWeightActual` to determine the total actual weight of the Piece Line. +* `PieceWeightDimensional` - This is the dimensional weight of the shipment. Dimensional weight is a conceptual value designed to represent impact of the size of a Piece in a way comparable to its weight. The `PieceCount` should be multiplied by the `PieceWeightDimensional` to determine the total dimensional weight of the Piece Line. The dimensional weight is calculated by taking the product of the length, width, and height (in inches) and dividing it by the dimensional factor. The dimensional factor can vary by customer agreement and/or mode of transport. Typically, 250 is used as a dimensional factor for ground shipments. As an example, a 20x30x40 carton would have a dimensional weight of 96 pounds. Typically, a customer is charged by the greater of the actual or dimensional weight for a shipment. +* `PieceDeclaredValue` - This is the declared value of *each* Piece in this Piece Line. The `PieceCount` should be multiplied by the `PieceDeclaredValue` to determine the total declared value for the Piece Line. The declared value is generally the maximum amount for which we would be liable in the case of loss or damage. Often, customers are charged based on the amount declared. +* `ProdType` - This is a textual code for the type of product contained in the Piece. It will be one of a list of product types configured for a customer. Generally, customers shipping TVs are required to specify the product type of the TV, which will be a code representing the TV technology and size. An example would be "LED-052" for a 52" LCD display with an LED back-light. +* `ProdID` - This is an optional field sometimes specified by customers. It often corresponds with the SKU of the product. +* `ProdName` - This is an optional long form name of a product. An example might be "52-inch LCD Display with LED Back-Light". + +Most of these elements correspond with similarly named elements in the [Shipment transmission](https://github.com/MFSTech/SendUsShipments "SendUsShipments Repository"). + +### Examples + +We have provided examples of real world shipments, scrubbed of any identifying information. + +* Slim format: [SlimSample.xml](SlimSample.xml) +* Full format: [Sample.xml](Sample.xml). \ No newline at end of file diff --git a/GetStatuses/Sample.xml b/GetStatuses/Sample.xml new file mode 100644 index 0000000..5d24228 --- /dev/null +++ b/GetStatuses/Sample.xml @@ -0,0 +1,707 @@ + + + 10535890 + 2014-12-31T11:22:50.047-06:00 + 2014-12-31T05:22:50.047Z + + + 10000000 + K10000000 + RefNum + PONum + RMANum + SONum + 0855573IN + + Exception: Damaged - Refused + + R + Ground + WG + White Glove + Damaged - Refused + + + + Sample Shipper + SampleShipper123 + Shipper@Example.com +
+ Sample Shipper + Gotama Gregor + 1760 Easy Autumn Maze + + Taylorsville + NC + + 28681 + US +
+ +
(828) 555-5555
+ + + + + + + + + Argyros Albinus + ArgyrosAlbinus + ArgyrosAlbinus@Example.com +
+ Argyros Albinus + + 9893 Gentle Dale Alley + + Irvine + CA + + 92603 + US +
+ +
310-555-5555
+ + + + + + + + + Sample Customer + SampleCust + SampleCustomer@Example.com +
+ Sample Customer + Customer Service + 5727 Wishing Butterfly Run + + Wilberforce + AZ + + 86527-2489 + US +
+ +
(520) 020-5767
+ + + + + + + + + Sample Customer + SampleCust + SampleCustomer@Example.com +
+ Sample Customer + Customer Service + 5727 Wishing Butterfly Run + + Wilberforce + AZ + + 86527-2489 + US +
+ +
(520) 020-5767
+ + + + + + + + + + 2014-10-21T00:00:00 + 2014-10-29T23:59:00 + 2014-10-31T17:00:00 + 13:00 + 17:00 + 2014-11-10T00:00:00 + 2014-11-03T13:54:38 + + + CLT + LAX + + + + 3555436 + 1 + 30 + 30 + 25 + 40.0000 + 90.0000 + 500.00 + + ABC123 + Fancy Ottoman + + + 3555437 + 2 + 40 + 40 + 45 + 60.0000 + 288.0000 + 1000.00 + + CDE123 + Fancy Chair + + + 3555438 + 1 + 85 + 42 + 38 + 200.0000 + 542.6400 + 2000.00 + + HIJ123 + Fancy Sofa + + + + 4 + 360 + 1209 + 360 + + + + 23333146 + OutForDel + Out for Delivery + 2014-10-31T08:49:00 + + Irvine, CA + ar + + + + + -1 + Closure + Damaged - Refused + 2014-11-03T13:54:40.990 + + + + + + 23333146 + OutForDel + Out for Delivery + 2014-10-31T08:49:00 + + Irvine, CA + ar + + + 23333092 + DelToAgt + Delivered to Agent + 2014-10-27T12:02:00 + + Los Angeles, CA + (LAX) POD: Iser Evander + + + 23332222 + OnHand + On Hand + 2014-10-26T17:20:00 + + Los Angeles, CA + (LAX) + + + 23332599 + TermArrive + Terminal Arrival + 2014-10-23T07:59:00 + + Atlanta, GA + (ATL) + + + 23331723 + OnBoard + On Board + 2014-10-23T04:01:00 + + Charlotte, NC + (CLT) + + + 23331602 + RecByCar + Received by Carrier + 2014-10-22T22:02:00 + + Charlotte, NC + (CLT) + + + 23331077 + Pickup + Proof of Pickup + 2014-10-21T17:15:00 + + Taylorsville, NC + mark + + + 23330527 + ODispatch + Dispatched for Pick-Up + 2014-10-20T16:01:00 + + Taylorsville, NC + Keefe Katharina + + + + + 2014-10-21T17:14:57.367 + Email: ScheduleMyDelivery.com Invitation + ArgyrosAlbinus@Example.com + + + 2014-10-21T19:23:13.090 + Call: Client Accepted Date & Time + Scheduled - Client Accepted + + + 2014-10-30T07:00:46.450 + Email: Schedule Reminder + Sched Reminder Email + + + + + 100 + INSH + Inserted + 2014-09-17T13:18:12.613 + + + + 200 + CP + Customer Processed + 2014-09-17T13:18:13.303 + + + + 300 + CONP + Consolidated to Pick-Up Manifest + 2014-10-20T15:42:18.740 + + + + 400 + CONM + Consolidated to MAWB + 2014-10-20T15:50:35.727 + + + + 600 + CONSD + Consolidated to Delivery Manifest + 2014-10-20T15:50:33.640 + + + + 820 + RVLCK + Rate Value Lock + 2014-12-09T13:23:17.637 + + + + 820 + RVLCK + Rate Value Lock + 2014-12-09T13:23:17.883 + + + + 820 + RVLCK + Rate Value Lock + 2014-12-09T13:23:17.990 + + + + 845 + STIC + Shipment Type Info Saved + 2014-10-21T19:23:13.180 + + + + 845 + STIC + Shipment Type Info Saved + 2014-10-30T18:53:18.690 + + + + 850 + INV + Customer Invoiced + 2014-11-10T07:39:41.520 + + + + 887 + PCIU + Potential Claim Information Updated + 2014-11-03T13:56:04 + + + + 887 + PCIU + Potential Claim Information Updated + 2014-11-03T13:56:06 + + + + 887 + PCIU + Potential Claim Information Updated + 2014-11-07T12:38:34 + + + + 887 + PCIU + Potential Claim Information Updated + 2014-11-07T12:39:22 + + + + 887 + PCIU + Potential Claim Information Updated + 2014-11-07T12:41:13 + + + + 887 + PCIU + Potential Claim Information Updated + 2014-11-07T12:41:19 + + + + 999 + FIN + Completed + 2014-11-03T13:54:40.990 + + + + 875 + RVA + Revenue Adjustment + 2014-12-09T13:23:18.103 + + + + 875 + RVA + Revenue Adjustment + 2014-12-09T13:23:18.100 + + + + 875 + RVA + Revenue Adjustment + 2014-12-09T13:23:18.100 + + + + 875 + RVA + Revenue Adjustment + 2014-12-09T13:23:18.097 + + + + 875 + RVA + Revenue Adjustment + 2014-12-09T13:23:18.093 + + + + 849 + STSWEC + Key Info Change - Window End + 2014-10-30T18:53:18.673 + Before: 20:00:00 / After: 17:00:00 + + + 849 + STSWEC + Key Info Change - Window End + 2014-10-21T19:23:12.967 + Before: 16:00:00 / After: 20:00:00 + + + 848 + STSWSC + Key Info Change - Window Start + 2014-10-30T18:53:18.610 + Before: 08:00:00 / After: 13:00:00 + + + 848 + STSWSC + Key Info Change - Window Start + 2014-10-21T19:23:12.883 + Before: 11:00:00 / After: 08:00:00 + + + 843 + STSSDC + Key Info Change - Schedule Date + 2014-10-30T18:53:18.677 + Before: 2014-10-31 20:00:00 / After: 2014-10-31 17:00:00 + + + 843 + STSSDC + Key Info Change - Schedule Date + 2014-10-21T19:23:12.970 + Before: 1900-01-01 00:00:00 / After: 2014-10-31 20:00:00 + + + 842 + STSRDC + Key Info Change - Ready Date + 2014-10-20T15:41:53.177 + Before: 2014-10-24 00:00:00 / After: 2014-10-21 00:00:00 + + + 841 + STSDDC + Key Info Change - Delivery Date + 2014-10-20T15:41:53.340 + Before: 2014-11-03 23:59:00 / After: 2014-10-29 23:59:00 + + + 836 + STSCAC + Key Info Change - Consignee Address + 2014-10-21T19:23:12.643 + + Before: 310-000-5555 + / After: 310-555-5555 + + + + 650 + OFD + Out For Delivery + 2014-10-31T10:49:19.280 + ar + + + 570 + DTA + Delivered to Agent - Last MAWB + 2014-10-27T17:35:24.690 + (LAX) POD: Omer Przemo + + + 550 + OH + On Hand - Last MAWB + 2014-10-26T16:55:04.897 + (LAX) + + + 540 + OBLM + On Board - Last MAWB + 2014-10-23T03:20:03.200 + (CLT) + + + 415 + RCVC + Received by Carrier - First MAWB + 2014-10-22T21:35:01.983 + (CLT) + + + 350 + POP + Initial Pick-Up Completed + 2014-10-21T17:14:57.150 + mark + + + 320 + DFP + Dispatched for Pickup + 2014-10-20T16:01:25.343 + MARK + + + + + Z03 + CUSTOMER REQUESTS DELIVERY AT LATER TIME + 2014-10-21T19:23:13.183 + Min First Avail = 29 Oct 2014 / Deliver Date = 29 Oct 2014 / Schedule Date = 31 Oct 2014 + + + D6 + DAMAGED FREIGHT - OSD + 2014-11-03T13:54:47.573 + Close Type Damaged - Rejeccted entered + + + Resched-WindowNarrow + Reschedule Reason - Window Narrowing + 2014-10-30T18:53:18.680 + + + + + + 81111168 + A1 + Freight Charge + Freight + S + System + 0.0000 + 0.0000 + 0.0000 + 0.00 + + + 81111169 + C002 + Declared Value + Insurance + D + Declared Value + 2.4000 + 4500.0000 + 50.0000 + 108.00 + + + 81111170 + C022 + Fuel Surcharge + Fuel + U + Fuel Sensitive + 0.0000 + 0.0000 + 0.0000 + 0.00 + + + 81111171 + C331 + Beyond Origin - Ground + Transport + W + Weight + 0.0000 + 0.0000 + 30.0000 + 0.00 + + + + 0.00 + 0.00 + 108.00 + 0.00 + 0.00 + 0.00 + 0.00 + 31.29 + + + + + 109203032 + 2014-11-03T13:57:54.747 + + + From: Juuso Gala + Sent: Monday, November 03, 2014 1:58 PM + To: SampleCustomer@Example.com + Subject: BOLSummary: BOL: K10000000 + Importance: High + + Good afternoon, + + We have been notified of a damage issue with your chair on order K10000000. Customer refused the order because of a dirt stain on the arm of the chair. + + To expedite the claims process I have attached the appropriate documents above. Please complete these documents and send it back to our Claims department claimsgroup@mfscorporate.com or fax number 651-695-7172. + + We regret the inconvenience and delay this has caused. + Juuso Gala + Message Date/Time: Nov 3 2014 1:56PM + BOL #: K10000000 + Reference #: RefMum + PO #: PONum + RMA #: RMANum + Sales Order #: SONum + Shipper Information: + Sample Shipper + 1760 Easy Autumn Maze + Taylorsville, NC 28681 US + Consignee Information: + Argyros Albinus + 9893 Gentle Dale Alley + Irvine, CA 92603 US + Ready Date: Oct 21, 2014 + Service Requested: R + Deliver Date: Oct 29, 2014 + Pieces: 4 + Weight: 360 + StatusInfo: + Status Type | Date | Notes + ---------------------------|-----------------------|-------------------- + A5 - Dispatched for Pick-Up | Oct 20 2014 4:01PM | MARK + B1 - Proof of Pickup | Oct 21 2014 5:15PM | mark + C0 - Received by Carrier | Oct 22 2014 10:02PM | (CLT) + C1 - On Board | Oct 23 2014 4:01AM | (CLT) + C1l - Terminal Arrival | Oct 23 2014 7:59AM | (ATL) + C2 - On Hand | Oct 26 2014 5:20PM | (LAX) + C3 - Delivered to Agent | Oct 27 2014 12:02PM | (LAX) POD: Iser Evander + T1 - Out for Delivery | Oct 31 2014 8:49AM | ar + + + + + + \ No newline at end of file diff --git a/GetStatuses/SlimSample.xml b/GetStatuses/SlimSample.xml new file mode 100644 index 0000000..857db14 --- /dev/null +++ b/GetStatuses/SlimSample.xml @@ -0,0 +1,139 @@ + + + 10535890 + 2014-12-31T11:35:35.283-06:00 + 2014-12-31T05:35:35.283Z + + + 10000000 + K10000000 + + Exception: Damaged - Refused + + R + Ground + WG + White Glove + Damaged - Refused + + + 2014-10-21T00:00:00 + 2014-10-29T23:59:00 + 2014-10-31T17:00:00 + 13:00 + 17:00 + 2014-11-03T13:54:38 + + + + 23333146 + OutForDel + Out for Delivery + 2014-10-31T08:49:00 + + Irvine, CA + ar + + + + + -1 + Closure + Damaged - Refused + 2014-11-03T13:54:40.990 + + + + + + 23333146 + OutForDel + Out for Delivery + 2014-10-31T08:49:00 + + Irvine, CA + ar + + + 23333092 + DelToAgt + Delivered to Agent + 2014-10-27T12:02:00 + + Los Angeles, CA + (LAX) POD: RAUL MADRIGAL + + + 23332222 + OnHand + On Hand + 2014-10-26T17:20:00 + + Los Angeles, CA + (LAX) + + + 23332599 + TermArrive + Terminal Arrival + 2014-10-23T07:59:00 + + Atlanta, GA + (ATL) + + + 23331723 + OnBoard + On Board + 2014-10-23T04:01:00 + + Charlotte, NC + (CLT) + + + 23331602 + RecByCar + Received by Carrier + 2014-10-22T22:02:00 + + Charlotte, NC + (CLT) + + + 23331077 + Pickup + Proof of Pickup + 2014-10-21T17:15:00 + + Taylorsville, NC + mark + + + 23330527 + ODispatch + Dispatched for Pick-Up + 2014-10-20T16:01:00 + + Taylorsville, NC + Keefe Katharina + + + + + 2014-10-21T17:14:57.367 + Email: ScheduleMyDelivery.com Invitation + ArgyrosAlbinus@Example.com + + + 2014-10-21T19:23:13.090 + Call: Client Accepted Date & Time + Scheduled - Client Accepted + + + 2014-10-30T07:00:46.450 + Email: Schedule Reminder + Sched Reminder Email + + + + \ No newline at end of file diff --git a/README.md b/README.md index 7514a38..5699723 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,25 @@ EDI API ======= -General overview for all EDI (Electronic Data Interchange) systems. +General overview for all of Manna's EDI (Electronic Data Interchange) systems. -You can also follow us on Twitter [@MFSTech](http://twitter.com/MFSTech). +Follow [@MFSTech](http://twitter.com/MFSTech) on Twitter! Customers --------- -* [Send Us Shipments](https://github.com/MFSTech/SendUsShipments) -* [Get Statuses](https://github.com/MFSTech/GetStatuses/) -* [Get Invoices](https://github.com/MFSTech/GetInvoices/) +* [Send Shipments](SendShipments) +* [Get Statuses](GetStatuses/) +* [Get Invoices](GetInvoices/) Vendors ------- -* [Get Shipments](https://github.com/MFSTech/GetShipments/) -* [Send Statuses](https://github.com/MFSTech/SendStatuses/) -* [Send Invoices](https://github.com/MFSTech/SendInvoices/) +* [Get Shipments](GetShipments/) +* [Send Statuses](SendStatuses/) +* [Send Invoices](SendInvoices/) Code Lists ---------- -* [MFS EDI API Codes](Codes.md) \ No newline at end of file +* [MFS EDI API Codes](Codes.md) diff --git a/SendInvoices/InvoiceXMLInbound-Sample.xml b/SendInvoices/InvoiceXMLInbound-Sample.xml new file mode 100644 index 0000000..817ecc8 --- /dev/null +++ b/SendInvoices/InvoiceXMLInbound-Sample.xml @@ -0,0 +1,161 @@ + + + + 781912826 + + + 2013-07-04T10:23:11-06:00 + + + 2013-07-04T16:23:11Z + + + + Clarity2UserName + + + 0xC8CCDC91AB2DF9EC8D449E987E727CB8A67E1330 + + + + + + 289121897 + + 2013-07-04T10:23:11-06:00 + + + + D1234568 + 1234568 + + + + 3119490 + 1 + 10 + 20 + 30 + 100 + 24 + + + + + FRT + A1 + Freight Charge + 0.10 + 100 + 5 + 10 + + + FUL + R022 + Fuel Surcharge + 0.005 + 10.00 + 0 + 0.05 + + + + 1 + 100 + 24 + 100 + 10.05 + + + + + D9832034 + 9832034 + + + + 3119484 + 5 + 2 + 10 + 12 + 100 + 24 + + + + + FRT + A1 + Freight Charge + .10 + 500 + 5 + 50 + + + + 5 + 100 + 24 + 100 + 50 + + + + + + + 289121975 + + 2013-07-04T10:24:11-06:00 + + + + D9723219 + 9723219 + + + + 3119825 + 25 + 1 + 2 + 5 + 145 + 24 + + + 3119821 + 5 + 12 + 1 + 1 + 20 + 10 + + + + + FRT + A1 + Freight Charge + 0.15 + 100 + 5 + 15 + + + + 30 + 165 + 34 + 165 + 15 + + + + + + diff --git a/SendInvoices/README.md b/SendInvoices/README.md new file mode 100644 index 0000000..fceced7 --- /dev/null +++ b/SendInvoices/README.md @@ -0,0 +1,5 @@ +SendInvoices +============ + +EDI (API) Documentation for the Standard, XML-Based, Vendor Invoice HTTP Endpoint + diff --git a/SendShipments/ProcessFlags.md b/SendShipments/ProcessFlags.md new file mode 100644 index 0000000..8002074 --- /dev/null +++ b/SendShipments/ProcessFlags.md @@ -0,0 +1,20 @@ +The Process element in the Shipment XML format accepts a number of keywords which impact the handling of your submission. You can specify multiple keywords by delimiting with the plus sign (+). + +Current flag keywords: + +* `FULL` - Shipment will be flagged as "customer processed". Username and password must be valid, and user must have access to create and process orders with the controller and bill-to specified. +* `NOW` - Shipment will be handled immediately and a tracking number will be provided. +* `LABEL` - Must correspond with `NOW`. Label printer code will be returned with shipment acknowledgment data. The default language is Datamax. +* `LABEL_DATAMAX` - Must correspond with `LABEL`. Indicates the label printer code will be in the Datamax label printing language. +* `LABEL_ZEBRA` - Must correspond with `LABEL`. Indicates the label printer code will be in the Zebra label printing language. +* `LABEL_EPL2` - Must correspond with `LABEL`. Indicates the label printer code will be in the EPL2 (some Zebra, formerly Eltron printers, especially those used by UPS and FedEx) label printing lanaguage. +* `LABEL_COGNITIVE` - Must correspond with `LABEL`. Indicates the label printer code will be in the Cognitive label printing language. +* `CHARGES` - Response will contain summary charge information (total charges). Must correspond with `NOW`. Username and password must be valid, and user must have access to create and process orders with the controller and bill-to specified. +* `NONAMESWAP` - The default behavior is to swap the Name and Contact fields of any address if the Name field is blank and the Contact field is not. (The system requires a non-blank Name to process a shipment, so it's convenient to the user to swap these values if the name has been placed in the Contact field instead of the Name field.) Specifying this flag suppress this default swapping behavior. +* `CLEANVIEW` - Only relevant if ShipmentFeeder.asp is used. Acknowledgment page will be formatted in a user-friendly manner. Must NOT correspond with `LABEL`. +* `BOLDRREDIR` - Only relevant if ShipmentFeeder.asp is used. Acknowledgment page will automatically redirect to shipment's Delivery Receipt. Must correspond with `NOW`. Must correspond with `FULL`. Must correspond with `CLEANVIEW`. +* `MAKERETURN` - We will create a Return shipment in the opposite direction of the original, linked as part of an Advance Exchange (AX) group. +* `CANCEL` - Shipment will be canceled. Shipment must not be processed, nor in transit. This flag will preempt most other flags. The MFSTextID or MFSID must be supplied. Username and password must be valid, and user must have access to create and process orders with the controller and bill-to specified. +* `DELAGENT` - Must correspond with `NOW`. Delivery Agent information will be returned with shipment acknolwedgement data. This will extend processing time as the system calculates and applies the appropriate routing. Username and Password security is enforced. +* `CUSTCARRIER` - Last Mile Style shipment will be updated with customer-controlled carrier tracking information. This flag will preempt most other flags. The MFSTextID or MFSID must be supplied. Username and password must be valid, and user must have access to create and process orders with the controller and bill-to specified. +* `INVENTORY` - Shipment will be integrated with inventory management system. Several other flags are incompatible with this, such as `FULL`, `NONAMESWAP`, `DELAGENT`, `CUSTCARRIER`, and `MAKERETURN`. diff --git a/SendShipments/README.md b/SendShipments/README.md new file mode 100644 index 0000000..17d4d65 --- /dev/null +++ b/SendShipments/README.md @@ -0,0 +1,120 @@ +Send Us Shipments +================= + +EDI (API) Documentation for the Standard, XML-Based, Customer Shipment HTTP Endpoint + +Overview +-------- + +Manna Freight Systems, Inc. has in place an electronic data transmission system capable of accepting and responding to shipment requests in near real time. It receives data in XML format using the same communication technology as web pages. It is flexible, extensible, human-readable, easy to use through firewalls, and can be initiated on-demand rather than merely at specified intervals. + +This is intended for our customers to send us the information required for us move product for them. We call this movement a shipment. The basic requirements for a shipment are the origin, destination, speed, level of service, and some information about what we are moving (i.e. the pieces). + +We are configured to receive this data as specially-formatted XML in a standard HTTP POST. However, it is not the same as a POST from an HTML page (that puts data in URL format-- strictly speaking, Internet media type "application/x-www-form-urlencoded"-- not XML). You must directly control the content of the POST (e.g. using a toolset such as Microsoft's XML over HTTP-- MSXML2.ServerXMLHTTP). + +The body of the HTTP response will be an XML acknowledgment, except in cases of unhandled errors or system failures. The same XML elements regardless of the success or failure of the transmission, though some elements are only populated in some situations. + +* The status code of the HTTP response to a successful POST will be either 200 or 202, depending on whether you choose to process the shipment information synchronously (immediately) or asynchronously (after the submission, for submission performance purposes). The choice is controlled using flags in your XML submission (see [ProcessFlags.md](ProcessFlags.md)). + * If you choose to process the submission synchronously, the status code will be 200, and the response will contain tracking numbers and other optional information. + * If you choose to process the submission asynchronously, the status code will be 202, and you will receive only a basic acknowledgment indicating that the submission passed basic (fast) syntactical checks. In that case, further information can optionally be sent to you via POST to a web resource (a mirror of your submission process). If you choose to process the submission synchronously, the response will contain tracking numbers and other optional information. Few customers choose this method. If you choose this method: + * You must establish an HTTP endpoint of your own to accept these responses. + * You will not know the true success or failure of your transmission until you receive the response transmission from us. +* In any case, if you get a response other than 200 or 202, likely something was wrong with your request or our servers. In anything but a serious error, you should get some information back in the XML which will tell you what was wrong with your request. Sometimes, there is something wrong with your shipment information which prevents it from fully processing in our system, but it is sufficient to create a shipment record. In this case, you will get a 200 status and more complete XML information, but there would still be some indication of the problem in the XML variables. + +Note that the XML spec presumes that you will use certain codes for service requests and product types, among other things. We will be able to provide you those codes once we verify with our sales or operations departments which are applicable to your relationship with us. + +We will update the XML system from time to time but the goal is to maintain as much backward compatibility as possible. + +If you experience problems using our XML system you contact our Help Desk at 651-994-7535 or email Support@MFSCorporate.com. + +Endpoint Addresses +------------------ + +All URLs which have a host name of "demo" are for testing. They are served by a sandbox system which can be but is not generally accessed by our operations staff. We recommend that you begin your development using these test URLs. New customers are not created immediately in this system, though do get migrated over time. You should coordinate with us to ensure your customer information is configured in the new system. + +All URLs which have a host name of "EDI" are for production. Unless you specially coordinate with us in advance, if you send shipment data to these addresses and it is successfully processed, we will act on the shipment and you will be subject to charges. Using fake names, addresses, or labeling it as "test" are insufficient protection. We have many automated processes which will not recognize the shipment as a test. + +All URLs are case insensitive. + +### Transmission Testing Addresses + +On either the test or production servers, you can test the transmission process without worrying about the XML content by using these URLs: + +* Test: [http://demo.MFSClarity.com/EDI/XMLInTest.asp](http://demo.MFSClarity.com/EDI/XMLInTest.asp) +* Production: [http://EDI.MFSClarity.com/EDI/XMLInTest.asp](http://EDI.MFSClarity.com/EDI/XMLInTest.asp) + +They gather XML from the HTTP POST body and echo it back out as part of a simplified XML acknowledgment. + +### Content Addresses + +These URLs receive shipment data in the official XML format and create shipments in our system. +* Test: [http://demo.MFSClarity.com/EDI/Cust/Shipment.asp](http://demo.MFSClarity.com/EDI/Cust/Shipment.asp) +* Production: [http://EDI.MFSClarity.com/EDI/Cust/Shipment.asp](http://EDI.MFSClarity.com/EDI/Cust/Shipment.asp) + +### Feeder Addresses + +If you have sample XML you wish to test without sending it through your system as an actual POST, you can use our testing "feeder" harness to send XML to the content or transmission testing pages. + +* Transmission Test, Test: [http://demo.MFSClarity.com/EDI/XMLInTestFeeder.asp](http://demo.MFSClarity.com/EDI/XMLInTestFeeder.asp) +* Transmission Test, Production: [http://EDI.MFSClarity.com/EDI/XMLInTestFeeder.asp](http://EDI.MFSClarity.com/EDI/XMLInTestFeeder.asp) +* Content, Test: [http://demo.MFSClarity.com/EDI/Cust/ShipmentFeeder.asp](http://demo.MFSClarity.com/EDI/Cust/ShipmentFeeder.asp) +* Content, Production: [http://EDI.MFSClarity.com/EDI/Cust/ShipmentFeeder.asp](http://EDI.MFSClarity.com/EDI/Cust/ShipmentFeeder.asp) + +### Clarity Addresses + +Our customers often use our Clarity web application to manually enter shipment requests and track shipments. Each system, test and production, has a connected Clarity web application which can be used to review your EDI submissions. It can also be used to adjust your credentials (username and password). + +* Test: [http://demo.MFSClarity.com/Clarity/](http://demo.MFSClarity.com/Clarity/) +* Production: [http://www.MFSClarity.com/Clarity/](http://www.MFSClarity.com/Clarity/) + +Key Files +--------- + +* [Shipment.dtd](Shipment.dtd) - The Document Type Definition which defines the XML format for the shipment transmission (sent to Shipment.asp). This is also hosted next to the EDI processing end point. For example, it is located at these locations: + * [http://demo.MFSClarity.com/EDI/Cust/Shipment.dtd](http://demo.MFSClarity.com/EDI/Cust/Shipment.dtd) + * [http://EDI.MFSClarity.com/EDI/Cust/Shipment.dtd](http://EDI.MFSClarity.com/EDI/Cust/Shipment.dtd) +* [Shipment.xml](Shipment.xml) - A sample submission of a new shipment request. +* [Shipment-Commented.xml](Shipment-Commented.xml) - A sample submission of a new shipment request, with comments on the various elements. +* [ShipAck.xml](ShipAck.xml) - A sample response to a successful transmission. +* [ShipAck-Commented.xml](ShipAck-Commented.xml) - A sample response to a successful transmission, with comments on the various elements. +* [ProcessFlags.md](ProcessFlags.md) - A list of all keywords which can be used in the `Process` element + +Special Cases +------------- + +### Cancellation + +The standard DTD and format is designed for new and updated shipment information. When canceling a shipment request, much less information is required, and the standard DTD would be too onerous. A revised DTD and associated example is provided here: + +* [ShipmentCancel.dtd](ShipmentCancel.dtd) - Specifying the DTD is optional. +* [ShipmentCancel.xml](ShipmentCancel.xml) - Sample + +### Carrier Update + +One type of service we provide involves the customer transporting the product to our "last mile" provider, which then makes the final delivery. For this style of shipment, the customer is required to specify the tracking information for the other carrier which will be delivering the product to our provider. Because this is a small subset of shipment information, we created a separate, simplified format. + +* [ShipmentCarrierUpdate.dtd](ShipmentCarrierUpdate.dtd) - Specifying the DTD is optional. +* [ShipmentCarrierUpdate.xml](ShipmentCarrierUpdate.xml) - Sample + +Helpful Hints +------------- + +* After this document, [Shipment-Commented.xml](Shipment-Commented.xml) should be the next document you review. +* If you get a 202 status code, you don't know whether you have really been successful. +* You probably want to send `NOW` in the `Process` element to engage synchronous processing and avoid getting a 202 status code. +* Even when you don't get a 200 or 202 status code, you should still mine the response for the XML, as it will usually contain information in the ParseErrors section which explain what went wrong. +* If you navigate directly to the endpoint URLs, you will receive an XML response which says, among other things, "XML document must have a top level element.". That is because you have not POSTed any XML. +* You cannot pass the endpoint your XML in a named parameter as you would with a normal web form. (You can pass the XML as a parameter named XML to the "feeder" pages, but that is intended only for testing and is not supported for automated use.) +* Having trouble getting a success out of our system? See if it's your transmission mechanism or the XML itself by posting the XML into our "feeder" page (see above). +* The sample files won't necessarily process without error. For example, if you put `NOW` into the `Process` element of the sample, you will get an error because `FULL` is not specified though the `ScheduleDate` element is populated. If you resolve that issue, you will often find other errors, such as the control number type "CustomControlNumber" not existing. The sample is designed to show a variety of features of the XML format; it is not designed to be a simple, successful transmission. +* Theoretically, you could begin using this system without assistance from us using your existing Clarity credentials. There are no special authorizations or settings required. However, you will likely need our help to make sure your customer information is configured in the sandbox environment and for the lists of codes required to represent service types and product types (for example). + +Technical Notes +--------------- + +* You do not need to specify a content-type. It is not enforced. +* The DTD reference is optional. When specified, our server will use the DTD to validate the XML and reject it if invalid (even if our lower level systems could still manage to interpret it). +* The order of XML elements is irrelevant once the XML makes its way through the DTD-based validation (or if you simply omit the DTD reference). +* The format of the acknowledgment XML sent in the body of the HTTP response will evolve. We will strive never to remove or alter existing elements-- and indeed have not to date-- but we have and will continue to add new elements. +* We won't act on a shipment unless it's fully processed, which requires you to send `FULL` in the `Process` element (see also [ProcessFlags.md](ProcessFlags.md)). +* You can only modify shipments until they are fully processed. You cannot cancel nor can you edit a shipment once it has been fully processed. diff --git a/SendShipments/ShipAck-Commented.xml b/SendShipments/ShipAck-Commented.xml new file mode 100644 index 0000000..4377cb4 --- /dev/null +++ b/SendShipments/ShipAck-Commented.xml @@ -0,0 +1,151 @@ + + + + + 200 + + + + 13239 + + + + 0 + + + + + + + + 2 + + + + Ready Date is less than Processing Date. Shipment Type must be selected. + + + + 2579859 + + + + H2579859 + + + + 0 + + + + f140 O0000 a L PK H20 191100305550015Manna Distribution Services 191100205350015800-394-3949 1a1200004550015*H2579859* 1X0000004470015L370003 111100005200015Ship: 11110000520010009/14/2004 111100005000015Deliver: 11110000500010009/20/2004 111100005400210PO: 111100005400250CustPONum 111100005200210REF: 111100005200250CustBOLNum 111100005000210RMA: 111100005000250CustRMANum 211100003800370BOL: 231100903000370H2579859 211100003800340PIECES: 222100003000340001 + 01 211100002200340OF: 2221000018003405 211100004200320SHIPPER: 211100003300320Billy Bob's TV Emporium 211100003300300Billy Bob 2111000033002801234 Main Street 211100003300260Bldg B 211100003300240Mendota Heights, MN 55120 US 1X0000000300237L002417 211100004200220Cons: 211100003300220Tommy Techno 211100003300200 2111000033001801234 Elm Street 211100003300160Los Angeles, CA 90001 US 211100003300140 292200703500000LAX 201100003900015Please treat this carefully. It's very important to me. :> 201100003900005 111100000010100Adult Signature Required Q0005 E + + + + 1234 + + + + http://www.MFSClarity.com/Clarity/Reports/BOLDR.asp?BOL=H2580701&SecCode=4184 + + + + http://www.MFSClarity.com/View/LabelPrinting/?BOL=H2580701&SecCode=4184 + + + + http://www.MFSClarity.com/View/LabelPrinting/?BOL=H2580701&SecCode=4184&Format=OnePerPage + + + + http://www.MFSClarity.com/View/LabelPrinting/pdflabel.aspx?tran=2580701&seccode=4184&Color=1 + + + + + SampleID + Sample Agent Name + 1234 Big Freight Lane + Suite 456 + Mendota Heights + MN + 55120 + US + 555-555-1999 + agentemail@example.com + + + + + diff --git a/SendShipments/ShipAck.xml b/SendShipments/ShipAck.xml new file mode 100644 index 0000000..406bb91 --- /dev/null +++ b/SendShipments/ShipAck.xml @@ -0,0 +1,48 @@ + + + + + 200 + + 13239 + + 0 + + + + 2 + + Ready Date is less than Processing Date. Shipment Type must be selected. + + 2579859 + + H2579859 + + 0 + + f140 O0000 a L PK H20 191100305550015Manna Distribution Services 191100205350015800-394-3949 1a1200004550015*H2579859* 1X0000004470015L370003 111100005200015Ship: 11110000520010009/14/2004 111100005000015Deliver: 11110000500010009/20/2004 111100005400210PO: 111100005400250CustPONum 111100005200210REF: 111100005200250CustBOLNum 111100005000210RMA: 111100005000250CustRMANum 211100003800370BOL: 231100903000370H2579859 211100003800340PIECES: 222100003000340001 + 01 211100002200340OF: 2221000018003405 211100004200320SHIPPER: 211100003300320Billy Bob's TV Emporium 211100003300300Billy Bob 2111000033002801234 Main Street 211100003300260Bldg B 211100003300240Mendota Heights, MN 55120 US 1X0000000300237L002417 211100004200220Cons: 211100003300220Tommy Techno 211100003300200 2111000033001801234 Elm Street 211100003300160Los Angeles, CA 90001 US 211100003300140 292200703500000LAX 201100003900015Please treat this carefully. It's very important to me. :> 201100003900005 111100000010100Adult Signature Required Q0005 E + + 1234 + + http://www.MFSClarity.com/Clarity/Reports/BOLDR.asp?BOL=H2580701&SecCode=4184 + + http://www.MFSClarity.com/View/LabelPrinting/?BOL=H2580701&SecCode=4184 + + http://www.MFSClarity.com/View/LabelPrinting/?BOL=H2580701&SecCode=4184&Format=OnePerPage + + http://www.MFSClarity.com/View/LabelPrinting/pdflabel.aspx?tran=2580701&seccode=4184&Color=1 + + + SampleID + Sample Agent Name + 1234 Big Freight Lane + Suite 456 + Mendota Heights + MN + 55120 + US + 555-555-1999 + agentemail@example.com + + + diff --git a/SendShipments/Shipment-Commented.xml b/SendShipments/Shipment-Commented.xml new file mode 100644 index 0000000..6dbef25 --- /dev/null +++ b/SendShipments/Shipment-Commented.xml @@ -0,0 +1,347 @@ + + + + + + + + + + + + + + + ACMEComp + CompACME + + + + 1111 + + + + 1234 + + + + ACMEComp + ACMEComp + + + + + + + + + + + + + + R + + + + 2008-08-21 + + + + 2008-08-21 + + + + 2008-08-21 + + + TH + + + + Delivery + + + + 1:00 PM + 5:00 PM + + + + CustPONum + CustBOLNum + CustRMANum + + + + Please treat this carefully. It's very important to me. :> + + + + This is a really big box. + + + + Check + 1234.56 + + + + BBTV + Billy Bob's TV Emporium + Billy Bob + 1234 Main Street + Bldg B + Mendota Heights + MN + 55120 + + US + 651-905-7560 + 555-555-5555 + 555-555-5555 + 555-555-5555 + 555-555-5555 + 555-555-5555 + spam@manna.com + Business + + + + + Tommy Techno + + 1234 Elm Street + + Los Angeles + CA + 90001 + + US + 555-555-5555 + + 555-555-5555 + 555-555-5555 + 555-555-5555 + 555-555-5555 + + Residential + + + + + 5 + BOXROXPTV60 + Big Box 60" PTV + + PDP-060 + + + + 120 + 2000 + Pallet + + + + 5 + RECEIVER123 + JVC Receiver 123 + + Receiver + 10 + 20 + 5 + 20 + 1000 + + + + + 1 + + + Pallet of 2 Microwaves and Range Hood + Other + 40 + 48 + 40 + 600 + 1500 + + 3 + + + + + + CustomControlNumber + 12345 + + + + + + Install + 1 + + + + Assembly + 1 + + + + + \ No newline at end of file diff --git a/SendShipments/Shipment.dtd b/SendShipments/Shipment.dtd new file mode 100644 index 0000000..432f203 --- /dev/null +++ b/SendShipments/Shipment.dtd @@ -0,0 +1,178 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/SendShipments/Shipment.xml b/SendShipments/Shipment.xml new file mode 100644 index 0000000..1d9be67 --- /dev/null +++ b/SendShipments/Shipment.xml @@ -0,0 +1,139 @@ + + + + + + + + + ACMEComp + CompACME + + 1111 + + 1234 + + ACMEComp + ACMEComp + + + + + + + R + 2008-08-21 + 2008-08-21 + 2008-08-21 + + TH + Delivery + 1:00 PM + 5:00 PM + + CustPONum + CustBOLNum + CustRMANum + + Please treat this carefully. It's very important to me. :> + This is a really big box. + Check + 1234.56 + + BBTV + Billy Bob's TV Emporium + Billy Bob + 1234 Main Street + Bldg B + Mendota Heights + MN + 55120 + + US + 651-905-7560 + 555-555-5555 + 555-555-5555 + 555-555-5555 + 555-555-5555 + 555-555-5555 + spam@manna.com + Business + + + Tommy Techno + + 1234 Elm Street + + Los Angeles + CA + 90001 + + US + 555-555-5555 + + 555-555-5555 + 555-555-5555 + 555-555-5555 + 555-555-5555 + + Residential + + + 5 + BOXROXPTV60 + Big Box 60" PTV + + PDP-060 + + + + 120 + 2000 + Pallet + + + + 5 + RECEIVER123 + JVC Receiver 123 + + Receiver + 10 + 20 + 5 + 20 + 1000 + + + + + 1 + + + Pallet of 2 Microwaves and Range Hood + Other + 40 + 48 + 40 + 600 + 1500 + + 3 + + + + CustomControlNumber + 12345 + + + + Install + 1 + + + + Assembly + 1 + + + \ No newline at end of file diff --git a/SendShipments/ShipmentCancel.dtd b/SendShipments/ShipmentCancel.dtd new file mode 100644 index 0000000..981ff27 --- /dev/null +++ b/SendShipments/ShipmentCancel.dtd @@ -0,0 +1,27 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/SendShipments/ShipmentCancel.xml b/SendShipments/ShipmentCancel.xml new file mode 100644 index 0000000..3e940b7 --- /dev/null +++ b/SendShipments/ShipmentCancel.xml @@ -0,0 +1,16 @@ + + + + + + + + + 1234 + ACMEComp + CompACME + + H1234568 + NOW+CANCEL + + \ No newline at end of file diff --git a/SendShipments/ShipmentCarrierUpdate.dtd b/SendShipments/ShipmentCarrierUpdate.dtd new file mode 100644 index 0000000..fc1f781 --- /dev/null +++ b/SendShipments/ShipmentCarrierUpdate.dtd @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/SendShipments/ShipmentCarrierUpdate.xml b/SendShipments/ShipmentCarrierUpdate.xml new file mode 100644 index 0000000..99b2791 --- /dev/null +++ b/SendShipments/ShipmentCarrierUpdate.xml @@ -0,0 +1,21 @@ + + + + + + + + + ACMEComp + CompACME + + H1234568 + UPS + United Parcel Service + 3/29/2010 + 5 + + 1Z1112345 + NOW+CUSTCARRIER + + \ No newline at end of file diff --git a/SendStatuses/README.md b/SendStatuses/README.md new file mode 100644 index 0000000..43ca6da --- /dev/null +++ b/SendStatuses/README.md @@ -0,0 +1,4 @@ +SendStatuses +============ + +EDI (API) Documentation for the Standard, XML-Based, Vendor Status HTTP Endpoint diff --git a/SendStatuses/StatusXMLInbound-Response-Failure-Sample.xml b/SendStatuses/StatusXMLInbound-Response-Failure-Sample.xml new file mode 100644 index 0000000..ce606a0 --- /dev/null +++ b/SendStatuses/StatusXMLInbound-Response-Failure-Sample.xml @@ -0,0 +1,23 @@ + + + + 781912826 + + + 3271616819 + + + 2012-10-18T21:02:17.300Z + + + 2012-10-18T16:02:17.300-05:00 + + + + + 123 + + + Invalid status type. + + diff --git a/SendStatuses/StatusXMLInbound-Response-Success-Sample.xml b/SendStatuses/StatusXMLInbound-Response-Success-Sample.xml new file mode 100644 index 0000000..38d164d --- /dev/null +++ b/SendStatuses/StatusXMLInbound-Response-Success-Sample.xml @@ -0,0 +1,22 @@ + + + + 781912826 + + + 3271616819 + + + 2012-10-18T21:02:17.300Z + + + 2012-10-18T16:02:17.300-05:00 + + + 1234556311 + + + + + + diff --git a/SendStatuses/StatusXMLInbound-Sample.xml b/SendStatuses/StatusXMLInbound-Sample.xml new file mode 100644 index 0000000..e14b404 --- /dev/null +++ b/SendStatuses/StatusXMLInbound-Sample.xml @@ -0,0 +1,216 @@ + + + + 781912826 + + + 2007-01-04T10:23:11-06:00 + + + 2007-01-04T16:23:11Z + + + + Clarity2UserName + + + 0xC8CCDC91AB2DF9EC8D449E987E727CB8A67E1330 + + + + + + 289121897 + + + + + 2007-01-04T17:00:00 + + + 2007-01-04T17:30:00 + + + + D1234568 + 1234568 + + + + 8887255 + 1 + 10 + 20 + 30 + 100 + 24 + + + + + FRT + A1 + Freight Charge + 0.10 + 100 + 5 + 10 + + + FUL + R022 + Fuel Surcharge + 0.005 + 10.00 + 0 + 0.05 + + + + 3 + 100 + 24 + 100 + 10.05 + + + + + 88237788 + + + 23123181 + + + MSP + + + VendID031 + + + Truck Loaded + + + OutForDel + + + 2007-01-04T10:00:00 + + + 2007-01-04T10:21:12 + + + + + Bobby + + + + + + 289121898 + + + + + 2007-01-03T10:00:00 + + + 2007-01-04T17:30:00 + + + + ZZZAAA222 + D5543214 + 5543214 + H5543213 + 5543213 + + + + 8887212 + 2 + 50 + 20 + 70 + 150 + 280 + + + 8887213 + 1 + 10 + 40 + 5 + 50 + 8 + + Crushed Top-Right Corner + + + + + + FRT + A1 + Freight Charge + 0.10 + 568 + 5 + 56.80 + + + FUL + R022 + Fuel Surcharge + 0.005 + 56.80 + 0 + 0.28 + + + + 3 + 350 + 568 + 568 + 57.08 + + + + + 88237789 + + + 23123324 + + + LAX + + + VendID097 + + + Product Delivered + + + Delivery + + + Proof of Delivery + + + 2007-01-04T17:30:00 + + + 2007-01-04T10:21:13 + + + + + Steve + + + + + \ No newline at end of file