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

# Creditar Pontos

> Adicionar pontos ao saldo de um cliente

# Creditar Pontos

Adiciona pontos ao saldo de um cliente. Útil para integração com sistemas de vendas (ERP/PDV) que creditam pontos automaticamente após uma compra.

## Comportamento atual

* a rota aceita `X-Idempotency-Key` para retry seguro
* o crédito é aplicado de forma atômica no saldo da carteira
* a resposta retorna o saldo final, não o histórico completo da transação

## Body Parameters

<ParamField body="client_id" type="string" required>
  ID do cliente que receberá os pontos (UUID)
</ParamField>

<ParamField body="amount" type="integer" required>
  Quantidade de pontos a creditar. Deve ser maior que 0.
</ParamField>

<ParamField body="reason" type="string">
  Motivo do crédito (ex: "Compra #12345", "Bonificação mensal")
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.indiqai.com/api/v1/public/points/credit" \
    -H "X-API-Key: indiqai_sua_chave_aqui" \
    -H "X-Idempotency-Key: pontos-erp-2026-05-12-001" \
    -H "Content-Type: application/json" \
    -d '{
      "client_id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 150,
      "reason": "Compra #12345 - R$ 150,00"
    }'
  ```

  ```typescript JavaScript theme={null}
  const response = await fetch('https://api.indiqai.com/api/v1/public/points/credit', {
    method: 'POST',
    headers: {
      'X-API-Key': 'indiqai_sua_chave_aqui',
      'X-Idempotency-Key': 'pontos-erp-2026-05-12-001',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: '550e8400-e29b-41d4-a716-446655440000',
      amount: 150,
      reason: 'Compra #12345 - R$ 150,00'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      'https://api.indiqai.com/api/v1/public/points/credit',
      headers={
          'X-API-Key': 'indiqai_sua_chave_aqui',
          'X-Idempotency-Key': 'pontos-erp-2026-05-12-001',
      },
      json={
          'client_id': '550e8400-e29b-41d4-a716-446655440000',
          'amount': 150,
          'reason': 'Compra #12345 - R$ 150,00'
      }
  )

  data = response.json()
  ```
</CodeGroup>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "balance": 1400,
    "empresa_id": "660f9500-f39c-52e5-b827-557766551111"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "detail": "Cliente não encontrado"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "detail": [
      {
        "loc": ["body", "amount"],
        "msg": "Input should be greater than 0",
        "type": "greater_than"
      }
    ]
  }
  ```
</ResponseExample>

## Campos da Resposta

<ResponseField name="client_id" type="string">
  ID do cliente que recebeu os pontos
</ResponseField>

<ResponseField name="balance" type="integer">
  Novo saldo de pontos do cliente após o crédito
</ResponseField>

<ResponseField name="empresa_id" type="string">
  Empresa dona da carteira creditada
</ResponseField>


## OpenAPI

````yaml POST /api/v1/public/points/credit
openapi: 3.1.0
info:
  contact:
    email: support@indiqai.com
    name: IndiqAI Support
    url: https://indiqai.com/
  description: Especificação OpenAPI da API Pública IndiqAI.
  license:
    name: Proprietary
    url: https://indiqai.com/license
  title: IndiqAI API Pública
  version: 1.5.0
servers:
  - description: Produção
    url: https://api.indiqai.com
security: []
paths:
  /api/v1/public/points/credit:
    post:
      tags:
        - API Pública
      summary: Creditar pontos
      description: Credita pontos para um cliente da empresa. Suporta X-Idempotency-Key.
      operationId: credit_points_api_v1_public_points_credit_post
      parameters:
        - in: header
          name: X-Idempotency-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Idempotency-Key
        - description: Chave de API
          in: header
          name: X-API-Key
          required: true
          schema:
            description: Chave de API
            title: X-Api-Key
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicPointsCredit'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPointsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    PublicPointsCredit:
      description: Creditar pontos para cliente.
      properties:
        amount:
          description: Quantidade de pontos a creditar
          exclusiveMinimum: 0
          title: Amount
          type: integer
        client_id:
          description: ID do cliente
          title: Client Id
          type: string
        reason:
          anyOf:
            - maxLength: 255
              type: string
            - type: 'null'
          default: Crédito via API Pública
          title: Reason
      required:
        - client_id
        - amount
      title: PublicPointsCredit
      type: object
    PublicPointsResponse:
      description: Saldo de pontos de um cliente.
      properties:
        balance:
          title: Balance
          type: integer
        client_id:
          title: Client Id
          type: string
        empresa_id:
          title: Empresa Id
          type: string
      required:
        - client_id
        - balance
        - empresa_id
      title: PublicPointsResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object

````