API Reference

Adjust a transaction

post
https://example.com/v1/transactions/adjustment

Create an adjustment for a previously submitted transaction.

Adjustment (also known as partial credit note) must reference the original transaction.

Use /adjustment endpoint for credit a subset of transaction (one or more line items).

Body Params
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.
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
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.
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.
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.
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.
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.

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

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

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:

  • Required property
  • 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
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
string

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

Validations:

  • Maximum length: 3000
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
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.
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
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
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.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
string
required

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

Validations:

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

Updated 7 months ago

Language
Credentials
Header
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 7 months ago