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: someone@email.com
        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: 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
    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: []