Invoices
========

.. seealso:: :doc:`../authentication` for JWT authentication details.

Invoices Service

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

    POST https://gateway.groupvan.com/json/federated/v3_2/invoice

Request
-------

The ``member`` field is required to make a request from the Buyer system. GroupVAN Gateway resolves account and
location information before forwarding the request to the Seller system.

The remaining fields are optional filters. Provide a date range with ``from_invoice_date`` and ``to_invoice_date``,
or narrow results to a specific ``invoice_number``, ``po_number``, ``location_id`` or ``part_number``.

Parameters
~~~~~~~~~~

``member`` :bdg:`string` :bdg-danger:`required`
    Member ID in GroupLink

``account`` :bdg:`string`
    Account ID in Member System

``invoice_number`` :bdg:`string`
    Filter results to a specific invoice number

``po_number`` :bdg:`string`
    Filter results to a specific purchase order number

``from_invoice_date`` :bdg:`string`
    Start of the invoice date range (``YYYY-MM-DD``)

``to_invoice_date`` :bdg:`string`
    End of the invoice date range (``YYYY-MM-DD``)

``location_id`` :bdg:`string`
    Filter results to a specific location

``part_number`` :bdg:`string`
    Filter results to a specific part number

``invoice_type`` :bdg:`string`
    Filter results to a specific invoice type

Examples
~~~~~~~~

.. code-block:: json

    {
        "member": "520",
        "account": "446641",
        "from_invoice_date": "2015-04-04",
        "to_invoice_date": "2015-04-06",
        "location_id": "Loc0001"
    }

Schema
~~~~~~~~

.. dropdown:: Request JSON Schema

    .. code-block:: json

        {
            "type": "object",
            "properties": {
                "member": {
                    "type": "string"
                },
                "account": {
                    "type": "string"
                },
                "invoice_number": {
                    "type": "string"
                },
                "po_number": {
                    "type": "string"
                },
                "from_invoice_date": {
                    "type": "string"
                },
                "to_invoice_date": {
                    "type": "string"
                },
                "location_id": {
                    "type": "string"
                },
                "part_number": {
                    "type": "string"
                },
                "invoice_type": {
                    "type": "string"
                }
            },
            "required": [
                "member"
            ]
        }

Response
--------

Seller returns the invoices matching the requested filters. Each invoice contains an ``invoice_detail`` array with
the line items on that invoice.

Examples
~~~~~~~~

.. code-block:: json

    {
        "status": "success",
        "error_description": "",
        "invoices": [
            {
                "invoice_number": "INV-23433",
                "invoice_date": "2015-04-05",
                "account_id": "446641",
                "location_id": "Loc0001",
                "location_description": "Fisher Auto Parts - TESTXX",
                "po_number": "WND-210108A",
                "item_count": 2,
                "total_cost": 59.98,
                "link_url": "https://example.com/invoices/INV-23433.pdf",
                "invoice_detail": [
                    {
                        "item_quantity": 1,
                        "line_code": "ACD",
                        "part_number": "PF63E",
                        "description": "Oil Filter",
                        "list_price": 12.89,
                        "cost": 8.79
                    },
                    {
                        "item_quantity": 4,
                        "line_code": "FBO",
                        "part_number": "5276029",
                        "description": "Air Filter",
                        "list_price": 28.10,
                        "cost": 17.42
                    }
                ]
            }
        ]
    }

Schema
~~~~~~~~

.. dropdown:: Response JSON Schema

    .. code-block:: json

        {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string"
                },
                "error_description": {
                    "type": "string"
                },
                "invoices": {
                    "type": "array",
                    "items": [
                        {
                            "type": "object",
                            "properties": {
                                "invoice_number": {
                                    "type": "string"
                                },
                                "invoice_date": {
                                    "type": "string"
                                },
                                "account_id": {
                                    "type": "string"
                                },
                                "location_id": {
                                    "type": "string"
                                },
                                "location_description": {
                                    "type": "string"
                                },
                                "po_number": {
                                    "type": "string"
                                },
                                "item_count": {
                                    "type": "float"
                                },
                                "total_cost": {
                                    "type": "float"
                                },
                                "link_url": {
                                    "type": "string"
                                },
                                "invoice_detail": {
                                    "type": "array",
                                    "items": [
                                        {
                                            "type": "object",
                                            "properties": {
                                                "item_quantity": {
                                                    "type": "float"
                                                },
                                                "line_code": {
                                                    "type": "string"
                                                },
                                                "part_number": {
                                                    "type": "string"
                                                },
                                                "description": {
                                                    "type": "string"
                                                },
                                                "list_price": {
                                                    "type": "float"
                                                },
                                                "cost": {
                                                    "type": "float"
                                                }
                                            },
                                            "required": [
                                                "item_quantity",
                                                "line_code",
                                                "part_number",
                                                "list_price",
                                                "cost"
                                            ]
                                        }
                                    ]
                                }
                            },
                            "required": [
                                "invoice_number",
                                "invoice_date",
                                "account_id",
                                "location_id",
                                "location_description",
                                "po_number",
                                "item_count",
                                "total_cost",
                                "invoice_detail"
                            ]
                        }
                    ]
                }
            },
            "required": [
                "status",
                "invoices"
            ]
        }

.. tip::

    ``link_url`` is optional and, when present, points to a downloadable copy of the invoice.