Sign in

v1

latestOpenAPI 3.0.02026-07-2436163302.7 KB

Submit a transaction

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

post/v1/transactions

Request body

accounting_entry_datestring

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_codestring

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
country_codestring 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_codestring

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_codestring 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
decimal_amountsboolean

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.

directionstring

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
end_datestring

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.
frequencystring

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

issue_datestring

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.
language_codestring 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
notestring

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

Validations:

  • Maximum length: 3000
operation_regimestring

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_detailsstring

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.
payment_due_datestring

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

Validations:

  • payment_due_date is not supported for the provided country
reference_transaction_idstring

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.
seriesstring

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.
signaturestring

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_datestring

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_datestring

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.
tax_authority_id_1string

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_2string

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.
total_amountnumber

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_amountnumber

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_amountnumber

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.
transaction_channelstring

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_datestring required

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

Validations:

  • Required property
  • Must be an RFC3339 format date
transaction_idstring 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_numberstring 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_scenariostring

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.
typestring

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

Response

Accepted - transaction was successfully submitted for processing.

messagestring

Information about the failure reason in case the request was unsuccessful.

operation_idstring

Auto-generated unique identifier of a transaction operation returned upon async operation request.

transaction_idstring

The unique external transaction identifier provided with the initial request.