Document Compliance Gateway v4

Document Compliance Gateway v4 API is designed to manage the transmission of the XML receipt file to the validating vendor. Vendors can implement the API to read the XML file sent to the SAP Concur system by the end user from an approved email, validate the XML against government records, and return the validation result. In addition, the vendor can read and parse the XML file to provide tax relevant data for creating expense entry.

The API supports an improved and efficient process for XML validation. The end user gets the XML validation result prior to expense creation preventing the unnecessary process, as well as, return and resubmission of the expense reports. The API also uses the data from the XML file to initiate the expense line item, saving the need for the user to manually type the information.

Currently, the API supports validating XML documents for Mexico called Comprobantes Fiscal Digital por Internet (CFDi).

Prior Versions

No prior API version available

Limitations

API access is available only to the authenticated companies with granted permission. Access to this documentation does not provide access to the API. The API will be deployed to US2 & EU2 data centers.

Process Flow

Products and Editions

• Concur Invoice Professional Edition
• Concur Invoice Standard Edition

Scope Usage

Authentication

Authentication is provided through an App for company JWT. This API requires the valid access token with required scopes. Before making requests to the API, please obtain an access token from the Authentication API.

Dependencies

None.

Endpoints

GET API CALL

Get the compliance document

Scopes

Refer to Scope Usage for full details.

receipts.read

Request

URI

Template

GET https://{region}.api.concursolutions.com/document-compliance-gateway/v4/tax-documents/{documentId}

Parameters

Headers

• Authorization is provided through an App for Business and the company JWT. More details can be found here
• concur-correlationid is used to track the workflow for every step.

Notes

• The company JWT is data center specific. The auth service (/token endpoint) that signs the JWT determines which data center the JWT will work in.
• To get a token or to refresh a token, use the curl command(s)specified here.
• Once you have the token use the following curl command to POST invoice details:

curl --location --request GET 'https://integration.api.concursolutions.com/document-compliance-gateway/v4/tax-documents/{documentId}' -H 'Authorization: Bearer <JWT token>'
  -H 'concur-correlationid: {LogicalId}'

Response

Error Codes

Example

Request

GET https://integration.api.concursolutions.com/document-compliance-gateway/v4/tax-documents/c92565ca-78c7-47be-a730-1d33ef35cdac
Authorization: Bearer <JWT Token>
concur-correlationid: "Test-FlOW"

Response

HTTP/1.1 200 OK
Content-Type: XML

PUT API CALL

Provide the XML validation result and parsed tax relevant data from the XML file.

Scopes

Refer to Scope Usage for full details.

receipts.write

Request

URI

Template

PUT https://{region}.api.concursolutions.com/document-compliance-gateway/v4/tax-documents/{documentId}

Parameters

Headers

• Authorization is provided through an App for Business and the company JWT. More details can be found here
• concur-correlationid is used to track the workflow for every step.

Payload

• DigitalTax Token

Notes

• The company JWT is data center specific. The auth service (/token endpoint) that signs the JWT determines which DC the JWT will work in.
• To get a token or to refresh a token, use the curl command(s)specified here. It is recommended to have a valid token and scope to make the post call to the API.
• Once you have the token, use the following curl command to POST invoice details:

curl --location --request PUT 'https://integration.api.concursolutions.com/document-compliance-gateway/v4/tax-documents/{documentId}' -H 'Authorization: Bearer <JWT token>'
  -H "concur-correlationid": {LogicalId}\
  --form "digitalTaxDocument"=@"DigitalTaxToken.json"

Response

Error Codes

Example

Request

POST https://integration.api.concursolutions.com/document-compliance-gateway/v4/tax-documents/c92565ca-78c7-47be-a730-1d33ef35cdac
Authorization: Bearer <JWT Token>
concur-correlationid: "Test-FlOW"
digitalTaxDocument:
{
   "Status":"processed",
   "DocumentData":{
      "FormatVersion":"4.0",
      "Code":"pos",
      "Number":"1234",
      "IssueDateTime":"2021-12-07T23:59:59",
      "UUID":"ED1752FE-E865-4FF2-BFE1-0F552E770DC9",
      "PaymentType":"Cash",
      "GrossAmount":0.0,
      "Discount":0.0,
      "Currency":"MXN",
      "ExchangeRate":"0.0",
      "NetAmount":0.0,
      "PaymentMethod":"PUE",
      "TotalWithholdingTax":0.0,
      "TotalSalesTax":0.0,
      "Vendor":{
         "CertificateNumber":"0000",
         "TaxNumber":"TXN-No-1000",
         "Name":"Vendor 1",
         "city":"Bellevue",
         "state":"WA",
         "country":"US",
         "phone":"888-867-5309",
         "addressLine":"123 Main St"
      },
      "Buyer":{
         "TaxNumber":"TXN-No-10001",
         "Name":"Buyer 1",
         "PostalCode":"MX-000001"
      },
      "LineItems":[
         {
            "ProductCode":"P1",
            "Description":"Decription",
            "Amount":0.0
         }
      ],
      "DocumentPostalCode":"MX-000002"
   },
   "Description":"Document is valid",
   "Code":"200"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "DocumentId": "c92565ca-78c7-47be-a730-1d33ef35cdac",
  "Description": "Tokens have been received."
}

Schema

DigitalTax Token