openapi: 3.0.0
info:
  title: Fonoa E-Invoicing Lookup V2 Transactions 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
security:
- ApiKeyAuth: []
tags:
- name: Transactions
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'
      tags:
      - Transactions
components:
  schemas:
    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: someone@email.com
        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
    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
    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
    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
    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
    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'
    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.
    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
    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: someone@email.com
        phone_number:
          type: string
          description: The customer's phone number.
          example: '+10023456789'
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key