rom1 - revenue commissionersrospublictest.ros.ie/schemas/rom1/v1/rom1_third... · revenue online...

Revenue Online Services ROM1 Schema Notes

of 40

Revenue Online Services

Schema Notes

ROM1

Last Updated 23/02/2015

Document Version 1.9


of 40

CONTENTS

Contents ................................................................................................................................................................................. 2 0 Document Information .................................................................................................................................................... 3

0.1 Synopsis ................................................................................................................................................................. 3 0.2 Change History ...................................................................................................................................................... 3 0.3 Abbreviations used in this Document ..................................................................................................................... 3 0.4 Additional Information ............................................................................................................................................ 4

1 Schema Overview .......................................................................................................................................................... 5 1.1 Supported Functions .............................................................................................................................................. 5 1.2 Schemas ................................................................................................................................................................ 5 1.3 Business Overview ................................................................................................................................................. 5

1.3.1 Return of Oil Movement Processes ................................................................................................................ 5 2 SUBMIT .......................................................................................................................................................................... 6

2.1 ROM1 Request....................................................................................................................................................... 6 2.2 ROM1SubmissionResponse .................................................................................................................................. 8

3 ROM1 Types .................................................................................................................................................................. 9 3.1 GeneralDetails Type .............................................................................................................................................. 9

3.1.1 Declarant Type ............................................................................................................................................... 9 3.1.2 Type ............................................................................................................................................................. 10

3.2 ProductBalances Type ......................................................................................................................................... 11 3.2.1 ProductBalance Type ................................................................................................................................... 11

3.3 InwardMovements Type ....................................................................................................................................... 13 3.3.1 SupplierRecord Type.................................................................................................................................... 13

3.4 OutwardMovements Type .................................................................................................................................... 15 3.4.1 NonTradeAggType Type .............................................................................................................................. 16 3.4.2 NonTradeCustomerRecord Type ................................................................................................................. 17 3.4.3 NonTraderType Type ................................................................................................................................... 17 3.4.4 NonTraderOutOfStateType Type ................................................................................................................. 18 3.4.5 NonTradeLineItemType Type ....................................................................................................................... 19 3.4.6 TradeCustomerRecord Type ........................................................................................................................ 20

3.5 ROM1 Common Types ......................................................................................................................................... 21 3.5.1 Shipment ...................................................................................................................................................... 21 3.5.2 TraderType ................................................................................................................................................... 22 3.5.3 UnlicencedTraderGroup ............................................................................................................................... 22 3.5.4 TraderOutOfStateType ................................................................................................................................. 23 3.5.5 LineItemTransType ...................................................................................................................................... 24 3.5.6 TaxRefGroup ................................................................................................................................................ 24 3.5.7 OutOfStateTaxRefGroup Type ..................................................................................................................... 25 3.5.8 LineItemType ............................................................................................................................................... 25 3.5.9 CommonNameAddressGroup Type ............................................................................................................. 26

Appendix 1 – ROM1 Types .................................................................................................................................................. 27 Enumerated Types ........................................................................................................................................................... 27 Simple Types ................................................................................................................................................................... 28

Appendix 2 – ROS Common Types ..................................................................................................................................... 30 Enumerated Types ........................................................................................................................................................... 30

Appendix 3 – Error Messages .............................................................................................................................................. 31 Appendix 4 – Product Balances ........................................................................................................................................... 33 Appendix 5 - Sample Requests............................................................................................................................................ 34

Authorised Warehousekeeper ......................................................................................................................................... 34 Distributor ......................................................................................................................................................................... 36 Forecourt Retailer ............................................................................................................................................................ 39


of 40

0 DOCUMENT INFORMATION

0.1 Synopsis

This document contains all the validation rules, which must be passed to enable a successful upload onto ROS for ROM1 return.

This is a draft version and may be subject to further changes.

0.2 Change History

Table 1: Change History

Version

Number

Section Affected Change Description Date

1.0 Initial Revision 10/07/2012

1.1 Section 3.4.1, 3.4.5, Appendix 1

Replace positive3 simple type with positive4 to represent a range 1-9999 for NumDeliveries, NumCustomers elements

04/09/2012

1.2 Add Section 2.2 Add ROM1SubmissionResponse element 24/09/2012

1.3 Table 15, 19, 25, 31, 38 Clarification to Produce Names (DERV ) updated to (DERV

- ROAD DIESEL) and (ULTRA_LOW_SULPHER) updated to (ULTRA_LOW_SULPHER_MARKED_GAS_OIL)

06/11/2012

1.4 Appendix 1 – Table 33 Update CountyType list 29/11/2012

1.5 Tables 23,24,27

Table 25

Clarification regarding Tax numbers.

Removal of “Country” under the LineItemTransType. 30/11/2012

1.6 Table 21

Table14

Table 8

Updated description of SAD and eAD. Update to the maximum number of NonTradeCustomerRecord. Update description of AutoFuelLicence and MarkedFuelLicence.

07/12/2012

1.7 3.3, 3.4

3.3.1

3.4.6

Nil Declarations added to Inward Movements and Outward Movements Specify that In State supplier must use Excise Licence number. Specify that In State customer must use Excise Licence number.

30/10/2014

1.8

2.5 – Table 5 Removed instruction to mark Forecourt Retailer outward movements as Nil Declaration. A value of either ‘true’ or ‘false’ is acceptable.

20/01/2015

1.9 Table 33 Updated incorrect county codes from version 1.8 Updated text description for InNilDeclaration and OutNilDeclaration

23/02/2015

0.3 Abbreviations used in this Document

Abbreviation Description

ROM1 Return of Oil Movement

XML eXtensible Mark-up Language

eAD Electronic Administrative Document

SAD Single Administrative Document


of 40

0.4 Additional Information

Information on existing ROS 3rd

party webservices is available here.

http://www.ros.ie/PublisherServlet/info/wsindex


of 40

1 SCHEMA OVERVIEW

This document contains the element definitions, field & cross-field dependency rules for the Revenue ROM1 schema. The element descriptions include the following:

Name

Type

Required (in the request)

Description.

o Required data format.

o Restricted data values where appropriate.

o Maximum and minimum values where applicable.

o Dependent elements – other elements that are optional but required in certain circumstances if other elements are not provided.

The element rules must be fulfilled for Revenue to accept and process the request.

1.1 Supported Functions

The following functions are supported using the ROM1 schema. These map to ROM1 business processes as outlined in Section 2 below.

Submit ROM1 Return

1.2 Schemas

There is one primary schema containing definitions for ROM1 requests and responses. There are also a number of supporting schemas that have custom types defined. Table 2 below outlines details of these schemas.

Table 3 ROM1 Schemas

Name File Namespace

Prefix

New or

Modified Reference

ROM1 Requests & Responses

schema.xsd N/A New Section 2

ROS Types rostypes/schema.xsd ros: Existing Appendix 2

The new and modified schemas will be made available on the ROS website as part of the ROM1 software release.

1.3 Business Overview

1.3.1 Return of Oil Movement Processes

1.3.1.1 Submit ROM1 Return

Third parties can submit a ROM1 Return through ROS. Only one ROM1 return can be included in a single request. The information that needs to be submitted for each Return is dependant on a number of factors. These include whether the Return is for an Auto-Fuel licence, Marked Fuel licence, or both, whether the trader type is an Authorised Warehousekeeper, Distributor or Forecourt Retailer and whether Suppliers/Customers Excise Licence numbers are known. Full details on the validation rules can be found in Section 3. Please also note the following points in relation to submitting returns:

Only one ROM1 Return can be made for an excise licence number combination (Auto-Fuel and/or Marked Fuel) in any given filing period.

To notify Revenue of a ROM1 Return, a ROM1 request needs to be submitted.

If the ROM1 submission is unsuccessful, i.e. the submission fails validation, a list of Errors will be returned. See Appendix 3 for more details on error messages. Please note that if validation fails for any of the submitted data then the entire submission will fail and the ROM1 will not be processed. The validation error needs to be resolved and the ROM1 re-submitted.


of 40

2 SUBMIT

2.1 ROM1 Request

Figure 1 ROM1 request

A ROM1 request contains all of the information required to submit a ROM1 Return to Revenue. The request contains a number of mandatory and optional elements. Some fields may be deemed mandatory/optional based on certain conditions (i.e. the Trader Type of the declarant, or the type of Excise Licence that the Return is being filed for). These conditions will be clearly indicated in the field description. The attributes/elements of a ROM1 Request are listed below.

Table 4 ROM1 request attributes

Name Type Minimum

Value/Length

Maximu

m Value

Required

(Y/N) Description / Validation

Unit

Text Characters Y The unit of volume for mineral oil within the Return.

Can be either litre or hectolitre.

Warehousekeepers, Distributors and Forecourt Retailers submit returns in litres.

See Appendix 1 for more detail

formversion Numeric 1 1 Y Version of the form

Form version must be 1

language Text Character 1 1 Y The language used in the form.

Can be set to E (English) or G (Gaelige)


product Text Characters 1 20 Y The name of the software/software company used to generate the return.

Table 5 ROM1 request elements

Name Type Required

(Y/N/C) Description / Validation

GeneralDetails

GeneralDetails Y General details for the submission. This includes the declarants excise licence number(s), the type of trader they are, and the filing period associated with the Return.

See Section 3.1 below for details.

ProductBalances ProductBalances Y Contains a list of balances for the product types associated


of 40

Name Type Required


with the Return. Balances represent the opening and closing stock balances for oil products within a monthly return period.

Product types included in this list are dependant on the type of excise licence number (Auto-Fuel or Marked Fuel) and trader type. The maximum number of product balances that can be associated with a Return is 11.

See Appendix 4 for more details.

InwardMovements InwardMovements Y A list of inward movements associated with the return.

See Section 3.3 below for details.

OutwardMovements OutwardMovements C Conditional

Required when submitting a return as Authorised Warehousekeeper or Distributor.

Not required when submitting a return as a Forecourt Retailer .


of 40

2.2 ROM1SubmissionResponse

Figure 2 ROM1SubmissionResponse

A ROM1SubmissionResponse contains the response from Revenue to a ROM1 request. This is applicable only when submitting a ROM1 Return via web services. In the case of a successful ROM1 Return, the response will contain the acknowledgement number associated with the submission. In the case of an unsuccessful ROM1 Return the response will contain one or more validation errors.

Table 6 ROM1SubmissionResponse elements

Name Type Required


SubmissionError

ErrorMessage C List of validation errors

AcknowledgementNumber ros:string20 C Acknowledgement number associated with the Return


of 40

3 ROM1 TYPES

3.1 GeneralDetails Type

Figure 3 GeneralDetails Type

The GeneralDetails Type contains details on the declarant who is filing the Return and the period of the Return.

Table 7 GeneralDetails Elements

Name Type Required

(Y/N)

Description / Validation

Declarant Declarant Y Declarant information including excise licence number(s), and trader type

Period dateMMYY Y The filing period.

The format of the monthly filing period is MM/YYYY i.e. for February 2013 value would be 02/2013

Date cannot be a filing period in the future.

3.1.1 Declarant Type

Figure 4 Declarant Type

The Declarant Type contains details on the entity that is making the Return. This includes details on the excise licence number(s) associated with the return and the trader type of the declarant.

Table 8 Declarant Elements

Name Type Required


AutoFuelLicence ExciseLicenceType C Required when trading in Auto-Fuel products.

AutoFuelLicence must be in the format [a-zA-Z0-9]{5,14}

At least one AutoFuelLicence or MarkedFuelLicence must be included on a return.

For a full list of Auto-Fuel products see Appendix 1.

MarkedFuelLicence ExciseLicenceType C Required when trading in Marked Fuel products.

MarkedFuelLicence must be in the format [a-zA-Z0-9]{5,14}


of 40

Name Type Required


At least one AutoFuelLicence or MarkedFuelLicence must be included on a return.

For a full list of Marked Fuel products see Appendix 1.

Type Type Y The Trader Type.

Trader type on a Return can be one or more of the following:

AuthWarehouseKeeper

Distributor

ForecourtRetailer

All Trader Type’s must be included in the request. At least one trader type must be set to true.

3.1.2 Type

Figure 5 Type Elements

Type holds the Trader Type details for a Return. The Trader Type may be set to one or more of the following types – AuthWarehouseKeeper, Distributor, ForecourtRetailer.

Table 9 Type Elements

Name Type Required


AuthWarehouseKeeper ros:boolean Y Flag to indicate if Declarant is an Authorised Warehousekeeper.

Must be set to either true or false

Distributor ros:boolean Y Flag to indicate if Declarant is a Distributor.


ForecourtRetailer ros:boolean Y Flag to indicate if Declarant is a Forecourt Retailer.



of 40

3.2 ProductBalances Type

Figure 6 ProductBalances

The ProductBalances Type contains a list of applicable product balances for a Return. A product balance represents the opening and closing stock balances for an oil product within a return period.

Table 10 ProductBalances Elements

Name Type Require

d (Y/N) Description / Validation

ProductBalance ProductBalance Y List of Product Balances for the Return.

Products to be declared on a Return are dependant on the Excise Licence Number(s) included on the Return (Auto-Fuel or Marked Fuel) and the Trader Type of the Declarant.

See Appendix 4 for a list of applicable Product Types per Trader Type/Excise Licence Type

3.2.1 ProductBalance Type

Figure 7 ProductBalance

The ProductBalance Type holds information on the oil product type, the opening balance, closing balance and optional Sales amounts if the trader type is a Forecourt Retailer. Product balance information for every oil product type that the declarant trades in should be included, up to a maximum of 11 product types. Each oil product type may only be included once.

Table 11 ProductBalance Elements

Name Type Required


Product AllProductType Y The type of product that this ProductBalance refers to.


of 40

Name Type Required



OpeningBalance BalanceQuantityType Y The opening balance for the inventory of oil product

An integer between 0 and 99999999

ClosingBalance BalanceQuantityType Y The closing balance for the inventory of oil product


Sales BalanceQuantityType N

(Y if Trader Type is Forecourt Retailer)

The total sales of the product


Required for Forecourt Retailers Only


of 40

3.3 InwardMovements Type

Figure 8 InwardMovements Type

The InwardMovements Type represents all inward movements on a ROM1 Return. Inward Movements may include

details relating to the importation of oil products via authorised shipments, or details relating to oil purchased through suppliers.

Table 12 InwardMovements Elements

Name Type Require


Shipment Shipment N A list of inward shipments of oil product. An Inward Movement can contain 0-50 Shipments

Only applicable to Authorised Warehousekeepers

See Common ROM1 Types for more details.

SupplierRecord SupplierRecord N A list of inward deliveries of oil product. An Inward Movement can contain 0-50 SupplierRecords.

Applicable to Authorised Warehousekeepers, Distributors and Forecourt Retailers.

InNilDeclaration ros:boolean N Nil Declaration checkbox for Inward Movements. To be selected when making a nil declaration.

If SupplierRecord is empty then InNilDeclaration must be true.

3.3.1 SupplierRecord Type

Figure 9 SupplierRecord Type

The SupplierRecord is a record of inward movements of oil product for a particular supplier. This will contain details of the Supplier (In State or Out of State), and the detail of the oil movements. For In State movements the excise licence number must be provided.


of 40

Table 13 SupplierRecord Elements

Name Type Required


Supplier rom1:TraderType Y Represents a Supplier within the State.

Excise Licence number must be provided for in state movements.

Only one of a Supplier or an OutOfStateSupplier can be included on a SupplierRecord.


OutOfStateSupplier rom1: TraderOutOfStateType

Y The OutOfStateSupplier for this SupplierRecord.

This represents a Supplier that trades outside of Ireland.

Only one of a Supplier or an OutOfStateSupplier can be included on a SupplierRecord


DetailedMovement rom1: LineItemTransType

N The details of the oil movement.

Required when the oil product is one of the Controlled Oil Products.

Contains extra detail regarding the date or invoice number of the oil movement.

See LineItemTransType for more details.

Movement rom1:LineItemType N The details of the oil movement.

Required when the oil product is one of the Non Controlled Oil Products.

See LineItemType for more details.


of 40

3.4 OutwardMovements Type

Figure 10 OutwardMovements

The OutwardMovements Type represents all outgoing oil movements for a Return period. This is only applicable to Authorised Warehousekeeper and Distributor Trader types. Outward movements can include deliveries to Non-Oil Traders, Mineral Oil Traders, and additionally in the case of Authorised Warehousekeepers, shipments of oil product to other warehouses within Ireland and abroad.

Table 14 OutwardMovements Elements

Name Type Required


BelowThresholdRecord rom1:NonTradeAggType

N Details of outward movements to non-oil traders whose aggregate deliveries do not exceed 2,000 litres a month.

BelowThresholdRecord are aggregated based on oil product type.

Up to 11 BelowThresholdRecord’s can be included in an OutwardMovement, one for each oil product type.

NonTradeCustomerRecord rom1: NonTradeCustomerRecord

N Details of outward movements to non-oil traders whose aggregate deliveries exceed 2,000 litres a month.

Up to 1000 records can be included in an OutwardMovement.

(Note: This is not enforced by the schema but by business validation)

TradeCustomerRecord rom1: TradeCustomerRecord

N Details of outward movements of oil product to mineral oil traders.

Up to 250 records can be included in an OutwardMovement

Shipment rom1:Shipment N Details of outward shipments to warehouses within Ireland and abroad.

An OutwardMovement can contain 0-50 Shipments

Only applicable to Authorised Warehousekeeper trader type

OutNilDeclaration ros:boolean N Nil Declaration checkbox for Outward Movements to mineral oil traders. To be selected when making a nil declaration for movements to mineral oil traders.

If TradeCustomerRecord is empty then OutNilDeclaration must be true.


of 40

3.4.1 NonTradeAggType Type

Figure 11 NonTradeAggType

The NonTradeAggType Type details the outward movements to non-oil traders whose aggregate deliveries do not exceed 2,000 litres a month

Table 15 NonTradeAggType Elements

Name Type Required


Product rom1:AllProductType N The oil product type.

Allowed values include

1 (PETROL),

2 (AVIATION_GASOLINE),

3 (DERV - ROAD DIESEL),

4 (HEAVY_AIR_NAV),

5 (ULTRA_LOW_SULPHER_MARKED_GAS_OIL),

6 (MARKED_GAS_OIL),

7 (KEROSENE)

8 (SUB_FUEL_PRO_PETROL),

9 (SUB_FUEL_PRO_DIESEL),

10 (LPG_PROPELLANT),

11 (LPG_OTHER)


Quantity rom1: MovementQuantityType

N The quantity of oil product in litres

Integer between 1 and 99999999

NumCustomers rom1:positive4 N Number of distinct customers


NumDeliveries rom1: positive4 N Number of distinct deliveries across all customers



of 40

3.4.2 NonTradeCustomerRecord Type

Figure 12 NonTradeCustomerRecord

The NonTradeCustomerRecord Type details the outward movements to non-oil traders whose aggregate deliveries exceed 2,000 litres a month.

Table 16 NonTradeCustomerRecord Elements

Name Type Required


Customer rom1:NonTraderType Y The customer for this outward movement of oil product

Only one of a Customer or OutOfStateCustomer can be included

OutOfStateCustomer rom1: NonTraderOutOfStateType

Y The out of state customer for this outward movement of oil product


Movement rom1:NonTradeLineItemType

Y Details of outward movements of oil product to non mineral oil traders.

3.4.3 NonTraderType Type

Figure 13 NonTraderType

The NonTraderType Type contains the details of a Non Mineral Oil Trader:

Table 17 NonTraderType Elements

Name Type Require


TaxRefGroup rom1:TaxRefGroup N Tax Reference details for non mineral oil trader

See ROM1 Common Types for more detail

CommonNameAddressGroup

rom1: CommonNameAddressGroup

Y Name and Address of the non mineral oil trader


County rom1:CountyType Y The county of the Trader.

See Appendix 1


of 40

3.4.4 NonTraderOutOfStateType Type

Figure 14 NonTraderOutOfStateType

The NonTraderOutOfStateType contains the details of an Out of State Non Mineral Oil Trader:

Table 18 NonTraderOutOfStateType Elements

Name Type Required


OutOfStateTaxRefGroup rom1: OutOfStateTaxRefGroup

N Foreign tax reference details for the Out of State Non Mineral Oil Trader



Y Name and Address of the Out of State Non Mineral Oil Trader


Postcode rom1:alpha12All Y Alphanumeric characters in the format

[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*

Must be between 1 and 12 characters in length

Country rom1:alpha70All Y The country of the Trader

Minimum length is 1

Maximum length is 70


of 40

3.4.5 NonTradeLineItemType Type

Figure 15 NonTradeLineItemType

The NonTradeLineItemType describes a line item within an oil movement to a Non-Oil Trader.

Table 19 NonTradeLineItemType Elements

Name Type Required


Product rom1: AllProductType Y The oil product type.


1 (PETROL),



4 (HEAVY_AIR_NAV),


6 (MARKED_GAS_OIL),

7 (KEROSENE)




11 (LPG_OTHER)


NumDeliveries rom1: positive4 Y Number of distinct deliveries



Y The quantity of oil product in litres or hectolitres



of 40

3.4.6 TradeCustomerRecord Type

Figure 16 TradeCustomerRecord

The TradeCustomerRecord contains details of outward movements of oil product to a Mineral Oil Trader. For In State movements the excise licence number must be provided.

Table 20 TradeCustomerRecord Elements

Name Type Required


Customer rom1:TraderType Y The customer for this outward movement of oil product

Excise Licence number must be provided for in state movements.



OutOfStateCustomer rom1: TraderOutOfStateType

Y The out of state customer for this outward movement of oil product



DetailedMovement rom1:LineItemTransType

N Details of outward movements of oil product to Mineral Oil Traders.

Required when the oil product is one of the Controlled Oil Products.

Contains extra detail regarding the date or invoice number of the oil movement.


Movement rom1:LineItemType N Details of outward movements of oil product to Mineral Oil Traders.

Required when the oil product is one of the Non Controlled Oil Products.



of 40

3.5 ROM1 Common Types

The following are elements that are common across the ROM1 Request.

3.5.1 Shipment

Figure 17 Shipment Type

A Shipment contains the Product, Date and Quantity as well as an Identifier for the Shipment. Shipments may be included in an inward or outward movement.

A Shipment is applicable to an Authorised Warehousekeeper trader type only.

Table 21 Shipment Elements

Name Type Required


Product rom1:AllProductType Y The type of product that this Shipment refers to.


Date ros:Date Y The date of the Shipment.

Field cannot be left blank.

Format of the date must be: DD/MM/YYYY

Date must not be earlier than today

Date must not be earlier than 01/01/1900

Quantity rom1:MovementQuantityType Y The quantity of oil product in litres

Field cannot be left blank.


SAD rom1:SAD C The SAD number.

Only one of a SAD or an eAD can be included on a Shipment.

SAD number should be in the format

[0-9]{2}[A-Z]{2}[A-Z0-9]{13}[0-9] or

[0-9]{2}[A-Z]{2}[A-Z0-9]{16}[0-9]

eAD rom1:eAD C The eAD number.

Only one of a SAD or an eAD can be included on a Shipment.

eAD number should be in the format

[0-9]{2}[a-zA-Z]{2}[a-zA-Z0-9]{16}[0-9]


of 40

3.5.2 TraderType

Figure 18 TraderType

The TraderType contains details of a Mineral Oil Trader:

Table 22 Supplier Elements

Name Type Required


Licence rom1:ExciseLicenceType Y The Excise Licence for this TraderType.

This should always be populated, as declarants should only trade with oil traders whose excise licence number is known to them.

It is the responsibility of the declarant to provide the excise licence number for each oil trader that they trade with.

Only one of Licence or UnlicencedTraderGroup can be included on a TraderType.

Licence should be in the format [a-zA-Z0-9]{5,14}

UnlicencedTraderGroup rom1: UnlicencedTraderGroup

Y Only to be used in exceptional circumstances when the Excise Licence Number of the Trader is not available. This will contain the Trader’s tax number, name, and address.

Only one of Licence or UnlicencedTraderGroup can be included on a TraderType


3.5.3 UnlicencedTraderGroup

Figure 19 UnlicensedTraderGroup

The UnlicencedTraderGroup Type contains details of a Mineral Oil Trader when the excise licence number is not known. This will contain a Trader’s tax number, name and address:

Table 23 UnlicencedTraderGroup Elements

Name Type Required


TaxType rom1:taxType Y The tax type of the Trader.

This will be VAT


of 40

Name Type Required


TaxRegistrationNumber ros:registration Y The tax registration number of the Trader


CommonNameAddressGroup rom1: CommonNameAddressGroup

Y Name and Address of the Trader


County rom1:CountyType Y The county of the Trader


3.5.4 TraderOutOfStateType

Figure 20 TraderOutOfStateType

The TraderOutOfStateType contains details of an Out Of State Mineral Oil Trader. This captures details of a trader who trades outside of Ireland.

Table 24 TraderOutOfStateType Elements

Name Type Required


TaxType rom1:taxType Y The tax type of the Trader.

This will be VAT

TaxRegistrationNumber rom1: alpha12AllRos

Y The tax registration number of the Trader




Y Name and Address of the Trader


Postcode rom1:alpha12All Y The postcode of the Trader

Should only contain the characters

Minimum length is 1


Country rom1:alpha70All Y The country of the Trader

Minimum length is 1



of 40

3.5.5 LineItemTransType

Figure 21 LineItemTransType

The LineItemTransType contains details of an inward or outward oil movement for controlled products on a per delivery basis. This includes the date of the movement, the oil product type, the quantity and the invoice for the movement.

Table 25 LineItemTransType Elements

Name Type Required


Date ros:Date Y The date of the movement

Format is DD/MM/YYYY

Product rom1: ControlledProductType

Y The oil product type.




6 (MARKED_GAS_OIL),

7 (KEROSENE)


Y The quantity of oil product in litres


Invoice rom1:alpha12All Y Invoice number associated with the movement of oil product.

Minimum length is 1


3.5.6 TaxRefGroup

Figure 22 TaxRefGroup

The TaxRefGroup Type contains the tax reference details for a Non Mineral Oil Trader

Table 26 TaxRefGroup Elements

Name Type Required



of 40

Name Type Required


TaxType rom1:TaxType Y The tax type.

This will be VAT, IT or CT.


TaxReferenceNumber ros:registration Y Tax registration Number

See Appendix 1for more detail

3.5.7 OutOfStateTaxRefGroup Type

Figure 23 OutOfStateTaxRefGroup

The OutOfStateTaxRefGroup contains the tax reference details for an Out Of State Non Mineral Oil Trader.

Table 27 OutOfStateTaxRefGroup Elements

Name Type Required


TaxType rom1:TaxType Y The tax type.

This will be VAT.


TaxReferenceNumber rom1: alpha12AllRos

Y Tax registration Number


3.5.8 LineItemType

Figure 24 LineItemType

The LineItemType contains details of an inward or outward oil movement. This includes the oil product type, and the quantity of the movement.

Table 28 LineItemType Elements

Name Type Required


Product rom1: NonControlledProductType

Y The oil product type.



of 40

Name Type Required


1 (PETROL),


4 (HEAVY_AIR_NAV),




11 (LPG_OTHER)


Y The quantity of oil product in litres or hectolitres


3.5.9 CommonNameAddressGroup Type

Figure 25 CommonNameAddressGroup

The CommonNameAddressGroup Type contains the name and address of a Trader:

Table 29 CommonNameAddressGroup Elements

Name Type Required


Name rom1:alpha70All Y The name of the entity.

Minimum length is 1


Should only contain characters:

[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*

AddressLine1 rom1:alpha70All Y Address line 1

Minimum length is 1



[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*

AddresLine2 rom1:alpha70All Y Address line 2

Minimum length is 1



[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*

AddressLine3 rom1:alpha70All N Address line 3

Minimum length is 1



[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*


of 40

APPENDIX 1 – ROM1 TYPES

Enumerated Types

Table 30 UnitType

Input Value

Litres litre

Hectolitre hectolitre

Table 31 ControlledProductType

Input Value

DERV - ROAD DIESEL 3

ULTRA_LOW_SULPHER_MARKED_GAS_OIL 5

MARKED_GAS_OIL 6

KEROSENE 7

Table 32 NonControlledProductType

Input Value

PETROL 1

AVIATION_GASOLINE 2

HEAVY_AIR_NAV 4

SUB_FUEL_PRO_PETROL 8

SUB_FUEL_PRO_DIESEL 9

LPG_PROPELLANT 10

LPG_OTHER 11

Table 33 CountyType

Input Value

CORK 1

KERRY 2

CARLOW 3

CAVAN 4

CLARE 5

DONEGAL 6

DUBLIN 7

GALWAY 8

KILDARE 9

KILKENNY 10

LEITRIM 11

LOAIS 12

LIMERICK 13

LONGFORD 14

LOUTH 15

MAYO 16

MEATH 17

MONAGHAN 18

OFFALY 19


of 40

Input Value

ROSCOMMON 20

SLIGO 21

TIPPERARY 22

WATERFORD 23

WESTMEATH 24

WEXFORD 25

WICKLOW 26

Table 34 TaxType

Input Value

VAT VAT

Income Tax IT

Corporation Tax CT

Simple Types

There are a number of simple types used in the ROM1 schema, to represent string, integers and decimal values. See the table below for details on the simple types.

Table 35 Simple Element Type Descriptions

Element Restriction

ros:language ROS Enumerated Type. See Appendix 2

ros:string20 String with a maximum length of 20

ros:boolean ROS Enumerated Type. See Appendix 2

ros:date Date in format DD/MM/YYYY

ros:alphaAll


[a-zA-Z 1234567890 /\-'@;:£€ \. \* \( \) &áéíóúÁÉÍÓÚ]*

ros:positive8 Integer between 0 and 99999999

ros:registration

The Tax Reference Number.

Format of the Tax Reference Number must be 7 digits followed by a check character between ‘a’ and ‘w’.

The check character must be valid after the standard PPSN weighted addition and modulus 23-algorithm check.

ExciseLicenceType String in the format [a-zA-Z0-9]{5,14}

dateMMYY Date in format MM/YYYY

AllProductType

List of all oil product types. This includes products applicable to an Auto-Fuel Licence (NonControlledProductType) and products applicable to Marked Fuel Licence (ControlledProductType)

See Enumerated Types

positive4 Integer between 1 and 9999

alphaESI


[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*”

alpha12All


[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*”


alpha15


[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*”


alpha15_1


[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*”

Minumum length is 1


of 40


alpha70All


[a-zA-Z, 0-9ÁÉÍÓÚáéíóú\-/&\.\(\)'*]*”

Minimum length is 1


alpha12AllRos


[a-zA-Z 1234567890 /\-‘@;:£€ \. \* \( \) &áéíóúÁÉÍÓÚ]*

Minimum length is 1


BalanceQuantityType Integer between 0 and 99999999

MovementQuantityType Integer between 1 and 99999999

SAD

String in the format

[0-9]{2}[a-zA-Z0-9]{13}[0-9]

or

[0-9]{2}[a-zA-Z]{2}[a-zA-Z0-9]{13}[0-9]

eAD

String with a length of 21 in the format

0-9]{2}[a-zA-Z]{2}[a-zA-Z0-9]{16}[0-9]


of 40

APPENDIX 2 – ROS COMMON TYPES

Enumerated Types

Table 36 language

Input Value

English E

Gaeilge G

Table 37 boolean

Input Value

True true

False false


of 40

APPENDIX 3 – ERROR MESSAGES

The Third Party ROM1 service can respond with persistent business errors based on simple-field or cross-field validation of input or due to inconsistent data.

The following persistent business errors can be returned:

Please enter an Auto-Fuel License Number and/or a Marked Fuel License Number

An invalid month has been entered

An invalid year has been entered

Zero or greater is required

Cannot be greater than 99,999,999

Maximum value of 99999999 litres

Invalid eAD/SAD

Invalid date entered. Should be in the format dd/mm/yyyy

Date must be in the range of the filing period

Invalid number of litres entered

Too many inward shipments added. Max 250

Invalid premises type entered

Invalid product entered

Invalid Excise Licence number

Invalid licence type

Enter number between 1 and 1,000

Please select a product

Only 1 Line Item per product is allowed

The licence number you have entered is not valid. Please enter a valid licence number

At least one supplier must be added

Invalid VAT number

Invalid CT number

Invalid IT number

Invalid Tax Registration number

Invalid Tax Type

Invalid reference number entered

Maximum 70 characters in address fields allowed. Permitted characters are: a-z, A-Z, 0-9, Á, É, Í, Ó, Ú, á, é, í, ó, ú - / & . ( ) ' *

Maximum 70 characters in name field allowed. Permitted characters are: a-z, A-Z, 0-9, Á, É, Í, Ó, Ú, á, é, í, ó, ú - / & . ( ) ' *

Maximum 12 characters in postcode field allowed. Permitted characters are: a-z, A-Z, 0-9, Á, É, Í, Ó, Ú, á, é, í, ó, ú - / & . ( ) ' *

Maximum 70 characters in country field allowed. Permitted characters are: a-z, A-Z, 0-9, Á, É, Í, Ó, Ú, á, é, í, ó, ú - / & . ( ) ' *

Maximum 15 characters in invoice field allowed. Permitted characters are: a-z, A-Z, 0-9, Á, É, Í, Ó, Ú, á, é, í, ó, ú - / & . ( ) ' *

Please enter an amount greater than '0' and less than 100 million litres (whole number only)

A future dated return cannot be made


of 40

Date must not be later than today

This field is present, but can't be empty

Delete from here

This is a required field

A return for this period has already been submitted

You do not have permission to file for this licence number

Opening balance must be entered

Closing balance must be entered

Aggregate sales must be entered

Invalid details submitted for trader type indicated

Details on a product for which you do not have a licence have been entered

Balances must be entered on all products for which you hold a licence

Invalid details submitted for trader type indicated

Balance(s) for this product required

Invalid product submitted for declarant's license number

Invalid product type submitted for declarant's licence number

Maximum of 1,500 movements can be added

Maximum of 5,000 movements can be added

Maximum of 50 suppliers can be added

Maximum of 250 customers can be added

Maximum of 100 line items can be added

CustIdInternal or AgentIdInternal is required

Both CustIdInternal and AgentIdInternal are present. Please select one or the other


of 40

APPENDIX 4 – PRODUCT BALANCES

Table 38 Applicable Products per Trader/Excise Licence Type

Authorised Warehousekeeper

Distributor Forecourt Retailer

Product Type Auto-Fuel

Marked Fuel

Auto-Fuel

Marked Fuel

Auto-Fuel

Marked Fuel

PETROL X X X

AVIATION_GASOLINE X X

DERV - ROAD DIESEL X X X

HEAVY_AIR_NAV X X

ULTRA_LOW_SULPHER_MARKED_GAS_OIL X X X

MARKED_GAS_OIL X X X

KEROSENE X X X

SUB_FUEL_PRO_PETROL X X X

SUB_FUEL_PRO_DIESEL X X X

LPG_PROPELLANT X X X

LPG_OTHER X X


of 40

APPENDIX 5 - SAMPLE REQUESTS

The below requests represent an individual ROM1 return for the 3 different types of trader – Authorised Warehousekeeper, Distributor, and Forecourt Retailer. Please note the request below contain sample data and should be used for reference only.

Authorised Warehousekeeper

<?xml version="1.0" encoding="UTF-8"?>

<ROM1 xmlns="http://www.ros.ie/schemas/rom1/v1/" Unit="litre" formversion="1" language="E"

product="Software Provider">

<GeneralDetails>

<Declarant>

<AutoFuelLicence>1001763</AutoFuelLicence>

<MarkedFuelLicence>1001764</MarkedFuelLicence>

<Type>

<AuthWarehouseKeeper>true</AuthWarehouseKeeper>

<Distributor>false</Distributor>

<ForecourtRetailer>false</ForecourtRetailer>

</Type>

</Declarant>

<Period>5/2012</Period>

</GeneralDetails>

<ProductBalances>

<ProductBalance>

<Product>1</Product>

<OpeningBalance>10000</OpeningBalance>

<ClosingBalance>15000</ClosingBalance>

</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>


of 40

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

</ProductBalances>

<InwardMovements>

<Shipment>


<Date>01/05/2012</Date>

<Quantity>15000</Quantity>

<SAD>12IEDUEX1000000001</SAD>

</Shipment>

<InNilDeclaration>false</InNilDeclaration>

</InwardMovements>

<OutwardMovements>

<Shipment>


<Date>31/05/2012</Date>


<SAD>12IEDUEX1000000002</SAD>

</Shipment>

<OutNilDeclaration>false</OutNilDeclaration>

</OutwardMovements>

</ROM1>


of 40

Distributor




<GeneralDetails>

<Declarant>



<Type>

<AuthWarehouseKeeper>false</AuthWarehouseKeeper>

<Distributor>true</Distributor>

<ForecourtRetailer>false</ForecourtRetailer>

</Type>

</Declarant>


</GeneralDetails>

<ProductBalances>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>


of 40

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

<ProductBalance>




</ProductBalance>

</ProductBalances>

<InwardMovements>

<SupplierRecord>

<Supplier>

<Licence>1001111</Licence>

</Supplier>

<Movement>



</Movement>

<DetailedMovement>

<Date>02/05/2012</Date>



<Invoice>11111A</Invoice>

</DetailedMovement>

</SupplierRecord>


</InwardMovements>

<OutwardMovements>

<BelowThresholdRecord>



<NumCustomers>2</NumCustomers>

<NumDeliveries>4</NumDeliveries>

</BelowThresholdRecord>

<NonTradeCustomerRecord>

<Customer>

<TaxType>VAT</TaxType>

<TaxReferenceNumber>1234567T</TaxReferenceNumber>

<Name>Above Thres</Name>

<AddressLine1>a1</AddressLine1>

<AddressLine2>a2</AddressLine2>

<County>1</County>

</Customer>

<Movement>


<NumDeliveries>2</NumDeliveries>


</Movement>

</NonTradeCustomerRecord>

<TradeCustomerRecord>

<Customer>


</Customer>


of 40

<DetailedMovement>

<Date>30/05/2012</Date>



<Invoice>22222A</Invoice>

</DetailedMovement>

</TradeCustomerRecord>

<OutNilDeclaration>false</OutNilDeclaration>

</OutwardMovements>

</ROM1>


of 40

Forecourt Retailer




<GeneralDetails>

<Declarant>



<Type>

<AuthWarehouseKeeper>false</AuthWarehouseKeeper>

<Distributor>false</Distributor>

<ForecourtRetailer>true</ForecourtRetailer>

</Type>

</Declarant>


</GeneralDetails>

<ProductBalances>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

<ProductBalance>





of 40

<Sales>500</Sales>

</ProductBalance>

<ProductBalance>




<Sales>500</Sales>

</ProductBalance>

</ProductBalances>

<InwardMovements>

<SupplierRecord>

<Supplier>


</Supplier>

<Movement>



</Movement>

</SupplierRecord>


</InwardMovements>

<OutwardMovements>

<OutNilDeclaration>true</OutNilDeclaration> </OutwardMovements>

</ROM1>

rom1 - revenue commissionersrospublictest.ros.ie/schemas/rom1/v1/rom1_third... · revenue online...

Documents