AP Invoice API Developer Guide

This developer guide describes how to define custom invoice fields that aren’t provided by default with the AP Invoice API for Accounts Payable Invoice Processing. Instructions are also provided for setting authentication when using cXML as the payload.

You can define custom invoice fields for the request body. Use the following flow to add custom fields, map them to target tables, and format them for availability in the payload:

1. Add custom fields for invoice import
2. Map custom fields between source and target tables
3. Map custom fields to a payload source format

Define credentials for cXML payloads in the Source system credential [sn_spend_intg_source_system_credential] table. For instructions, see Setting credentials for authentication in the cXML payload.

See also:

• Accounts Payable Invoice Processing
• AP Invoice API

Add custom fields for invoice import

Use the following procedure to add custom fields for invoices, invoice lines, and invoice tax lines to be used with the AP Invoice API.

Before you begin

• Role required: admin
• Application scope: Source-to-Pay Integrations

Procedure

1. Navigate to All > System Definition > Tables.
2. Select one of the following invoice import tables:
   • Invoice Import [sn_spend_intg_imp_invoice]
   • Invoice Line Import [sn_spend_intg_imp_invoice_line]
   • Invoice Tax Line Import [sn_spend_intg_imp_invoice_tax_line]
3. On the Table Columns tab, select New.
4. Select a type associated with the field value (for example, Integer) from the Type menu.
   Note:

   For a list of valid types, see Field types reference.
5. Enter a meaningful name in the Column label field.
   Text including the label is automatically populated in the Column name field.
6. Select Save or Submit.
7. Add a column of the same name and type to the Invoice [sn_shop_invoice] table.
   Note:

   For more information on columns and fields, see Exploring field administration.
8. Map the fields between the source and target tables.

Map custom fields between source and target tables

Use the following procedure to map custom fields between source and target tables for the AP Invoice API.

Before you begin

• Role required: admin
• Application scope: Source-to-Pay Integrations

Create table columns for mapping the new field from the source table to the target table. Use the steps in Add custom fields for invoice import.

Procedure

1. Navigate to All > System Import Sets > Transform Maps.
2. Open the Invoice Import table transform map.
3. Click New on the Field Maps tab.
4. Select the name of the custom field from the Source field menu.
5. Select the name of the custom field from the Target field menu.
6. Select Save or Submit.
7. Map custom fields to a payload source format.

Map custom fields to a payload source format

Use the following procedure to map custom fields to a payload entry in JSON, cXML, or XML for the AP Invoice API.

Before you begin

• Role required: admin
• Application scope: Source-to-Pay Integrations
• Add custom fields for invoice import
• Map custom fields between source and target tables

Procedure

1. Navigate to All > Procurement Integrations > Suppliers > Invoice Integration Field Mappings.
2. Select New.
3. Add the name of the source system to the Source system field.
   • If this field mapping applies to all source systems, enter Default.
   • If the mapping is specific to a particular source system, this value must match the value of the Source-System header parameter received in the API.
     Note:

     All remaining field mappings must be configured specifically for this source system.
4. Select the format of the source system for which the mapping is being created from the Source format choice list (cXML or JSON).
5. Provide a name (JSON property) or path (cXML/XML attribute or element) for the payload entry in the Source field field.
   You can view the Invoice integration field mapping [sn_spend_intg_invoice_intg_field_mapping] table for examples of cXML and XML path settings.
6. Add the name of an attribute if the field is to be defined as an element attribute for cXML payloads, otherwise leave the field empty.
7. Select the name of the target table containing your custom field from the Related table list.
8. Select the name of the custom field from the Target field list.
9. Select Save or Submit.
   The mapped field is added to the Invoice integration field mapping [sn_spend_intg_invoice_intg_field_mapping] table.

Setting credentials for authentication in the cXML payload

The sn_spend_intg/ap_invoice/cxml endpoint is authenticated in the payload using credentials stored in the Source System Credential [sn_spend_intg_source_system_credential] table.

Before you begin

Role required: admin

Identify the payload source system listed in the Invoice integration field mappings [sn_spend_intg_invoice_intg_field_mapping] table.

See also AP Invoice – POST sn_spend_intg/ap_invoice/cxml.

Procedure

1. Navigate to All > Procurement Integrations > Source System Credentials.
2. Select New.
3. Add the name of the source system listed in the Invoice integration field mappings [sn_spend_intg_invoice_intg_field_mapping] table in the Source System field.
   The source system name must match the Source-System header parameter.
4. Add the user name to be fetched in the User name field.
   Use this value in the /cXML/Header/To/Credential [@domain='NetworkID']/Identity element.
5. Add a strong combination of letters, numbers, and special characters to the Password field.
   Use this value in the /cXML/Header/Sender/Credential [@domain='NetworkID']/SharedSecret element.
6. Select Submit.