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

# Conectar WhatsApp

> Abre uma nova sessão do WhatsApp e retorna o payload do QR Code para parear o dispositivo.

<Badge size="lg" shape="rounded" color="blue" stroke color="blue">POST</Badge> /session/connect

```curl theme={null}
curl -X POST "BASE_URL/v1/session/connect" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "sessionName": "NOME_DA_SESSAO",
    "webhookUrl": "https://seu-webhook.com/eventos",
    "webhookMessages": true,
    "mode": "qr",
    "pairingNumber": "5511999999999"
  }'
```

* `sessionName` (string) e `webhookUrl` (URL) sao obrigatorios.
* `webhookMessages` bool (default `true`).
* `mode`: `qr` ou `pairing` (default `qr`).
* `pairingNumber`: so quando `mode = pairing` (DDI+numero).
* Se o ambiente exigir API key, adicione o header extra (ex.: `-H "x-api-key: SUA_API_KEY"`).


## OpenAPI

````yaml POST /session/connect
openapi: 3.1.0
info:
  title: Loce Zap API
  description: >-
    API REST para conectar sessões do WhatsApp e enviar mensagens de texto,
    mídia e automações via Loce Zap.
  version: 1.0.0
servers:
  - url: https://apizap.loce.io/v1
    description: Ambiente de produção
security:
  - bearerAuth: []
paths:
  /session/connect:
    post:
      summary: Criar sessão
      description: >-
        Abre uma nova sessão do WhatsApp e retorna o payload do QR Code para
        parear o dispositivo.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionConnectRequest'
      responses:
        '200':
          description: Sessão criada com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionConnectResponse'
        '400':
          description: Erro de validação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SessionConnectRequest:
      type: object
      required:
        - sessionName
        - webhookUrl
      properties:
        sessionName:
          type: string
          description: Nome amigável exibido no painel. Deve ser único por workspace.
        webhookUrl:
          type: string
          format: uri
          description: Endpoint HTTPS que receberá eventos da sessão.
        webhookMessages:
          type: boolean
          description: Ativa o envio de webhooks de mensagens (dependente do plano).
    SessionConnectResponse:
      type: object
      properties:
        sessionId:
          type: string
          description: Identificador único da sessão criada.
        status:
          type: string
          description: 'Estado atual da sessão (ex.: pending, connected).'
        qrCode:
          type: string
          description: Payload do QR Code que deve ser renderizado para pareamento.
        webhookUrl:
          type: string
          format: uri
        webhookMessages:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````