{
  "openapi": "3.0.3",
  "info": {
    "title": "CYSMS B2B SMS API",
    "version": "1.0.0",
    "description": "Secure API for queuing SMS messages in the CYSMS platform. Recommended mode: POST + application/json + HTTP Basic Authentication. Legacy mode with username/password fields is still supported for backward compatibility."
  },
  "servers": [
    {
      "url": "https://cysms.eu/sms",
      "description": "Production domain"
    },
    {
      "url": "http://46.62.221.123/sms",
      "description": "Production server IP"
    }
  ],
  "paths": {
    "/b2b.php": {
      "post": {
        "tags": [
          "SMS"
        ],
        "summary": "Queue SMS message for one or more recipients",
        "description": "Queues one SMS job in scheduled_jobs and one record per recipient in scheduled_phones.",
        "security": [
          {
            "basicAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendSmsRequest"
              },
              "examples": {
                "singleRecipient": {
                  "summary": "One recipient",
                  "value": {
                    "to": "35799596295",
                    "sender": "CYSMS",
                    "message": "Test message"
                  }
                },
                "multipleRecipients": {
                  "summary": "Many recipients",
                  "value": {
                    "to": "35799596295,35799111222,35799777888",
                    "sender": "MyBrand",
                    "message": "Campaign message"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message accepted and queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueSuccessResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "ok": true,
                      "queued": true,
                      "jobId": 22588,
                      "recipients": 3,
                      "creditsRequired": 3,
                      "availableCredits": 197,
                      "mode": "v2_json"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidRecipients": {
                    "value": {
                      "ok": false,
                      "error": "invalid_recipients",
                      "message": "Parameter to must contain at least one valid phone number."
                    }
                  },
                  "invalidMessage": {
                    "value": {
                      "ok": false,
                      "error": "invalid_message",
                      "message": "Message is required."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "authRequired": {
                    "value": {
                      "ok": false,
                      "error": "authentication_required",
                      "message": "Provide credentials using Basic Auth (recommended) or legacy fields."
                    }
                  },
                  "badCredentials": {
                    "value": {
                      "ok": false,
                      "error": "invalid_credentials",
                      "message": "Please check username/password."
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Not enough SMS credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsufficientCreditsResponse"
                },
                "examples": {
                  "insufficientCredits": {
                    "value": {
                      "ok": false,
                      "error": "insufficient_credits",
                      "availableCredits": 1,
                      "requiredCredits": 3
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Legacy mode disabled and non-JSON request was used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "methodNotAllowed": {
                    "value": {
                      "ok": false,
                      "error": "method_not_allowed",
                      "message": "Use POST application/json with Basic Auth."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server side error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "dbConnectionFailed": {
                    "value": {
                      "ok": false,
                      "error": "db_connection_failed"
                    }
                  },
                  "queueInsertFailed": {
                    "value": {
                      "ok": false,
                      "error": "queue_insert_failed"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    },
    "schemas": {
      "SendSmsRequest": {
        "type": "object",
        "required": [
          "to",
          "sender",
          "message"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "Comma-separated recipients in international format without plus sign.",
            "example": "35799596295,35799111222"
          },
          "sender": {
            "type": "string",
            "description": "Sender ID, normalized to gateway-safe value.",
            "maxLength": 11,
            "example": "CYSMS"
          },
          "message": {
            "type": "string",
            "description": "SMS message body.",
            "example": "Test message"
          }
        }
      },
      "QueueSuccessResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "queued": {
            "type": "boolean",
            "example": true
          },
          "jobId": {
            "type": "integer",
            "example": 22588
          },
          "recipients": {
            "type": "integer",
            "example": 2
          },
          "creditsRequired": {
            "type": "integer",
            "example": 2
          },
          "availableCredits": {
            "type": "integer",
            "example": 197
          },
          "mode": {
            "type": "string",
            "enum": [
              "v2_json",
              "legacy"
            ],
            "example": "v2_json"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "invalid_credentials"
          },
          "message": {
            "type": "string",
            "nullable": true,
            "example": "Please check username/password."
          }
        }
      },
      "InsufficientCreditsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorResponse"
          },
          {
            "type": "object",
            "properties": {
              "availableCredits": {
                "type": "integer",
                "example": 1
              },
              "requiredCredits": {
                "type": "integer",
                "example": 3
              }
            }
          }
        ]
      }
    }
  }
}