NONCONFIDENTIAL // EXTERNAL

Overview of G-Invoicing

System Interfaces

Version 2.1

June 21, 2023
NONCONFIDENTIAL // EXTERNAL

Page 2 L EAD ∙ T RANSFORM ∙ D ELIVER

• System Integration Guide

• System Interface Specifications

• Pull Documents

o XML-based: GT&C, Order, Performance, Attachments

o JSON-based: GT&C, Order, Performance, 7600EZ, 

Attachments, Org, Features, Remittance Advice

• Push Documents

o Order

o Orders

o Performance

o 7600EZ

o Attachments

Agenda
NONCONFIDENTIAL // EXTERNAL

Page 3 L EAD ∙ T RANSFORM ∙ D ELIVER

• Communicates how Federal Program Agencies (FPA) may utilize automated 

data exchanges to communicate IGT Buy/Sell activities to/from G-Invoicing

– Describes the automated data exchanges

– Provides references to additional information

– Details the steps needed to establish system interfaces

– Recommended best practices for pushing/pulling data from G-Invoicing

System Integration Guide
NONCONFIDENTIAL // EXTERNAL

Page 4 L EAD ∙ T RANSFORM ∙ D ELIVER

Application Program Interfaces
NONCONFIDENTIAL // EXTERNAL

Page 5 L EAD ∙ T RANSFORM ∙ D ELIVER

• It’s highly recommended if a system is utilizing the existing XML endpoints in G-Invoicing to have 

an upgrade path in place to move to the JSON endpoints. 

• G-Invoicing will continue to support older XML endpoints for the documents (GTC, Orders, and 

Performance) for a time, but they will not be upgraded or enhanced.

• All future endpoints will be created only utilizing JSON

• G-Invoicing currently supports all endpoints in JSON 

JSON or XML?
NONCONFIDENTIAL // EXTERNAL

Page 6 L EAD ∙ T RANSFORM ∙ D ELIVER

• Systems must be granted user roles and data access in order to pull/push data 

from/to G-Invoicing

– Permissions are maintained by Administrators at each agency

– An agency system ID only requires access to one side of a document to view all data 

associated with the document, including attachments

– The agency system ID must be assigned an organizational Group high enough in the agency's 

hierarchy to access the requested data

– System gain access to all documents at the group assigned and below

– Systems granted access to Order roles/data also have access to view Performance data, but to 

create Performance it will need access to Performance roles/data

– All authenticated system IDs have access to organizational (group) data for all agency accounts

Authorization
NONCONFIDENTIAL // EXTERNAL

Page 7 L EAD ∙ T RANSFORM ∙ D ELIVER

• Required for authorization of Partner ID (i.e., client certificate) 

System ID Parameter
NONCONFIDENTIAL // EXTERNAL

Page 8 L EAD ∙ T RANSFORM ∙ D ELIVER

• The API Gateway 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

Security

• No high Personal Identifying Information (PII) 

is being transported by this system interface

– G-Invoicing cannot control the content of attachments
NONCONFIDENTIAL // EXTERNAL

Page 9 L EAD ∙ T RANSFORM ∙ D ELIVER

• Standard web service faults are generated for exceptions that can cause the request to not be 

processed

• All services may return the following HTTP status codes along with variable error message text 

describing the error(s) in the response

– 400 Bad Request

o ValidationFailedException

– 403 Unauthorized

o AccessDeniedException

– 500 Internal Server Error

o ServerException

Error Handling
NONCONFIDENTIAL // EXTERNAL

Page 10 L EAD ∙ T RANSFORM ∙ D ELIVER

• Requests for documents (e.g., GT&C or Attachment) are fulfilled with current data only

– G-Invoicing will not provide a document history for GT&Cs or deleted attachments (i.e., multiple versions 

of the same document)

– G-Invoicing does support pulling document history for Orders

• (XML-based only) Character entity references “ampersand” (&) and “less than” (<) are escaped on 

output to XML

– The escape sequence for ampersand is &

– The escape sequence for less than is <

• Clients should not validate XML returned from API request

– XML schema version number may change when optional tag(s) added, for example:

o 3.2 release introduced new (2.1) version of the GT&C schema

o added optional Requesting and Servicing Group Name(s)

o kept the Pull API at version 1_0

Pull Interfaces – General Rules
NONCONFIDENTIAL // EXTERNAL

Page 11 L EAD ∙ T RANSFORM ∙ D ELIVER

• Agency Tracking Identifier

– Unique identifier from agency system, optionally supplied in the request and returned in the response

• Agency Location Code

– Limits results to documents related to one of the requested ALCs

• Last Modified Date Time

– Limits results to documents updated since the requested timestamp

– Client keeps track of date/time of last successful pull request 

• Status

̶ Limits documents to one of the requested status types

̶ Most draft and deleted documents are not accessible 

o Exception: Order drafts where Mod > 0

o Deleted 7600EZ & Performance records are accessible 

Each API supports a unique set of parameters – Please reference the specific API specification for 

more details on the G-Invoicing Resource website

Pull Interfaces – General Parameters
NONCONFIDENTIAL // EXTERNAL

Page 12 L EAD ∙ T RANSFORM ∙ D ELIVER

Document List

GT&C, Order,

Performance

Document List

The initial request to G-Invoicing will return a list of GT&C’s, Orders or 

Performance based on the API resource polled and the System User’s access 

and permissions. The list returned in the response will contain meta data about 

each document as well as the link (URL) to request the individual documents in 

a subsequent request.

Individual Document

Individual document requests (e.g., GT&C, Order, Performance) will return all 

non-empty data elements in the XML payload of the requested document 

along with meta data about attachments (if any exist) associated with the 

document. The meta data contains links (URLs) for agency systems to pull 

individual attachments.

Attachment

Individual Attachments may be pulled by agency systems on request. 

Attachments are pulled by passing a unique identifier in the request URL, 

found in the attachment meta data, located in the XML payload of the 

associated document.

3 Steps to Pull G-Invoicing Documents and Attachments

Requesting G-Invoicing Documents

3 steps to pull G-Invoicing documents (i.e., GT&C, Order, Performance, 

7600EZ) and attachments – Supported in XML & JSON
NONCONFIDENTIAL // EXTERNAL

Page 13 L EAD ∙ T RANSFORM ∙ D ELIVER

• Pull Organization (JSON)

• Get Accounts

• Get Groups in an Agency Account

• Get Groups for a GT&C

• Get TAS-BETCs for a Group

• Pull Features or BizApps (JSON)

• Extract which Account supports different G-Invoicing features. Turning features on our Account-wide and 

allows for additional functionality within the UI and APIs. Both trading partners must have a feature 

activated to be able to use the feature within G-Invoicing. This API gives out that information to clients.

• Pull Remittance Advice (JSON)

– Limited to a single ALC on a single date

Single Step Pull APIs
NONCONFIDENTIAL // EXTERNAL

Page 14 L EAD ∙ T RANSFORM ∙ D ELIVER

• Requesting and Servicing Groups are 

established on the GT&C 

• Orders must reference an open GT&C and two 

valid Groups, ALCs and TAS-BETCs

• Question: How can agency systems guide their 

users’ selections?

How does a system know which groups to us on an Order or Invoice?
NONCONFIDENTIAL // EXTERNAL

Page 15 L EAD ∙ T RANSFORM ∙ D ELIVER
NONCONFIDENTIAL // EXTERNAL

Page 16 L EAD ∙ T RANSFORM ∙ D ELIVER

Potential Reasons to repull Org Data

• Modification or Admin Changes to a GT&C

o Increment the Last Modified Date/Time, which should be used to pull updated data using the GT&C List (#4 API).

o It’s recommended that a system pulls the GT&C Detail (#5 API).

o It’s recommended that a system pulls the Get Groups for GT&C (#6 API).

o It is highly recommended that a system stores this data and doesn’t rely on G-Invoicing for every Order or 7600EZ 

Invoice creation within their system.

• Organizational Group Changes

o It’s recommended that a system pulls the Get Accounts (#1 API) no more than once a day. 

 By using the lastModifiedDateTime parameter G-Invoicing will only return Accounts that have been updated since 

the last time the system has pulled data from this endpoint.

o If using the Get Groups for Account (for either their own Account or Trading Partners) we recommend storing the data 

and only repulling if the account appears in the Get Accounts response. 

o This would pull in any new, updated, or deactivated Org groups due to an organization change.

As G-Invoicing matures this data will become more and more static over time, but there always a potential organizational changes to occur governmentwide.

Best Practices for utilizing the Org API
NONCONFIDENTIAL // EXTERNAL

Page 17 L EAD ∙ T RANSFORM ∙ D ELIVER

• Four sets of services

1. Create or update Order

2. Create or delete Performance

3. Create or delete 7600Ez

4. Create or delete Attachment

• Based on RESTful API principles

• Synchronous processing of one document per request

• Response includes critical information, for example:

– Order, Performance & EZ Number

– Complete XML or JSON representation of document

– Attachment IDs

– Error descriptions

Push Interfaces
NONCONFIDENTIAL // EXTERNAL

Page 18 L EAD ∙ T RANSFORM ∙ D ELIVER

• Servicing Agency are not allowed to change data elements belonging to Requesting Agency and 

vice-versa

̶ Submission of partner’s data will be ignored

̶ Exception: Some data may be provided by either partner. Please reference the appropriate SM&VR or FIDS on the G-Invoicing 

website under Resources. 

• XML included in request must comply with appropriate schema

• JSON is must comply with business validations

• Attachments may be added to, and deleted from, existing Order, Performance, 7600EZ records 

using the Attachment service

• For add Attachment requests, the attachment FileName in the XML or JSON payload must exactly 

match the filename in the Content-Disposition parameter within the multipart form-data

General Rules for Push Interfaces
NONCONFIDENTIAL // EXTERNAL

Page 19 L EAD ∙ T RANSFORM ∙ D ELIVER

• Order State Diagram for System User 
NONCONFIDENTIAL // EXTERNAL

Page 20 L EAD ∙ T RANSFORM ∙ D ELIVER

Order REST Service (1 of 4)

1A. Partner 1 submits (pushes) a new Order to be processed immediately

1B. G-Invoicing processes the single Order transaction and synchronously delivers

a response to Partner 1

1A

1B

Transaction

Request

Response 

with Result

Create
NONCONFIDENTIAL // EXTERNAL

Page 21 L EAD ∙ T RANSFORM ∙ D ELIVER

Order REST Service (2 of 4)

2A. Partner 2 requests a pull of new/modified documents from G-Invoicing

2B. G-Invoicing responds by delivering the requested data to Partner 2

Note: This is a 3-step process as described by Requesting G-Invoicing Documents slide

2A

2B

Information

Request

Response

with Data

Read
NONCONFIDENTIAL // EXTERNAL

Page 22 L EAD ∙ T RANSFORM ∙ D ELIVER

Order REST Service (3 of 4)

3A. Partner 2 submits (pushes) an Order approval transaction to G-Invoicing

3B. G-Invoicing processes the single Order transaction request and delivers a

response to Partner 2

3A

3B

Transaction

Request

Response

with Result

Update
NONCONFIDENTIAL // EXTERNAL

Page 23 L EAD ∙ T RANSFORM ∙ D ELIVER

Order REST Service (4 of 4)

4A

4B

4A. Partner 1 requests a pull of new/modified documents from G-Invoicing

4B. G-Invoicing responds by delivering the requested data to Partner 1

Note: This is a 3-step process as described by Requesting G-Invoicing Documents slide

Information

Request

Response

with Data

Read
NONCONFIDENTIAL // EXTERNAL

Page 24 L EAD ∙ T RANSFORM ∙ D ELIVER

• Order Processing

Requested By Type of Request Method Current State New State Data Validation Rules

Partner 1 New Order POST N/A Shared with Partner 

2

• All required Partner 1 data in request (see SM&VR)

• Partner 2 (only) data in request will be ignored

Partner 2 Approved Order PUT Shared with Partner 

2

Open • All required Partner 2 data in request (see SM&VR)

• Partner 1 (only) data in request will be ignored

Partner 2 Rejected Order PUT Shared with Partner 

2

Rejected • Required data for rejection in request (see SM&VR)

• All other Partner 2 data in request will be ignored

• Partner 1 (only) data not in request

Partner 1 Modified Order PUT Open, Rejected or 

Closed

Shared with Partner 

2

• All required Partner 1 data in request (see SM&VR)

• Changes detected to Partner 1 data elements (xml/json)

• Partner 2 (only) data in request will be ignored

Requesting Agency Closed Order PUT Open Closed • Required data for closure in request (see SM&VR)

• All other Buyer data in request will be ignored

• All Seller data in request will be ignored

Requesting Agency Requesting Admin 

Changes

PUT Open Open • All required Buyer data in request (see SM&VR)

• Administrative changes detected to Buyer data (xml/json)

• Only data elements Provided By ‘Requesting’ (BIO or SFO, depending on the 

situation) with How to Update ‘Admin Change’ in FIDS may be altered

Servicing Agency Servicing Admin 

Changes

PUT Open Open • All required Seller data in request (see SM&VR)

• Administrative changes detected to Seller data (xml/json)

• Only data elements Provided By ‘Servicing’ (BIO or SFO, depending on the situation) 

with How to Update ‘Admin Change’ in FIDS may be altered
NONCONFIDENTIAL // EXTERNAL

Page 25 L EAD ∙ T RANSFORM ∙ D ELIVER

• Business Transaction Identifier on Orders

– Unique identifier used to guarantee an update request is based on the most recent version of the Order

– Every change made to an Order results in the assignment of a new Business Transaction Identifier 

– If the latest Business Transaction Identifier is not included in the XML/JSON, the request will be 

rejected

• Performance/7600EZTransactions

– There is no way to update a Performance transaction

– Transactions with a future Performance Date may be deleted

• There is no API to create or update GT&C agreements

– GT&C agreements must be negotiated in the user interface

Push Interfaces – Updating Documents
NONCONFIDENTIAL // EXTERNAL

Page 26 L EAD ∙ T RANSFORM ∙ D ELIVER

• Federal Intragovernmental Data Elements (FIDS)

̶ Data dictionary for GT&Cs, Orders, Performance and Organization

̶ Ties data elements to Schemas and to Fiscal Service Data Registry

̶ Contains critical information

o Which partner supplies each data element for Buyer initiated Order

o Which partner supplies each data element for Seller Facilitated Order

o What action can be taken (if any) to change the value of each data element 

• System Mapping and Validation Rules (SM&VR)

̶ Show detailed validation rules for each data element in each status 

̶ Separate worksheets for Buyer Initiated Orders and Seller Facilitated

̶ Includes UI statuses, so focus on column headings with orange highlights

o Approved Order from Buyer (or Seller for SFO)

o Approved Order from Seller (or Buyer for SFO)

o Modified Order from Buyer (or Seller for SFO)

Supporting Documents
NONCONFIDENTIAL // EXTERNAL

Page 27 L EAD ∙ T RANSFORM ∙ D ELIVER

Logical Data Model for Orders
NONCONFIDENTIAL // EXTERNAL

Page 28 L EAD ∙ T RANSFORM ∙ D ELIVER

• GT&C must be in open status to update an Order

• Period of Performance (POP) for the Order must fall within the GT&C’s POP

• In a future release, G-Invoicing will allow either trading partner to initiate Orders 

– System user presenting the Order must have proper access as required by the Order Originating Partner 

Indicator in the GT&C 

o ‘R’ requires Requesting Order Manager & Approver roles

o ‘S’ requires Servicing Order Manager & Approver roles

These and many more rules may be found in the Order SM&VR

Push Order – Basic Requirements
NONCONFIDENTIAL // EXTERNAL

Page 29 L EAD ∙ T RANSFORM ∙ D ELIVER

• Some data elements are system generated

– Order Number 

• Some data elements are exclusively supplied by one partner

– Program Authority Citation

• Some data elements are sent in by both partners

– Attachment File Name

• Some data elements are supplied by Partner 1 once, then exclusively updated by Partner 2

– (Partner 2’s) Group Name

• Data supplied by the wrong partner is ignored

– Unless otherwise specified in SM&VR

Data sources are defined in the Order FIDS

Push Order – Data Sources
NONCONFIDENTIAL // EXTERNAL

Page 30 L EAD ∙ T RANSFORM ∙ D ELIVER

• Lines and Schedules cannot be physically deleted

• Lines and Schedules can be cancelled

• Schedule Quantity may be set to zero

• All lines and schedules must be pushed for an Order, even those that have been cancelled or 

zeroed out

• Missing lines or schedules will result in error code 400

– “The lines and schedules provided for this order do not match existing data. Please send all lines and 

schedules for this order”

Push Order – Lines and Schedules
NONCONFIDENTIAL // EXTERNAL

Page 31 L EAD ∙ T RANSFORM ∙ D ELIVER

• Values of certain “administrative” data may be changed while Order remains in open status

• Filter the “How to Update” column in FIDS for ‘Admin Change’

• Attempts to change the value of a data element not marked for ‘Admin Change’ will be ignored

– i.e., G-Invoicing will only examine candidates for Admin Change

• Attempts to change values of data elements on a Schedule against which Performance has been 

reported will be rejected

• System user must be assigned Order Manager role

• Admin Changes work the same for Seller Facilitated Orders

Push Order – Administrative Changes
NONCONFIDENTIAL // EXTERNAL

Page 32 L EAD ∙ T RANSFORM ∙ D ELIVER

• Modifications may be requested by “Partner 1” (i.e., the same partner that introduced the new 

Order)

• See Order FIDS to determine which data may be modified

• Partner 2 may modify data once Partner 1 has approved 

• Modifications require approval by each trading partner

• Modifications can be rejected and sent back to draft status

– An Order in Rejected status by Partner 1, if Order Revert feature is enabled and both trading partners can 

support

• Order Schedule Quantity cannot be reduced to a point below the sum of quantity performed for any 

Performance Type

– Most recent Deferred Payment is evaluated with Delivered/Performed

• Modifications may also alter data elements eligible for “Administrative Change” (see Order FIDS)

Push Order – Modifications
NONCONFIDENTIAL // EXTERNAL

Page 33 L EAD ∙ T RANSFORM ∙ D ELIVER

Push Order – Closing Rules

• Orders can be closed under the following conditions

– Sum of Advanced quantity equals sum of Delivered/Performed

– Sum of Delivered/Performed equals sum of Received/Accepted

o when FOB Point is ‘Destination’ or ‘Other’ (and not Advanced)

o when Received/Accepted has been provided by Buyer

– No Performance pending settlement

– At least one of the following conditions are met for each Schedule on the Order:

1. Balance is zero (i.e., no unpaid quantity), or

2. Seller has reported the “final” Delivered/Performed transaction
NONCONFIDENTIAL // EXTERNAL

Page 34 L EAD ∙ T RANSFORM ∙ D ELIVER

Logical Data Model for Performance

Performance 

Headers and Details 

may reference prior 

Performance

Performance Types

014 - Deferred Payment

035 - Delivered/Performed

050 - Received/Accepted

548 - Advance
NONCONFIDENTIAL // EXTERNAL

Page 35 L EAD ∙ T RANSFORM ∙ D ELIVER

• G-Invoicing settles qualified Performance through IPAC to CARS

• Performance status is included in API response:

• Future dated Performance settles on the Performance Date

• Advance settles immediately, unless future dated

• Delivered/Performed settles if FOB Point is Source/Origin

• Received/Accepted settles if FOB Point is Destination or Other

• Adjustments follow the same settlement rules

• Settlement errors will be corrected by G-Invoicing Production Support

Settlement of Performance

Performance Status Code Use Case

Informational INF Performance has not triggered settlement

Pending

Previously Settled

PND

PRE

Performance awaiting settlement

Performance will not settle

Settled STL Performance has been settled

Deleted XXX Performance has been logically deleted

Error ERR Performance for which settlement has failed
NONCONFIDENTIAL // EXTERNAL

Page 36 L EAD ∙ T RANSFORM ∙ D ELIVER

Logical Data Model for 7600EZ
NONCONFIDENTIAL // EXTERNAL

Page 37 L EAD ∙ T RANSFORM ∙ D ELIVER

Settlement of 7600EZ

• G-Invoicing settles qualified 7600EZ transactions through IPAC to CARS

• 7600EZ status is included in API response but may change later

• Future dated Invoices settles on the Performance Date

• Invoice & Reversed settles settled on Performance Date

• Accepted is always Informational 

• Rejected settles if transaction is submitted within Rejection Days window of the Invoice

• 7600EZs don’t allow adjustments are need to be fully reversed if needed

• Settlement errors will be corrected by G-Invoicing Production Support

Performance Status Code Use Case

Informational INF 7600EZ has not triggered settlement

Pending PND 7600EZ awaiting settlement

Settled STL 7600EZ has been settled

Deleted XXX 7600EZ has been logically deleted

Error ERR 7600EZ for which settlement has failed
NONCONFIDENTIAL // EXTERNAL

Page 38 L EAD ∙ T RANSFORM ∙ D ELIVER

Attachment Services

• Stand-alone Attachment web service

– Pull single Attachment (GT&C, Order, Performance, 7600EZ)

– Push single Attachment (Order, Performance, 7600EZ)

o The method for submitting an attachment is POST

o DocumentNumber is required in the XML body of the attachment request in order to add the attachment to 

the appropriate document

o See Push Spec Appendix B for more details (Section 4 Multipart Form-Data)