Place Order
===========

Order Placement Service

.. code-block:: none
    :caption: Service Endpoint

    POST https://gateway.groupvan.com/json/federated/v3_1/place_order

Request
-------

Parameters
~~~~~~~~~~

``purchase_order_number`` :bdg:`string` :bdg-danger:`required`
    Purchase order number assigned by the buyer

``comment`` :bdg:`string`
    Optional comment to be sent to the seller system

``order_type`` :bdg:`integer` :bdg-danger:`required`
    See `Order Type <../reference/common-codes.html#order-type>`_ for options.

``items`` :bdg:`array` :bdg-danger:`required`
    An array of items to request from the seller system

    ``id`` :bdg:`string` :bdg-danger:`required`
        Unique ID assigned by the seller system

    ``mfr_code`` :bdg:`string` :bdg-danger:`required`
        Manufacturer Code

    ``part_number`` :bdg:`string` :bdg-danger:`required`
        Part Number

    ``location_id`` :bdg:`string` :bdg-danger:`required`
        Location ID

    ``quantity_ordered`` :bdg:`float` :bdg-danger:`required`
        Quantity Ordered

    ``vehicle_description`` :bdg:`string`
        Optional vehicle description. This is only required if the seller system requires it.

``ship_to`` :bdg:`object`
    An optional object containing ship to information. This is only required if the seller system requires it.

    ``company_name`` :bdg:`string`
        Company Name

    ``first_name`` :bdg:`string`
        First Name

    ``last_name`` :bdg:`string`
        Last Name

    ``title`` :bdg:`string`
        Title

    ``phone`` :bdg:`string`
        Phone Number

    ``fax`` :bdg:`string`
        Fax Number

    ``email`` :bdg:`string`
        Email Address

    ``address_1`` :bdg:`string`
        Address Line 1

    ``address_2`` :bdg:`string`
        Address Line 2

    ``city`` :bdg:`string`
        City

    ``country_division_code`` :bdg:`string`
        Country Division Code (State)

    ``country_code`` :bdg:`string`
        Country Code (ISO 3166-1 alpha-2)

    ``postal`` :bdg:`string`
        Postal Code

``ship_via`` :bdg:`string`
    Optional field to specify the shipping method.

Examples
~~~~~~~~

.. tab:: Buyer

    .. code-block:: json

        {
            "purchase_order_number": "WND-210108A",
            "comment": "optional comment",
            "order_type": 1,
            "items": [
                {
                    "id": "1",
                    "mfr_code": "ACD",
                    "part_number": "PF63E",
                    "location_id": "Loc0001",
                    "quantity_ordered": 1,
                    "vehicle_description": "Toyota Corolla"
                },
                {
                    "id": "2",
                    "mfr_code": "FBO",
                    "part_number": "5276029",
                    "location_id": "Loc0001",
                    "quantity_ordered": 4,
                    "vehicle_description": "Mazda Miata"
                }
            ],
            "ship_to": {
                "company_name": "City Automotive",
                "first_name": "John",
                "last_name": "Doe",
                "title": "Service Manager",
                "phone": "5555555555",
                "fax": "5555555555",
                "email": "email@example.com",
                "address_1": "123 Main St",
                "address_2": "Unit 1",
                "city": "Staunton",
                "country_division_code": "VA",
                "country_code": "US",
                "postal": "24401",
            }
        }

.. tab:: Seller

    .. code-block:: json

        {
            "service": "place_order",
            "integration": "B2C",
            "terminal_id": "optional field",
            "purchase_order_number": "WND-210108A",
            "comment": "please deliver ASAP",
            "order_type": 1,
            "items": [
                {
                    "id": "1",
                    "mfr_code": "ACD",
                    "part_number": "PF63E",
                    "location_id": "Loc0001",
                    "account_id": "987654",
                    "quantity_ordered": 1,
                    "vehicle_description": "Toyota Corolla"
                },
                {
                    "id": "2",
                    "mfr_code": "FBO",
                    "part_number": "5276029",
                    "location_id": "Loc0001",
                    "account_id": "987654",
                    "quantity_ordered": 4,
                    "vehicle_description": "Mazda Miata"
                }
            ]
        }

Schema
~~~~~~~~

.. dropdown:: Request JSON Schema

    .. code-block:: json

        {
          "type": "object",
          "properties": {
            "service": {
              "type": "string"
            },
            "integration": {
              "type": "string"
            },
            "terminal_id": {
              "type": "string"
            },
            "purchase_order_number": {
              "type": "string"
            },
            "comment": {
              "type": "string"
            },
            "order_type": {
              "type": "integer"
            },
            "items": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "mfr_code": {
                      "type": "string"
                    },
                    "part_number": {
                      "type": "string"
                    },
                    "location_id": {
                      "type": "string"
                    },
                    "account_id": {
                      "type": "string"
                    },
                    "member_id": {
                      "type": "string"
                    },
                    "quantity_ordered": {
                      "type": "float"
                    },
                    "vehicle_description": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "mfr_code",
                    "part_number",
                    "location_id",
                    "account_id",
                    "member_id",
                    "quantity_ordered"
                  ]
                }
              ]
            },
            "ship_to": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "company_name": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "last_name": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "fax": {
                      "type": "string"
                    },
                    "email": {
                      "type": "float"
                    },
                    "address_1": {
                      "type": "string"
                    },
                    "address_2": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "country_division_code": {
                      "type": "string"
                    },
                    "country_code": {
                      "type": "string"
                    },
                    "postal": {
                      "type": "string"
                    }
                  }
                }
              ]
            }
          },
          "required": [
            "service",
            "purchase_order_number",
            "order_type",
            "items"
          ]
        }

Response
--------

Seller must return the same ``id`` as defined by the Buyer system.

Example
~~~~~~~~

.. code-block:: json

    {
        "order_number": "ABC1234",
        "status_code": 2000,
        "comment": "optional human readable comment",
        "items": [
            {
                "id": "1",
                "status_code": 1,
                "quantity_ordered": 1,
                "comment": "optional human readable comment"
            },
            {
                "id": "2",
                "status_code": 1,
                "quantity_ordered": 1,
                "comment": "optional human readable comment"
            }
        ]
    }


Schema
~~~~~~~~

.. dropdown:: Response JSON Schema

    .. code-block:: json

        {
            "type": "object",
            "properties": {
                "order_number": {
                    "type": "string"
                },
                "status_code": {
                    "type": "integer"
                },
                "comment": {
                    "type": "string"
                },
                "items": {
                    "type": "array",
                    "items": [
                        {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "status_code": {
                                    "type": "integer"
                                },
                                "quantity_ordered": {
                                    "type": "float"
                                },
                                "comment": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "id",
                                "status_code",
                                "quantity_ordered"
                            ]
                        }
                    ]
                }
            },
            "required": [
                "order_number",
                "status_code",
                "items"
            ]
        }

.. tip::

    ``comment`` fields are optional and can by used to return a human readable message to the buyer