Unified e-invoicing API that manages the full transaction lifecycle including submitting, adjusting, crediting, and canceling e-invoices in compliance with local mandates across multiple countries. Supports backfilling previously reported transactions and retrieving transaction history and status.
openapi: 3.0.0
info:
title: Fonoa E-Invoicing API
description: >
Unified e-invoicing API that manages the full transaction lifecycle including submitting,
adjusting, crediting, and canceling e-invoices in compliance with local mandates across
multiple countries. Supports backfilling previously reported transactions and retrieving
transaction history and status.
version: 1.0.0
servers:
- url: https://api-demo.fonoa.com
description: Fonoa API demo environment
- url: https://sandbox.fonoa.com/
description: Fonoa API sandbox environment
- url: https://api.fonoa.com
description: Fonoa API production (live) environment
paths:
/v1/transactions:
post:
summary: Submit a transaction
description: >
Submit a transaction to fulfill digital reporting requirements. Depending on the
configuration one or more operations may be executed.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
responses:
'202':
description: Accepted - transaction was successfully submitted for processing.
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResultResponse'
'400':
description: Bad customer request - some of the provided information is incorrect or mandatory data is missing.
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResultResponse'
'401':
description: Authentication failed - missing or incorrect subscription key.
'429':
description: Too many requests were sent for a short period of time. Try again a bit later.
'5XX':
description: Internal server error. Retry again later.
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResultResponse'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Ocp-Apim-Subscription-Key
schemas:
BusinessLocation:
type: object
properties:
name:
type: string
description: The name of the business location.
example: Store1
DocumentReference:
type: object
required:
- identifier
properties:
identifier:
type: string
description: Buyer's document reference identifier (e.g., PO number).
example: PO-123
issue_date:
type: string
description: Date when the referenced document was issued (RFC3339 format).
reason:
type: string
description: Reason for the document reference.
tender_reference:
type: string
description: Identifier of the procurement procedure associated with the referenced document.
type:
type: string
description: Type of the document reference.
OperationResultResponse:
type: object
properties:
errors:
type: array
description: List of errors in case the request was unsuccessful.
items:
$ref: '#/components/schemas/TransactionErrorResponse'
message:
type: string
description: Information about the failure reason if unsuccessful.
operation_id:
type: string
description: Auto-generated unique identifier of a transaction operation.
transaction_id:
type: string
description: The unique external transaction identifier provided with the initial request.
OperationalContext:
type: object
properties:
line_of_business:
type: string
description: Classification of the business line this transaction belongs to.
example: delivery
source_system:
type: string
description: Identifier for the internal system that originated this transaction.
example: workday
PaymentDetailBankInfo:
type: object
properties:
account_number:
type: string
description: Bank account number used for the payment.
example: '1234567890'
bank_identifier:
type: string
description: Bank identifier used for the payment.
example: ZABAHR2X
bank_name:
type: string
description: Name of the bank where the payment was made.
example: Bank of America
PaymentProcessor:
type: object
properties:
authorization_code:
type: string
description: Authorization code of the payment processor.
example: '123456'
integration_type:
type: string
description: Type of integration with the payment processor.
example: NOT_INTEGRATED
tax_number:
type: string
description: Tax number of the payment processor.
example: 69061864-2-99
terminal_id:
type: string
description: Terminal ID of the payment processor.
example: '1234567890'
PaymentSettlement:
type: object
properties:
instalment_number:
type: integer
description: The sequential number of the instalment this settlement represents.
example: 1
outstanding_balance:
type: number
description: The remaining unpaid balance after this settlement is applied.
example: 100.00
reference_transaction_id:
type: string
description: The external transaction identifier of the original transaction.
example: MY_ORIGINAL_IDENTIFIER_0001
settled_amounts:
type: array
description: How the payment amount is allocated.
items:
$ref: '#/components/schemas/SettledAmount'
PosDevice:
type: object
properties:
code:
type: string
description: The code of the pos device.
example: SN1
SettledAmount:
type: object
properties:
base_amount:
type: number
description: The untaxed portion of the settled amount.
example: 100.00
tax_breakdown:
type: array
description: A detailed list of applied taxes corresponding to this settled base amount.
items:
$ref: '#/components/schemas/TransactionLineItemTaxBreakdown'
TransactionAttachmentRequest:
type: object
required:
- content
- kind
- name
- type
properties:
content:
type: string
description: Base64 encoded content of the attachment.
kind:
type: string
description: 'Attachment kind. Allowed values: REPORT'
name:
type: string
description: Name of the attachment (max 255 chars).
type:
type: string
description: 'Attachment type. Allowed values: XML, JSON'
TransactionEntityAddress:
type: object
required:
- country_code
properties:
address_line_1:
type: string
description: Street name and number of the company.
example: R. Augusta 2
address_line_2:
type: string
canton:
type: string
city:
type: string
description: The city where the entity is registered.
example: Lisbon
city_code:
type: string
country_code:
type: string
description: ISO 3166-1 alpha-2 uppercase country code.
example: PT
district:
type: string
neighbourhood:
type: string
number:
type: string
example: '2'
postal_code:
type: string
example: 1100-053
prefix:
type: string
province:
type: string
example: Estremadura
region:
type: string
state:
type: string
suffix:
type: string
TransactionEntityContactDetails:
type: object
required:
- email
properties:
email:
type: string
description: Email address for tax authority communications.
example: [email protected]
phone_number:
type: string
description: The customer's phone number.
example: '+10023456789'
TransactionEntityTaxInformation:
type: object
properties:
activity_code:
type: string
description: Code representing the activity of the entity.
additional_tax_numbers:
type: array
items:
$ref: '#/components/schemas/TransactionEntityTaxNumberCountrySpecific'
distribution_address:
type: string
description: Email address for forwarding invoices to the customer.
example: [email protected]
regime:
type: string
description: Tax regime the entity is registered with.
example: VAT
tax_code:
type: string
description: Tax code that complements tax number.
tax_number:
type: string
description: Tax number of tax registered entity.
example: 69061864-2-99
TransactionEntityTaxNumberCountrySpecific:
type: object
properties:
business_model:
type: array
items:
type: string
country_code:
type: string
example: US
country_subdivision_code:
type: string
tax_number:
type: string
example: '123456789'
type:
type: string
TransactionErrorResponse:
type: object
properties:
code:
type: string
description: Error code. e.g., field_not_valid
doc_link:
type: string
description: Link to error documentation.
field:
type: string
description: Field from the input request that caused the error.
message:
type: string
description: Error message.
type:
type: string
description: 'Error type. e.g., warning, validation, general, tax_authority'
TransactionLabel:
type: object
required:
- label
- value
properties:
label:
type: string
maxLength: 35
example: Purchase Order No.
value:
type: string
maxLength: 35
example: 12345/67890/X
TransactionLineItem:
type: object
required:
- name
- number
- quantity
- unit_price
properties:
code:
type: string
maxLength: 60
description: Item code used by Tax Authorities to classify transaction items.
example: '08081000'
description:
type: string
maxLength: 200
description: Description of the item.
ean:
type: string
maxLength: 13
description: European article number (EAN).
example: '5012345678900'
name:
type: string
maxLength: 200
description: Item name displayed on an invoice.
example: Chocolate cookies
net_price:
type: number
description: Item net price.
example: '2.30'
number:
type: integer
description: Ordinal number of the item in the transaction.
example: 1
quantity:
type: number
description: Quantity of units of the line item.
example: '3.1'
tax_breakdown:
type: array
description: Taxes applied to this line item.
items:
$ref: '#/components/schemas/TransactionLineItemTaxBreakdown'
type:
type: string
description: 'Type of item: GOODS, SERVICES, or DISCOUNT.'
example: GOODS
unit:
type: string
maxLength: 20
description: Unit of measurement for the item.
example: pcs
unit_price:
type: number
description: Price of a single unit, excluding taxes based on net price.
example: '2.30'
TransactionLineItemDetail:
type: object
required:
- name
properties:
name:
type: string
description: Description of the line item detail.
example: Chocolate cookies
net_price:
type: number
example: '4.10'
quantity:
type: number
example: '2.50'
TransactionLineItemTaxBreakdown:
type: object
required:
- rate
- regime
properties:
amount:
type: number
description: Tax amount applied.
example: '2.30'
application_mode:
type: string
description: 'Defines tax basis: ADD_TO_UNIT_PRICE or INCLUDED_IN_UNIT_PRICE.'
code:
type: string
maxLength: 10
description: Tax code required by some tax authorities.
example: M11
rate:
type: number
description: Non-negative tax rate percentage applied to an item.
example: 25
regime:
type: string
maxLength: 10
description: Name of the tax regime.
example: VAT
type:
type: string
maxLength: 10
description: Tax type required by some tax authorities.
example: PT-MA
TransactionNonOnboardedEntity:
type: object
required:
- legal_name
- type
properties:
address:
allOf:
- $ref: '#/components/schemas/TransactionEntityAddress'
description: Address of an entity.
type: object
contact_details:
allOf:
- $ref: '#/components/schemas/TransactionEntityContactDetails'
description: Contact details of an entity.
type: object
entity_number:
type: string
maxLength: 50
description: Company registration number or personal identifier.
example: '011589551'
entity_number_type:
type: string
maxLength: 50
description: Company or individual number type.
example: '93'
legal_name:
type: string
maxLength: 450
description: Full legal name of the company or individual.
example: Acme LLC
tax_information:
allOf:
- $ref: '#/components/schemas/TransactionEntityTaxInformation'
description: Tax information of an entity.
type: object
trade_name:
type: string
maxLength: 450
description: The name used for doing business.
example: Acme
type:
type: string
description: 'Entity type defining the type of transaction: BUSINESS, INDIVIDUAL, or ECONOMIC_OPERATOR.'
example: BUSINESS
TransactionOnboardedEntity:
type: object
required:
- id
properties:
external_id:
type: string
maxLength: 150
description: External resource identifier provided by the customer.
example: MY_EXTERNAL_ID_001
id:
type: string
description: Fonoa id representing a resource. Exact length 32.
example: a7cc64422fc247069aa64d4fe8b387c5
TransactionPayment:
type: object
required:
- type
properties:
amount:
type: number
description: Amount paid by this payment type.
example: '122.00'
card_brand:
type: string
description: Card brand used for the payment.
example: VISA
code:
type: string
maxLength: 32
description: Payment type code required by some tax authorities.
example: PUE
date_of_payment:
type: string
description: Date of the payment (RFC3339 format).
example: '2021-01-01T00:00:00Z'
type:
type: string
maxLength: 32
description: 'Free text or predefined payment type: CARD, CASH, CHECK, etc.'
example: CARD ending in 2022
TransactionPaymentDetail:
type: object
properties:
bank_info:
allOf:
- $ref: '#/components/schemas/PaymentDetailBankInfo'
type: object
condition:
type: string
description: 'Payment structure: FULL, INSTALLMENTS, or ADVANCE.'
example: FULL
payments:
type: array
items:
$ref: '#/components/schemas/TransactionPayment'
TransactionRequest:
type: object
required:
- country_code
- currency_code
- items
- language_code
- supplier
- transaction_date
- transaction_id
- transaction_number
properties:
country_code:
type: string
description: ISO 3166-1 alpha-2 uppercase country code the transaction is taking place in.
example: PT
currency_code:
type: string
description: ISO 4217 3-letter uppercase currency code.
example: USD
customer:
description: Customer (buyer) in the transaction.
oneOf:
- $ref: '#/components/schemas/TransactionOnboardedEntity'
- $ref: '#/components/schemas/TransactionNonOnboardedEntity'
type: object
direction:
type: string
description: 'Document direction: SENT or RECEIVED. Default: SENT.'
example: SENT
items:
type: array
description: Goods, services, and discounts exchanged in the transaction.
items:
$ref: '#/components/schemas/TransactionLineItem'
language_code:
type: string
description: ISO 639-1 uppercase language code for the transaction document.
example: EN
note:
type: string
maxLength: 3000
description: HTML-enabled text note attached to the transaction.
example: This is my HTML <e>enabled</e> note.
operation_regime:
type: string
description: 'Operation regime: GENERAL or SELF_BILLING.'
example: GENERAL
payments:
type: array
description: List of transaction payments.
items:
$ref: '#/components/schemas/TransactionPayment'
reference_transaction_id:
type: string
maxLength: 150
description: External transaction identifier of the original transaction for credits.
example: MY_ORIGINAL_IDENTIFIER_0001
supplier:
description: Supplier entity referenced by Fonoa ID or customer provided ID.
oneOf:
- $ref: '#/components/schemas/TransactionOnboardedEntity'
- $ref: '#/components/schemas/TransactionNonOnboardedEntity'
type: object
total_amount:
type: number
description: Total amount of the transaction.
example: '122.00'
total_net_amount:
type: number
description: Total net amount of the transaction.
example: '100.00'
total_tax_amount:
type: number
description: Total tax amount of the transaction.
example: '22.00'
transaction_date:
type: string
description: RFC3339 datetime when the transaction was executed.
example: '2021-01-07T01:00:00+00:00'
transaction_id:
type: string
maxLength: 150
description: Unique external transaction identifier (idempotency key).
example: Reference101
transaction_number:
type: string
maxLength: 50
description: Unique sequential identifier displayed on the document and reported to tax authorities.
example: IE00000001
type:
type: string
description: 'Type of the transaction: FULL, SIMPLIFIED, RECEIPT, RECEIPT_INVOICE, BILLING_STATEMENT, or DRAFT_INVOICE.'
example: FULL
TransactionSecondaryCurrency:
type: object
required:
- currency_code
- exchange_rate
properties:
currency_code:
type: string
description: ISO 4217 currency code of the secondary transaction currency.
example: MXN
exchange_date:
type: string
description: Date of the currency exchange rate (RFC3339 format).
example: '2021-01-01T00:00:00Z'
exchange_rate:
type: number
description: Currency exchange rate between main and secondary currency.
example: '18.38'
security:
- ApiKeyAuth: []