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

# Identificar o cliente logado

> Troca um passe emitido pela vitrine pela identidade do cliente que está logado na loja. É como um sistema externo descobre, com segurança, quem está do outro lado da tela, sem pedir um segundo login.
O passe vem de `GET /auth/handoff`, chamado pela página da loja. Ele vale 60 segundos, funciona uma vez só e não serve para nada sem a chave de API da loja. Veja [Identificação de cliente](/api-reference/customer-identification) para o fluxo completo.
Este endpoint usa o escopo `customers:identify`, separado de `customers:read` porque é a credencial que sustenta o login de um sistema de terceiro.
<Warning>A CentralCart responde **quem** é o cliente, e nada além disso. O que fazer com essa informação é regra do seu sistema.</Warning>



## OpenAPI

````yaml /openapi/customers.yaml post /app/customer/identify
openapi: 3.1.0
info:
  title: CentralCart API
  version: 1.0.0
  description: >-
    Consultas sobre os compradores da loja. Os endpoints aqui usam o escopo
    `customers:read` da chave de API.
servers:
  - url: https://api.centralcart.io/v1
    description: Produção
security:
  - bearerAuth: []
paths:
  /app/customer/identify:
    post:
      tags:
        - Clientes
      summary: Identificar o cliente logado
      description: >-
        Troca um passe emitido pela vitrine pela identidade do cliente que está
        logado na loja. É como um sistema externo descobre, com segurança, quem
        está do outro lado da tela, sem pedir um segundo login.

        O passe vem de `GET /auth/handoff`, chamado pela página da loja. Ele
        vale 60 segundos, funciona uma vez só e não serve para nada sem a chave
        de API da loja. Veja [Identificação de
        cliente](/api-reference/customer-identification) para o fluxo completo.

        Este endpoint usa o escopo `customers:identify`, separado de
        `customers:read` porque é a credencial que sustenta o login de um
        sistema de terceiro.

        <Warning>A CentralCart responde **quem** é o cliente, e nada além disso.
        O que fazer com essa informação é regra do seu sistema.</Warning>
      operationId: identifyCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - handoff
              properties:
                handoff:
                  type: string
                  description: O passe recebido da página da loja
            example:
              handoff: V1StGXR8Z5jdHi6BmyT0eQx7KpLmN3cWaF9uYbZQsRtVhJdG
      responses:
        '200':
          description: Cliente identificado. O passe foi consumido e não vale mais.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer:
                    $ref: '#/components/schemas/IdentifiedCustomer'
              example:
                customer:
                  store_id: 1234
                  email: cliente@exemplo.com
                  name: Fulano de Tal
                  avatar: null
                  discord_id: null
                  issued_at: '2026-09-22T14:03:11.284Z'
        '422':
          description: >-
            Passe inválido, expirado, já usado ou emitido por outra loja. A
            resposta é a mesma nos quatro casos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                errors:
                  - message: Passe inválido ou expirado.
                    code: HANDOFF_INVALID
components:
  schemas:
    IdentifiedCustomer:
      type: object
      properties:
        store_id:
          type: number
          description: Loja que emitiu o passe
        email:
          type: string
          description: Identidade do cliente na loja, e a chave para casar com a sua base
        name:
          type: string
        avatar:
          type: string
          nullable: true
          description: Preenchido quando o cliente entrou por Google ou Discord
        discord_id:
          type: string
          nullable: true
        issued_at:
          type: string
          description: Quando o passe foi emitido pela vitrine
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              ref:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token de API gerado no painel da CentralCart.

````