oracle.oci.oci_osp_gateway_invoice_facts – Fetches details about one or multiple Invoice resources in Oracle Cloud Infrastructure

Note

This plugin is part of the oracle.oci collection (version 4.14.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install oracle.oci.

To use it in a playbook, specify: oracle.oci.oci_osp_gateway_invoice_facts.

New in version 2.9.0: of oracle.oci

Synopsis

  • Fetches details about one or multiple Invoice resources in Oracle Cloud Infrastructure

  • Returns a list of invoices

  • If internal_invoice_id is specified, the details of a single Invoice will be returned.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter Choices/Defaults Comments
api_user
string
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_ID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See config_file_location). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_fingerprint
string
Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See config_file_location). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_key_file
string
Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See config_file_location). If the key is encrypted with a pass-phrase, the api_user_key_pass_phrase option must also be provided.
api_user_key_pass_phrase
string
Passphrase used by the key referenced in api_user_key_file, if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See config_file_location).
auth_purpose
string
    Choices:
  • service_principal
The auth purpose which can be used in conjunction with 'auth_type=instance_principal'. The default auth_purpose for instance_principal is None.
auth_type
string
    Choices:
  • api_key ←
  • instance_principal
  • instance_obo_user
  • resource_principal
The type of authentication to use for making API requests. By default auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
cert_bundle
string
The full path to a CA certificate bundle to be used for SSL verification. This will override the default CA certificate bundle. If not set, then the value of the OCI_ANSIBLE_CERT_BUNDLE variable, if any, is used.
compartment_id
string / required
The OCID of the compartment.
config_file_location
string
Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
config_profile_name
string
The profile to load from the config file referenced by config_file_location. If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in config_file_location.
internal_invoice_id
string
The identifier of the invoice.
Required to get a specific invoice.

aliases: id
invoice_id
string
The invoice query param (not unique).
osp_home_region
string / required
The home region's public name of the logged in user.
region
string
The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is not specified through a configuration file (See config_file_location). Please refer to https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm for more information on OCI regions.
search_text
string
A filter to only return resources that match the given value. Looking for partial matches in the following fileds: Invoice No., Reference No. (plan number), Payment Ref, Total Amount(plan number), Balance Due(plan number) and Party/Customer Name
sort_by
string
    Choices:
  • INVOICE_NO
  • REF_NO
  • STATUS
  • TYPE
  • INVOICE_DATE
  • DUE_DATE
  • PAYM_REF
  • TOTAL_AMOUNT
  • BALANCE_DUE
The field to sort by. Only one field can be selected for sorting.
sort_order
string
    Choices:
  • ASC
  • DESC
The sort order to use (ascending or descending).
status
list / elements=string
    Choices:
  • OPEN
  • PAST_DUE
  • PAYMENT_SUBMITTED
  • CLOSED
A filter to only return resources that match one of the status elements.
tenancy
string
OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See config_file_location). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm
time_invoice_end
string
description: End time (UTC) of the target invoice date range for which to fetch invoice data (exclusive).
time_invoice_start
string
description: Start time (UTC) of the target invoice date range for which to fetch invoice data (inclusive).
time_payment_end
string
description: End time (UTC) of the target payment date range for which to fetch invoice data (exclusive).
time_payment_start
string
description: Start time (UTC) of the target payment date range for which to fetch invoice data (inclusive).
type
list / elements=string
    Choices:
  • HARDWARE
  • SUBSCRIPTION
  • SUPPORT
  • LICENSE
  • EDUCATION
  • CONSULTING
  • SERVICE
  • USAGE
A filter to only return resources that match the given type exactly.

Examples

- name: Get a specific invoice
  oci_osp_gateway_invoice_facts:
    # required
    internal_invoice_id: "ocid1.internalinvoice.oc1..xxxxxxEXAMPLExxxxxx"
    osp_home_region: us-phoenix-1
    compartment_id: "ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx"

- name: List invoices
  oci_osp_gateway_invoice_facts:
    # required
    osp_home_region: us-phoenix-1
    compartment_id: "ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx"

    # optional
    invoice_id: "ocid1.invoice.oc1..xxxxxxEXAMPLExxxxxx"
    type: [ "HARDWARE" ]
    search_text: search_text_example
    time_invoice_start: 2013-10-20T19:20:30+01:00
    time_invoice_end: 2013-10-20T19:20:30+01:00
    time_payment_start: 2013-10-20T19:20:30+01:00
    time_payment_end: 2013-10-20T19:20:30+01:00
    status: [ "OPEN" ]
    sort_by: INVOICE_NO
    sort_order: ASC

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
invoices
complex
on success
List of Invoice resources

Sample:
[{'bill_to_address': {'address_line1': 'address_line1_example', 'address_line2': 'address_line2_example', 'address_line3': 'address_line3_example', 'address_line4': 'address_line4_example', 'city': 'city_example', 'company_name': 'company_name_example', 'contact_name': 'contact_name_example', 'country': {'ascii3_country_code': 'ascii3_country_code_example', 'country_code': 'country_code_example', 'country_id': 10, 'country_name': 'country_name_example', 'language_id': 10}, 'county': 'county_example', 'postal_code': 'postal_code_example', 'province': 'province_example', 'state': 'state_example', 'street_name': 'street_name_example', 'street_number': 'street_number_example'}, 'currency': {'currency_code': 'currency_code_example', 'currency_symbol': 'currency_symbol_example', 'name': 'name_example', 'round_decimal_point': 10, 'usd_conversion': 10}, 'internal_invoice_id': 'ocid1.internalinvoice.oc1..xxxxxxEXAMPLExxxxxx', 'invoice_amount': 10, 'invoice_amount_adjusted': 10, 'invoice_amount_applied': 10, 'invoice_amount_credited': 10, 'invoice_amount_due': 10, 'invoice_amount_in_dispute': 10, 'invoice_id': 'ocid1.invoice.oc1..xxxxxxEXAMPLExxxxxx', 'invoice_number': 'invoice_number_example', 'invoice_po_number': 'invoice_po_number_example', 'invoice_ref_number': 'invoice_ref_number_example', 'invoice_status': 'OPEN', 'invoice_type': 'HARDWARE', 'is_credit_card_payable': True, 'is_display_download_pdf': True, 'is_display_view_pdf': True, 'is_paid': True, 'is_payable': True, 'is_payment_failed': True, 'is_pdf_email_available': True, 'last_payment_detail': {'amount_paid': 10, 'credit_card_type': 'VISA', 'echeck_routing': 'echeck_routing_example', 'last_digits': 'last_digits_example', 'name_on_card': 'name_on_card_example', 'paid_by': 'paid_by_example', 'payment_method': 'CREDIT_CARD', 'paypal_id': 'ocid1.paypal.oc1..xxxxxxEXAMPLExxxxxx', 'paypal_reference': 'paypal_reference_example', 'time_expiration': '2013-10-20T19:20:30+01:00', 'time_paid_on': '2013-10-20T19:20:30+01:00'}, 'party_name': 'party_name_example', 'payment_terms': 'payment_terms_example', 'preferred_email': 'preferred_email_example', 'subscription_ids': [], 'tax': 10, 'time_invoice': '2013-10-20T19:20:30+01:00', 'time_invoice_due': '2013-10-20T19:20:30+01:00'}]
 
bill_to_address
complex
on success
Returned for get operation

   
address_line1
string
on success
Address line 1

Sample:
address_line1_example
   
address_line2
string
on success
Address line 2

Sample:
address_line2_example
   
address_line3
string
on success
Address line 3

Sample:
address_line3_example
   
address_line4
string
on success
Address line 4

Sample:
address_line4_example
   
city
string
on success
Name of the city

Sample:
city_example
   
company_name
string
on success
Name of the customer company

Sample:
company_name_example
   
contact_name
string
on success
Name of the contact person

Sample:
contact_name_example
   
country
complex
on success

     
ascii3_country_code
string
on success
Country code in ISO-3166-1 3-letter format

Sample:
ascii3_country_code_example
     
country_code
string
on success
Country code in ISO-3166-1 2-letter format

Sample:
country_code_example
     
country_id
float
on success
Indentifier of the country. This is a DB side unique id which was generated when the entity was created in the table

Sample:
10
     
country_name
string
on success
Name of the country

Sample:
country_name_example
     
language_id
float
on success
Language identifier

Sample:
10
   
county
string
on success
County name

Sample:
county_example
   
postal_code
string
on success
ZIP no

Sample:
postal_code_example
   
province
string
on success
Name of the province

Sample:
province_example
   
state
string
on success
Name of the state

Sample:
state_example
   
street_name
string
on success
Street name

Sample:
street_name_example
   
street_number
string
on success
House no

Sample:
street_number_example
 
currency
complex
on success

   
currency_code
string
on success
Currency code

Sample:
currency_code_example
   
currency_symbol
string
on success
Currency symbol

Sample:
currency_symbol_example
   
name
string
on success
Name of the currency

Sample:
name_example
   
round_decimal_point
float
on success
Round decimal point

Sample:
10
   
usd_conversion
float
on success
USD conversion rate of the currency

Sample:
10
 
internal_invoice_id
string
on success
Transaction identifier

Sample:
ocid1.internalinvoice.oc1..xxxxxxEXAMPLExxxxxx
 
invoice_amount
float
on success
Total amount of invoice

Sample:
10
 
invoice_amount_adjusted
float
on success
Invoice amount adjust

Sample:
10
 
invoice_amount_applied
float
on success
Invoice amount applied

Sample:
10
 
invoice_amount_credited
float
on success
Invoice amount credit

Sample:
10
 
invoice_amount_due
float
on success
Balance of invoice

Sample:
10
 
invoice_amount_in_dispute
float
on success
Invoice amount in dispute
Returned for list operation

Sample:
10
 
invoice_id
string
on success
Invoice identifier which is generated on the on-premise sie. Pls note this is not an OCID

Sample:
ocid1.invoice.oc1..xxxxxxEXAMPLExxxxxx
 
invoice_number
string
on success
Invoice external reference

Sample:
invoice_number_example
 
invoice_po_number
string
on success
Invoice PO number

Sample:
invoice_po_number_example
 
invoice_ref_number
string
on success
Invoice reference number

Sample:
invoice_ref_number_example
 
invoice_status
string
on success
Invoice status

Sample:
OPEN
 
invoice_type
string
on success
Type of invoice

Sample:
HARDWARE
 
is_credit_card_payable
boolean
on success
Is credit card payment eligible

Sample:
True
 
is_display_download_pdf
boolean
on success
Is pdf download access allowed

Sample:
True
 
is_display_view_pdf
boolean
on success
Is view access allowed
Returned for list operation

Sample:
True
 
is_paid
boolean
on success
Is the invoice has been already payed
Returned for list operation

Sample:
True
 
is_payable
boolean
on success
Whether invoice can be payed

Sample:
True
 
is_payment_failed
boolean
on success
Is the last payment failed
Returned for list operation

Sample:
True
 
is_pdf_email_available
boolean
on success
Is emailing pdf allowed

Sample:
True
 
last_payment_detail
complex
on success

   
amount_paid
float
on success
Amount that paid

Sample:
10
   
credit_card_type
string
on success
Credit card type

Sample:
VISA
   
echeck_routing
string
on success
Last four routing digits of the card

Sample:
echeck_routing_example
   
last_digits
string
on success
Last four digits of the card

Sample:
last_digits_example
   
name_on_card
string
on success
Name on the credit card

Sample:
name_on_card_example
   
paid_by
string
on success
example

Sample:
paid_by_example
   
payment_method
string
on success
Payment method

Sample:
CREDIT_CARD
   
paypal_id
string
on success
The id (email address) of the paypal payment

Sample:
ocid1.paypal.oc1..xxxxxxEXAMPLExxxxxx
   
paypal_reference
string
on success
paypal payment reference

Sample:
paypal_reference_example
   
time_expiration
string
on success
Expired date of the credit card

Sample:
2013-10-20T19:20:30+01:00
   
time_paid_on
string
on success
Paid the invoice on this day

Sample:
2013-10-20T19:20:30+01:00
 
party_name
string
on success
Name of the bill to customer
Returned for list operation

Sample:
party_name_example
 
payment_terms
string
on success
Payment terms
Returned for get operation

Sample:
payment_terms_example
 
preferred_email
string
on success
Preferred Email on the invoice
Returned for get operation

Sample:
preferred_email_example
 
subscription_ids
list / elements=string
on success
List of subscription identifiers

 
tax
float
on success
Tax of invoice amount
Returned for get operation

Sample:
10
 
time_invoice
string
on success
Date of invoice

Sample:
2013-10-20T19:20:30+01:00
 
time_invoice_due
string
on success
Due date of invoice

Sample:
2013-10-20T19:20:30+01:00


Authors

  • Oracle (@oracle)