Introduction to AppZen Developer Hub

Welcome to the AppZen Developer hub. This page will help you connect your Expense and/or Invoice management system with AppZen. You will find comprehensive guides and documentation to help get started with the pre-built integrations and AppZen APIs as quickly as possible, as well as reference data and support if you have difficulties.

The Getting Started Guide provides the background information developers need to successfully integrate with AppZen products. Understanding how to access the APIs, develop appropriate security measures, and properly structure API requests and responses are all found in this guide.

AppZen's APIs are built around REST and support the following products

 

Capabilities

AP

AppZen’s Autonomous AP provides a considerable automation to manual invoice entry with multiple back office systems or ERPs. 

AppZen Autonomous AP API

 

Developer Resources

  • JSON formatted requests and responses
  • Standard HTTP Verbs/Methods
  • Standard HTTP Error Codes

Introduction

AppZen provides APIs for Invoice documents, supplier, purchase order, invoice audit results, search invoice audit, and bulk import. AppZen API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON responses, and uses standard HTTP response codes, and verbs.

These APIs can be used against below environments with following details:

Environment Name Base URL

PROD https://api.appzen.com

SBUS https://api.us.sandbox.appzen.com

EU  http://eu-api.appzen.com/dictionary-data-services

 

Onboarding a customer

AppZen provides end-to-end API service to its customers. When you onboard as a customer in the Autonomous AP, you will be assigned an ISM. An ISM is your point of contact for all API related queries. As a part of onboarding you will also get access to Customer Email IDs, Customer ID and Customer Key. All of which are important while making API calls. 

Screenshot_2022-02-28_at_4.47.39_PM.png

 

Authentication

Currently, AppZen has multiple integrations for AppZen Autonomous AP. AppZen uses BSI (Boutique System Integrator) partners for customer implementations. BSI uses AppZen’s APIs to complete all integrations for historical data ingestion and transactional integrations. 

 

Authentication for AppZen Integration:

AppZen uses API Key mechanism to validate calls to the API. It uses customer_id and API Key combination to allow the access to the public APIs. 

 

API Key Based Authentication:

In order to consume APIs protected using an API-Key, integration developers will use the API Key Based Authentication security policy.

REST Adapter provides an extensible interface for developers to declaratively define how the API Key needs to be sent as part of the request. During API invocation, the adapter will inject the API-Key as specified in the API Key Usage along with the request.

 

Sample Call to AppZen :

Authentication for these APIs are done based on following fields:

  1. customer-id : customer will have a unique value for this field. 
  2. x-api-key: Each partner/integration will have a unique value for it. Same value has to be used for all customers belonging to a particular integration.
  3. customer-key: Each customer will have a unique value for this field.

Testing API Keys

Once the customer receives the API key they can run the following curl command to test the API.

"curl --location --request GET 
'https://api.us.sandbox.appzen.com/dictionary-data-services/generate-upload-url' \
--header 'customer-id: {{customer id}}' \
--header 'customer-key: {{customer key}}' \
--header 'x-api-key: {{customer key}}' \
--header 'Content-Type: application/json'

If all the fields are correct, then it will display a 200 OK response. 

Extracting the Master Data

  1. Payment Terms
  2. Chart of accounts
  3. Supplier 
  4. Entity
  5. Purchase Order
  6. Invoice and Document 

Order of Ingestion of an Invoice 

During the Master Data extraction, an Invoice can be extracted by following the given order. 

Screenshot_2021-12-27_at_2.45.07_PM.png

Payment Term: The first API call that needs to be made is for the Payments Term. 

Chart of Account (COA)/Supplier: The COA and Supplier can be ingested simultaneously. Entities are then mapped to the COAs accordingly.

Purchase Order: Once the supplier is ingested you can move towards Purchase Order. 

Invoice: After Purchase Order you can ingest the Invoices. But before you move towards making the call, you need to have the document uuid which can be retrieved from the documents API call. The steps to generate a document UUID is given in the next section. 

"documents":[
{
"uuid":"string"
}
]

Available APIs

Master Data

  • Payment Terms: Creates a new payment term in AppZen. Returns a uuid for this payment term. When there already exists a payment term (with the same payment_term_id), then the operation is an update (in this case, the status in the response will be UPDATED).
  • Chart of Accounts: Creates a new chart of account segments in AppZen and returns a uuid that uniquely identifies it. When there already exists a chart of the account segment (segment_code), then the operation is an update (the status would be UPDATED in this case).
  • Entities: Creates a new entity in AppZen. Returns a uuid for this entity. When there already exists an entity (with the same entity_id), then the operation is an update (in this case, the status in the response will be UPDATED).
  • Suppliers: Creates a new supplier in AppZen. Returns a uuid for this supplier. When there already exists a supplier (with the same supplier_id), then the operation is an update (in this case, the status in the response will be UPDATED).
  • Purchase Orders: Creates a new purchase order in AppZen and returns a uuid that uniquely identifies it. When there already exists a purchase order (purchase_order_number), then the operation is an update (the status would be UPDATED in this case).

 

Transactional Data

  • Documents: Generates a url to upload an Invoice document into the AppZen repository.
  • Invoices: This will create a new invoice in AppZen referred by uuid. This invoice will be processed further by AppZen for extraction and validation. When there already exists an invoice (invoice_id), then the operation is an update (the status would be UPDATED in this case). Invoice search API returns a list of the invoice uuids that match the status, from-date and end-date
  • Processed Invoices: Returns the processed results and invoice by uuid. The invoice will have results based on supplier check and duplication check. This will then give a warning message at invoice header level, such as LOW, MEDIUM, HIGH. This is shown along with invoice status  such as Approved, Rejected and invoice detail. The download links to the images are valid for only 5 minutes.
  • Invoice Status Sync: This is used to update the external ERP status as well as AppZen internal state for an invoice referred by uuid.
  • Invoice Audit Results: Returns the audit results of an invoice by uuid. It includes the risk at invoice header level, such as LOW, MEDIUM, HIGH and the overall invoice status, such as Approved, Rejected.

Error Codes

Here are some of the common error/status codes used by AppZen Autonomous AP. 

Error/Status Code

Message Meaning 
200 OK Everything worked as expected.
201

Created 

Request was Created 

400

Bad Request

The request was unacceptable, often due to missing a required parameter

401

Unauthorized

No valid authentication (e.g.: Customer Key could be missing/invalid)

403

Forbidden 

The x-api key doesn’t have permission to perform the request 

404

Not Found

The request resource doesn’t exist

500

Internal Server Errors

Something went wrong on AppZen’s end

429

Too Many Requests

Available quota/limit already consumed 

Note: AppZen allows 1,000 requests per second and 300,000 requests per day. If you are exceeding either off the limits, you’ll get an HTTP 429 error.

 

 

 

 

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.