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

# Crear un cliente

> Da de alta un cliente en el programa de fidelidad del comercio.

Hace falta al menos `email` o `documentNumber`: son las claves con las que Tienda de Puntos identifica al cliente dentro del comercio. Si mandás los dos y ya existe un cliente con ese documento y otro email, la llamada falla con 409.

El alta dispara los mismos automatismos que el panel: puntos de bienvenida (si el comercio los tiene configurados), asignación de nivel inicial y email de bienvenida. El nivel se asigna de forma asincrónica, así que la respuesta del alta puede traer `level` en `null`.



## OpenAPI

````yaml /api-reference/openapi.json post /external/clients
openapi: 3.0.0
info:
  title: API de Tienda de Puntos
  description: >-
    API pública de Tienda de Puntos. Permite sumar puntos por compra, consultar
    clientes, validar canjes y consumir cupones desde tu POS, ERP o e-commerce.


    Todas las llamadas se autentican con el header `x-api-key`.
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.tiendadepuntos.com
    description: Producción
  - url: https://apidev.tiendadepuntos.com
    description: Desarrollo
security:
  - ApiKeyAuth: []
tags: []
paths:
  /external/clients:
    post:
      tags:
        - Clientes
      summary: Crear un cliente
      description: >-
        Da de alta un cliente en el programa de fidelidad del comercio.


        Hace falta al menos `email` o `documentNumber`: son las claves con las
        que Tienda de Puntos identifica al cliente dentro del comercio. Si
        mandás los dos y ya existe un cliente con ese documento y otro email, la
        llamada falla con 409.


        El alta dispara los mismos automatismos que el panel: puntos de
        bienvenida (si el comercio los tiene configurados), asignación de nivel
        inicial y email de bienvenida. El nivel se asigna de forma asincrónica,
        así que la respuesta del alta puede traer `level` en `null`.
      operationId: ExternalClientController_create
      parameters:
        - name: x-branch-id
          in: header
          description: >-
            ID de la sucursal en la que se registra la operación. Si se omite,
            la operación queda asociada al comercio sin sucursal.
          required: false
          schema:
            type: integer
            example: 1972
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalClientDto'
      responses:
        '201':
          description: Cliente creado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: Request was successful
                  data:
                    $ref: '#/components/schemas/ExternalClientOutputDto'
                required:
                  - success
                  - status
                  - message
        '400':
          description: El cuerpo o los parámetros no pasaron la validación.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 400
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-07-31T14:05:12.431Z'
                  path:
                    type: string
                    example: /external/tags/add
                  method:
                    type: string
                    example: POST
                  message:
                    type: string
                    example: Error de validación
                  errors:
                    type: array
                    nullable: true
                    items:
                      type: object
                  data:
                    type: object
                    nullable: true
        '404':
          description: >-
            Falta el header `x-api-key` (`Api Key is required`) o la API key no
            corresponde a ningún comercio (`Business not found`). También se usa
            cuando el recurso pedido no existe.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 404
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-07-31T14:05:12.431Z'
                  path:
                    type: string
                    example: /external/tags/add
                  method:
                    type: string
                    example: POST
                  message:
                    type: string
                    example: Api Key is required
                  errors:
                    type: array
                    nullable: true
                    items:
                      type: object
                  data:
                    type: object
                    nullable: true
        '409':
          description: >-
            El email o el documento ya están registrados para otro cliente del
            comercio, o la tarjeta de afiliado ya está en uso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 409
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-07-31T14:05:12.431Z'
                  path:
                    type: string
                    example: /external/tags/add
                  method:
                    type: string
                    example: POST
                  message:
                    type: string
                    example: El cliente ya se encuentra registrado.
                  errors:
                    type: array
                    nullable: true
                    items:
                      type: object
                  data:
                    type: object
                    nullable: true
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateExternalClientDto:
      type: object
      properties:
        firstName:
          type: string
          description: Nombre del cliente.
          example: Juan Manuel
        lastName:
          type: string
          description: Apellido del cliente.
          example: Pérez
        email:
          type: string
          description: Email del cliente. Obligatorio si no mandás `documentNumber`.
          example: juanma@mailinator.com
        documentNumber:
          type: string
          description: Número de documento. Obligatorio si no mandás `email`.
          example: '40100800'
        documentType:
          type: string
          description: >-
            Tipo de documento. Si se omite, se infiere por el país del comercio.
            Usá `PASSPORT` para documentos extranjeros alfanuméricos.
          example: DNI
        phone:
          type: string
          description: Teléfono del cliente.
          example: '+541164593678'
        birthday:
          type: string
          description: >-
            Fecha de nacimiento en ISO 8601. Si el comercio tiene una edad
            mínima configurada, se valida contra ella.
          example: '1990-01-01'
        gender:
          type: number
          description: Género. 0 = masculino, 1 = femenino, 2 = otro, 3 = sin datos.
          enum:
            - 0
            - 1
            - 2
            - 3
          example: 3
        affiliateCard:
          type: string
          description: >-
            Número de tarjeta de afiliado. Tiene que ser único dentro del
            comercio.
          example: '00012345'
        description:
          type: string
          description: Observaciones internas del comercio sobre el cliente.
          example: Alta desde el POS de la sucursal Centro.
        branchId:
          type: number
          description: >-
            Sucursal en la que se registra el cliente. Los IDs salen de `GET
            /external/branch`. También se puede mandar en el header
            `x-branch-id`.
          example: 1972
        tagIds:
          description: IDs de las etiquetas del comercio que se le asignan al cliente.
          example:
            - 4
          type: array
          items:
            type: number
    ExternalClientOutputDto:
      type: object
      properties:
        id:
          type: number
          description: ID del cliente en Tienda de Puntos
          example: 84213
        name:
          type: string
          description: Nombre completo
          example: Juan Manuel Pérez
        first_name:
          type: string
          description: Nombre
          example: Juan Manuel
        last_name:
          type: string
          description: Apellido
          example: Pérez
        email:
          type: string
          description: Email
          example: juanma@mailinator.com
          nullable: true
        dni:
          type: string
          description: >-
            Número de documento. Alias de `document_number`, se mantiene por
            compatibilidad.
          example: '40100800'
          nullable: true
        document_number:
          type: string
          description: Número de documento
          example: '40100800'
          nullable: true
        document_type:
          type: string
          description: Tipo de documento
          example: DNI
          nullable: true
        phone:
          type: string
          description: Teléfono
          example: '+541164593678'
          nullable: true
        gender:
          type: number
          description: Género. 0 = masculino, 1 = femenino, 2 = otro, 3 = sin datos.
          enum:
            - 0
            - 1
            - 2
            - 3
          example: 0
        affiliate_card:
          type: string
          description: Número de tarjeta de afiliado
          example: '00012345'
          nullable: true
        score:
          type: number
          description: Puntos disponibles del cliente
          example: 1250
        total_score:
          type: number
          description: Puntos acumulados históricamente
          example: 8400
        description:
          type: string
          description: Observaciones internas del comercio
          example: null
          nullable: true
        birthday:
          format: date-time
          type: string
          description: Fecha de nacimiento
          example: '1990-01-01T00:00:00.000Z'
          nullable: true
        status:
          type: string
          description: Estado del cliente en el programa de fidelidad
          enum:
            - SUSPEND
            - ACTIVE
          example: ACTIVE
        level:
          description: >-
            Nivel actual del cliente. `null` si el comercio no usa niveles o el
            cliente todavía no alcanzó el primero.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ExternalClientLevelOutputDto'
        created_at:
          format: date-time
          type: string
          description: Fecha de alta
          example: '2026-02-14T12:30:00.000Z'
        last_transaction:
          format: date-time
          type: string
          description: Fecha de la última transacción de puntos
          example: '2026-07-28T18:05:00.000Z'
          nullable: true
        purchases_counter:
          type: number
          description: Cantidad de canjes realizados
          example: 7
        reads_counter:
          type: number
          description: Cantidad de operaciones de suma de puntos
          example: 32
      required:
        - id
        - name
        - first_name
        - last_name
        - email
        - dni
        - document_number
        - document_type
        - phone
        - gender
        - affiliate_card
        - score
        - total_score
        - description
        - birthday
        - status
        - created_at
        - last_transaction
        - purchases_counter
        - reads_counter
    ExternalClientLevelOutputDto:
      type: object
      properties:
        id:
          type: number
          description: ID del nivel.
          example: 3
        name:
          type: string
          description: Nombre del nivel.
          example: Nivel 2
      required:
        - id
        - name
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key del comercio. Se genera desde el panel de Tienda de Puntos, en
        Configuración → Integraciones.

````