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

# Loja (Vendas)

> API pública v1 para clientes, produtos, cupons e links de pagamento.

Recursos da **loja** no dashboard GoatPay, expostos na **API pública v1** com chave `gp_live_...`.

## Base URL e autenticação

Todas as rotas abaixo usam o prefixo:

```
https://api.goatpay.com.br/v1
```

```bash theme={null}
curl 'https://api.goatpay.com.br/v1/products/list' \
  -H 'X-API-Key: gp_live_SUA_CHAVE'
```

O trilho **PADRAO** vem da **API key**, não do body. Respostas seguem o [envelope padrão](/api-reference/overview#envelope-de-resposta).

## Módulos

| Recurso  | Prefixo `/v1`      | Seção                                     |
| -------- | ------------------ | ----------------------------------------- |
| Clientes | `/customers/*`     | [Clientes](#clientes)                     |
| Produtos | `/products/*`      | [Produtos](#produtos)                     |
| Cupons   | `/coupons/*`       | [Cupons](#cupons)                         |
| Links    | `/payment-links/*` | [Links de pagamento](#links-de-pagamento) |

## Permissões na API key

Ative na criação da chave (dashboard → Integrações):

| Grupo    | Permissões                                                                            |
| -------- | ------------------------------------------------------------------------------------- |
| Clientes | `customers/create`, `get`, `list`, `update`, `delete`                                 |
| Produtos | `products/create`, `get`, `list`, `update`, `delete`                                  |
| Cupons   | `coupons/create`, `get`, `list`, `update`, `delete`, `validate`                       |
| Links    | `payment-links/create`, `get`, `list`, `update`, `delete`, `checkout`, `sessions/get` |

Lista completa: [Permissões](/pages/guides/api-permissions) · Mapa geral: [Rotas da API](/api-reference/escopo-api-publica).

## Fluxo típico de venda

```mermaid theme={null}
sequenceDiagram
  participant Loja
  participant GoatPay
  participant Cliente

  Loja->>GoatPay: POST /v1/products/create
  Loja->>GoatPay: POST /v1/payment-links/create
  Loja->>GoatPay: POST /v1/coupons/validate
  Loja->>GoatPay: POST /v1/payment-links/checkout
  GoatPay-->>Loja: payCheckoutUrl (PIX ou cripto)
  Loja->>Cliente: Redirecionar
  GoatPay-->>Loja: webhook payment_link.paid
```

1. Cadastre **produto** (opcional) e **link** com `allowedMethods` (`PIX`, `CRYPTO`).
2. Opcional: `POST /v1/coupons/validate` e depois `couponCode` no checkout.
3. `POST /v1/payment-links/checkout` → redirecione o cliente para `payCheckoutUrl`.
4. Confirme com webhook [`payment_link.paid`](/api-reference/guides/webhooks#links-de-pagamento) ou `GET /v1/payment-links/sessions/get/:sessionId`.

<h2 id="clientes">
  Clientes
</h2>

Gerencie a base de clientes vinculada ao trilho da sua API key. Os mesmos pagadores servem [cobranças e assinaturas](/api-reference/guides/cobrancas-assinaturas#clientes).

### Rotas

| Método | Rota                       | Permissão          | Documentação                                          |
| ------ | -------------------------- | ------------------ | ----------------------------------------------------- |
| POST   | `/v1/customers/create`     | `customers/create` | [Criar](/api-reference/endpoint/customers/create)     |
| GET    | `/v1/customers/get/:id`    | `customers/get`    | [Consultar](/api-reference/endpoint/customers/get)    |
| GET    | `/v1/customers/list`       | `customers/list`   | [Listar](/api-reference/endpoint/customers/list)      |
| PATCH  | `/v1/customers/update/:id` | `customers/update` | [Atualizar](/api-reference/endpoint/customers/update) |
| DELETE | `/v1/customers/delete/:id` | `customers/delete` | [Excluir](/api-reference/endpoint/customers/delete)   |

### Listagem

[GET /v1/customers/list](/api-reference/endpoint/customers/list) aceita:

* `page`, `pageSize` (máx. 100)
* `search` — nome, e-mail ou documento
* `status` — `Ativo`, `Inativo`, `Bloqueado` ou `active` / `inactive` / `blocked`

Resposta paginada: `items`, `page`, `pageSize`, `total`, `pages`.

### Campos do cliente

| Campo                                | Descrição                              |
| ------------------------------------ | -------------------------------------- |
| `name`, `email`, `document`          | Obrigatórios na criação                |
| `type`                               | `PF` ou `PJ`                           |
| `status`                             | Situação comercial                     |
| `phone`, `whatsapp`, `city`, `state` | Opcionais                              |
| `transactions`, `volume`             | Métricas na resposta (somente leitura) |

### Checkout automático

Clientes também são criados ou atualizados no checkout de links quando o `customerMode` do link exige cadastro. Você pode manter o CRM sincronizado via API ou confiar no fluxo do link.

<h2 id="produtos">
  Produtos
</h2>

Catálogo e entregas digitais. Base: `https://api.goatpay.com.br/v1/products/*`

### Rotas

| Método | Rota                      | Permissão         | Documentação                                         |
| ------ | ------------------------- | ----------------- | ---------------------------------------------------- |
| POST   | `/v1/products/create`     | `products/create` | [Criar](/api-reference/endpoint/products/create)     |
| GET    | `/v1/products/get/:id`    | `products/get`    | [Consultar](/api-reference/endpoint/products/get)    |
| GET    | `/v1/products/list`       | `products/list`   | [Listar](/api-reference/endpoint/products/list)      |
| PATCH  | `/v1/products/update/:id` | `products/update` | [Atualizar](/api-reference/endpoint/products/update) |
| DELETE | `/v1/products/delete/:id` | `products/delete` | [Excluir](/api-reference/endpoint/products/delete)   |

### Corpo de criação

| Campo                         | Descrição              |
| ----------------------------- | ---------------------- |
| `name`                        | Obrigatório            |
| `sku`, `description`, `price` | Opcionais              |
| `status`                      | `ACTIVE` ou `INACTIVE` |
| `deliveries[]`                | Entrega digital        |

#### Tipos de entrega (`deliveries[].type`)

| Tipo            | Uso                                                |
| --------------- | -------------------------------------------------- |
| `LINK`          | `redirectUrl` após pagamento                       |
| `TEXT_INFINITE` | Conteúdo rich text (`richContent`)                 |
| `TEXT_LINES`    | Linhas de texto/códigos (`linesText` no dashboard) |

<Warning>
  Upload de **imagem** e arquivos em lote permanece no dashboard (`multipart`). A API cobre metadados, preço, status e regras de entrega.
</Warning>

### Vincular a links

Passe `productIds` ao [criar](/api-reference/endpoint/payment-links/create) ou [atualizar](/api-reference/endpoint/payment-links/update) um link de pagamento.

<h2 id="cupons">
  Cupons
</h2>

Cupons de desconto para links. Base: `https://api.goatpay.com.br/v1/coupons/*`

### Rotas

| Método | Rota                     | Permissão          | Documentação                                        |
| ------ | ------------------------ | ------------------ | --------------------------------------------------- |
| POST   | `/v1/coupons/create`     | `coupons/create`   | [Criar](/api-reference/endpoint/coupons/create)     |
| GET    | `/v1/coupons/get/:id`    | `coupons/get`      | [Consultar](/api-reference/endpoint/coupons/get)    |
| GET    | `/v1/coupons/list`       | `coupons/list`     | [Listar](/api-reference/endpoint/coupons/list)      |
| PATCH  | `/v1/coupons/update/:id` | `coupons/update`   | [Atualizar](/api-reference/endpoint/coupons/update) |
| DELETE | `/v1/coupons/delete/:id` | `coupons/delete`   | [Excluir](/api-reference/endpoint/coupons/delete)   |
| POST   | `/v1/coupons/validate`   | `coupons/validate` | [Validar](/api-reference/endpoint/coupons/validate) |

### Tipos de desconto

| `discountType` | Efeito                                |
| -------------- | ------------------------------------- |
| `PERCENT`      | Percentual sobre o valor              |
| `FIXED`        | Valor fixo em BRL (limitado ao total) |

### Restrições

* `productIds` — cupom só vale para produtos listados
* `paymentLinkIds` — cupom só vale para links listados
* `maxUses`, `expiresAt` — limite de uso e validade

### Fluxo no checkout

<Steps>
  <Step title="Validar">
    [POST /v1/coupons/validate](/api-reference/endpoint/coupons/validate) com `code`, `amount`, `paymentLinkId` (e `productId` se restrito).
  </Step>

  <Step title="Checkout">
    [POST /v1/payment-links/checkout](/api-reference/endpoint/payment-links/checkout) com `couponCode` igual ao código validado.
  </Step>

  <Step title="Confirmar">
    Webhook `payment_link.paid` ou [sessão](/api-reference/endpoint/payment-links/sessions-get).
  </Step>
</Steps>

<h2 id="links-de-pagamento">
  Links de pagamento
</h2>

Checkouts hospedados na GoatPay — **PIX e cripto**. Base: `https://api.goatpay.com.br/v1/payment-links/*`

Links permitem que seu site ou app **crie cobranças pela API** e redirecione o cliente para `pay.goatpay.com.br`.

### Rotas

| Método | Rota                                        | Permissão                    |
| ------ | ------------------------------------------- | ---------------------------- |
| POST   | `/v1/payment-links/create`                  | `payment-links/create`       |
| GET    | `/v1/payment-links/get/:id`                 | `payment-links/get`          |
| GET    | `/v1/payment-links/list`                    | `payment-links/list`         |
| PATCH  | `/v1/payment-links/update/:id`              | `payment-links/update`       |
| PATCH  | `/v1/payment-links/status/:id`              | `payment-links/update`       |
| DELETE | `/v1/payment-links/delete/:id`              | `payment-links/delete`       |
| POST   | `/v1/payment-links/checkout`                | `payment-links/checkout`     |
| GET    | `/v1/payment-links/sessions/get/:sessionId` | `payment-links/sessions/get` |

### Pré-requisitos

Conta verificada; métodos `PIX` e/ou `CRYPTO` habilitados no trilho PADRÃO da API key.

### Fluxo recomendado

<Steps>
  <Step title="1. Criar o link">
    [POST /v1/payment-links/create](/api-reference/endpoint/payment-links/create) com `allowedMethods`, valor fixo (`fixedAmount`) ou aberto.
  </Step>

  <Step title="2. Iniciar checkout">
    [POST /v1/payment-links/checkout](/api-reference/endpoint/payment-links/checkout) com `linkId`, `method` e dados do pagador.
  </Step>

  <Step title="3. Pagar">
    Redirecione para `payCheckoutUrl` ou a página `payPageUrl` do link.
  </Step>

  <Step title="4. Confirmar">
    Webhook [`payment_link.paid`](/api-reference/guides/webhooks#links-de-pagamento) ou [GET /v1/payment-links/sessions/get/:sessionId](/api-reference/endpoint/payment-links/sessions-get).
  </Step>
</Steps>

### Idempotência

Envie `Idempotency-Key` em `POST /v1/payment-links/checkout` para evitar cobranças duplicadas em retentativas.

### Referência externa

`externalReference` no checkout correlaciona com seu pedido. Aparece na transação e no webhook `payment_link.paid`.

<CardGroup cols={2}>
  <Card title="Criar cliente" icon="user-plus" href="/api-reference/endpoint/customers/create">
    POST /v1/customers/create
  </Card>

  <Card title="Criar link" icon="link" href="/api-reference/endpoint/payment-links/create">
    POST /v1/payment-links/create
  </Card>
</CardGroup>