Statements
==========

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

Statements Service

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

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

Request
-------

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

Parameters
~~~~~~~~~~

``account`` :bdg:`string` :bdg-danger:`required`
    Account ID in Member System

``from_statement_date`` :bdg:`string` :bdg-danger:`required`
    Start of the statement date range (``YYYY-MM-DD``)

``to_statement_date`` :bdg:`string` :bdg-danger:`required`
    End of the statement date range (``YYYY-MM-DD``)

``member`` :bdg:`string`
    Member ID in GroupLink

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

``statement_type`` :bdg:`string`
    Filter results to a specific statement type

Examples
~~~~~~~~

.. code-block:: json

    {
        "member": "520",
        "account": "446641",
        "from_statement_date": "2023-03-01",
        "to_statement_date": "2023-05-31",
        "location_id": "Loc0001"
    }

Schema
~~~~~~~~

.. dropdown:: Request JSON Schema

    .. code-block:: json

        {
            "type": "object",
            "properties": {
                "member": {
                    "type": "string"
                },
                "account": {
                    "type": "string"
                },
                "from_statement_date": {
                    "type": "string"
                },
                "to_statement_date": {
                    "type": "string"
                },
                "location_id": {
                    "type": "string"
                },
                "statement_type": {
                    "type": "string"
                }
            },
            "required": [
                "account",
                "from_statement_date",
                "to_statement_date"
            ]
        }

Response
--------

Seller returns the statements matching the requested date range. Each statement contains a ``statement_detail``
array with the invoices that make up that statement.

Examples
~~~~~~~~

.. code-block:: json

    {
        "status": "success",
        "error_description": "",
        "statements": [
            {
                "statement_date": "2023-05-01",
                "account_id": "446641",
                "location_id": "Loc0001",
                "account_description": "City Automotive",
                "total_cost": 18588.60,
                "link_url": "https://example.com/statements/202305.pdf",
                "statement_detail": [
                    {
                        "invoice_date": "2023-05-03",
                        "invoice_number": "INV-23433",
                        "reference_number": "PO-32456",
                        "original_amount": 129.98,
                        "paid_amount": 77.12,
                        "reference_type": "invoice"
                    },
                    {
                        "invoice_date": "2023-05-03",
                        "invoice_number": "INV-23434",
                        "reference_number": "PO-32457",
                        "original_amount": 47.23,
                        "paid_amount": 0,
                        "reference_type": "invoice"
                    }
                ]
            }
        ]
    }

Schema
~~~~~~~~

.. dropdown:: Response JSON Schema

    .. code-block:: json

        {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string"
                },
                "error_description": {
                    "type": "string"
                },
                "statements": {
                    "type": "array",
                    "items": [
                        {
                            "type": "object",
                            "properties": {
                                "statement_date": {
                                    "type": "string"
                                },
                                "account_id": {
                                    "type": "string"
                                },
                                "location_id": {
                                    "type": "string"
                                },
                                "account_description": {
                                    "type": "string"
                                },
                                "total_cost": {
                                    "type": "float"
                                },
                                "link_url": {
                                    "type": "string"
                                },
                                "statement_detail": {
                                    "type": "array",
                                    "items": [
                                        {
                                            "type": "object",
                                            "properties": {
                                                "invoice_date": {
                                                    "type": "string"
                                                },
                                                "invoice_number": {
                                                    "type": "string"
                                                },
                                                "reference_number": {
                                                    "type": "string"
                                                },
                                                "original_amount": {
                                                    "type": "float"
                                                },
                                                "paid_amount": {
                                                    "type": "float"
                                                },
                                                "reference_type": {
                                                    "type": "string"
                                                }
                                            },
                                            "required": [
                                                "invoice_date"
                                            ]
                                        }
                                    ]
                                }
                            },
                            "required": [
                                "statement_date",
                                "account_id",
                                "total_cost",
                                "statement_detail"
                            ]
                        }
                    ]
                }
            },
            "required": [
                "status",
                "statements"
            ]
        }

.. tip::

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