-
Notifications
You must be signed in to change notification settings - Fork 256
Add Reports feature documentation #2370
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
rodrigogsn
wants to merge
12
commits into
stellar:main
Choose a base branch
from
CheesecakeLabs:sdp-report-generation
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
24370cc
docs(admin-guide): add Reports UI page and screenshots
rodrigogsn 1359468
docs(api-reference): add Reports API (statement and payment PDF exports)
rodrigogsn c45cf6a
docs: reorder API Reference sidebar
rodrigogsn 6c30d90
docs(admin-guide): add feature flag info in Reports UI
rodrigogsn d6dc9dc
docs(admin-guide): update Reports UI feature flag instructions
rodrigogsn 28fba9b
docs(admin-guide): update Reports feature toggle instructions
rodrigogsn bdf760a
docs: remove duplicated content in reports.mdx
rodrigogsn efc5296
docs: simplify report details for api consumers
rodrigogsn ef7d2a7
docs: remove unwanted code format
rodrigogsn f5e8a39
feat: add updated reports feature description for YAML files
rodrigogsn 026c8c2
docs: html-unescape characters
rodrigogsn 6ded812
chore: update routes.txt to reflect new report feature routes
rodrigogsn File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
48 changes: 48 additions & 0 deletions
48
.../platforms/stellar-disbursement-platform/admin-guide/user-interface/reports.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: Reports | ||
| sidebar_position: 65 | ||
| --- | ||
|
|
||
| The Reports page is where you export PDFs: a wallet statement for your distribution account and individual transaction notices for single payments. | ||
|
|
||
|  | ||
|
|
||
| :::info | ||
|
|
||
| The Reports menu item and page are optional and disabled by default. Organization owners can enable it from the **Settings** page using the "Enable Reports" toggle. This sets the `reporting_enabled` flag on the organization, which is served via the `/app-config` endpoint. When disabled, the Reports entry is hidden from the sidebar and the `/reports` route is not available. | ||
|
|
||
| ::: | ||
|
|
||
| The Reports page includes the following: | ||
|
|
||
| ### Wallet Statement | ||
|
|
||
|  | ||
|
|
||
| - **Header**: Organization logo and name, "Operated by" (provider URL), and "Generated on" (timestamp). | ||
| - **Statement period**: The date range (From–To) covered by the statement. | ||
| - **Wallet address**: Your distribution account's Stellar address (clickable in the PDF; opens in Stellar Expert per the info above). | ||
| - **Account summary table**: One row per currency (e.g. USDC, XLM) with Beginning Balance, Total Credits, Total Debits, and Ending Balance. | ||
| - **Transactions table**: Per-asset list of transactions with Date, Transaction ID (and optional Payment ID), Counterparty (wallet/recipient), Debits, Credits, and Balance. | ||
|
|
||
| - **Individual Transaction Notice**: Generate a PDF for a single payment. | ||
| - Search by SDP Transaction ID or Payment ID: Enter a full or partial ID to find the payment; results appear in a table with Transaction ID, Payment ID, Date, and Disbursement Name. | ||
| - Select one payment from the results using the radio button. | ||
| - Notes (optional): Add up to 500 characters of notes; they are included in the generated PDF. | ||
| - Download Notice: Click to generate and download the PDF for the selected payment (e.g. `transaction_notice_{paymentID}.pdf`). | ||
|
|
||
| ### Transaction Notice | ||
|
|
||
|  | ||
|
|
||
| - **Header**: Organization logo and name, "Operated by" (provider URL), and "Generated on" (timestamp). | ||
| - **Title and Stellar Transaction ID**: "Transaction Notice" and the on-chain transaction hash (clickable; opens in Stellar Expert per the info above). | ||
| - **Transaction summary table**: Amount, Currency, Status (e.g. SUCCESS), Payment ID, and Status Update At. | ||
| - **Transaction details**: Sender (organization name, wallet address, MEMO, fee) and Recipient (org ID, wallet address, wallet provider), in two columns. | ||
| - **Disbursement details**: Disbursement ID and Disbursement Name for context. | ||
|
|
||
| :::info | ||
|
|
||
| Transaction and wallet address links in the generated PDFs open in Stellar Expert Explorer. The explorer network (testnet or public) is determined by the **backend** `STELLAR_EXPERT_URL` environment variable; when this variable is not set, the default is testnet. | ||
|
|
||
| ::: | ||
110 changes: 110 additions & 0 deletions
110
...latforms/stellar-disbursement-platform/api-reference/get-payment-export.api.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| --- | ||
| id: get-payment-export | ||
| title: "Get Payment Transaction Notice (PDF)" | ||
| description: "Returns a single-page Transaction Notice PDF for the given payment (id). Optional internal_notes are included in the PDF (max 500 characters). The PDF is built with gofpdf: single-page A4, payment details, disbursement info when applicable, and organization branding." | ||
| sidebar_label: "Get Payment Transaction Notice (PDF)" | ||
| hide_title: true | ||
| hide_table_of_contents: true | ||
| api: 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 | ||
| sidebar_class_name: "get api-method" | ||
| info_path: docs/platforms/stellar-disbursement-platform/api-reference/stellar-disbursement-platform-api | ||
| custom_edit_url: null | ||
| --- | ||
|
|
||
| import { SepBadge } from "@site/src/components/SepBadge"; | ||
|
|
||
| <SepBadge tags={''} /> | ||
|
|
||
| import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; | ||
| import ParamsDetails from "@theme/ParamsDetails"; | ||
| import RequestSchema from "@theme/RequestSchema"; | ||
| import StatusCodes from "@theme/StatusCodes"; | ||
| import OperationTabs from "@theme/OperationTabs"; | ||
| import TabItem from "@theme/TabItem"; | ||
| import Heading from "@theme/Heading"; | ||
|
|
||
| <Heading | ||
| as={"h1"} | ||
| className={"openapi__heading"} | ||
| children={"Get Payment Transaction Notice (PDF)"} | ||
| > | ||
| </Heading> | ||
|
|
||
| <MethodEndpoint | ||
| method={"get"} | ||
| path={"/reports/payment/{id}"} | ||
| context={"endpoint"} | ||
| > | ||
|
|
||
| </MethodEndpoint> | ||
|
|
||
|
|
||
|
|
||
| Returns a single-page Transaction Notice PDF for the given payment (id). Optional internal_notes are included in the PDF (max 500 characters). The PDF is built with gofpdf: single-page A4, payment details, disbursement info when applicable, and organization branding. | ||
|
|
||
| ## Fields in the generated PDF | ||
|
|
||
| The following tables describe the fields that appear in the transaction notice PDF, how they are calculated (when applicable), and whether the value comes from the **DB**, **Horizon**, or **Request**. Tables are grouped by source. | ||
|
|
||
| ### Request | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Internal notes | Free text included in the PDF | Request (`internal_notes` query param) | | ||
|
|
||
| ### Context | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Sender Wallet Address | Distribution account Stellar address | Context (distribution account) | | ||
|
|
||
| ### DB | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Organization name, logo | Header | `Organizations` | | ||
| | Stellar Transaction ID | Link to Stellar Expert | `Payment` | | ||
| | Amount, Currency, Status, Payment ID (external), Status Update At | Transaction summary section | `Payment`, `Payment.Asset`, `Payment.status_history` | | ||
| | Sender Name | Organization name | `Organizations` | | ||
| | MEMO (Text) | When taken from receiver wallet | `ReceiverWallet.StellarMemo` | | ||
| | Recipient Org ID | Receiver external ID | `ReceiverWallet.Receiver` | | ||
| | Recipient Wallet Address | Receiver Stellar address | `ReceiverWallet` | | ||
| | Wallet Provider | Wallet name | `ReceiverWallet.Wallet` | | ||
| | Disbursement ID, Name | When payment is a disbursement | `Payment.Disbursement` | | ||
| | Created by / Approved by | User names and timestamps from disbursement status history (`DRAFT` → `Created`, `STARTED` → `Approved`) | `Disbursement.status_history`, `AuthManager.GetUsersByID` | | ||
|
|
||
| ### Horizon | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | MEMO (Text) | When taken from transaction | `TransactionDetail.Memo` | | ||
| | Fee Charged | Transaction fee in XLM (`FeeCharged` in `stroops` ÷ 10^7) | `TransactionDetail.FeeCharged` | | ||
|
|
||
| <Heading | ||
| id={"request"} | ||
| as={"h2"} | ||
| className={"openapi-tabs__heading"} | ||
| children={"Request"} | ||
| > | ||
| </Heading> | ||
|
|
||
| <ParamsDetails | ||
| parameters={[{"name":"id","in":"path","description":"ID of the Payment.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"internal_notes","in":"query","description":"Optional notes included in the PDF. Max 500 characters.","required":false,"style":"form","explode":true,"schema":{"type":"string","maxLength":500}},{"name":"base_url","in":"query","description":"Base URL used in the PDF for \"Operated by\" and footer links.","required":false,"style":"form","explode":true,"schema":{"type":"string"}}]} | ||
| > | ||
|
|
||
| </ParamsDetails> | ||
|
|
||
| <RequestSchema | ||
| title={"Body"} | ||
| body={undefined} | ||
| > | ||
|
|
||
| </RequestSchema> | ||
|
|
||
| <StatusCodes | ||
| id={undefined} | ||
| label={undefined} | ||
| responses={{"200":{"description":"PDF file (transaction_notice_{id}.pdf)","headers":{"Content-Disposition":{"description":"Filename of the returned PDF file.","style":"simple","explode":false,"schema":{"type":"string"}},"Content-Type":{"description":"application/pdf","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"example":""}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"extras":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}},"example":{"error":"Not authorized","extras":{"status":401,"message":"Not authorized"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Forbidden"}}}},"404":{"description":"Payment not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"extras":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}},"example":{"error":"Not found","extras":{"status":404,"message":"Resource not found"}}}}}}} | ||
| > | ||
|
|
||
| </StatusCodes> |
122 changes: 122 additions & 0 deletions
122
...tforms/stellar-disbursement-platform/api-reference/get-statement-export.api.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| --- | ||
| id: get-statement-export | ||
| title: "Get Statement (PDF)" | ||
| description: "Returns a ledger-style PDF for the authenticated tenant's distribution account over the given date range. The PDF is built with gofpdf (multi-page, A4). Only supported for Stellar (non-Circle) distribution accounts; returns 400 if the account is not Stellar." | ||
| sidebar_label: "Get Statement (PDF)" | ||
| hide_title: true | ||
| hide_table_of_contents: true | ||
| api: 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 | ||
| sidebar_class_name: "get api-method" | ||
| info_path: docs/platforms/stellar-disbursement-platform/api-reference/stellar-disbursement-platform-api | ||
| custom_edit_url: null | ||
| --- | ||
|
|
||
| import { SepBadge } from "@site/src/components/SepBadge"; | ||
|
|
||
| <SepBadge tags={''} /> | ||
|
|
||
| import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; | ||
| import ParamsDetails from "@theme/ParamsDetails"; | ||
| import RequestSchema from "@theme/RequestSchema"; | ||
| import StatusCodes from "@theme/StatusCodes"; | ||
| import OperationTabs from "@theme/OperationTabs"; | ||
| import TabItem from "@theme/TabItem"; | ||
| import Heading from "@theme/Heading"; | ||
|
|
||
| <Heading | ||
| as={"h1"} | ||
| className={"openapi__heading"} | ||
| children={"Get Statement (PDF)"} | ||
| > | ||
| </Heading> | ||
|
|
||
| <MethodEndpoint | ||
| method={"get"} | ||
| path={"/reports/statement"} | ||
| context={"endpoint"} | ||
| > | ||
|
|
||
| </MethodEndpoint> | ||
|
|
||
|
|
||
|
|
||
| Returns a ledger-style PDF for the authenticated tenant's distribution account over the given date range. The PDF is built with gofpdf (multi-page, A4). Only supported for Stellar (non-Circle) distribution accounts; returns 400 if the account is not Stellar. | ||
|
|
||
| ## Fields in the generated PDF | ||
|
|
||
| The following tables describe the fields that appear in the statement PDF, how they are calculated (when applicable), and whether the value comes from the **DB**, **Horizon**, or **Request**. Tables are grouped by source. | ||
|
|
||
| ### Request | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Statement period (from / to) | Date range of the statement | Request (`from_date`, `to_date`) | | ||
|
|
||
| ### Context | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Wallet address | Distribution account Stellar address | Context (distribution account) | | ||
| | Account (summary) | Same as wallet address, prefixed `stellar:` | Context (distribution account) | | ||
|
|
||
| ### Calculated | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Beginning balance (per asset) | `ending_balance` − `total_credits` + `total_debits`; clamped to ≥ 0 | Calculated from Horizon totals | | ||
| | Total credits (per asset) | Sum of credit amounts in range from payment-like operations | Calculated from Horizon transactions in range | | ||
| | Total debits (per asset) | Sum of debit amounts in range from payment-like operations | Calculated from Horizon transactions in range | | ||
| | Ending balance (per asset) | `current_balance` − `credits_after_period` + `debits_after_period` | Calculated (Horizon `GetBalance` + totals after period) | | ||
| | Running balance (per row) | Beginning balance ± credits/debits up to that row | Calculated in PDF | | ||
|
|
||
| ### DB | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Organization name, logo | Shown in header | `Organizations` | | ||
| | Transaction line: Updated at | Success timestamp when payment matched by `tx` hash | `Payment.status_history` | | ||
| | Transaction line: Counterparty name | Receiver external ID when resolved by Stellar address | `ReceiverWallet.Receiver` | | ||
| | Transaction line: External payment ID | From payment record when matched by `tx` hash + `operation_id` | `Payment` | | ||
| | Asset list (when no `asset_code`) | Non-native assets with balance | `Assets` | | ||
|
|
||
| ### Horizon | ||
|
|
||
| | Field | Description | Source | | ||
| | ----- | --------------------------- | ------ | | ||
| | Transaction line: ID | Stellar transaction hash | Horizon (transactions in range) | | ||
| | Transaction line: Created at | Ledger close time of the transaction | Horizon | | ||
| | Transaction line: Type | `credit` or `debit` (derived from `from`/`to`) | Horizon | | ||
| | Transaction line: Amount | Operation amount | Horizon | | ||
| | Transaction line: Counterparty address | Other account in the payment operation | Horizon | | ||
| | Asset list (when no `asset_code`) | Assets with balance on distribution account | Horizon (`GetBalances`) | | ||
|
|
||
| <Heading | ||
| id={"request"} | ||
| as={"h2"} | ||
| className={"openapi-tabs__heading"} | ||
| children={"Request"} | ||
| > | ||
| </Heading> | ||
|
|
||
| <ParamsDetails | ||
| parameters={[{"name":"from_date","in":"query","description":"Start date of the statement (inclusive). Format YYYY-MM-DD.","required":true,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"example":"2025-01-01"},{"name":"to_date","in":"query","description":"End date of the statement (inclusive). Must be greater than or equal to from_date. Format YYYY-MM-DD.","required":true,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"example":"2025-01-31"},{"name":"asset_code","in":"query","description":"Filter by asset code (e.g. USDC). Omit or leave empty for all assets.","required":false,"style":"form","explode":true,"schema":{"type":"string"}},{"name":"base_url","in":"query","description":"Base URL used in the PDF for \"Operated by\" and footer links.","required":false,"style":"form","explode":true,"schema":{"type":"string"}}]} | ||
| > | ||
|
|
||
| </ParamsDetails> | ||
|
|
||
| <RequestSchema | ||
| title={"Body"} | ||
| body={undefined} | ||
| > | ||
|
|
||
| </RequestSchema> | ||
|
|
||
| <StatusCodes | ||
| id={undefined} | ||
| label={undefined} | ||
| responses={{"200":{"description":"PDF file (statement_YYYYMMDD-YYYYMMDD.pdf)","headers":{"Content-Disposition":{"description":"Filename of the returned PDF file.","style":"simple","explode":false,"schema":{"type":"string"}},"Content-Type":{"description":"application/pdf","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"example":""}}},"400":{"description":"Invalid query parameters or statement is only supported for Stellar distribution accounts","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Details about the error"},"extras":{"type":"object","properties":{}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"extras":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}},"example":{"error":"Not authorized","extras":{"status":401,"message":"Not authorized"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Forbidden"}}}},"404":{"description":"Asset not found for account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"extras":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}},"example":{"error":"Not found","extras":{"status":404,"message":"Resource not found"}}}}}}} | ||
| > | ||
|
|
||
| </StatusCodes> | ||
|
|
||
|
|
20 changes: 20 additions & 0 deletions
20
docs/platforms/stellar-disbursement-platform/api-reference/reports.tag.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| id: reports | ||
| title: "Reports" | ||
| description: "Reports" | ||
| custom_edit_url: null | ||
| --- | ||
|
|
||
|
|
||
|
|
||
| Reports endpoints return PDF documents: a multi-page ledger-style wallet statement and a single-page transaction notice per payment. Each PDF includes the organization name and logo. | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ```mdx-code-block | ||
| import DocCardList from '@theme/DocCardList'; | ||
| import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; | ||
|
|
||
| <DocCardList items={useCurrentSidebarCategory().items}/> | ||
| ``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.