Oracle Financials Cloud

Latin America Cloud Local Solution

Costa Rica

XML Canonical for Electronic

Invoice
Technical Implementation Guide

Version 6

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 Canonical for Electronic Invoice – Technical Installation Guide
1
TABLE OF CONTENTS
TABLE OF CONTENTS ..............................................................................................................................................2

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

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

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

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

SEND PROCESS.............................................................................................................................................................. 7
RETURN PROCESS ........................................................................................................................................................ 11
CANONICAL XML STRUCTURE ........................................................................................................................................ 14

THIRD PARTY INTEGRATION USER AND ROLES..................................................................................................... 15

LACLS Costa Rica – XML Canonical for Electronic Invoice – 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

19-NOV-2020 2 Include input parameters for Extractor BI
07-Dec-2020 3 Publishing
23-Mar-2021 4 Typo fix
13-May-2021 5 Typo fixes
08-Jun-2021 6 Change guide name

LACLS Costa Rica – XML Canonical for Electronic Invoice – Technical Implementation Guide
3
INTRODUCTION TO XML CANONICAL FOR ELECTRONIC INVOICE 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” solution for Costa Rica providing BI Publisher extractor to
generate canonical XML file containing information about Oracle Receivables (AR) transactions 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 LACLS XML Canonical for Electronic Invoice solution for Costa Rica. This guide is intended to be used
by the third party software provider 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 Canonical for Electronic Invoice – Technical Installation 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 – Technical Implementation Guide
5
INTEGRATING WITH THIRD PARTY SOLUTION
The XML Canonical for Electronic Invoice solution for Costa Rica is composed by:
 “E-INVOICE 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 extractor and the WS APIs.
The third party is responsible to:
 Request the transactions that must be issued electronically;
 Decompose the file into individual transaction;
 Transform, validate and format according to MH specifications;
 Include digital signature, when required;
 Control regarding which transaction 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 – Technical Implementation Guide
6
SEND PROCESS
The solution is based on transactions created under Oracle Receivables (AR) in the ERP Cloud.
The solution is composed by BI Publisher that expose the AR information in a canonical XML and two Web Services
(WS): one to execute the BI extractor and other to return the information to AR.

To retrieve the eligible Receivables transactions execute the following steps:

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

Instruction:

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

Attribute Value
Operation runReport
attributeFormat xml
reportAbsolutPath /Custom/Local Solution/CR/E-INVOICE/Process/E-INVOICE Send.xdo
userID <Oracle ERP Third Party Integration User >
password <Oracle ERP Third Party Integration User password>
Input Parameters Name Input Parameters Value Default Required
P_LEGAL_ENTITY_IDENTIFIER Put the Legal Entity Identifier Yes
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 8 Yes
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 – 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 – Technical Implementation Guide
8
 Example:

Response:

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

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

Instruction:

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

for each transaction returned. Inform the attributes bellow:

Attribute Value
Operation updateDffEntityDetails
OperationMode SINGLE
EntityName Receivables 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 EDF Status Attribute Name> = value of tag <Invoice>/<Header>/<Integration>/<EfdStatus>
<EFD Status> = string “SENT”

LACLS Costa Rica – XML Canonical for Electronic Invoice – Technical Implementation Guide
9
 Example:

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 – Technical Implementation Guide
10
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 Receivables transaction.
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 the DFFs, that hold the following information:
 EFD Status:
 APPROVED – Indicates the electronic fiscal document was processed and approved by MH;
 APPROVED WITH WARNING – Indicates the electronic fiscal document was processed and
approved with warnings by MH;
 ERROR – 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).
 REJECTED – Indicates the electronic fiscal document was rejected by MH.
 FIXED – Indicates electronic fiscal documents was in error and was fixed.
 PROCESSING – Indicates electronic fiscal documents was taken by third party and is processing for
MH.
 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 AR transaction. This API requires as input parameters the field names and the content of
each field.

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

Once the mapping of attributes is known (Integration group), the electronic fiscal document 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 Receivables 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> = Number of Key assigned by MH
<dff EFD Date Attribute Name> = value of tag
<Invoice>/<Header>/<Integration>/<EfdKeyDate>
<Key Date> = Date of Key generation
<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 – Technical Implementation Guide
12
Example:

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

LACLS Costa Rica – XML Canonical for Electronic Invoice – Technical Implementation Guide
13
CANONICAL XML STRUCTURE

To understand the structure and field mapping of the XML files generated by the Send process, please verify the
mapping file “Costa Rica XML Canonical Mapping for Electronic Invoice.xls”.

LACLS Costa Rica – XML Canonical for Electronic Invoice – Technical Implementation Guide
14
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 – Technical Implementation Guide
15
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 – Technical Implementation Guide
16