> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ipbox.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# login

> Efetua o login do agente, associando-o a um time e criando a sessão no ramal/IP informado.

Após o login, o agente fica no estado **paused** (motivo "Login") — é necessário chamar `pauseout` em seguida para ficar disponível para receber chamadas.



## OpenAPI

````yaml /openapi.yaml post /ipbox/api/login
openapi: 3.0.0
info:
  title: IPBoX Api Documentation v1.1
  description: >-
    Nesse documento são descritos os comandos presentes na API Rest do IPBoX. Os
    comandos são executados com chamadas POST e com respostas em formato JSON.
  version: 1.0.0
servers:
  - url: https://{baseUrl}
    description: Dominio (e porta, se houver) do servidor IPBoX do cliente
    variables:
      baseUrl:
        default: cliente.ipboxcloud.com.br:9052
        description: >-
          Substitua pelo dominio real do seu servidor IPBoX. A maioria dos
          servidores usa uma porta especifica - inclua-a junto ao dominio (ex.:
          cliente.ipboxcloud.com.br:9052)
security:
  - ApiToken: []
tags:
  - name: Agente
  - name: Ligações
  - name: Prospects
  - name: Agendamentos
  - name: Listas
  - name: Filas
  - name: Lotes
  - name: Relatórios
  - name: Outros
  - name: Times
  - name: Blacklist
  - name: Áudios
  - name: URAs
paths:
  /ipbox/api/login:
    post:
      tags:
        - Agente
      summary: login
      description: >-
        Efetua o login do agente, associando-o a um time e criando a sessão no
        ramal/IP informado.


        Após o login, o agente fica no estado **paused** (motivo "Login") — é
        necessário chamar `pauseout` em seguida para ficar disponível para
        receber chamadas.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                user:
                  type: string
                  description: Login/username do agente.
                  example: usuario
                senha:
                  type: string
                  description: Senha do agente.
                  example: senha
                time:
                  type: string
                  description: >-
                    ID de um time ao qual o usuário pertence — o time precisa
                    estar associado a pelo menos uma fila. Use `getTime` para
                    consultar os times cadastrados.
                  example: time
                ramal:
                  type: string
                  description: >-
                    Ramal do agente (ex.: 2000). Se informado, é usado para
                    localizar uma sessão existente nesse ramal; se omitido, a
                    sessão existente é localizada pelo IP.
                  example: ramal
                ip:
                  type: string
                  description: >-
                    [Opcional] IP da máquina do agente; se não for informado
                    será capturado automaticamente. 
                  example: ip
              required:
                - user
                - senha
                - time
      responses:
        '200':
          description: Login efetuado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        description: Tipo do usuário autenticado.
                        example: agente
                      id:
                        type: integer
                        description: Id do usuário/agente.
                        example: 42
              example:
                data:
                  type: agente
                  id: 42
        '409':
          description: Não foi possível efetuar o login.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                usuarioInvalido:
                  summary: Usuário ou senha inválidos
                  value:
                    errors:
                      - status: 409
                        title: Usuário inválido
                        detail: O usuário é inválido
                usuarioJaLogado:
                  summary: Usuário já logado
                  value:
                    errors:
                      - status: 409
                        title: Usuário já logado
                        detail: >-
                          O login não foi possível pois o usuário já estava
                          logado
                outroUsuarioLogado:
                  summary: Outro usuário logado no mesmo ramal/IP
                  value:
                    errors:
                      - status: 409
                        title: Outro Usuário logado
                        detail: Outro usuário já está logado
                usuarioNaoPertenceAoTime:
                  summary: Usuário não pertence ao time informado
                  value:
                    errors:
                      - status: 409
                        title: Usuário não pertence ao time
                        detail: O usuário não pertence ao time
                limiteDeAgentesAtingido:
                  summary: Limite de agentes logados da licença atingido
                  value:
                    errors:
                      - status: 409
                        title: Número máximo de usuários logados
                        detail: O número máximo de usuários logados foi atingido
                interfaceNaoEncontrada:
                  summary: Interface (ramal) não encontrada
                  value:
                    errors:
                      - status: 409
                        title: Interface não encontrada
                        detail: A interface não foi encontrada
                filaNaoEncontrada:
                  summary: Fila associada ao time não encontrada
                  value:
                    errors:
                      - status: 409
                        title: Fila não encontrada
                        detail: A fila não foi encontrada
components:
  schemas:
    ApiError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                example: 409
              title:
                type: string
              detail:
                type: string
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Token gerado em IPBoX > API > Token. Aceita o token puro, ou com prefixo
        `Bearer ` / `Basic `.

````