You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
827 lines
21 KiB
827 lines
21 KiB
---
|
|
swagger: "2.0"
|
|
host: "localhost:8000"
|
|
basePath: "/api/v1.0"
|
|
info:
|
|
description: An API which supports creation, deletion, listing etc of Billing
|
|
version: "1.0.0"
|
|
title: Billing Management API
|
|
contact:
|
|
email: diego@cyclops-labs.io
|
|
license:
|
|
name: Apache 2.0
|
|
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
|
|
|
|
tags:
|
|
- name: statusManagement
|
|
description: Actions relating to the reporting of the state of the service
|
|
- name: triggerManagement
|
|
description: Actions relating to the periodics actions to be triggered in the system
|
|
- name: bulkManagement
|
|
description: Actions relating to the bulk generations/retrieval of invoices.
|
|
- name: invoiceManagement
|
|
description: Actions relating to the generation and retrieval of invoices.
|
|
|
|
securityDefinitions:
|
|
APIKeyHeader:
|
|
type: apiKey
|
|
in: header
|
|
name: X-API-KEY
|
|
APIKeyParam:
|
|
type: apiKey
|
|
in: query
|
|
name: api_key
|
|
Keycloak:
|
|
type: oauth2
|
|
flow: accessCode
|
|
authorizationUrl: 'http://localhost:8080/auth/realms/Dev/protocol/openid-connect/auth'
|
|
tokenUrl: 'http://localhost:8080/auth/realms/Dev/protocol/openid-connect/token'
|
|
scopes:
|
|
admin: Admin scope
|
|
user: User scope
|
|
|
|
schemes:
|
|
- http
|
|
- https
|
|
|
|
security:
|
|
- Keycloak: [user,admin]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
|
|
paths:
|
|
/status:
|
|
get:
|
|
tags:
|
|
- statusManagement
|
|
produces:
|
|
- application/json
|
|
summary: Basic status of the system
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: showStatus
|
|
responses:
|
|
'200':
|
|
description: Status information of the system
|
|
schema:
|
|
$ref: "#/definitions/Status"
|
|
/status/{id}:
|
|
get:
|
|
tags:
|
|
- statusManagement
|
|
produces:
|
|
- application/json
|
|
summary: Basic status of the system
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: getStatus
|
|
responses:
|
|
'200':
|
|
description: Status information of the system
|
|
schema:
|
|
$ref: "#/definitions/Status"
|
|
'404':
|
|
description: The endpoint provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: string
|
|
enum:
|
|
- kafka-receiver
|
|
- kafka-sender
|
|
- status
|
|
- trigger
|
|
- bulk
|
|
- invoice
|
|
required: true
|
|
description: Id of the endpoint to be checked
|
|
|
|
/trigger/periodicrun:
|
|
get:
|
|
tags:
|
|
- triggerManagement
|
|
produces:
|
|
- application/json
|
|
summary: Periodic run of the bulk generation of invoices
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: periodicRun
|
|
responses:
|
|
'202':
|
|
description: The request for processing the periodic run had been added to the queue
|
|
schema:
|
|
$ref: "#/definitions/ItemCreatedResponse"
|
|
parameters:
|
|
- name: today
|
|
in: query
|
|
description: Datetime to override the time.now() to simulate other days
|
|
type: string
|
|
format: datetime
|
|
|
|
/billrun:
|
|
get:
|
|
tags:
|
|
- bulkManagement
|
|
produces:
|
|
- application/json
|
|
summary: Show the status report of the billruns present in the system
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ListBillRuns
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/BillRunList"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: months
|
|
in: query
|
|
description: Amount of months to have in the report
|
|
type: integer
|
|
put:
|
|
tags:
|
|
- bulkManagement
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
summary: Try to re-run the failed invoices in all the billruns.
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ReRunAllBillRuns
|
|
responses:
|
|
'202':
|
|
description: The request for processing had been added to the queue
|
|
schema:
|
|
$ref: "#/definitions/ItemCreatedResponse"
|
|
'404':
|
|
description: The invoice id provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: months
|
|
in: query
|
|
description: Amount of months to check for failed invoices.
|
|
type: integer
|
|
/billrun/{id}:
|
|
get:
|
|
tags:
|
|
- bulkManagement
|
|
produces:
|
|
- application/json
|
|
summary: Get the status report of the billrun requested
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: GetBillRun
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
$ref: "#/definitions/BillRunReport"
|
|
'404':
|
|
description: The invoice id provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the invoice to be checked
|
|
required: true
|
|
type: string
|
|
format: uuid
|
|
put:
|
|
tags:
|
|
- bulkManagement
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
summary: Try to re-run the failed invoices in the billrun.
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ReRunBillRun
|
|
responses:
|
|
'202':
|
|
description: The request for processing had been added to the queue
|
|
schema:
|
|
$ref: "#/definitions/ItemCreatedResponse"
|
|
'404':
|
|
description: The invoice id provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the billrun to be re-run.
|
|
required: true
|
|
type: string
|
|
format: uuid
|
|
/billrun/organization/{id}:
|
|
get:
|
|
tags:
|
|
- bulkManagement
|
|
produces:
|
|
- application/json
|
|
summary: Show the status report of the billruns present in the system
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ListBillRunsByOrganization
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/BillRunList"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the billrun to be re-run.
|
|
required: true
|
|
type: string
|
|
- name: months
|
|
in: query
|
|
description: Amount of months to have in the report
|
|
type: integer
|
|
|
|
/invoice:
|
|
get:
|
|
tags:
|
|
- invoiceManagement
|
|
produces:
|
|
- application/json
|
|
summary: Summary for this endpoint
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ListInvoices
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Invoice"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: model
|
|
in: body
|
|
description: Invoice model partially filled to use for the filtering of the invoices
|
|
schema:
|
|
$ref: "#/definitions/Invoice"
|
|
/invoice/{id}:
|
|
get:
|
|
tags:
|
|
- invoiceManagement
|
|
produces:
|
|
- application/json
|
|
summary: Summary for this endpoint
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: GetInvoice
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
$ref: "#/definitions/Invoice"
|
|
'404':
|
|
description: The invoice id provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the invoice to be checked
|
|
required: true
|
|
type: string
|
|
format: uuid
|
|
|
|
/invoice/reseller:
|
|
get:
|
|
tags:
|
|
- invoiceManagement
|
|
produces:
|
|
- application/json
|
|
summary: Retrieve resellers' invoices
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ListResellerInvoices
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Invoice"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
/invoice/reseller/{id}:
|
|
get:
|
|
tags:
|
|
- invoiceManagement
|
|
produces:
|
|
- application/json
|
|
summary: Retrieve invoices by reseller id
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: GetInvoicesByReseller
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Invoice"
|
|
'404':
|
|
description: The invoice id provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the account to be checked
|
|
required: true
|
|
type: string
|
|
- name: months
|
|
in: query
|
|
description: Amount of months to have in the report
|
|
type: integer
|
|
post:
|
|
tags:
|
|
- invoiceManagement
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
summary: Generate invoice for the provided reseller for the provided time window or last period
|
|
security:
|
|
- Keycloak: [admin]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: GenerateInvoiceForReseller
|
|
responses:
|
|
'202':
|
|
description: The request for processing had been added to the queue
|
|
schema:
|
|
$ref: "#/definitions/ItemCreatedResponse"
|
|
'400':
|
|
description: Invalid input, object invalid
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the account to be checked
|
|
required: true
|
|
type: string
|
|
- name: from
|
|
in: query
|
|
description: Datetime from which to generate the invoice
|
|
type: string
|
|
format: datetime
|
|
- name: to
|
|
in: query
|
|
description: Datetime until which to generate the invoice
|
|
type: string
|
|
format: datetime
|
|
|
|
/invoice/customer:
|
|
get:
|
|
tags:
|
|
- invoiceManagement
|
|
produces:
|
|
- application/json
|
|
summary: Retrieve customers' invoices
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: ListCustomerInvoices
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Invoice"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
/invoice/customer/{id}:
|
|
get:
|
|
tags:
|
|
- invoiceManagement
|
|
produces:
|
|
- application/json
|
|
summary: Retrieve invoices by customer id
|
|
security:
|
|
- Keycloak: [user]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: GetInvoicesByCustomer
|
|
responses:
|
|
'200':
|
|
description: Description of a successfully operation
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Invoice"
|
|
'404':
|
|
description: The invoice id provided doesn't exist
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the account to be checked
|
|
required: true
|
|
type: string
|
|
- name: months
|
|
in: query
|
|
description: Amount of months to have in the report
|
|
type: integer
|
|
post:
|
|
tags:
|
|
- invoiceManagement
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
summary: Generate invoice for the provided customer for the provided time window or last period
|
|
security:
|
|
- Keycloak: [admin]
|
|
- APIKeyHeader: []
|
|
- APIKeyParam: []
|
|
operationId: GenerateInvoiceForCustomer
|
|
responses:
|
|
'202':
|
|
description: The request for processing had been added to the queue
|
|
schema:
|
|
$ref: "#/definitions/ItemCreatedResponse"
|
|
'400':
|
|
description: Invalid input, object invalid
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
'500':
|
|
description: Something unexpected happend, error raised
|
|
schema:
|
|
$ref: "#/definitions/ErrorResponse"
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Id of the account to be checked
|
|
required: true
|
|
type: string
|
|
- name: from
|
|
in: query
|
|
description: Datetime from which to generate the invoice
|
|
type: string
|
|
format: datetime
|
|
- name: to
|
|
in: query
|
|
description: Datetime until which to generate the invoice
|
|
type: string
|
|
format: datetime
|
|
|
|
definitions:
|
|
ErrorResponse:
|
|
type: object
|
|
required:
|
|
- errorString
|
|
properties:
|
|
errorString:
|
|
type: string
|
|
ItemCreatedResponse:
|
|
properties:
|
|
ApiLink:
|
|
type: string
|
|
Message:
|
|
type: string
|
|
Metadata:
|
|
type: object
|
|
x-go-type:
|
|
import:
|
|
package: "gitlab.com/cyclops-enterprise/datamodels"
|
|
type: JSONdb
|
|
StringArray:
|
|
x-go-type:
|
|
import:
|
|
package: "github.com/lib/pq"
|
|
type: StringArray
|
|
Status:
|
|
type: object
|
|
required:
|
|
- SystemState
|
|
properties:
|
|
AverageResponseTime:
|
|
type: number
|
|
format: double
|
|
DBState:
|
|
type: string
|
|
LastRequest:
|
|
type: string
|
|
RequestsBoT:
|
|
type: integer
|
|
RequestsLastHour:
|
|
type: integer
|
|
RequestsToday:
|
|
type: integer
|
|
SystemState:
|
|
type: string
|
|
|
|
BillRun:
|
|
type: object
|
|
properties:
|
|
ID:
|
|
type: string
|
|
format: uuid
|
|
x-go-custom-tag: gorm:"type:uuid;primary_key;unique;default:md5(random()::text || clock_timestamp()::text)::uuid"
|
|
AmountInvoiced:
|
|
type: number
|
|
format: double
|
|
default: 0.0
|
|
x-go-custom-tag: gorm:"type:numeric(23,13)"
|
|
CreationTimestamp:
|
|
type: string
|
|
format: date-time
|
|
x-go-custom-tag: gorm:"type:timestamptz"
|
|
InvoicesCount:
|
|
type: integer
|
|
InvoicesErrorCount:
|
|
type: integer
|
|
InvoicesErrorList:
|
|
$ref: '#/definitions/StringArray'
|
|
x-go-custom-tag: gorm:"type:text[]"
|
|
InvoicesList:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/InvoiceMetadata'
|
|
x-go-custom-tag: gorm:"-"
|
|
InvoicesProcessedCount:
|
|
type: integer
|
|
OrganizationsInvolved:
|
|
$ref: '#/definitions/StringArray'
|
|
x-go-custom-tag: gorm:"type:text[]"
|
|
Status:
|
|
type: string
|
|
default: QUEUED
|
|
enum:
|
|
- ERROR
|
|
- FINISHED
|
|
- PROCESSING
|
|
- QUEUED
|
|
x-go-custom-tag: gorm:"default:QUEUED"
|
|
ExecutionType:
|
|
type: string
|
|
|
|
BillRunList:
|
|
type: object
|
|
properties:
|
|
ID:
|
|
type: string
|
|
format: uuid
|
|
AmountInvoiced:
|
|
type: number
|
|
format: double
|
|
default: 0.0
|
|
CreationTimestamp:
|
|
type: string
|
|
format: date-time
|
|
InvoicesCount:
|
|
type: integer
|
|
InvoicesErrorCount:
|
|
type: integer
|
|
InvoicesErrorList:
|
|
$ref: '#/definitions/StringArray'
|
|
x-go-custom-tag: gorm:"type:text[]"
|
|
InvoicesProcessedCount:
|
|
type: integer
|
|
OrganizationsInvolved:
|
|
$ref: '#/definitions/StringArray'
|
|
x-go-custom-tag: gorm:"type:text[]"
|
|
Status:
|
|
type: string
|
|
default: QUEUED
|
|
enum:
|
|
- ERROR
|
|
- FINISHED
|
|
- PROCESSING
|
|
- QUEUED
|
|
|
|
BillRunReport:
|
|
type: object
|
|
properties:
|
|
ID:
|
|
type: string
|
|
format: uuid
|
|
AmountInvoiced:
|
|
type: number
|
|
format: double
|
|
default: 0.0
|
|
CreationTimestamp:
|
|
type: string
|
|
format: date-time
|
|
InvoicesCount:
|
|
type: integer
|
|
InvoicesErrorCount:
|
|
type: integer
|
|
InvoicesErrorList:
|
|
$ref: '#/definitions/StringArray'
|
|
x-go-custom-tag: gorm:"type:text[]"
|
|
InvoicesList:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/InvoiceMetadata'
|
|
x-go-custom-tag: gorm:"-"
|
|
InvoicesProcessedCount:
|
|
type: integer
|
|
Status:
|
|
type: string
|
|
default: QUEUED
|
|
enum:
|
|
- ERROR
|
|
- FINISHED
|
|
- PROCESSING
|
|
- QUEUED
|
|
|
|
Invoice:
|
|
type: object
|
|
properties:
|
|
ID:
|
|
type: string
|
|
format: uuid
|
|
x-go-custom-tag: gorm:"type:uuid;primary_key;unique;default:md5(random()::text || clock_timestamp()::text)::uuid"
|
|
AmountInvoiced:
|
|
type: number
|
|
format: double
|
|
default: 0.0
|
|
x-go-custom-tag: gorm:"type:numeric(23,13)"
|
|
BillingContact:
|
|
type: string
|
|
BillRunID:
|
|
type: string
|
|
format: uuid
|
|
Currency:
|
|
type: string
|
|
default: CHF
|
|
enum:
|
|
- CHF
|
|
- EUR
|
|
- USD
|
|
GenerationTimestamp:
|
|
type: string
|
|
format: date-time
|
|
x-go-custom-tag: gorm:"type:timestamptz"
|
|
Items:
|
|
$ref: '#/definitions/Metadata'
|
|
x-go-custom-tag: gorm:"type:jsonb"
|
|
OrganizationID:
|
|
type: string
|
|
OrganizationName:
|
|
type: string
|
|
OrganizationType:
|
|
type: string
|
|
PaymentDeadline:
|
|
type: string
|
|
format: date
|
|
x-go-custom-tag: gorm:"type:date"
|
|
PaymentStatus:
|
|
type: string
|
|
default: UNPAID
|
|
enum:
|
|
- CANCELLED
|
|
- PAID
|
|
- UNPAID
|
|
PeriodEndDate:
|
|
type: string
|
|
format: date
|
|
x-go-custom-tag: gorm:"type:date"
|
|
PeriodStartDate:
|
|
type: string
|
|
format: date
|
|
x-go-custom-tag: gorm:"type:date"
|
|
Status:
|
|
type: string
|
|
default: NOT_PROCESSED
|
|
enum:
|
|
- ERROR
|
|
- FINISHED
|
|
- NOT_PROCESSED
|
|
- PROCESSING
|
|
x-go-custom-tag: gorm:"default:NOT_PROCESSED"
|
|
|
|
InvoiceMetadata:
|
|
type: object
|
|
properties:
|
|
ID:
|
|
type: string
|
|
format: uuid
|
|
AmountInvoiced:
|
|
type: number
|
|
format: double
|
|
default: 0.0
|
|
Currency:
|
|
type: string
|
|
default: CHF
|
|
enum:
|
|
- CHF
|
|
- EUR
|
|
- USD
|
|
OrganizationID:
|
|
type: string
|
|
OrganizationName:
|
|
type: string
|
|
PaymentDeadline:
|
|
type: string
|
|
format: date
|
|
PaymentStatus:
|
|
type: string
|
|
default: UNPAID
|
|
enum:
|
|
- CANCELLED
|
|
- PAID
|
|
- UNPAID
|
|
PeriodEndDate:
|
|
type: string
|
|
format: date
|
|
PeriodStartDate:
|
|
type: string
|
|
format: date
|
|
Status:
|
|
type: string
|
|
default: NOT_PROCESSED
|
|
enum:
|
|
- ERROR
|
|
- FINISHED
|
|
- NOT_PROCESSED
|
|
- PROCESSING
|
|
|
|
|