Wallet Endpoints¶

Wallet API endpoints.

Overview¶

Method	Endpoint	Description
GET	`/api/v1/organizations/{organization_id}/billing/rollup`	Get Organization Billing Rollup
GET	`/api/v1/organizations/{organization_id}/wallet`	Get Organization Wallet
POST	`/api/v1/organizations/{organization_id}/wallet`	Create Organization Wallet
POST	`/api/v1/organizations/{organization_id}/wallet/entries`	Create Organization Wallet Entry
DELETE	`/api/v1/organizations/{organization_id}/wallet/entries/{entry_id}`	Delete Organization Wallet Entry
GET	`/api/v1/organizations/{organization_id}/wallet/ledger`	Get Organization Wallet Ledger

API Reference¶

Sartiq Backend Server - Wallet 0.1.0¶

wallet¶

GET /api/v1/organizations/{organization_id}/wallet¶

Get Organization Wallet

Description

Wallet balance in tokens: granted / burned / in-flight estimate / available, plus the Annex A rate-card panel.

The in-flight figure is an estimate: shots currently in REVIEW/PROPOSAL x default-grade rate x 0.85 (the pools.json realistic factor).

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OAuth2PasswordBearer`	header	string	N/A	No
`organization_id`	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "anyOf": [
        {
            "$ref": "#/components/schemas/TokenWalletSuperuserPublic"
        },
        {
            "$ref": "#/components/schemas/TokenWalletPublic"
        }
    ],
    "title": "Response Get Organization Wallet"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /api/v1/organizations/{organization_id}/wallet¶

Create Organization Wallet

Description

Create the organization's wallet plus its initial GRANT entry. Superuser only.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OAuth2PasswordBearer`	header	string	N/A	No
`organization_id`	path	string		No

Request body

application/json

{
    "name": "string",
    "granted_tokens": 0,
    "effective_rate": null,
    "currency": "string",
    "starts_at": null,
    "expires_at": null,
    "rollover_until": null,
    "default_grade": "EXPRESS"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "name": {
            "type": "string",
            "maxLength": 255,
            "title": "Name"
        },
        "granted_tokens": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Granted Tokens"
        },
        "effective_rate": {
            "anyOf": [
                {
                    "type": "number"
                },
                {
                    "type": "string",
                    "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
                }
            ],
            "title": "Effective Rate",
            "default": "1.00"
        },
        "currency": {
            "type": "string",
            "maxLength": 3,
            "title": "Currency",
            "default": "EUR"
        },
        "starts_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Starts At"
        },
        "expires_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Expires At"
        },
        "rollover_until": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Rollover Until"
        },
        "default_grade": {
            "$ref": "#/components/schemas/WalletGrade",
            "default": "STUDIO"
        }
    },
    "type": "object",
    "required": [
        "name",
        "granted_tokens"
    ],
    "title": "TokenWalletCreate",
    "description": "Superuser payload to create an organization wallet."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "046f5e3b-f4f3-44bf-bce3-bda95b0aae3f",
    "organization_id": "adbea943-2a8d-4fff-816a-7657c0194402",
    "name": "string",
    "status": "ACTIVE",
    "default_grade": "EXPRESS",
    "starts_at": null,
    "expires_at": null,
    "rollover_until": null,
    "granted_tokens": 0,
    "burned_tokens": 0,
    "in_flight_tokens": 0,
    "available_tokens": 0,
    "rate_card": {},
    "effective_rate": "string",
    "currency": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "organization_id": {
            "type": "string",
            "format": "uuid",
            "title": "Organization Id"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "status": {
            "$ref": "#/components/schemas/WalletStatus"
        },
        "default_grade": {
            "$ref": "#/components/schemas/WalletGrade"
        },
        "starts_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Starts At"
        },
        "expires_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Expires At"
        },
        "rollover_until": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Rollover Until"
        },
        "granted_tokens": {
            "type": "integer",
            "title": "Granted Tokens"
        },
        "burned_tokens": {
            "type": "integer",
            "title": "Burned Tokens"
        },
        "in_flight_tokens": {
            "type": "integer",
            "title": "In Flight Tokens"
        },
        "available_tokens": {
            "type": "integer",
            "title": "Available Tokens"
        },
        "rate_card": {
            "additionalProperties": {
                "type": "integer"
            },
            "type": "object",
            "title": "Rate Card"
        },
        "effective_rate": {
            "type": "string",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Effective Rate"
        },
        "currency": {
            "type": "string",
            "title": "Currency"
        }
    },
    "type": "object",
    "required": [
        "id",
        "organization_id",
        "name",
        "status",
        "default_grade",
        "granted_tokens",
        "burned_tokens",
        "in_flight_tokens",
        "available_tokens",
        "rate_card",
        "effective_rate",
        "currency"
    ],
    "title": "TokenWalletSuperuserPublic",
    "description": "Superuser wallet view — adds the commercial terms."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /api/v1/organizations/{organization_id}/wallet/ledger¶

Get Organization Wallet Ledger

Description

Paginated token ledger — the contractual consumption record, in tokens.

Input parameters

Parameter	In	Type	Default	Nullable
`OAuth2PasswordBearer`	header	string	N/A	No
`entry_type`	query			No
`from`	query			No
`limit`	query	integer	50	No
`organization_id`	path	string		No
`skip`	query	integer	0	No
`to`	query			No

Responses

200 OK422 Unprocessable Entity

application/json

⚠️ This example has been generated automatically href="#__codelineno-9-1">{ "data": [ { "id": "4db07321-e45e-41be-82e4-3800bde819de", "wallet_id": "e4826a06-ebc0-43a7-ba12-0e8d38b71738", "organization_id": "58bdd7dd-7b2c-48f1-9854-fa9e11343f87", "delta": 0, "entry_type": "GRANT", "deliverable_type": null, "shot_id": null, "shot_revision_id": null, "production_request_id": null, "generation_id": null, "quantity": 0, "is_manual": true, "note": null, "created_by": null, "created_at": "2022-04-13T15:42:05.901Z" } ], "count": 0 } from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/TokenLedgerEntryPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "TokenLedgerEntriesPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /api/v1/organizations/{organization_id}/billing/rollup¶

Get Organization Billing Rollup

Description

Org roll-up of the per-shooting billing meter (§7.4 of the metering proposal): every shooting's derived gross/net tokens, plus a per-PO grouping of net tokens. Reuses the same per-shooting counting the /shootings/{id}/billing/summary endpoint uses, so the roll-up and the leaf view can never diverge. Billing-role gated via BillingOrganizationDep.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OAuth2PasswordBearer`	header	string	N/A	No
`organization_id`	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "organization_id": "dffc31c9-1f96-4298-b4de-9f2438e1e9f7",
    "shootings": [
        {
            "shooting_id": "7012c1f2-44f0-4910-85a7-411547a72658",
            "name": "string",
            "billing_state": null,
            "billing_metering_rule": null,
            "po_tag": null,
            "tokens_gross": 10.12,
            "tokens_billable": null
        }
    ],
    "by_po": [
        {
            "po_tag": null,
            "tokens_billable": 10.12,
            "shooting_count": 0
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "organization_id": {
            "type": "string",
            "format": "uuid",
            "title": "Organization Id"
        },
        "shootings": {
            "items": {
                "$ref": "#/components/schemas/OrgBillingRollupShooting"
            },
            "type": "array",
            "title": "Shootings"
        },
        "by_po": {
            "items": {
                "$ref": "#/components/schemas/OrgBillingRollupByPo"
            },
            "type": "array",
            "title": "By Po"
        }
    },
    "type": "object",
    "required": [
        "organization_id",
        "shootings",
        "by_po"
    ],
    "title": "OrgBillingRollup",
    "description": "Org-level roll-up: every shooting's meter plus a per-PO grouping."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /api/v1/organizations/{organization_id}/wallet/entries¶

Create Organization Wallet Entry

Description

Manual ledger entry: top-up, adjustment, or off-platform burn (deliverable_type x quantity). Superuser only.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OAuth2PasswordBearer`	header	string	N/A	No
`organization_id`	path	string		No

Request body

application/json

{
    "entry_type": "GRANT",
    "tokens": null,
    "deliverable_type": null,
    "quantity": 0,
    "note": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "entry_type": {
            "$ref": "#/components/schemas/LedgerEntryType"
        },
        "tokens": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Tokens"
        },
        "deliverable_type": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/DeliverableType"
                },
                {
                    "type": "null"
                }
            ]
        },
        "quantity": {
            "type": "integer",
            "minimum": 1.0,
            "title": "Quantity",
            "default": 1
        },
        "note": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 1000
                },
                {
                    "type": "null"
                }
            ],
            "title": "Note"
        }
    },
    "type": "object",
    "required": [
        "entry_type"
    ],
    "title": "TokenLedgerEntryCreate",
    "description": "Superuser payload for manual ledger entries.\n\n- ``BURN``: off-platform burn, requires ``deliverable_type``;\n  delta = -(rate card x quantity).\n- ``TOP_UP`` / ``ADJUSTMENT``: requires explicit ``tokens`` delta."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "cd10d686-e6a4-4db9-aaa8-1b1bceb8af16",
    "wallet_id": "c0b28880-5bba-4421-a99d-c7b9061d88bf",
    "organization_id": "8fe6f7b9-a2b8-49fb-9e46-a0df23db960d",
    "delta": 0,
    "entry_type": "GRANT",
    "deliverable_type": null,
    "shot_id": null,
    "shot_revision_id": null,
    "production_request_id": null,
    "generation_id": null,
    "quantity": 0,
    "is_manual": true,
    "note": null,
    "created_by": null,
    "created_at": "2022-04-13T15:42:05.901Z"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "wallet_id": {
            "type": "string",
            "format": "uuid",
            "title": "Wallet Id"
        },
        "organization_id": {
            "type": "string",
            "format": "uuid",
            "title": "Organization Id"
        },
        "delta": {
            "type": "integer",
            "title": "Delta"
        },
        "entry_type": {
            "$ref": "#/components/schemas/LedgerEntryType"
        },
        "deliverable_type": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/DeliverableType"
                },
                {
                    "type": "null"
                }
            ]
        },
        "shot_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Shot Id"
        },
        "shot_revision_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Shot Revision Id"
        },
        "production_request_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Production Request Id"
        },
        "generation_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Generation Id"
        },
        "quantity": {
            "type": "integer",
            "title": "Quantity"
        },
        "is_manual": {
            "type": "boolean",
            "title": "Is Manual"
        },
        "note": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Note"
        },
        "created_by": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created By"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        }
    },
    "type": "object",
    "required": [
        "id",
        "wallet_id",
        "organization_id",
        "delta",
        "entry_type",
        "quantity",
        "is_manual",
        "created_at"
    ],
    "title": "TokenLedgerEntryPublic",
    "description": "Ledger entry — tokens only (no commercial terms exist on entries)."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

DELETE /api/v1/organizations/{organization_id}/wallet/entries/{entry_id}¶

Delete Organization Wallet Entry

Description

Delete a manual ledger entry (correction tool). Superuser only; automatic production burns cannot be deleted.

Input parameters

Parameter	In	Type	Default	Nullable
`OAuth2PasswordBearer`	header	string	N/A	No
`entry_id`	path	string		No
`organization_id`	path	string		No

Responses

204 No Content422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Schemas¶

DeliverableType¶

Type: string

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

LedgerEntryType¶

Type: string

OrgBillingRollup¶

Name	Type	Description
`by_po`	Array<OrgBillingRollupByPo>
`organization_id`	string(uuid)
`shootings`	Array<OrgBillingRollupShooting>

OrgBillingRollupByPo¶

Name	Type	Description
`po_tag`
`shooting_count`	integer
`tokens_billable`	number

OrgBillingRollupShooting¶

Name	Type	Description
`billing_metering_rule`
`billing_state`
`name`	string
`po_tag`
`shooting_id`	string(uuid)
`tokens_billable`
`tokens_gross`	number

TokenLedgerEntriesPublic¶

Name	Type	Description
`count`	integer
`data`	Array<TokenLedgerEntryPublic>

TokenLedgerEntryCreate¶

Name	Type	Description
`deliverable_type`
`entry_type`	LedgerEntryType
`note`
`quantity`	integer
`tokens`

TokenLedgerEntryPublic¶

Name	Type	Description
`created_at`	string(date-time)
`created_by`
`deliverable_type`
`delta`	integer
`entry_type`	LedgerEntryType
`generation_id`
`id`	string(uuid)
`is_manual`	boolean
`note`
`organization_id`	string(uuid)
`production_request_id`
`quantity`	integer
`shot_id`
`shot_revision_id`
`wallet_id`	string(uuid)

TokenWalletCreate¶

Name	Type	Description
`currency`	string
`default_grade`	WalletGrade
`effective_rate`
`expires_at`
`granted_tokens`	integer
`name`	string
`rollover_until`
`starts_at`

TokenWalletPublic¶

Name	Type	Description
`available_tokens`	integer
`burned_tokens`	integer
`default_grade`	WalletGrade
`expires_at`
`granted_tokens`	integer
`id`	string(uuid)
`in_flight_tokens`	integer
`name`	string
`organization_id`	string(uuid)
`rate_card`
`rollover_until`
`starts_at`
`status`	WalletStatus

TokenWalletSuperuserPublic¶

Name	Type	Description
`available_tokens`	integer
`burned_tokens`	integer
`currency`	string
`default_grade`	WalletGrade
`effective_rate`	string
`expires_at`
`granted_tokens`	integer
`id`	string(uuid)
`in_flight_tokens`	integer
`name`	string
`organization_id`	string(uuid)
`rate_card`
`rollover_until`
`starts_at`
`status`	WalletStatus

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string

WalletGrade¶

Type: string

WalletStatus¶

Type: string

Security schemes¶

Name	Type	Scheme	Description
OAuth2PasswordBearer	oauth2