{
  "openapi": "3.0.3",
  "info": {
    "title": "VOIS Ses API",
    "version": "1.1.0",
    "description": "Tam doküman: https://docs.vois.com.tr/voice/\n\nKimlik doğrulama: VOIS panelinde (Ayarlar › Entegrasyonlar › REST API & Webhook) oluşturduğunuz anahtar; `Authorization: Bearer <anahtar>` ya da `X-API-Key`.\n\nWebhook olayları (call.ringing, call.answered, call.ended) ve imza doğrulaması için: https://docs.vois.com.tr/voice/#webhook\n\nDestek: destek@vois.com.tr · 0850 340 6 340",
    "contact": {
      "name": "VOIS Destek",
      "email": "destek@vois.com.tr",
      "url": "https://docs.vois.com.tr/"
    }
  },
  "servers": [
    {
      "url": "https://api.vois.com.tr/v1/voice"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "Okuma"
    },
    {
      "name": "Arama"
    },
    {
      "name": "Webhook"
    }
  ],
  "paths": {
    "/extensions": {
      "get": {
        "tags": [
          "Okuma"
        ],
        "summary": "Dahililer",
        "operationId": "extensions",
        "description": "Yetki: voice:read. Arama yapmaz — anahtar testi için idealdir.\n\nDoküman: https://docs.vois.com.tr/voice/#ext",
        "responses": {
          "200": {
            "description": "Dahili listesi",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "extension": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "enabled": {
                            "type": "boolean"
                          },
                          "registered": {
                            "type": "boolean"
                          },
                          "in_call": {
                            "type": "boolean"
                          },
                          "user_agent": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "voice_not_enabled / insufficient_scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "İstek sınırı (anahtar başına dakikada 60).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/calls/active": {
      "get": {
        "tags": [
          "Okuma"
        ],
        "summary": "Süren çağrılar",
        "operationId": "activeCalls",
        "description": "Yetki: voice:read.\n\nDoküman: https://docs.vois.com.tr/voice/#active",
        "responses": {
          "200": {
            "description": "Süren çağrılar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "call_id": {
                            "type": "string"
                          },
                          "direction": {
                            "type": "string"
                          },
                          "from": {
                            "type": "string"
                          },
                          "to": {
                            "type": "string"
                          },
                          "extension": {
                            "type": "string",
                            "nullable": true
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "RINGING",
                              "EARLY",
                              "ACTIVE",
                              "HELD"
                            ]
                          },
                          "started_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "pbx_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "voice_not_enabled / insufficient_scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "İstek sınırı (anahtar başına dakikada 60).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/calls": {
      "post": {
        "tags": [
          "Arama"
        ],
        "summary": "Tıkla-ara",
        "operationId": "clickToCall",
        "description": "Yetki: voice:call. Önce dahili çalar, açınca numara aranır. ⚠️ Gerçek arama başlatır.\n\nDoküman: https://docs.vois.com.tr/voice/#call",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "extension",
                  "number"
                ],
                "properties": {
                  "extension": {
                    "type": "string",
                    "pattern": "^[0-9]{1,10}$"
                  },
                  "number": {
                    "type": "string",
                    "maxLength": 32
                  },
                  "caller_id_number": {
                    "type": "string",
                    "maxLength": 20
                  },
                  "auto_answer": {
                    "type": "boolean",
                    "default": false,
                    "description": "Hesapta VOIS açtıysa."
                  },
                  "reference": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[A-Za-z0-9._:-]*$"
                  }
                }
              },
              "examples": {
                "Basit": {
                  "value": {
                    "extension": "101",
                    "number": "05321234567",
                    "reference": "musteri-4521"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Çağrı başlatıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "call_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "example": "ringing_extension"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "voice_not_enabled / insufficient_scope / auto_answer_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "extension_unavailable / extension_busy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "invalid_request / extension_not_found / number_not_allowed / number_blocked / caller_id_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / daily_limit / too_many_calls",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "pbx_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/calls/{call_id}": {
      "delete": {
        "tags": [
          "Arama"
        ],
        "summary": "Çağrıyı kapat",
        "operationId": "hangup",
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "Yetki: voice:call.\n\nDoküman: https://docs.vois.com.tr/voice/#hangup",
        "responses": {
          "200": {
            "description": "Kapatıldı",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "hung_up": {
                          "type": "boolean"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "pbx_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "voice_not_enabled / insufficient_scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "İstek sınırı (anahtar başına dakikada 60).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cdr": {
      "get": {
        "tags": [
          "Okuma"
        ],
        "summary": "Çağrı geçmişi",
        "operationId": "cdr",
        "description": "Yetki: voice:read. Dışarıyla yapılan çağrılar; aralık en çok 31 gün.\n\nDoküman: https://docs.vois.com.tr/voice/#cdr",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-11-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-11-12"
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "answered",
                "no_answer",
                "busy",
                "failed"
              ]
            }
          },
          {
            "name": "extension",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "number",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Son 10 hane eşleşir."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Çağrılar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Cdr"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "invalid_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "voice_not_enabled / insufficient_scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "İstek sınırı (anahtar başına dakikada 60).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cdr/{call_id}": {
      "get": {
        "tags": [
          "Okuma"
        ],
        "summary": "Tek çağrı",
        "operationId": "cdrShow",
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "Yetki: voice:read.\n\nDoküman: https://docs.vois.com.tr/voice/#cdr1",
        "responses": {
          "200": {
            "description": "Çağrı",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Cdr"
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "voice_not_enabled / insufficient_scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "İstek sınırı (anahtar başına dakikada 60).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/recordings/{call_id}": {
      "get": {
        "tags": [
          "Okuma"
        ],
        "summary": "Ses kaydı",
        "operationId": "recording",
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "Yetki: voice:recordings. Yeni kayıtlar WAV, gece sıkıştırıldıktan sonra MP3; dosya adı Content-Disposition başlığındadır.\n\nDoküman: https://docs.vois.com.tr/voice/#rec",
        "responses": {
          "200": {
            "description": "Kayıt dosyası",
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks": {
      "servers": [
        {
          "url": "https://api.vois.com.tr/v1"
        }
      ],
      "get": {
        "tags": [
          "Webhook"
        ],
        "summary": "Webhook listesi",
        "operationId": "webhooksList",
        "description": "Yetki: webhooks:manage. Yalnız bu anahtarın oluşturduğu webhook'lar listelenir; secret dönmez.\n\nDoküman: https://docs.vois.com.tr/voice/#webhook-api",
        "responses": {
          "200": {
            "description": "Webhook listesi",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "event": {
                            "type": "string",
                            "example": "call.ended"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "active": {
                            "type": "boolean"
                          },
                          "created_at": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "insufficient_scope (webhooks:manage gerekir)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Webhook"
        ],
        "summary": "Webhook ekle",
        "operationId": "webhooksCreate",
        "description": "Yetki: webhooks:manage. Hesap başına en çok 50 webhook. secret yalnız bu yanıtta döner.\n\nDoküman: https://docs.vois.com.tr/voice/#webhook-api",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event",
                  "url"
                ],
                "properties": {
                  "event": {
                    "type": "string",
                    "example": "call.ended",
                    "description": "call.ringing, call.answered, call.ended ya da * (tümü)."
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "call.* olayları için https zorunlu."
                  }
                }
              },
              "examples": {
                "call.ended": {
                  "value": {
                    "event": "call.ended",
                    "url": "https://ornek.com/vois-webhook"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Eklendi. secret yalnız burada görünür.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "event": {
                          "type": "string",
                          "example": "call.ended"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "secret": {
                          "type": "string"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "error: invalid_request (event/url eksik ya da hatalı) | invalid_event | url_not_allowed | https_required | limit_reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "insufficient_scope (webhooks:manage gerekir)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{id}": {
      "servers": [
        {
          "url": "https://api.vois.com.tr/v1"
        }
      ],
      "delete": {
        "tags": [
          "Webhook"
        ],
        "summary": "Webhook sil",
        "operationId": "webhooksDelete",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "description": "Yetki: webhooks:manage. Yalnız bu anahtarın oluşturduğu webhook silinebilir; diğerleri için 404.\n\nDoküman: https://docs.vois.com.tr/voice/#webhook-api",
        "responses": {
          "204": {
            "description": "Silindi (gövde yok)."
          },
          "404": {
            "description": "error: not_found (webhook yok, bu anahtarın değil ya da geçersiz id)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "insufficient_scope (webhooks:manage gerekir)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "extension_unavailable"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Cdr": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "format": "uuid"
          },
          "direction": {
            "type": "string",
            "enum": [
              "inbound",
              "outbound"
            ]
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "extension": {
            "type": "string",
            "nullable": true
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "answered_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ended_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "duration": {
            "type": "integer"
          },
          "talk_time": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "answered",
              "no_answer",
              "busy",
              "failed"
            ]
          },
          "recording_available": {
            "type": "boolean"
          },
          "reference": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  }
}
