> ## Documentation Index > Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar clientes > Retorna uma lista paginada de clientes da conta. ## OpenAPI ````yaml /api-reference/openapi.yml get /api/v1/customers openapi: 3.1.0 info: title: API - Simplo version: 1.0.0 description: API para cobrança e assinaturas para contas Simplo contact: name: Simplo url: https://besimplo.com email: team@besimplo.com servers: - url: https://besimplo.com description: Produção security: - apiKeyAuth: [] tags: - name: Clientes description: Clientes são as pessoas que pagarão pelos produtos da sua conta - name: Produtos description: Produtos representam os bens ou serviços que você vende - name: Preços description: Preços definem quanto cobrar e a frequência de cobrança de um Produto - name: Assinaturas description: Assinaturas conectam clientes aos seus planos para cobrança recorrente - name: Checkout description: >- Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web - name: Faturas description: Faturas representam cobranças geradas para clientes - name: Reembolsos description: Reembolsos permitem devolver pagamentos já realizados aos clientes - name: Webhooks description: > Eventos enviados via HTTP POST para a URL configurada na sua conta. Responda com status 2xx rapidamente. Processe o evento de forma assincrona. Use o campo `event.id` para garantir idempotencia. paths: /api/v1/customers: get: tags: - Clientes summary: Listar clientes description: Retorna uma lista paginada de clientes da conta. operationId: listCustomers parameters: - name: email in: query description: Filtrar por e-mail do cliente schema: type: string format: email - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 description: Resultados por página - name: page in: query schema: type: string description: Cursor para próxima página responses: '200': description: Lista de clientes content: application/json: schema: type: object unevaluatedProperties: false required: - object - url - has_more - data properties: object: type: string description: Tipo do objeto. Sempre 'list'. enum: - list example: list url: type: string format: uri-reference description: URL do recurso solicitado. example: /api/v1/customers has_more: type: boolean description: Indica se há mais resultados disponíveis para paginação. example: false data: type: array description: Lista de clientes. items: type: object unevaluatedProperties: false required: - id - object - live_mode - created - name properties: id: type: string pattern: ^cus_[0-9a-z]{26}$ readOnly: true description: >- ID único do cliente, no formato TypeID com prefixo `cus_`. example: cus_01h455vb4pex5vsknk084sn02q object: type: string description: Tipo do objeto. Sempre 'customer'. enum: - customer example: customer live_mode: type: boolean description: >- Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente. example: true external_code: type: string description: >- Código externo para integração. Deve ser único por conta. maxLength: 250 example: 01953808-3a3a-712f-99ce-f6943c8141db created: type: integer format: int64 readOnly: true description: Timestamp Unix de quando o cliente foi criado. example: 1680893993 identifier: type: - string - 'null' nullable: true description: CPF ou CNPJ do cliente. example: 123.456.789-00 name: type: string description: Nome do cliente. minLength: 1 maxLength: 250 example: João Silva email: type: - string - 'null' nullable: true description: E-mail do cliente. example: joao.silva@exemplo.com phone: type: - string - 'null' nullable: true description: Telefone do cliente. example: '+5511999998888' description: type: - string - 'null' nullable: true description: >- Tipo de cliente baseado no documento: 'individual' para CPF, 'business' para CNPJ. enum: - individual - business example: individual address: type: object unevaluatedProperties: false required: - zip_code - street - number - district - city - state properties: zip_code: type: string description: CEP example: '12345012' street: type: string description: Rua example: Alguma Rua number: type: string description: Número example: '9934' district: type: string description: Bairro example: D'algum Bairro city: type: string description: Cidade example: Campinas state: type: string description: Estado example: SP complement: type: - string - 'null' description: Complemento example: Apt. 123 '404': description: Não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: URI que identifica o tipo de problema format: uri enum: - https://problems-registry.smartbear.com/not-found status: type: integer description: O código de status HTTP format: int32 enum: - 404 title: type: string description: O nome do status HTTP enum: - Not Found detail: type: string description: Mensagem descritiva do erro code: type: string description: Código de erro interno da API enum: - NOT_FOUND - RESOURCE_MISSING examples: not_found: summary: Recurso não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: The requested resource was not found code: NOT_FOUND customer_not_found: summary: Cliente não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such customer: ''019abc12-3456-7890-abcd-ef1234567890''' code: RESOURCE_MISSING components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > A chave de API usada para autenticar a requisição e identificar a sua conta. **Exemplo:** `Authorization: ApiKey my-secure-key` ````