Business cards
==============

API docs: `api.mobilum.com <https://api.mobilum.com/index.html#operations-tag-Corporates>`_

Authentication: :ref:`api_authentication_hmac`

Overview
--------

This system is designed to manage corporate card transactions based on a master corporate balance.
It introduces a structure where **approvals** are issued against the corporate balance to allocate
specific budgets for card usage.

Key Concepts
------------

- **Corporate Balance**:
  A centralized pool of funds managed by the organization.

- **Approval**:
  A budget authorization linked to a specific card, representing a portion of the corporate balance
  that can be used for transactions.

- **Card Assignment**:
  Each approval is tied to a single card and user. Card data remains constant across approval changes.

- **Approval Lifecycle**:
  Any modification to an approval (e.g., budget change, PIN update) results in the creation
  of a **new approval instance**. The new instance retains the same card association but reflects
  updated parameters. The original approval is considered closed or replaced.

Approval Statuses
-----------------

The lifecycle of an approval involves several statuses that reflect the current state of the approval request and its
usage. These statuses are key to understanding how approvals move through the system from creation to expiration.

.. glossary::

    CREATED
        Occurs only when a user requests changes on a reapproval.

    ACCEPTED
        Assigned when an approval is initially created. It transitions to the :term:`DELIVERED` status
        after registration is completed.

    CANCELED
        Indicates that an approval or reapproval in status :term:`CREATED`, :term:`ACCEPTED`, or :term:`PREPARED`
        has been canceled by the corporation.

    REJECTED
        Assigned when a reapproval in the :term:`CREATED` status is rejected by the corporation.

    EXPIRED
        Assigned when a reapproval in :term:`CREATED` status is neither accepted nor rejected before
        expiration.

    PREPARED
        The approval has been :term:`ACCEPTED` and is waiting for card generation. The card is generated
        on the ``validFrom`` of the approval.

    DELIVERED
        Indicates the card has been issued. This is the active state in which card transactions can
        occur.

    FINISHED
        The approval was in :term:`DELIVERED` status and has now exceeded the end date of its assignment.

    REAPPROVED
        A reapproval has been created for an existing approval that is currently in :term:`ACCEPTED` or
        :term:`DELIVERED` status.

    LOCKED
        *(Card status)*
        This is a status of the **card**, not the approval itself. However, it is shown in the approval
        flow to indicate that a card can only be locked or unlocked when the related approval is in the
        :term:`DELIVERED` state.



Basic Flow
----------

.. uml::
    :align: center

    skinparam monochrome true

    participant App
    participant API

    ==Create user==

    App -> API : POST /corporates/users \n //name, lastName, email, phone//
    return //user//

    ==Create card==

    App -> API : POST /corporates/corporates/{corporateUuid}/approvals \n //userUuid, budget, validTo, validFrom//
    activate API
    API --> App : //approval//
    API -> API : Issuing a card
    App -> API : GET /corporates/{corporateUuid}/approvals/{approvalUuid}
    return //approval & card//
    deactivate API

    ==Get card data==

    App -> API : GET /corporates/{corporateUuid}/users/{userUuid}/approvals
    return //approvals//
    App -> API : GET /corporates/{corporateUuid}/approvals/{approvalUuid}/details \n //public key//
    return //encrypted card details//

    ==Deposits==

    App -> API : GET /corporates/{corporateUuid}/deposits
    return //deposit addresses//
    App -> App: Deposit
    App -> API : GET /corporates/{corporateUuid}/top-ups
    return //top-ups//

    App -> API : POST /corporates/{corporateUuid}/approvals/{approvalUuid}/increase-budget \n //additionalBudget//
    return //reapproval//