NONCONFIDENTIAL // EXTERNAL
G-Invoicing
System Interface
Specifications - Pull
A Guide to extracting, packaging, and transmitting GT&C,
Order and Performance data from G-Invoicing
General Terms and Conditions (GT&C),
Orders and Performance
Version 7.2
October 2022
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
2
NONCONFIDENTIAL // EXTERNAL
Table of Contents
1
Introduction ................................................................................................................................ 3
1.1
Purpose ............................................................................................................................... 3
1.2
Scope ................................................................................................................................... 3
1.3
References .......................................................................................................................... 3
2
Assumptions/Constraints ......................................................................................................... 4
2.1
Assumptions ....................................................................................................................... 4
2.2
Constraints .......................................................................................................................... 4
3
Interface Mechanism ................................................................................................................. 4
3.1
Physical Interface ............................................................................................................... 4
3.2
Protocol ............................................................................................................................... 4
3.3 Supported Environments ................................................................................................. 13
4
Interface Specification ............................................................................................................ 13
4.1
Processing Logic .............................................................................................................. 13
4.2
Business Rules ................................................................................................................. 14
4.3
File Naming Convention .................................................................................................. 14
4.4
Interface Timing ................................................................................................................ 14
4.5
Retransmissions ............................................................................................................... 15
4.6
Interface Data Details ....................................................................................................... 15
5
Error Specifications ................................................................................................................. 19
6
Security ..................................................................................................................................... 19
7
Interface Integrity ..................................................................................................................... 20
7.1
TWAI .................................................................................................................................. 20
7.2
Communication Channel ................................................................................................. 20
8
Revision History ...................................................................................................................... 21
Appendix A: Messaging Protocol & Data Encapsulation ............................................................ 24
1
G-Invoicing Message Encapsulation ..................................................................................... 24
1.1
HTTP Request .....................................................................................................................................................24
1.2
HTTP Response ...................................................................................................................................................24
2
Call Detail ................................................................................................................................. 25
3
Document List .......................................................................................................................... 25
4
Error .......................................................................................................................................... 26
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
3
NONCONFIDENTIAL // EXTERNAL
1
Introduction
1.1
Purpose
This artifact defines the interface specification to define the transmission of General Terms &
Conditions (GT&C), Order and Performance data from the G-Invoicing application to Federal
Program Agency systems. It serves as an agreement between G-Invoicing, agencies with
interfacing systems, their software provider development teams and Bureau of the Fiscal
Service business owners, upon which the system-to-system interface will be based.
1.2
Scope
This artifact defines the G-Invoicing specifications to extract, package and transmit GT&C,
Order and Performance data and the communication channel that carries these messages. The
focus is on the specifications that must be mutually agreed upon by G-Invoicing and agencies
with interfacing systems. The G-Invoicing team owns the maintenance of this document.
1.3
References
The artifacts listed below support the current Production release of this specification and may be
downloaded from the provided location. Artifacts that support future enhancements and
releases of this specification can be made available upon request.
1.3.1 The Federal Intragovernmental Data Standards (FIDS) for GT&C, Order and
Performance Data Elements
https://www.fiscal.treasury.gov/fsservices/gov/acctg/g_invoice/g_invoice_home.htm
1.3.2 System Mapping and Validation Rules (SM&VR) for GT&C and Order, explains how
each data element in the FIDS maps to G-Invoicing and the validation rules enforced for
each change in status.
https://www.fiscal.treasury.gov/fsservices/gov/acctg/g_invoice/g_invoice_home.htm
Note: There is no SM&VR document for Performance data because there are not
multiple, complex status scenarios to support. Validation rules appear in the
Performance FIDS.
1.3.3 XML Schema Documentation
• GTC.xsd (payload)
• Documents Summary.xsd
• Error.xsd
The following schemas are used for Orders and Performance:
• Order_Documents Summary.xsd
• Order_Error.xsd
• Order.xsd (payload)
• Performance.xsd (payload)
https://www.fiscal.treasury.gov/data/
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
4
NONCONFIDENTIAL // EXTERNAL
2
Assumptions/Constraints
2.1
Assumptions
1. While this artifact represents an agreement by G-Invoicing, Federal Program Agencies
and their software providers, it does not imply a release schedule or project plan.
Those topics are described by other artifacts for the respective projects and are not
referenced here.
2. The interface is limited to the transmission of GT&C, Order and Performance data
outbound from G-Invoicing to agencies with interfacing systems. Additional data types
are not included in this interface at this time.
2.2
Constraints
1. This interface will be delivered via web services, access governed by the Treasury
Web Application Infrastructure (TWAI), as per agreement between FRB St Louis, the
Department of the Treasury Bureau of the Fiscal Service and Defense Logistics
Agency (DLA) Transaction Services, and is consistent with the Bureau of the Fiscal
Service’s desire to move towards delivering system-to-system interfaces via web
services.
a. Similar operating agreements may be made with other agencies, as-needed.
2. Messages will be sent over the internet utilizing the HTTPS protocol.
3. The Bureau of the Fiscal Service reference data XML Schemas will be published by
the Enterprise Data Architecture group at https://www.fiscal.treasury.gov/data/. These
schemas will be used to format the payload portion of the data transmission.
a. XML namespaces may vary with each new schema version
3
Interface Mechanism
3.1
Physical Interface
The G-Invoicing to agency system interface will communicate using HTTPS with 2-way TLS
(Transport Layer Security) using a client certificate through the TWAI. The TWAI will employ a
web service proxy to serve as a focal route for incoming web service requests so that the web
service provider is only configured to receive requests from a single point of origination. The
web service response is routed back on the same stream to the initial requestor.
3.2
Protocol
The G-Invoicing to agency system interface will employ a push/pull model utilizing REST
Services with an XML payload.
All services below are referenced via URLs in the following format.
https://host-name:port/base-path/resource-path
3.2.1 Host names:
Production: ws.igt.fiscal.treasury.gov
Quality Assurance Current: qa.ws.igt.fiscal.treasury.gov
Quality Assurance Future: qaf.ws.igt.fiscal.treasury.gov
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
5
NONCONFIDENTIAL // EXTERNAL
Functional Test: ft.ws.igt.fiscal.treasury.gov
3.2.2 Base Path: /ginv
3.2.3 Resource: /services
Note: G-Invoicing supports a one-to-many relationship between a Partner ID and a
System ID whereby one Partner created and managed within a single agency account
can represent multiple Systems spread across many agency accounts. Policy requires
that at least one System ID must be created and managed in each agency account to
push data. The Partner ID must be assigned a client certificate to access G-Invoicing.
3.2.3.1 Resource: GT&C List
Component Detail / Description
Path
/ginv/services/v1_0/gtc/ (for single ALC per partner v2.1 XML schema)
/ginv/services/v2_0/gtc/ (for 1-to-many ALCs per partner v3.0 XML schema)
Method
GET
Description
Returns a list of all GT&Cs from the System that the User is authorized to access.
Example
GET /ginv/services/v1_0/gtc?status=REC,CLZ
GET /ginv/services/v2_0/gtc?status=REC,CLZ
GET /ginv/services/v1_0/gtc?agencyLocationCode=17000001,17000002,17000003
&lastModifiedDateTime=2020-06-17T13:30:00.000-04:00
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: agencyLocationCode
Description: Limits results to GT&Cs which contains at least one of the passed ALCs.
In: query
Type: Comma separated array of strings
Required: false
Name: status
Description: Limits results of GT&Cs associated with one of the passed status types.
In: query
Type: Comma separated array of strings, enumeration
Values: “REC” (Open For Orders), “CLZ” (Closed), “PND” (Pending Approval), “REJ” (Rejected).
Required: false
Name: lastModifiedDateTime
Description: Limits results to GT&Cs updated since the passed date/time.
In: query
Type: dateTime; Format: YYYY-MM-DDThh:mm:ss.SSS+|-00:00
All time should be specified in local time zone with time zone offset from UTC in hours
and minutes ahead (+) or behind (-) UTC.
Required: false
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
6
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
Produces
Status Code: 200
Description: Successful call returns Call Detail and a list of GT&Cs.
Content Type: application/xml
Schema(s): Call Detail, Document List
3.2.3.2 Resource: Single GT&C by ID
Component Detail / Description
Path
/ginv/services/v1_0/gtc/<id> (to pull single GT&C for v2.1 XML schema)
or ginv/services/v2_0/gtc/<id> (to pull single GT&C for v3.0 XML schema)
Method
GET
Description
Returns an individual GT&C referenced by the passed unique RequestType /
RequestTypeID combination.
Example
GET /ginv/services/v1_0/gtc/A1610-017-021-012345
GET /ginv/services/v2_0/gtc/A2006-017-021-123456
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: id
Description: A Unique ID referencing an individual GT&C.
In: path (required)
Type: string [20]
Required: true
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
7
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
Produces
Status Code: 200
Description: Successful call returns Call Detail and an individual GT&C.
Content Type: application/xml
Schema(s): Call Detail, GT&C
3.2.3.3 Resource: Single Attachment by ID
Component Detail / Description
Path
/ginv/services/v1_0/attachment/<id> (for GT&C attachment)
/ginv/services/v1_0/order/attachment/<id> (for Order attachment)
/ginv/services/v1_0/order/performance/attachment/<id> (for Performance attachment)
Method
GET
Description
Returns an individual Attachment referenced by the passed unique ID.
Example
GET /ginv/services/v1_0/attachment/987654321
GET /ginv/services/v1_0/order/attachment/987654321
GET /ginv/services/v1_0/order/performance/attachment/987654321
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: id
Description: A Unique ID referencing an individual Attachment.
In: path
Type: string [30]
Required: true
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
8
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Produces
Status Code: 200
Description: Successful call returns the binary content of the Attachment file.
Content Type: application/octet-stream
Schema(s): file
3.2.3.4 Resource: Orders List
Component Detail / Description
Path
Ginv/services/v1_0/order (to pull list of Orders for v2.2 of the XML schema)
or Ginv/services/v2_0/order> (to pull list of Orders for v2.3 of the XML schema)
Note: The v2.3 Order_Document_Summary.xsd uses the same format as the v3.0
Document_Summary.xsd for GT&Cs, which supports 1-to-many ALCs per partner.
ALCs for an Order will only occupy the first occurrence of AgencyLocationCode.
Method
GET
Description
Returns a list of all Orders from the System that the User is authorized to access. The
keys necessary to obtain detailed Order data are obtained by pulling the Orders List.
Example
GET /ginv/services/v1_0/order?lastModifiedDateTime=2017-05-09T17:30:00.000-04:00
GET /ginv/services/v2_0/order?lastModifiedDateTime=2021-03-08T19:20:00.000-04:00
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: agencyLocationCode
Description: Limits results to Orders associated with one of the passed ALCs.
In: query
Type: Comma separated array of strings
Required: false
Name: status
Description: Limits results of Orders associated with one of the passed status types.
In: query
Type: Comma separated array of strings, enumeration
v1_0 Values: “PRA” (Pending Requesting Approval) or “P1A” (Pending Partner 1
Approval), “SSA” (Share with Servicing) or “SP2” (Shared with Partner 2), “PSA”
(Pending Servicing Approval) or “P2A” (Pending Partner 2 Approval), “REC”
(Open), “DR” (Draft - when Order Mod>0), “REJ” (Rejected), “CLZ” (Closed)
v2_0 Values: “P1A” (Pending Partner 1 Approval), “SP2” (Shared with Partner 2),
“P2A” (Pending Partner 2 Approval), “REC” (Open), “DR” (Draft - when Order
Mod>0), “REJ” (Rejected), “CLZ” (Closed)
Required: false
Name: lastModifiedDateTime
Description: Limits results to Orders updated since the passed date/time.
In: query
Type: dateTime; Format: YYYY-MM-DDThh:mm:ss.SSS+|-00:00
All time should be specified in local time zone with time zone offset from UTC in hours
and minutes ahead (+) or behind (-) UTC.
Required: false
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
9
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
Produces
Status Code: 200
Description: Successful call returns Call Detail and a list of Orders.
Content Type: application/xml
Schema(s): Call Detail, Document List
3.2.3.5 Resource: Single Order by ID
Component Detail / Description
Path
Ginv/services/v1_0/order/<id> (to pull Orders for v2.2 of the XML schema)
or Ginv/services/v2_0/order/<id> (to pull Orders for v2.3 of the XML schema)
Method
GET
Description
Returns an individual Order referenced by the passed unique identifier for an individual
Order. Identifiers to Attachments related to an Order (i.e., Attachment IDs) are obtained
by pulling the Single Order by ID.
Example
GET /ginv/services/v1_0/order/O1705-123-234-000146
or GET /ginv/services/v2_0/order/O2005-123-234-000146
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: id
Description: A Unique ID referencing an individual Order.
In: path (required)
Type: string [20]
Required: true
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
10
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
Produces
Status Code: 200
Description: Successful call returns Call Detail and an individual Order.
Content Type: application/xml
Schema(s): Call Detail, Order
3.2.3.6 Resource: Performance List
Component Detail / Description
Path
/ginv/services/v1_0/order/performance
Method
GET
Description
Returns a list of all Performance transactions from the System that the User is authorized
to access, based on Order permissions.
Example
GET /ginv/services/v1_0/order/performance?lastModifiedDateTime=2017-05-
09T17:30:00.000-04:00?agencyLocationCode=12010001
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: agencyLocationCode
Description: Limits results to Performance transactions related to Orders containing one
of the passed ALCs.
In: query
Type: Comma separated array of strings
Required: false
Name: lastModifiedDateTime
Description: Limits results to Performance transactions created since the passed
date/time.
In: query
Type: dateTime (ISO 8601)
Required: false
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
11
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Name: status
Description: Limits results of Performance associated with one of the passed Status
values.
In: query
Type: Comma separated array of strings, enumeration
Values: All values in Performance FIDS are supported
Required: false
Name: orderNumber
Description: Limits results to Performance associated with a single Order
In: query
Type: string [20]
Required: false
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
Produces
Status Code: 200
Description: Successful call returns Call Detail and a list of Performance transactions.
Content Type: application/xml
Schema(s): Call Detail, Document List
Note: Settlement Status and lastModifiedDateTime are initially set by G-Invoicing when
Performance is reported. The values of both will change if/as settlement occurs.
3.2.3.7 Resource: Single Performance by ID
Component Detail / Description
Path
Ginv/services/v1_0/order/performance/{id}
Method
GET
Description
Returns an individual Performance transaction referenced by the passed unique identifier
for an individual Performance transaction.
Example
GET /ginv/services/v1_0/order/performance/P1805-123-234-000456
Host: ws.igt.fiscal.treasury.gov
Accept: application/xml
Accept Encoding: gzip, deflate
Connection: Keep-Alive
Parameters
Name: id
Description: A Unique ID referencing an individual Performance transaction.
In: path (required)
Type: string [20]
Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
12
NONCONFIDENTIAL // EXTERNAL
Component Detail / Description
Name: SystemID
Description: Identifies the system that is exchanging data with G-Invoicing.
In: header
Type: string [100]
Required: true
Name: Agency-Tracking-Identifier
Description: Unique identifier from agency system, optionally supplied in the request.
In: header
Type: string [50]
Required: false
Consumes
N/A
Produces
Status Code: 200
Description: Successful call returns an individual Performance transaction.
Content Type: application/xml
Schema: Performance
3.2.4 Common Headers
3.2.4.1 Accept Header
Component
Detail / Description
Name
Accept
Value
application/xml
Description
Indicates the service client expects content in XML format. No other format is currently
supported.
3.2.4.2 Accept-Encoding
Component Detail / Description
Name
Accept-Encoding
Value
gzip, deflate
Description
Allows the service client to indicate it supports compressing the response payload using
gzip compression.
3.2.4.3 Connection Header
Component Detail / Description
Name
Connection
Value
keep-alive
Description
Indicates the service client wants to use HTTP keep-alive to more efficiently make
multiple requests.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
13
NONCONFIDENTIAL // EXTERNAL
3.3 Supported Environments
The G-Invoicing application operates within the Treasury Web Application Infrastructure (TWAI)
environments. Interface testing will take place in G-Invoicing’s Functional Test and Quality
Assurance environments. G-Invoicing operates both Production and Contingency environments.
Fail-over by G-Invoicing from Production to Contingency environments will be transparent.
Table 1: Supported Environments
G-Invoicing TWAI Use
Functional Test (FT)
Future view of Production (new release) – will be used on a limited
basis for interface testing.
Quality Assurance - Current (QAC) Current view of Production environment – used for agency testing.
Quality Assurance - Future (QAF) Future view of Production (new release) – used for UAT.
Production Production
4
Interface Specification
4.1
Processing Logic
4.1.1 Agencies with interfacing systems will make a web service call to G-Invoicing to request
new or modified GT&C, Order or Performance information. The credentials for the
agency systems are verified by the TWAI. Certificate-based authentication is performed
against TWAI policies. Web service requests for G-Invoicing data require a United
States Department of the Treasury issued certificate.
4.1.2 Validate the parameters that are passed in the request depending on the data being
requested (e.g., Document List, Single Document, Single Attachment) as stated in
Section 3.2 of this document. The parameters to be passed are either required,
optional, and/or conditional depending on the request.
4.1.3 G-Invoicing will retrieve the requested data.
4.1.4 The data is formatted into an XML document per the XML schema(s) referenced in
Appendix A of this document.
4.1.5 G-Invoicing transmits the data to the agency system.
4.1.6 If errors are encountered at any time while processing the request, G-Invoicing will
capture that data and respond back to the agency partner with the error details.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
14
NONCONFIDENTIAL // EXTERNAL
4.2
Business Rules
4.2.1 System requests for GT&C, Order and Attachment data will be fulfilled with data as it
exists when the request is answered.
Note: This statement covers any previous or historical states that a document would
have been in prior to its current state. G-Invoicing will not provide a document history
(i.e., multiple versions of the same document) or deleted attachments.
4.2.2 The agency system must be granted permissions (aka, user role) to view the type of
data being requested.
4.2.3 The agency system must be assigned to Organizational Group(s) containing the ALC(s)
for which the data is being requested.
4.2.3.1 An agency system only requires access to one side of an agreement (Requesting
or Servicing) not both to view all data associated with the agreement, including
attachments. The agency system will be properly authorized to ensure it is valid
for the type of request being submitted.
4.2.3.2 Users granted data access to an Order will be allowed to access Performance
related to that Order (assuming they are assigned a role to view Performance).
4.2.4 GT&C and Order document requests submitted with a Status parameter of “Delete” will
not be fulfilled.
Note: There are no restrictions on pulling deleted Performance records.
4.2.5 GT&C document requests submitted with a Status parameter of “Draft” (DR) will
not be fulfilled.
4.2.6 Order document requests submitted with a Status parameter of “Draft” (DR) will only
return Orders with Modification Number > 0.
4.2.7 GT&C and Order requests for Document Types submitted without a Status parameter
will return documents in all statuses, except where noted above.
4.2.8 Character entity references ampersand (&) and less than (<) are escaped on output to
XML. The escape sequence for ampersand is & and the escape sequence for less
than is <.
4.3
File Naming Convention
N/A
4.4
Interface Timing
The web service is available 24 hours per day, 7 days per week. G-Invoicing has a daily
scheduled outage for maintenance as noted below.
3:45 AM - 4:15 AM EST (Monday through Saturday)
11:00 AM - 11:30 AM EST (Sunday)
Agency systems are in full control of the frequency and the timing of this interface.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
15
NONCONFIDENTIAL // EXTERNAL
4.5
Retransmissions
Retransmissions are not needed because the G-Invoicing web services provide for
synchronous operation in that the agencies with interfacing systems will be waiting for the
response from G-Invoicing before continuing.
Should the web service connection somehow fail in the middle of a series of client
requests to G-Invoicing (e.g., multiple document requests, multiple attachment requests)
the client (i.e., interfacing agency system) is responsible for continuing the requests when
services are restored.
4.6
Interface Data Details
The information below documents the data sent for the methods available on the web
service. For more details, refer to the XML schemas for the service in Appendix A.
4.6.1 Business – Data Elements
The business data for GT&C and Orders may be accessed on the Bureau of the Fiscal
Service G-Invoicing website.
The data elements in Table 2 will be returned with each single GT&C, Order or
Performance request where the requested document contains one or more attachments.
This data describes each attachment and provides the means (i.e., URL) for a
subsequent request to retrieve the attachment(s).
Table 2: Attachment Summary Data Elements
Familiar Name XML Tag Definition Constraints Optionality
Attachment File
Name
<FileName> The actual name of the
attachment file.
String [1, 32] Maximum
length = 132 String UTF-
8
Required
Attachment File
Alias
<FileNameAlias> Descriptive name for an
attachment. Different from
the name assigned to the
file itself.
String [0,132] Maximum
length = 132 String UTF-
8
Optional
Attachment ID <AttachmentID> Unique identifier for an
attachment.
Integer
Maximum length = 30
Required
Attachment
Updated By
<FullName> The username or partner
(Buyer or Seller) that
uploaded the attachment.
String [0,100] Maximum
length = 100 String UTF-
8
Required
Attachment Date
Time
<UploadDateTime> The date and time the file
was uploaded into G-
Invoicing.
DateTime Format: YYYY-MM-
DDThh:mm:ss.SSS+|- 00:00
All time should be specified in
local time zone with time zone
offset from UTC in hours and
minutes ahead (+) or behind
(-) UTC.
Required
File Size <FileSize> The size of the attachment
expressed in kilobytes
(kB). Note: Small files may
be expressed as 0 kB.
Integer
Minimum length = 1
Maximum length = 8
Required
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
16
NONCONFIDENTIAL // EXTERNAL
Familiar Name XML Tag Definition Constraints Optionality
Document URL <URL> The URL that will be used
in a subsequent request by
the agency system to
retrieve the attachment.
String [0, 4000]
Maximum length = 4000
String UTF-8
Required
4.6.2 Response – Data elements
The data elements below in Table 3 will be returned in the body of every response
generated by G-Invoicing. The data elements contained in Table 4 will be returned when
requesting a list of new or modified documents from G-Invoicing.
Table 3: Call Detail Response Data Elements
Familiar Name XML Tag Definition Constraints Optionality
Agency Partner ID <PartnerID> Identifies the intended
recipient of the
transmission.
String [100]
Minimum length = 0
Maximum length = 100
String UTF-8
Required
Agency System ID <SystemID> Identifies the system that is
exchanging data with G-
Invoicing.
String [100]
Minimum length = 1
Maximum length = 100
String UTF-8
Required
Agency Tracking
Identifier
<RequestID> Unique identifier, optionally
supplied in the request and
echoed back in the
response.
String [50]
Minimum length = 0
Maximum length = 50
String UTF-8
Optional
G-Invoicing
Tracking Identifier
<GINVTrackingID> Unique tracking identifier,
generated by G-Invoicing.
String [50]
Minimum length = 1
Maximum length = 50
String UTF-8
Required
Environment <Environment> Describes the environment
in which the system
interface resides.
String [30]
Minimum length = 0
Maximum length = 30
String UTF-8
Values: “Production”, “Quality
Assurance”, “Functional Test”.
Required
Request Type <RequestType> Type of request that was
submitted to G-Invoicing by
the agency system.
String [30]
Minimum length = 0
Maximum length = 30
String UTF-8
Values: “GTC List”, “Order List”,
“Performance List”, “Single
GTC”, “Single Order”, “Single
Performance”, “Single
Attachment”.
Note: Values are derived from
the service being accessed.
Required
Record Count <RecordCount> The total number of
records in the payload.
Integer
Minimum length = 1
Maximum length = 8
Required
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
17
NONCONFIDENTIAL // EXTERNAL
Table 4: Document List Data Elements
Familiar
Name
XML Tag Definition Constraints Optionality
Requesting
Agency
Location
Code(s)
GT&C/Orders:
<RequestingAgencyLoc
ations/AgencyLocation
Code>
Performance:
<RequestingAgencyLoc
ationCode>
Unique identifier(s) for
a federal agency
buying goods and/or
services.
GT&Cs: 1-to-many
ALCs per side.
Orders: Only one ALC
for per side, each
appearing in array.
Performance: ALCs
are not (yet) returned
in arrays.
String [0-9]{8} (i.e., Digits 0 to 9.
Length must be eight digits.)
String UTF-8.
Min=1. no Max
Required
Servicing
Agency
Location
Code(s)
GT&C/Orders:
<ServicingAgencyLocati
ons/AgencyLocationCo
de>
Performance:
<ServicingAgencyLocati
onCode>
String [0-9]{8} (i.e., Digits 0 to 9.
Length must be eight digits.)
String UTF-8.
Min=1. no Max
Required
Document
Type
<DocumentType> Describes the
document type (e.g.,
GT&C, Order,
Performance) that was
requested.
String [30]
Minimum length = 0
Maximum length = 30
String UTF-8
Values: “GTC”, “Performance”
For Orders the DocumentType is
being utilized to indicate an In-flight
Order.
There are 5 different DocumentType
values:
APIOrder: In-flight Order = No
UIOrder: In-flight Order = No
UIOrderIFO: In-flight Order = Yes
UIOrderUpload: In-flight Order = No
UIOrderUploadIFO: In-flight Order =
Yes
Required
Manual Entry
Indicator
<Manual EntryIndicator> Indicates whether the
document was
introduced by a user or
a system.
String
Enumeration: “Y” (Yes), “N” (No)
“N” indicates System generated
“Y” indicates User generated
Required
Document ID <DocumentNumber> Unique identifier for a
document.
String [20] Minimum
length = 0
Maximum length = 20
String UTF-8 [A-Z, 0-9, -]
(i.e., upper case alpha characters,
digits 0-9, and dashes.)
Required
Modification
Number
<ModificationNumber> Unique identifier
assigned to a GT&C or
Order document that
has been modified form
the original.
Integer
Maximum length = 10
Conditional
Status <Status> The current status of
the GT&C or Order
document.
See Federal Intragovernmental
Data Standards (FIDS).
Conditional
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
18
NONCONFIDENTIAL // EXTERNAL
Last Modified
Date/Time
<LastModifiedDateTime
>
The date/time the
document was last
updated.
DateTime
Format: YYYY-MM-
DDThh:mm:ss.SSS+|-00:00
All time should be specified in local
time zone with time zone offset from
UTC in hours and minutes ahead (+)
or behind (-) UTC.
Required
Document
URL
<URL> The URL that will be
used in a subsequent
request by the agency
system to retrieve the
document.
String [4000]
Minimum length = 0
Maximumlength = 4000
String UTF-8
Required
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
19
NONCONFIDENTIAL // EXTERNAL
5
Error Specifications
Standard web service faults are generated for exceptions that can cause the request to not be
processed. If the agency system cannot be authenticated or authorized, then a fault is returned.
If the requested resource is unavailable then a fault will be thrown. All services may return the
following HTTP status codes along with variable error message text describing the error(s) in
the response.
Error ID HTTP Status Code Example
1 400 – Bad Request
ValidationFailedException
Note: Message text included
in the <ErrorDesc> element
will vary depending on the
error condition.
<ns0:ErrorDetail>
<ns0:ErrorDesc>ValidationFailedException message = Requesting agency Point Of Contact
Full Name is required.</ns0:ErrorDesc>
<ns0:ErrorTitle>400 ValidationFailedException</ns0:ErrorTitle>
<ns0:RequestDateTime>2018-05-24T15:43:27.578-04:00</ns0:RequestDateTime>
<ns0:RequestTypeIdentifier>Order Create</ns0:RequestTypeIdentifier>
<ns0:Status>400</ns0:Status>
</ns0:ErrorDetail>
2
403 – Unauthorized
AccessDeniedException
Note: Message text included
in the <ErrorDesc> element
will vary depending on the
error condition.
<ns0:ErrorDetail>
<ns0:ErrorDesc>AccessDeniedException message = User is not authorized to the
system.</ns0:ErrorDesc>
<ns0:ErrorTitle>403 AccessDeniedException</ns0:ErrorTitle>
<ns0:RequestDateTime>2018-05-23T08:33:04.426-04:00</ns0:RequestDateTime>
<ns0:RequestTypeIdentifier>Order Create</ns0:RequestTypeIdentifier>
<ns0:Status>403</ns0:Status>
</ns0:ErrorDetail>
</Ginv_Error>
3
500 – Internal Server
Error
ServerException
Note: Message text included
in the <ErrorDesc> element
will vary depending on the
error condition.
<ns0:ErrorDetail>
<ns0:ErrorDesc>ServerException message = Multiple users found.</ns0:ErrorDesc>
<ns0:ErrorTitle>500 ServerException</ns0:ErrorTitle>
<ns0:RequestDateTime>2018-05-23T08:29:07.566-04:00</ns0:RequestDateTime>
<ns0:RequestTypeIdentifier>Order Create</ns0:RequestTypeIdentifier>
<ns0:Status>500</ns0:Status>
</ns0:ErrorDetail>
6
Security
The TWAI will accept web service traffic, perform certificate-based authentication against
security policies, and route the requests to G-Invoicing. Separate certificates are needed for test
and production environments.
No Personal Identifying Information (PII) is being transported by this system interface. There is
no risk that this interface or the included functions will allow additional access to G-Invoicing
data.
The Department of Defense has rated information contained in G-Invoicing as Mission
Assurance Category III. The MAC III rating is for systems handling information that is necessary
to conduct day-to-day business, but does not materially affect support to deployed or
contingency forces in the short-term. The consequences of loss of integrity or availability can be
tolerated or overcome without significant impacts on mission effectiveness or operational
readiness. The consequences could include the delay or degradation of services or
commodities enabling routine activities. Mission Assurance Category III systems require
protective measures, techniques or procedures generally commensurate with commercial best
practices.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
20
NONCONFIDENTIAL // EXTERNAL
7
Interface Integrity
7.1
TWAI
TWAI security infrastructure, policies and procedures guarantee that only authenticated and
authorized entities are permitted access to the G-Invoicing application and its assets. Virus
detection, intrusion detection, and network and infrastructure monitoring software and hardware
are provided by and operated in the TWAI.
7.2
Communication Channel
Adhere to the Guidelines for protecting sensitive data during electronic dissemination across
networks as stated in the NIST Special Publication (SP) 800-52 (rev 1), Selection,
Configuration, and Use of Transport Layer Security (TLS) Implementations.
Meet security requirements for NIST Special Publication (SP) 800-53 (rev 4), Recommended
Security Controls for Federal Information Systems, and other applicable guidance, such as
Treasury Directive Publication (TDP) 85-01.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
21
NONCONFIDENTIAL // EXTERNAL
8
Revision History
Vers.
Num.
Date of
Change
G-Inv
Rel.
Change/Revision Description
Page/Section
Affected
0.1
09/22/16
2.1
Initial Draft
All
0.2
01/05/17
2.1
Updates after meeting with GEX group
All
0.3
02/02/17
2.1
3.2 Protocol information added, updates to all sections.
All
0.4
02/06/17
2.1
Updates after peer review.
All
0.5
02/23/17
2.1
Added XML schema documentation.
4.6, 5, Appendix A
0.6
02/28/17
2.1
Added sample XML.
Appendix A
0.7
03/03/17
2.1
Updates after internal review.
All
0.8
03/07/17
2.1
Updates after peer review.
All
0.9
03/10/17
2.1
Updates after final internal review.
All
0.10
03/29/17
2.1
Updates after Fiscal Service review.
4.1.1, 5, 4.6.1, A
1.0
03/29/17
2.1
Baseline
All
1.1
04/24/17
2.1
Data element edits from D.O.D. BIO.
4.6.1
Appendix A
1.2
04/26/17
2.1
Omit “Draft” and “Delete” statuses.
3.2.3.1
4.2
4.6.1
1.3
05/19/17
2.1
Drop enumeration from Status element, added
Environment element values.
Updated data elements that were “Optional” with min
required char of 1 to 0.
Error Detail in Error schema is 1:Many
4.6.1
4.6.1
Appendix A
1.4
05/26/17
2.1
Updated schema versions to 2.0
Data element edits.
Added 400 HTTP error code.
Schema updates
1.3.3
4.6.1
5
Appendix A
1.5
06/05/17
2.1
Changed PartnerID and SystemID elements from Integer to
String.
Error schema changed to Ginv_Error.
4.6.1
Appendix A
1.6
06/19/17
2.1
Removed Attachment List Summary
1.3.3, 3.2.3,
4.1.2, 4.6.1,
Appendix A
1.7
06/20/17
2.2
Added Order to specification.
All
2.0
07/06/17
2.2
Prepped for Fiscal Service approval.
All
2.0.1
07/13/17
2.2
Raised SystemID, PartnerID to 100 chars.
Added 2
nd
approval for GT&C
3.2.3, 4.6.1
Appendix A
2.0.2
08/08/17
2.2
Removed GT&C and Order data tables.
4.6.1, 4.6.2
2.0.3
09/07/17
2.2
Added HTTP Error Code Table
5
2.0.4
10/25/17
2.2
Added min and max length to Record Count data element.
Added Attachment Summary table.
Table 3
4.6.1
2.0.5
11/08/17
2.2
GINV-1295, GINV-1326
Updated schema reference info.
Enumerated StatusCode values,
Made approval fields optional, corrected document
inconsistencies.
Appendix A
1.3.2
Appendix A
Table 2, Table 3
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
22
NONCONFIDENTIAL // EXTERNAL
2.0.6
12/12/17
2.2
Updated schema and XML information.
Appendix A
2.0.7
01/19/18
2.2
Updates based on data standards.
All
2.0.8
02/01/18
2.2
Updated schema and XML information
Appendix A
2.0.9
02/28/18
2.2
Removed /gtc from Attachment URL
3.2.3.3
2.0.10
03/14/18
2.2
Removed Attachment from examples provided for
Document Type.
Added business rule for status “PRA”
Table 4
4.2.6
2.0.11
04/11/18
2.2
1) Added character entity reference codes business rule.
(2) Updated date/time format. (3) Updated FileSize to
reflect kB.
(1) 4.2.7
(2)
All
(3)
Table 2
2.0.12
04/30/18
2.2
Add ‘Single Attachment’ to Request Types
Table 3
2.0.13
05/21/18
2.2
GINV-1787 move Org Ref data to Header level in XSD
Appendix A
2.0.14
5/30/18
2.2
Updated HTTP error status codes
5
2.0.15
6/6/18
2.2
Updated Resource information
3.2.3
3.0
6/8/18
2.2
Baseline
All
3.0.1
6/27/18
2.2
Updated Header
Appendix A
3.1
7/31/18
2.3
Added Performance transaction
All
3.2
8/6/18
2.3
Updated following internal review
All
3.3
8/28/18
2.3
Following Treasury review: (1) updated Partner/System
note, (2) removed GTC and Order XML samples
3.2.3
Appendix A
4.0
9/4/18
2.3
Approved – see GINV-1933
N/A
4.0.1
10/12/18
2.3
Deleted attachments are excluded. Order access =
Performance access.
4.2.1-3
4.0.2
10/24/18
2.3
Perf IDs obtained via Single Order by ID resource … (No
longer true)
3.2.3, 4.2.3.2 Table
4
4.1
12/20/18
2.3
Numerous changes in reaction to Dec 4-6 Perf mtgs. Added
Performance List.
All
4.2
12/24/18
2.3
Updates after internal review
4.2.1, Table 4
4.3
1/9/19
2.3
Better aligned schemas to FIDS.
Updated Treasury system owner name.
Extend Order services for Performance.
1.3.3, 3.2.3.3,
3.2.3.6-7
4.4
2/13/19
2.3
Allow agencies to pull Orders in draft status if Mod > 0 so
they know Orders are not open.
4.2.4 – 4.2.9
5.0
2/25/19
2.3
Baseline for Performance Txn
All
5.0.1
3/19/19
n/a
Removed extra requirement to disallow pull of GT&Cs in
pending status. This matches code.
4.2.7
5.0.2
3/22/19
n/a
Corrected spec to match code … Manual Entry Indicator ‘Y’
indicates manual entry.
Table 4
5.1
4/15/19
2.3 +1
(TBD)
Added settlement parameters to Pull Performance List
3.2.3.6
5.2
4/16/19
2.3 +1
(TBD)
Removed comments after internal review.
Added explanation of how Settlement is audited.
Distributed for Settlement approval.
3.2.3.6
6.0
4/29/19
2.3 +1
(TBD)
Baselined for Settlement
History
6.1
6/12/19
2.3 +1
(TBD)
Changed ‘settlementStatus’ to ‘status’ for Performance
List. Added note to 4.2.4
3.2.3.6
4.2.4
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
23
NONCONFIDENTIAL // EXTERNAL
6.1.1
8/29/19
N/A
Clarified policy requiring at least one System ID per
Partner ID.
3.2.3
v6.1.2
3/20/20
N/A
XML namespaces may vary w/ schema version
2.2.3a
v6.2
6/12/20
r4.0
Single GT&C resource supports v 1_0 and 2_0
3.2.3.2
v6.2.1
6/17/20
r4.0
GT&C List resource supports v 1_0 and 2_0
3.2.3.1, Table 4
v6.3
6/23/20
r4.0
1. As of r2.2, G-Invoicing does not send empty tags.
2. SystemID is now required.
Appendix A
Every resource
v6.4
12/03/20
r4.0
Removed DAG reference as System Ids are now assigned
to Org Groups
P1A or PRA Orders will be returned in the Order
list when
Mod>=0
4.2.3
v7.0
5/21/20
r4.1
New version to support Seller Facilitated Orders. Three
statuses have changed.
3.2.3.4, 4.2.7
v7.0.1
5/29/20
r4.1
Order List resource must support v 2_0
3.2.3.4
v7.1
12/03/20
r4.1
Clarified Order List status parameters for v 1_0 & v 2_0
3.2.3.4
v7.1.1
1/12/2021
r4.0
Clarification on change introduced in r4.0: Document
Summary List now includes ALCs in arrays for GT&Cs and
Orders, but not (yet) for Performance.
Table 4
v7.1.2
2/23/2021
r4.0
Removed reference to TWAI architecture diagram, which
is not publicly available
7.1
7.2
10/12/22
5.0
Added info on Order DocumentType for the Order List
pull
Table 4
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
24
NONCONFIDENTIAL // EXTERNAL
Appendix A: Messaging Protocol & Data Encapsulation
1
G-Invoicing Message Encapsulation
Transmissions into and out of G-Invoicing will utilize RESTful web-services over the
internet with an XML payload. The HTTP Request and Response will have the structure
depicted in diagrams in 1.1 and 1.2 below.
1.1
HTTP Request
The HTTP Request will have an empty Body when the Header contains a “GET” command.
When the Request contains a “PUT” command the Body will contain an XML payload.
1.2
HTTP Response
Call Detail data will be returned in every response generated by G-Invoicing with the
exception of the individual attachment download. Call Detail contains metadata about the
Request/Response. The Call Detail data will be part of the HTTP Body and precede any
data included in the response that satisfies the initial request.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
25
NONCONFIDENTIAL // EXTERNAL
2
Call Detail
3
Document List
Call Detail Sample XML
<?xml version="1.0" encoding="UTF-8"?>
<!--Sample XML file generated by XMLSpy v2017 sp2 (x64) (http://www.altova.com)-->
<cmn:Call_Detail xmlns:cmn="urn:us:gov:treasury"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:us:gov:treasury:ginv:gtc GTC.xsd">
<cmn:RecordCount>50</cmn:RecordCount>
<cmn:RequestID>277655239</cmn:RequestID>
<cmn:GINVTrackingID>3357822214</cmn:GINVTrackingID>
<cmn:PartnerID>1789</cmn:PartnerID>
<cmn:Environment>Production</cmn:Environment>
<cmn:RequestType>Single GTC</cmn:RequestType>
<cmn:SystemID>789</cmn:SystemID>
</cmn:Call_Detail>
Document List Sample XML
<?xml version="1.0" encoding="UTF-8"?>
<!--Sample XML file generated by XMLSpy v2017 sp2 (x64) (http://www.altova.com)-->
<cmn:DocumentList xmlns:cmn="urn:us:gov:treasury" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:us:gov:treasury:ginv:documents Documents_Summary.xsd">
<cmn:Document>
<cmn:DocumentNumber>A1610-017-017-000170</cmn:DocumentNumber>
<cmn:Status>REC</cmn:Status>
<cmn:LastModifiedDateTime>2017-08-28T14:05:37.534-04:00</cmn:LastModifiedDateTime>
<cmn:URL>https://host-name:port/base-path/resource-path</cmn:URL>
<cmn:RequestingAgencyLocationCode>00005023</cmn:RequestingAgencyLocationCode>
<cmn:ServicingAgencyLocationCode>00005197</cmn:ServicingAgencyLocationCode>
<cmn:DocumentType>GTC</cmn:DocumentType>
<cmn:ModificationNumber/>
<cmn:ManualEntryIndicator>Y</cmn:ManualEntryIndicator>
</cmn:Document>
</cmn:DocumentList>
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance
Version 7.2 – October 2022
26
NONCONFIDENTIAL // EXTERNAL
4
Error
Error Sample XML
<?xml version="1.0" encoding="UTF-8"?>
<!--Sample XML file generated by XMLSpy v2017 sp2 (x64) (http://www.altova.com)-->
<cmn:ErrorDetail xmlns:cmn="urn:us:gov:treasury" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:us:gov:treasury:ginv:error Error.xsd">
<cmn:ErrorDesc>Unknown GTC ID provided. Correct and resubmit.</cmn:ErrorDesc>
<cmn:ErrorTitle>400 Unknown GTC ID</cmn:ErrorTitle>
<cmn:RequestDateTime>2017-08-28T14:05:37.534-04:00</cmn:RequestDateTime>
<cmn:AgencyLocationCodes>00008501,00008502</cmn:AgencyLocationCodes>
<cmn:RequestTypeIdentifier/>
<cmn:Status>PND</cmn:Status>
</cmn:ErrorDetail>
