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

# Registrar Leitura

> Registra uma nova leitura de conteúdo para um usuário

## Descrição

Registra uma nova leitura de conteúdo para um usuário, atualizando seu streak.

O post pode ser identificado pelo `postId` ou pela `postUrl`. Se nenhum dos dois for fornecido, o endpoint apenas recalcula o streak do usuário sem registrar uma nova leitura.

## Autenticação

<Note>
  **Requer autenticação.** O email do leitor é obtido automaticamente do token JWT. Não é necessário enviar o email no body da requisição.
</Note>

<ParamField header="Authorization" type="string" required>
  Token JWT no formato `Bearer <token>`
</ParamField>

## Request Body

<ParamField body="postId" type="string">
  ID do post lido. Opcional se `postUrl` for fornecido.
</ParamField>

<ParamField body="postUrl" type="string">
  URL do post lido. Alternativa ao `postId` - o sistema buscará o post correspondente pela URL no banco de dados. Opcional se `postId` for fornecido.
</ParamField>

<ParamField body="utm_source" type="string">
  Fonte UTM para tracking
</ParamField>

<ParamField body="utm_medium" type="string">
  Meio UTM para tracking
</ParamField>

<ParamField body="utm_campaign" type="string">
  Campanha UTM para tracking
</ParamField>

<Note>
  **Identificação do Post:** Forneça `postId` OU `postUrl`. Se ambos forem fornecidos, o `postId` terá prioridade. Se nenhum for fornecido, o endpoint apenas recalculará o streak do usuário.
</Note>

## Response

<ResponseField name="success" type="boolean">
  Indica se a operação foi bem-sucedida
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem informativa sobre o resultado
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="readerId" type="string">
      ID único do leitor
    </ResponseField>

    <ResponseField name="currentStreak" type="number">
      Streak atual do usuário
    </ResponseField>

    <ResponseField name="maxStreak" type="number">
      Maior streak já alcançado pelo usuário
    </ResponseField>

    <ResponseField name="readToday" type="boolean">
      Indica se o usuário já leu hoje
    </ResponseField>
  </Expandable>
</ResponseField>

## Exemplos de Uso

### Registrar leitura com postId

<RequestExample>
  ```bash Usando postId theme={null}
  curl --request POST \
    --url https://backend.testeswaffle.org/streaks/read \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "postId": "post_123456",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "daily_news"
    }'
  ```

  ```bash Usando postUrl theme={null}
  curl --request POST \
    --url https://backend.testeswaffle.org/streaks/read \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "postUrl": "https://thenewscc.beehiiv.com/p/minha-newsletter",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "daily_news"
    }'
  ```

  ```bash Recalcular streak (sem post) theme={null}
  curl --request POST \
    --url https://backend.testeswaffle.org/streaks/read \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{}'
  ```
</RequestExample>

<ResponseExample>
  ```json Leitura registrada theme={null}
  {
    "success": true,
    "message": "Leitura registrada com sucesso",
    "data": {
      "readerId": "reader_789",
      "currentStreak": 7,
      "maxStreak": 15,
      "readToday": true
    }
  }
  ```

  ```json Streak recalculado theme={null}
  {
    "success": true,
    "message": "Streak recalculado com sucesso.",
    "data": {
      "readerId": "reader_789",
      "currentStreak": 7,
      "maxStreak": 15,
      "readToday": true
    }
  }
  ```

  ```json Post não encontrado (pela URL) theme={null}
  {
    "success": false,
    "message": "Post não encontrado para a URL informada."
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /streaks/read
openapi: 3.1.0
info:
  title: Streaks API
  description: API para gerenciamento de streaks e gamificação de leitura do the news
  version: 1.0.0
servers:
  - url: https://backend.testeswaffle.org
security:
  - bearerAuth: []
paths:
  /streaks/read:
    post:
      tags:
        - Streaks
      summary: Registrar Leitura
      description: Registra uma nova leitura de conteúdo para um usuário
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - postId
              properties:
                email:
                  type: string
                  format: email
                  description: Email do leitor
                postId:
                  type: string
                  description: ID do post lido
                utm_source:
                  type: string
                  description: Fonte UTM para tracking
                utm_medium:
                  type: string
                  description: Meio UTM para tracking
                utm_campaign:
                  type: string
                  description: Campanha UTM para tracking
      responses:
        '200':
          description: Leitura registrada com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      readerId:
                        type: string
                      currentStreak:
                        type: number
                      maxStreak:
                        type: number
                      readToday:
                        type: boolean
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````