Submit a transaction

post

https://example.com/v1/transactions

Submit a transaction to fulfill digital reporting requirements. Depending on the configuration one or more operations may be executed

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

accounting_entry_date

string

The date of the accounting entry for an Account payable (AP) invoice/transaction

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

activity_code

string

Activity code is a standard classification of productive economic activities. It can be used to represent EAC (Economic Activity code), a standard classification governed by ISIC and NACE (https://joinup.ec.europa.eu/collection/eu-semantic-interoperability-catalogue/solution/statistical-classification-economic-activities-european-community/about), or other similar concepts.

e.g., 10.32 is Manufacture of fruit and vegetable juice

Validations:

Maximum length: 20

attachments

array of objects

Attachments to be included in the transaction.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

attachments

business_location

object

Represents a distinct physical location where business activities, such as transactions, occur. This typically refers to stores, offices, or other defined spaces registered for fiscal purposes. Also known as business premise, business space, branch and more depending on the jurisdiction.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

country_code

string

required

ISO 3166-1 alpha-2 uppercase country code the transaction is taking place in.

Validations:

Country code must be uppercase ISO 3166-1 alpha-2.
Required property
Customer's address country code and transaction's country code must be different when operation regime is EXPORT.

country_subdivision_code

string

ISO 3166-2 uppercase code of the principal country subdivision (province, state, region) the transaction is taking place in.

Validations:

Values allowed are (letter case matters): AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT
Values allowed are (letter case matters): AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY, DC
Country subdivision code is only supported for US and Canada.

currency_code

string

required

Primary currency code of the transaction represented as ISO 4217 3 letter uppercase currency code e.g. USD.

Validations:

Currency must be one of ISO 4217 codes.
Required property

customer

Customer (sometimes called buyer) in a transaction. Can be an individual or a business. Can be omitted for most jurisdictions depending on the transaction size. In self-billing regime the customer must be a pre-onboarded entity (TransactionOnboardedEntity).

Validations:

Customer entity should be onboarded in case of self-billing. For more information about onboarding refer to the public documentation.

decimal_amounts

boolean

A flag to be used in a migration phase. It signals in which format amounts should be parsed. If true amounts are parsed as decimals, if false amounts are parsed as an integer representing the minor currency unit.

direction

string

Document representing a transaction can be sent or received. Allows businesses to report both inbound and outbound transactions for VAT deduction purposes. Default: SENT.

Validations:

Maximum length: 20
Values allowed are (letter case matters): SENT, RECEIVED

document_references

array of objects

List of document references related to the transaction, such as transport documents, customs documents, or other relevant references.

The property applies only for France,Germany,Costa Rica
Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

document_references

end_date

string

RFC3339 datetime string representing an ending point in time.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

frequency

string

Describes the frequency of reporting invoices to tax authority, used with SUMMARY invoice types.

issue_date

string

The date when the transaction was issued by an external application.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

issuer

object

Entity issuing a transaction document (usually invoice) on behalf of supplier. This is typically used for marketplace scenarios.

items

array of objects

required

Goods, services, and discounts exchanged in a transaction.

Validations:

Must not be empty.
Must be empty for PASS_THROUGH transactions.
Reference Item Number must reference actual Item Number.
Transaction item numbers must be unique.
Discount and fee tax rates must match the referenced item tax rates.
Discount items must be margin when referencing margin line items or when all line items are margin.
All or no items should reference a transaction.
Discount and fee items applied to this transactions must reference items that are not a discount or fee item.
The transaction may not have more than {{.max}} items. Please reach out to Fonoa support to learn about the alternatives.
A transaction with item level references may not have more than {{.max}} items. Please reach out to Fonoa support to learn about the alternatives.

items*

labels

array of objects

A list of transaction labels to be applied to the generated document.
Labels are not supported in all countries, please see the Country Integration Guides for details.

Validations:

Cannot contain more than {{.max}} labels, provided {{.actual}}.

labels

language_code

string

required

Language of the transaction document represented as ISO 639-1 uppercase language code. Required when document generation is enabled. Defaults to EN (English) if not provided.

Validations:

Language of the transaction must be uppercase ISO 639-1.
Required property

note

string

A text note attached to a transaction. Notes are HTML enabled and will be displayed on the visual document.

Validations:

Maximum length: 3000

operation_regime

string

A value describing the operation regime for the transaction if applicable. e.g., export - indicating the transaction should be reported as cross-border transaction.

Validations:

Values allowed are (letter case matters): GENERAL, SELF_BILLING

operation_regime_details

string

A value providing additional information on the specified operation regime. e.g., providing a tax authority supported export type.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

operational_context

object

Operational context for the transaction. Fields in this object are usually not used for compliance reporting or document generation. Examples include your internal line of business
or the source system of the transaction.

operator

Operator in a transaction. Usually the individual (employee) responsible for creating the transaction.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

payment_details

array of objects

Payment details for the transaction.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

payment_details

payment_due_date

string

RFC3339 datetime string representing the deadline until which the payment must be made.

Validations:

payment_due_date is not supported for the provided country

payments

array of objects

A list of transaction payments. The sum of all payment amounts must match the total transaction amount.
i.e., sum(payments[].amount) == sum(items[].quantity items[].unit_price (1 + sum(tax_breakdown[].rate)/100))

Validations:

Sum of payment amounts must be equal to total transaction amount.

payments

place_of_supply

object

Location of the place of supply for the transaction, as determined by local rules in respect of supply of goods/services and business model (B2B/B2C/B2G)

pos_device

object

POS (Point of Sale) devices are systems used at sales points, such as retail outlets, to generate, sign, and send e-invoices as per regulatory requirements. The pos device must be unique for a given business location. They are also known as cash register, billing device, payment device and more depending on the jurisdiction.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

purchase_orders

array of objects

Buyer’s purchase orders information (e.g., PO number) this document relates to.

The property applies only for Ghana,Italy,Nigeria
Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

purchase_orders

reference_transaction_id

string

The external transaction identifier of the original transaction the credit is referencing. e.g., MY_ORIGINAL_IDENTIFIER_0001

Validations:

Maximum length: 150
And other transaction refences (in items and payments) cannot be provided together.

secondary_currency

object

Secondary currency exchange information. Secondary currency displayed on the visual document.

secondary_entities

array of objects

Secondary entities involved in the transaction. e.g., buyer agency, buyer branch information, supplier payee, etc.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

secondary_entities

series

string

A pool of transaction numbers issued by tax authorities to pick the transaction number from.

The transaction shall be assigned one of the numbers from this pool when reporting it to the tax authorities.

Usually series can be opened and closed at any time and there can be multiple open series at the same time.

e.g., 2022_01

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

signature

string

The transaction signature generated by an external application.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

signature_date

string

The date of the transaction signature generated by an external application.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

start_date

string

RFC3339 datetime string representing a starting point in time.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

supplier

required

Supplier entity referenced by either Fonoa ID or customer provided ID. If both values are provided, Fonoa ID has precedance over external ID. In self-billing regime supplier can be non onboarded (TransactionNonOnboardedEntity).

Validations:

Required property
Supplier entity should be onboarded in any case other than self-billing. For more information about onboarding refer to the public documentation.

tax_authority_id_1

string

Main transaction identifier returned by or to be provided to the tax authorities. e.g., JIR in Croatia.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

tax_authority_id_2

string

Secondary transaction identifier returned by or to be provided to the tax authorities. e.g., ZKI in Croatia.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

tax_reason

object

A value describing the utility that will be attributed to the transaction for tax deduction purposes.

Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

total_amount

number

A high precision decimal representing the total amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding

Validations:

Cannot exceed the maximum allowed precision of 9 decimals.
Please provide either all amounts (totals and line item's) or only the items unit price.
Line item values and total amounts must add up.

total_net_amount

number

A high precision decimal representing the total net amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding

Validations:

Cannot exceed the maximum allowed precision of 9 decimals.

total_tax_amount

number

A high precision decimal representing the total tax amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding

Validations:

Cannot exceed the maximum allowed precision of 9 decimals.

total_tax_amounts

array of objects

A list of total tax amounts broken down by tax regime. Each entry represents the total for a specific tax regime (e.g., ISH, VAT).

The property applies only for Mexico
Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

total_tax_amounts

transaction_channel

string

The channel through which the transaction was conducted, such as in-person, online, telephone order, etc.

The property applies only for Brazil
Validations:

Values allowed are (letter case matters): IN_PERSON_AT_ESTABLISHMENT, ONLINE, TELEPHONE, IN_PERSON_OUTSIDE_ESTABLISHMENT, OTHER, NOT_APPLICABLE
This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

transaction_date

string

required

RFC3339 datetime string representing the point in time when transaction is executed.

Validations:

Required property
Must be an RFC3339 format date

transaction_id

string

required

Unique external transaction identifier provided by the customer. Used as idempotency key. e.g., MY_EXTERNAL_IDENTIFIER_0001.

Validations:

Maximum length: 150
Required property

transaction_number

string

required

Unique and usually sequential identifier of a transaction displayed on the document and reported to tax authorities. e.g., invoice number for debit scenario or credit note number for credit scenario. e.g., IE00000001

Validations:

Maximum length: 50
Is required when Fonoa is not managing transaction numbers.
Must be empty when Fonoa is managing transaction numbers.

transaction_scenario

string

The scenario type for a corrective invoice. Describes the type of correction being applied to the original transaction.

The property applies only for France
Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

transport_data

object

Transport data for the transaction usually used when submitting invoices with transportation data and standalone transport documents.

The property applies only for Portugal,Brazil
Validations:

This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.

type

string

Type of the transaction that usually depends on transaction value and business model (B2B or B2C).

The most common types are FULL, SIMPLIFIED, RECEIPT, RECEIPT_INVOICE.

Validations:

Values allowed are (letter case matters): FULL, SIMPLIFIED, RECEIPT, RECEIPT_INVOICE, BILLING_STATEMENT, DRAFT_INVOICE

Responses

401

Authentication failed - missing or incorrect subscription key

429

Too many requests were sent for a short period of time. Try again a bit later.

202Accepted - transaction was successfully submitted for processing.

400Bad customer request - some of the provided information is incorrect or mandatory data is missing. Check the message and errors section of the response for more details.

5XXInternal server error. Its not you, its us! We are experiencing a rare and unexpected system disruption. Retry again later. The message field of the response will contain more information for the cause. Feel free to contact us.