Dartmouth API Developer Portal

Accounts Receivable Postings Batches

The accounts receivable postings batches API is available for authorized source systems to transmit accounts receivable transactions as batch jobs to the Banner Account Receivable system. The application to use this service must be approved by the Campus Billing office. Transactions posted to this service are monitored and audited by the Campus Billing office. Unauthorized use or attempted use of this service will be considered a major violation of the Dartmouth Code of Conduct/and or possibly a criminal violation and be adjucated accordingly.

Notes on usage

The API takes in a batch of transactions. A batch can be one or more accounts receivable transactions. The batch does not imply any type of integrity across the transactions other than they all are coming from one source system.

Each transaction in the set stands alone in terms of processing acceptance or failure. One incorrect transaction does not invalidate the entire set. Use of the posting_type attribute as either TRIAL or COMMIT will determine if the set is ultimately committed or rolled back.

Billing Types

The billing type determines the system the posting batch will be sent to, currently only BANNER is supported. In the future additional accounts receivable billing systems may be implemented. The structure of the individual transactions depend on the billing type being requested.

Source Name

The source name determines the source system that made the request, only certain values are supported and these must be coordinated with the Campus Billing office and the Packaged Application Group.

Postings Batches Request

Request

POST /api/accounts_receivable/postings/batches

Required Scope

api:accounts_receivable.postings.batches:write

Parameters

None

Body

Postings batches request payload (see example below)

Sample Request

https://api.dartmouth.edu/api/accounts_receivable/postings/batches

POST request with example body

```json
{
    "source_batch_id": "SYSTEM_XYZ_BATCH_123",
    "billing_type": "BANNER",
    "posting_type": "TRIAL",
    "source_name": "SYSTEM_XYZ",
    "batch_name": "SYSTEM_XYZ work order billing",
    "accounting_date": "2018-02-01T04:00:00Z",
    "record_count": 2,
    "total_amount": 7797.94,
    "transactions": [
        {
            "source_transaction_id": "WO12345",
            "source_transaction_date": "2017-06-30T04:00:00Z",
            "account_id": 99999,
            "detail_code": "A484",
            "description": "This is a description",
            "amount": 1198.00
        },
        {
            "source_transaction_id": "WO12AAAA",
            "source_transaction_date": "2017-06-30T04:00:00Z",
            "account_id": 73491,
            "detail_code": "ABC123",
            "description": "This is a description",
            "amount": 6599.94
        }
    ]
}
```

Main Body Attributes

All of the following attributes are required.

Field	Type	Description
accounting_date	string	string in ISO8601 format specifies the date of the batch submission
batch_name	string	a descriptive name
billing_type	string	currently must be coded to "BANNER" to utilize the Banner AR billing system
posting_type	string	set to TRIAL for a pre-check of the set, COMMIT to send the set to HRS if passes integrity checks
record_count	number	a number indicating the expected number of transaction in the transactions array
source_batch_id	string	An indentifier that uniquely identifies the source system batch for tracing purposes
source_name	string	assigned source name (by campus billing and packaged application group) of the system posting the batch
total_amount	number	the sum of all amounts in the transactions array
transactions	array	the array of transactions as described in the next section

Transactions Attributes

Field	Type	Required/Optional	Description
amount	number	required	the amount of the transaction
account_id	string	required	the banner accounts receivable account the transaction will be billed to
description	string	required	the netid of the employee this transaction affects
detail_code	string	required	used by banner to determine which GL account will receive the revenue
source_transaction_id	string	required	id that uniquely identified the source transaction for tracing and/or reporting
source_transaction_date	string	required	string in ISO8601 format specifies the date of the batch submission

POST Returns

Status Code	Description
202	The batch has been accepted for processing

Location header:

/api/tasks/5deeb1c608a94008f54748b2

Body:

{
    "status": "accepted"
}

Get Processing Status

This call can be used at any time to get the current status of the set. The status field can return the following values and meanings:

Status	Description
accepted	the transaction set has been accepted for further processing
processing	the transaction set is currently being processed
error	the transaction set has run through processing with errors encountered
complete	the transaction set has run through processing with no errors encountered

Task Request

GET /api/tasks/{id}

Task Required Scope

api:accounts_receivable.postings.batches:write

Task Parameters

Field	Type	Description
id	string	the id of the task

Accepted

{
    "status": "accepted",
    "path": null,
    "id": "629df2a4f4863068fa050db8"
}

Processing

{
    "status": "processing",
    "message": null,
    "id": "629e481cd2061015a24ab338"
}

Error

{
    "status": "error",
    "path": "/accounts_receivable/postings/batches/21176",
    "message": {
        "source_batch_id": "SYSTEM_XYZ_BATCH_123",
        "batch_id": "21176",
        "status": "failure",
        "billing_type": "BANNER",
        "posting_type": "TRIAL",
        "source_name": "SYSTEM_XYZ",
        "batch_name": "SYSTEM_XYZ work order billing",
        "accounting_date": "2018-02-01T04:00:00Z",
        "record_count": 2,
        "total_amount": 7798.14,
        "transactions_loaded": 1,
        "failures": [
            {
                "account_id": "99999",
                "detail_code": "AX84",
                "description": "This is a description",
                "reference_number": "WO12345",
                "amount": 1198.2,
                "error_message": "Invalid detail code: AX84"
            }
        ],
        "transactions": [
            {
                "amount": 1198.2,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12345",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            },
            {
                "amount": 6599.94,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12AAAA",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            }
        ]
    },
    "id": "63d2dbb98954ba5c8eb5c616"
}

Complete

{
    "status": "complete",
    "path": "/accounts_receivable/postings/batches/21179",
    "message": {
        "source_batch_id": "SYSTEM_XYZ_BATCH_123",
        "batch_id": "21179",
        "status": "success",
        "billing_type": "BANNER",
        "posting_type": "TRIAL",
        "source_name": "SYSTEM_XYZ",
        "batch_name": "SYSTEM_XYZ work order billing",
        "accounting_date": "2018-02-01T04:00:00Z",
        "record_count": 2,
        "total_amount": 7797.94,
        "transactions_loaded": 2,
        "failures": [],
        "transactions": [
            {
                "amount": 1198.0,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12345",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            },
            {
                "amount": 6599.94,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12AAAA",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            }
        ]
    },
    "id": "63d2def58954ba5c8eb5c61a"
}

GET Returns

Status Code	Description
200	The status of the task is returned
404	Not found. The {id} does not reference a valid task id

Sample GET Request

GET https://api.dartmouth.edu/api/accounts_receivable/postings/batches/15837

Sample Return

```json
{
    "source_batch_id": "SYSTEM_XYZ_BATCH_123",
    "batch_id": "15839",
    "status": "success",
    "billing_type": "BANNER",
    "posting_type": "TRIAL",
    "source_name": "SYSTEM_XYZ",
    "batch_name": "SYSTEM_XYZ work order billing",
    "accounting_date": "2018-02-01T04:00:00Z",
    "record_count": 2,
    "total_amount": 7797.94,
    "transactions_loaded": 2,
    "failures": [],
    "transactions": [
        {
            "amount": 1198.0,
            "account_id": "99999",
            "detail_code": "A484",
            "source_transaction_id": "WO12345",
            "source_transaction_date": "2017-06-30T04:00:00Z",
            "description": "This is a description"
        },
        {
            "amount": 6599.94,
            "account_id": "73491",
            "detail_code": "ABC123",
            "source_transaction_id": "WO12AAAA",
            "source_transaction_date": "2017-06-30T04:00:00Z",
            "description": "This is a description"
        }
    ]
}
```

Sample Return with Transaction Errors

```json
{
    "source_batch_id": "SYSTEM_XYZ123ABC",
    "batch_id": "15838",
    "status": "failure",
    "billing_type": "BANNER",
    "posting_type": "TRIAL",
    "source_name": "SYSTEM_XYZ",
    "batch_name": "SYSTEM_XYZ work order billing",
    "accounting_date": "2018-02-01T04:00:00Z",
    "record_count": 2,
    "total_amount": 7798.14,
    "transactions_loaded": 1,
    "failures": [
        {
            "account_id": "99999",
            "detail_code": "ABC123",
            "description": "This is a description",
            "reference_number": "WO12345",
            "amount": 1198.2,
            "error_message": "Invalid detail code: ABC123"
        }
    ],
    "transactions": [
        {
            "amount": 1198.2,
            "account_id": "99999",
            "detail_code": "ABC123",
            "source_transaction_id": "WO12345",
            "source_transaction_date": "2017-06-30T04:00:00Z",
            "description": "This is a description"
        },
        {
            "amount": 6599.94,
            "account_id": "99999",
            "detail_code": "ABC123",
            "source_transaction_id": "WO12AAAA",
            "source_transaction_date": "2017-06-30T04:00:00Z",
            "description": "This is a description"
        }
    ]
}
```

Get Postings History

This call can be used at any time to get status of previously-submitted batch postings.

Sample GET Collection Request

GET /api/accounts_receivable/postings/batches

Collection Required Scope

api:accounts_receivable.postings.batches:write

Collection Parameters

Field	Type	Required	Description
source_name	string	optional
submit_date	string	optional	ISO 8601 formatted
source_batch_id	string	optional
batch_id	string	optional
status	string	optional
billing_type	string	optional
posting_type	string	optional
source_name	string	optional
batch_name	string	optional
accounting_date	string	optional	ISO 8601 formatted
record_count	number	optional
total_amount	number	optional
transactions_loaded	number	optional
failures	array	optional
transactions	array	optional

Returns

Status Code	Description
200	All postings that qualify based on query parameters are returned

Sample Collection Request

GET https://api.dartmouth.edu/api/accounts_receivable/postings/batches?source_name=SYSTEM_XYZ

Sample Collection Return

```json
[
    {
        "source_batch_id": "SYSTEM_XYZ_BATCH_123",
        "batch_id": "15839",
        "status": "success",
        "billing_type": "BANNER",
        "posting_type": "TRIAL",
        "source_name": "SYSTEM_XYZ",
        "batch_name": "SYSTEM_XYZ work order billing",
        "accounting_date": "2018-02-01T04:00:00Z",
        "record_count": 2,
        "total_amount": 7797.94,
        "transactions_loaded": 2,
        "failures": [],
        "transactions": [
            {
                "amount": 1198.0,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12345",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            },
            {
                "amount": 6599.94,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12AAAA",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            }
        ]
    },
    {
        "source_batch_id": "SYSTEM_XYZ123ABC",
        "batch_id": "15838",
        "status": "failure",
        "billing_type": "BANNER",
        "posting_type": "TRIAL",
        "source_name": "SYSTEM_XYZ",
        "batch_name": "SYSTEM_XYZ work order billing",
        "accounting_date": "2018-02-01T04:00:00Z",
        "record_count": 2,
        "total_amount": 7798.14,
        "transactions_loaded": 1,
        "failures": [
            {
                "account_id": "99999",
                "detail_code": "ABC123",
                "description": "This is a description",
                "reference_number": "WO12345",
                "amount": 1198.2,
                "error_message": "Invalid detail code: ABC123"
            }
        ],
        "transactions": [
            {
                "amount": 1198.2,
                "account_id": "99999",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12345",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            },
            {
                "amount": 6599.94,
                "account_id": "73491",
                "detail_code": "ABC123",
                "source_transaction_id": "WO12AAAA",
                "source_transaction_date": "2017-06-30T04:00:00Z",
                "description": "This is a description"
            }
        ]
    }
]
```