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

# Buscar Lojas

> Aprenda a listar todas as lojas cadastradas na Cabra API usando o endpoint GET /stores.

## 🏬 Buscar Lojas

Este endpoint permite **listar todas as lojas associadas** à sua conta.

As lojas são retornadas na ordem de `position` (ascendente).

Ele é ideal para:

* Exibir lojas em painéis administrativos
* Integrar dados com outros sistemas
* Automatizar consultas de lojas

## 🔐 Autenticação

Esta rota **exige autenticação** via **API Key**, enviada no header da requisição:

```http theme={null}
Authorization: SUA_API_KEY_AQUI
```

## 📋 Exemplo de Requisição

```bash theme={null}
curl --location "https://api.cabrapi.com.br/v1/stores?page=1&limit=20" --header "Authorization: SUA_API_KEY_AQUI"
```

## 📊 Exemplo de Resposta (200)

```json theme={null}
{
  "code": "SUCCESS",
  "stores": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "teste",
      "position": 1,
      "description": "Loja de teste",
      "image": "https://example.com/image.png",
      "domain": "dominio.exemplo.com",
      "template": "PERSONALIZADO",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "createdAt": "2000-02-23T15:17:23.064Z",
      "updatedAt": "2000-02-23T15:17:50.527Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "nextCursor": null,
    "hasMore": false
  }
}
```

> A primeira chamada (sem `cursor`) já retorna `nextCursor` e `hasMore` na paginação, permitindo iniciar a paginação por cursor sem chamadas extras.

## 📌 Parâmetros

### Query params

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `page` | number | Não | Página atual (padrão: `1`) |
| `limit` | number | Não | Itens por página (padrão: `20`, máximo: `100`) |
| `cursor` | string | Não | Cursor opaco para paginação por cursor. Use o `nextCursor` da resposta anterior. Não pode ser usado junto com `page` |

Caso não existam lojas na página consultada, `stores` é retornado como array vazio.

### 🔄 Paginação por cursor

Para listas grandes (mais de \~100 itens), prefira paginação por **cursor** no lugar de `page`:

1. Faça a primeira chamada **sem** `cursor`.
2. Se `hasMore` for `true`, a resposta traz o campo `nextCursor`.
3. Envie esse `nextCursor` no parâmetro `cursor` da próxima requisição para buscar a página seguinte.

```bash theme={null}
curl --location "https://api.cabrapi.com.br/v1/stores?cursor=v1:SEU_CURSOR_AQUI&limit=20" --header "Authorization: SUA_API_KEY_AQUI"
```

No modo cursor, a paginação é retornada apenas com `nextCursor`, `hasMore` e `limit`:

```json theme={null}
{
  "code": "SUCCESS",
  "stores": [],
  "pagination": {
    "nextCursor": "v1:e2xFn...",
    "hasMore": true,
    "limit": 20
  }
}
```

* `cursor` e `page` **não podem** ser usados juntos (`400 INVALID_PAGINATION`).
* `nextCursor: null` com `hasMore: false` indicam o fim da lista (a API responde `200` com array vazio).

## ⚠️ Possíveis erros

* `400 INVALID_PAGINATION_LIMIT` → `limit` fora do intervalo permitido (`1` a `100`)
* `400 INVALID_PAGINATION_PAGE` → `page` inválida
* `400 INVALID_PAGINATION_CURSOR` → `cursor` inválido ou malformado
* `400 INVALID_PAGINATION` → `page` e `cursor` utilizados juntos
* `401 API_KEY_NOT_PROVIDED` → header `Authorization` não enviado
* `401 INVALID_API_KEY` → API Key inválida ou não encontrada
* `401 UNAUTHENTICATED` → sessão/usuário não autenticado
* `403 USER_DISABLED` → conta do usuário desativada ou excluída
* `403 NO_ACTIVE_SUBSCRIPTION` → conta sem plano ativo
* `429 RATE_LIMIT_EXCEEDED` → limite de requisições por minuto do plano excedido
* `500 INTERNAL_SERVER_ERROR` → erro interno
* `503 SERVICE_UNAVAILABLE` → serviço temporariamente indisponível

## 🔗 Links Úteis

* [Documentação de Autenticação](https://docs.cabrapi.com.br/pages/pt-BR/api-reference/authorization.md)
* [Buscar loja por ID](https://docs.cabrapi.com.br/pages/pt-BR/api-reference/store/get-by-id.md)
* [Criar Loja](https://docs.cabrapi.com.br/pages/pt-BR/api-reference/store/post.md)
* [Atualizar Loja](https://docs.cabrapi.com.br/pages/pt-BR/api-reference/store/put.md)
* [Deletar Loja](https://docs.cabrapi.com.br/pages/pt-BR/api-reference/store/delete.md)

Update: 23/05/2024 as 13:00


## OpenAPI

````yaml GET /stores
openapi: 3.1.0
info:
  title: caBRAPI
  version: 1.0.0
servers:
  - url: https://api.cabrapi.com.br/v1
security: []
paths:
  /stores:
    get:
      tags:
        - Stores
      summary: List stores
      operationId: listStores
      parameters:
        - in: query
          name: page
          schema:
            default: 1
            minimum: 1
            type: integer
        - in: query
          name: limit
          schema:
            default: 20
            maximum: 100
            minimum: 1
            type: integer
        - description: Opaque cursor from previous page (do not combine with page).
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  code:
                    example: SUCCESS
                    type: string
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  stores:
                    items:
                      $ref: '#/components/schemas/Store'
                    type: array
                required:
                  - code
                  - stores
                  - pagination
                type: object
          description: Owner stores list ordered by position.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: >-
            INVALID_PAGINATION, INVALID_PAGINATION_LIMIT,
            INVALID_PAGINATION_PAGE, INVALID_PAGINATION_CURSOR
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: USER_DISABLED, NO_ACTIVE_SUBSCRIPTION
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Rate limit exceeded.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Service unavailable.
      security:
        - ApiKey: []
components:
  schemas:
    Pagination:
      properties:
        hasMore:
          type: boolean
        limit:
          type: integer
        nextCursor:
          nullable: true
          type: string
        page:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
      type: object
    Store:
      properties:
        createdAt:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        domain:
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        image:
          nullable: true
          type: string
        metadata:
          nullable: true
          type: object
        name:
          type: string
        position:
          type: integer
        template:
          enum:
            - PERSONALIZADO
            - N/A
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - id
        - name
        - position
        - template
        - createdAt
        - updatedAt
      type: object
    Error:
      properties:
        code:
          example: STORE_NOT_FOUND
          type: string
      required:
        - code
      type: object
  securitySchemes:
    ApiKey:
      in: header
      name: Authorization
      type: apiKey
      x-default: YOUR_API_KEY_HERE

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.