Oracle Financials Cloud

Latin America Cloud Local Solution

Costa Rica

XML Canonical for Electronic

Invoice - Payables
Technical Implementation Guide

Version 7

08 Jun 2021

DISCLAIMER:

This guide may contain screen shots and output reports to facilitate the user comprehension about the
topic. The content represents a fictitious sample. Any similarity to actual persons, living o. dead, or
company names, active or inactive, is purely coincidental and not intended in any manner.

LACLS Costa Rica – XML for Electronic Invoice - Payables – Technical Implementation Guide
1
TABLE OF CONTENTS
TABLE OF CONTENTS ..............................................................................................................................................2

REVISION HISTORY ......................................................................................................................................................... 3

INTRODUCTION TO XML CANONICAL FOR ELECTRONIC INVOICE – PAYABLES FOR COSTA RICA .............................4

INTENDED AUDIENCE...................................................................................................................................................... 4
APPLICATIONS TECHNOLOGY............................................................................................................................................ 5

INTEGRATING WITH THIRD PARTY SOLUTION ........................................................................................................6

SEND PROCESS.............................................................................................................................................................. 7
RETURN PROCESS ........................................................................................................................................................ 12
CANONICAL XML STRUCTURE ........................................................................................................................................ 15

THIRD PARTY INTEGRATION USER AND ROLES..................................................................................................... 16

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
2
REVISION HISTORY

This document will continue to evolve as existing sections change and new information is added. All updates are
logged below:

Data Version Description Delivery by Included in

Standalone Patchset

28-OCT-2020 1 Document creation - Draft

20-NOV-2020 2 Topic Send Process has description how to execute BI
Extractor using the Input Parameters available
07-Dec-2020 3 Publish version
08-Dec-2020 4 Typo fixes
23-Mar-2021 5 Typo fix
13-May-2021 6 Typo fixes
08-Jun-2021 7 Change guide name

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
3
INTRODUCTION TO XML CANONICAL FOR ELECTRONIC INVOICE – PAYABLES FOR
COSTA RICA

Latin America Cloud Local Solution (LACLS) for Costa Rica is a set of components that complements the core
functionalities providing new features used to meet legal requirements requested by government agencies.

For Costa Rica, the government agency responsible to establish the legal requirements is named MH (Ministerio de
Hacienda).

LACLS released “XML Canonical for Electronic Invoice - Payables” solution for Costa Rica providing BI Publisher
extractors to generate canonical XML files containing information about Oracle Payables (AP) Invoices eligible to
generate electronic fiscal document (EFD). The XML file can be consumed by the third party software providers to
create electronic fiscal document files to be sent to the government agency (MH).

In this manual you will find:

 How to call the Web Services to execute BI Publisher extractor;

 How to call the Web Services to update Oracle ERP Cloud;

 The Canonical XML Structure.

MACRO FLOW OVERVIEW

INTENDED AUDIENCE

Welcome to XML Canonical Electronic Invoice – Payables solution for Costa Rica. This guide is intended to be used
by the third party consultants and product analysts.

This guide assumes you have a working knowledge of the following:

• The principles and practices of your business area;

LACLS Costa Rica – XML for Electronic Invoice - Payables – Technical Implementation Guide
4
 • Computer desktop application usage and terminology;

 BIP architecture;

 Web Services concepts.

APPLICATIONS TECHNOLOGY

CONSUMPTION OF WEB SERVICES

Third party must be familiar with tools to consume SOAP and REST APIs Services from Oracle ERP Cloud.

XML FILES

Third party must be familiar XML structure.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
5
INTEGRATING WITH THIRD PARTY SOLUTION
The XML Canonical for Electronic Invoice – Payables solution for Costa Rica is composed by:
 “E-INVOICE AP Send” BI Publisher extractor
 WS SOAP API PublicReportService
 WS SOAP API ERPObjectDFFUpdateService
The third party must verify with Oracle ERP Cloud functional implementers if the BI Publisher extractor is installed
and the necessary access to run the BI Publisher extractors and the WS APIs.
The third party is responsible to:
 Request the Invoices that must be issued electronically;
 Decompose the file into individual Invoices;
 Transform, validate and format according to MH specifications;
 Include digital signature, when required;
 Control regarding which Invoice has already being processed and communicated with MH;
 Get MH response;
 Return information to Oracle ERP Cloud.
 New legal requirements established by MH that involves changes at canonical XML structure must be
informed to Oracle's LACLS Development team in advance.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
6
SEND PROCESS
The solution is based on Invoices created under Oracle Payables (AP) in the ERP Cloud for Suppliers from Simplified
Regime.
The solution is composed by BI Publishers that expose the AP information in a canonical XML and two Web Services
(WS): one to execute the BI extractors and other to return the information to AP.

To retrieve the eligible Payables Invoices execute the following steps:

1. Execute the “E-INVOICE AP Send” BI Publisher extractor to retrieve the invoices eligible to generate an
electronic fiscal document. An output XML file containing information about all retrieved invoices is
created.

Instruction:

Call the SOAP API “<Oracle ERP Cloud URL>/xmlpserver/services/PublicReportService?wsdl”

Attribute Value
Operation runReport
attributeFormat txt
reportAbsolutPath /Custom/Local Solution/CR/E-INVOICE/Process/E-INVOICE AP Send.xdo
Input Parameters Name Input Parameters Value Default Required
P_LEGAL_ENTITY_ID Put the Legal Entity Identifier No
P_TRX_NUM_FROM Put Start Transaction Number in order to run 1 No
extraction for a specifics transactions.
P_TRX_NUM_TO Put End Transaction Number in order to run 999999999 No
extraction for a specifics transactions.
P_DAYS It indicates the number of the days that process will 1 No
extract transactions. The default value 1, represents
that process will extract only transactions done in
the day. For example: if the value informed is 5, it

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
7
 means that process will retrieve transaction
completed in the last 5 days
P_ROWNUM_LIMIT It indicates the Maximum Limit to retrieve 100 No
transaction headers. It is required to avoid
generating payload too large, what can impact the
process
userID <Oracle ERP Third Party Integration User >
Password <Oracle ERP Third Party Integration User password>

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
8
 Example:

Response:

The “reportBytes” tag shows, in base64 format, payload related to all retrieved invoices to be processed.
This tag should be decoded to XML format.

2. For each retrieved Payables Invoice contained in the payload XML file, the EFD Status must be updated to
“SENT” indicating that the transaction has been already captured by the third party.

Instruction:

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
9
Call the SOAP API “<Oracle ERP Cloud URL>/fscmService/ErpObjectDFFUpdateService?wsdl” individually
for each invoice returned. Inform the attributes bellow:

Attribute Value
Operation updateDffEntityDetails
OperationMode SINGLE
EntityName Payables Invoice
ContextValue Value of tag <Invoice>/<Header>/<Integration>/<AttributeCategory>.
UserKeyA Value of tag <Invoice>/<Header>/<InvoiceNumber>
UserKeyB #NULL
UserKeyC #NULL
UserKeyD Value of tag <Invoice>/<Header>/<InvoiceId>
UserKeyE #NULL
UserKeyF #NULL
UserKeyG #NULL
UserKeyH #NULL
{“<dff EFD Status Attribute Name>” : “<EFD Status>”}

Where:
DFFAttributes
<dff EFD Status Attribute Name> = value of tag <Invoice>/<Header>/<Integration>/<EfdStatus>
<EFD Status> = string “SENT”

Example:

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
10
Response Example:
Take note that the result returned must be 1, which indicates the update was executed successfully.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
11
RETURN PROCESS

Once MH has answered, the third party needs to return these information to Oracle ERP Cloud. All information about
the electronic fiscal document issued is registered in Oracle ERP Cloud in Descriptive Flexfields (DFFs) according
LACLS setup definition in the header of the Payables Invoice.
DFF is a flexible data field that the Oracle customer can configure according their business needs without
programming. Note the DFF is used to enter additional information for which your Oracle Applications product has
not already provided a field.
Each company can create those DFFs in different attributes columns, called ATTRIBUTE<number>, according with
their availability. So, when the Return process is performed, it is needed to understand the mapping between
column attribute names and the set of information required.
The return flow will need to update a few DFFs, since they hold the following information:
 EFD Status:
 1 – Indicates the electronic fiscal document was processed and approved by MH;
 2 – Indicates the electronic fiscal document was processed and approved with warnings by MH;
 3 – Indicates the electronic fiscal document was processed and rejected by MH.
 SENT – Indicates the electronic fiscal document was captured by the third party.
 Null – Indicates electronic fiscal documents that needs to be sent to third party (new ones or the
fixed prior in ERROR ones).
 EFD Number – Number of Key assigned by MH.
 EFD Date – Date of Key generation.
 EFD Message – Relevant messages (optional).

In order to do the returning those information, the third party must call an API to update the electronic fiscal
document fields of the AP Invoice. This API requires as input parameters the field names and the content of each
field.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
12
RETURN EFD INFORMATION TO ORACLE ERP CLOUD

Once the mapping of attributes is known (Integration group), the electronic voucher information of the transaction
should be updated according to the returned information from MH.

Instruction:

Call SOAP API “<Oracle ERP Cloud URL>/fscmService/ErpObjectDFFUpdateService?wsdl”

Attribute Value
Operation updateDffEntityDetails
OperationMode SINGLE
EntityName Payables Invoice
ContextValue
Value of tag <Invoice>/<Header>/<Integration>/<AttributeCategory>.
UserKeyA Value of tag <Invoice>/<Header>/<InvoiceNumber>

UserKeyB #NULL
UserKeyC #NULL
UserKeyD This information is available in the tag <Invoice>/<Header>/<InvoiceId>
UserKeyE #NULL
UserKeyF #NULL
UserKeyG #NULL
UserKeyH #NULL
DFFAttributes {“<dff EFD Status Attribute Name >” : “<EFD Status>” , ”<dff EFD Number Attribute Name>”:
“<Key Number>” , “<dff EFD Date Attribute Name>”: “<Key Date>” , “<dff EFD Message
Attribute Name>”: “<Message>”}

Where:
<dff EFD Status Attribute Name> = value of tag
<Invoice>/<Header>/<Integration>/<EfdStatus>
<EFD Status> = string “1” (if EFD was approved), ‘3” (for rejected EFDs) or “2” (for approved
EFDs with warnings)
<dff EFD Number Attribute Name> = value of tag
<Invoice>/<Header>/<Integration>/<EfdKeyNumber>
<Key number> = Key Number retrieved by MH
<dff EFD Date Attribute Name> = value of tag
<Invoice>/<Header>/<Integration>/<EfdKeyDate>
<Key Date> = Date of Key retrieved by MH
<dff EFD Message Attribute Name> = value of tag
<Invoice>/<Header>/<Integration>/<EfdMessage>
<dff EFD Message> = relevant message (optional).

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
13
Example:

Important: The Response result must be 1, which indicates the update was executed successfully.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
14
CANONICAL XML STRUCTURE

To understand the structure and field mapping of the XML files generated by the Send and Return processes, please
verify the mapping file “Costa Rica XML Canonical Mapping for Electronic Invoice de Compra.xlsx”.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
15
THIRD PARTY INTEGRATION USER AND ROLES
It is mandatory to have a user in Oracle ERP Cloud to allow third party execute:

 WS responsible to execute the BI Publisher;

 WS responsible to update the DFFs.

We recommend be created a specific user to be used as “ERP Third Party Integration User” instead of use a regular
natural person user.

Following the recommendation for Roles:

Job Roles

 Financial Integration Specialist

 Integration Specialist
 BI Consumer Role
 Rest API Extract Privilege

After assign the roles to the third party Integration User, execute the following processes:

 Import User and Role Application Security Data

 Retrieve Latest LDAP Changes

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
16
Copyright © 2021, Oracle and/or its affiliates. All rights reserved.

This document is provided for information purposes only, and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject
to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose.
We specifically disclaim any liability with respect to this document, and no contractual obligations are formed either directly or indirectly by this document. This document may not
be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of
SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered
trademark of The Open Group.

LACLS Costa Rica – XML Canonical for Electronic Invoice - Payables – Technical Implementation Guide
17