openapi: 3.0.3
info:
  title: CedCast Developer API
  description: |
    High-throughput RESTful API for SMS dispatch, wallet balance inquiry, delivery updates, and contact management across West African telecommunication networks.
  version: 1.0.0
  contact:
    name: CedCast API Support
    email: support@cedcast.com
servers:
  - url: https://api.cedcast.com
    description: Production API Server
  - url: http://127.0.0.1:8000
    description: Sandbox / Local Development Server

paths:
  /api/v1/auth/token/:
    post:
      summary: Obtain API Authentication Token
      description: Retrieve a persistent API token using account credentials.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  example: "api_user_account"
                password:
                  type: string
                  format: password
                  example: "SecretPassword123"
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  token:
                    type: string
                    example: "9944b09199c62bcf9418ad846d0e4ebc01523f31"
                  user_id:
                    type: integer
                    example: 42
                  username:
                    type: string
                    example: "api_user_account"
                  organization:
                    type: string
                    example: "Enterprise Account"
        '400':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/balance/:
    get:
      summary: Query Wallet Balance & Rates
      description: Retrieve current organization wallet balance, active currency, and per-SMS billing rates.
      tags:
        - Account & Balance
      security:
        - TokenAuth: []
      responses:
        '200':
          description: Wallet balance retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    type: string
                    example: "Enterprise Account"
                  balance:
                    type: string
                    example: "1500.50"
                  currency:
                    type: string
                    example: "GHS"
                  current_sms_rate:
                    type: string
                    example: "0.038"
        '401':
          description: Unauthorized / Missing Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/messages/:
    get:
      summary: List Dispatched Messages
      description: Retrieve history of messages dispatched by the organization.
      tags:
        - SMS Dispatch
      security:
        - TokenAuth: []
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of messages retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    example: 120
                  next:
                    type: string
                    nullable: true
                    example: "https://api.cedcast.com/api/v1/messages/?page=2"
                  previous:
                    type: string
                    nullable: true
                    example: null
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MessageObject'

    post:
      summary: Dispatch SMS Broadcast
      description: High-throughput direct SMS dispatch. Phone numbers are passed directly in E.164 or normalized local formats.
      tags:
        - SMS Dispatch
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
                - recipients
              properties:
                sender_id:
                  type: string
                  description: Optional Sender ID to dispatch from (e.g. "PAY_ALERT"). Must be assigned to your organization. Aliases 'from' and 'sender' are also supported.
                  example: "CEDCAST"
                content:
                  type: string
                  description: The text message payload. GSM-7 supports up to 160 chars per segment; Unicode/UTF-8 supports up to 70 chars per segment.
                  example: "Your OTP verification code is 884120."
                recipients:
                  type: array
                  description: Array of phone numbers in E.164 or normalized local formats.
                  items:
                    type: string
                  example: ["+233241234567", "+233501234567"]
                scheduled_time:
                  type: string
                  format: date-time
                  description: Optional ISO-8601 timestamp for scheduled future dispatch.
                  example: "2026-08-26T10:00:00Z"
      responses:
        '201':
          description: SMS accepted and queued for carrier delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageObject'
        '400':
          description: Validation failure or invalid recipient payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient wallet balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded (Sandbox: 10 req/min, Production: 500 req/sec)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/messages/{id}/:
    get:
      summary: Retrieve Message Status
      description: Fetch details and batch delivery state for a specific message batch.
      tags:
        - SMS Dispatch
      security:
        - TokenAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          example: 10482
      responses:
        '200':
          description: Message details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageObject'
        '404':
          description: Message not found

  /api/v1/contacts/:
    get:
      summary: List Contacts
      description: List contacts associated with the organization.
      tags:
        - Contact Management
      security:
        - TokenAuth: []
      responses:
        '200':
          description: List of contacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactObject'

    post:
      summary: Create Single Contact
      description: Create a contact record for CRM/Dashboard syncing.
      tags:
        - Contact Management
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phone_number
              properties:
                name:
                  type: string
                  example: "John Doe"
                phone_number:
                  type: string
                  example: "+233241234567"
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactObject'

  /api/v1/contacts/bulk_create/:
    post:
      summary: Bulk Import Contacts
      description: Sync multiple contacts in a single batch query.
      tags:
        - Contact Management
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contacts
              properties:
                contacts:
                  type: array
                  items:
                    type: object
                    required:
                      - phone_number
                    properties:
                      name:
                        type: string
                        example: "Jane Smith"
                      phone_number:
                        type: string
                        example: "+233501234567"
      responses:
        '201':
          description: Contacts imported
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  message:
                    type: string
                    example: "2 contacts created successfully"

components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Standard DRF token authentication. Format header as `Token <your_api_key>`

  schemas:
    MessageObject:
      type: object
      properties:
        id:
          type: integer
          example: 10482
        organization:
          type: integer
          example: 12
        sender_id:
          type: string
          nullable: true
          example: "CEDCAST"
        content:
          type: string
          example: "Your OTP verification code is 884120."
        scheduled_time:
          type: string
          format: date-time
          example: "2026-08-25T14:30:00Z"
        sent:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: "2026-08-25T14:29:55Z"
        is_batch_message:
          type: boolean
          example: true
        batch_status:
          type: string
          example: "completed"

    ContactObject:
      type: object
      properties:
        id:
          type: integer
          example: 501
        name:
          type: string
          example: "John Doe"
        phone_number:
          type: string
          example: "+233241234567"
        created_at:
          type: string
          format: date-time
          example: "2026-08-25T12:00:00Z"

    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: "error"
        error:
          type: object
          properties:
            code:
              type: string
              example: "VALIDATION_FAILED"
            message:
              type: string
              example: "Detailed error explanation."

    DeliveryReportWebhook:
      type: object
      description: Outbound webhook payload delivered to partner's callback URL.
      properties:
        event:
          type: string
          example: "sms.delivery_update"
        message_id:
          type: integer
          example: 10482
        recipient:
          type: string
          example: "+233241234567"
        status:
          type: string
          enum: [queued, dispatched, delivered, failed, undelivered, expired]
          example: "delivered"
        network:
          type: string
          example: "MTN"
        segments:
          type: integer
          example: 1
        error_code:
          type: string
          nullable: true
          example: null
        updated_at:
          type: string
          format: date-time
          example: "2026-08-25T14:30:00Z"