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

# Referência

> Gerencie produtos para suas cobranças

Produtos são itens do seu catálogo usados nas cobranças: nome, preço, descrição e opcionalmente ciclo de assinatura. **Avulso** = pagamento único (`cycle` omitido ou `null`). **Assinatura** = `cycle`: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY` ou `ANNUALLY`.

Produtos também podem ter um **arquivo para download** vinculado: um PDF que o comprador recebe acesso após o pagamento (e-books, ingressos, licenças, etc.).

## Criar produto

Use `/products/create`. Moeda é sempre `BRL`.

<Card title="Campos obrigatórios" horizontal>
  Obrigatórios: `externalId` (único no seu sistema), `name`, `price`, `currency`. Opcionais: `description`, `imageUrl`, `fileUrl`, `cycle` (null/omitido = avulso), `trialDays` (requer `cycle`).
</Card>

**Exemplo (produto avulso):**

```json theme={null}
POST /products/create
{
  "externalId": "prod-123",              // obrigatório - identificador único do produto no seu sistema
  "name": "Produto Exemplo",             // obrigatório - nome do produto
  "price": 10000,                        // obrigatório - preço em centavos
  "currency": "BRL",                     // obrigatório - moeda (sempre BRL)
  "description": "Descrição do produto", // opcional - descrição
  "imageUrl": null                       // opcional - URL da imagem (string | null)
}
```

**Exemplo (produto de assinatura):**

```json theme={null}
POST /products/create
{
  "externalId": "prod-assinatura-1",
  "name": "Plano Mensal",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY"                     // opcional - WEEKLY | MONTHLY | QUARTERLY | SEMIANNUALLY | ANNUALLY; omitir ou null = avulso
}
```

**Exemplo (produto de assinatura com período de teste gratuito):**

```json theme={null}
POST /products/create
{
  "externalId": "prod-assinatura-trial",
  "name": "Plano Mensal com 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7                         // opcional - inteiro 1–90; requer cycle
}
```

**Resposta (modelo Product):**

```json theme={null}
{
  "data": {
    "externalId": "prod-assinatura-trial",
    "name": "Plano Mensal com 7 dias grátis",
    "description": null,
    "imageUrl": null,
    "hasFile": false,
    "price": 4990,
    "devMode": false,
    "currency": "BRL",
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z",
    "status": "ACTIVE",
    "id": "prod_abc123xyz",
    "cycle": "MONTHLY",
    "trialDays": 7
  },
  "success": true,
  "error": null
}
```

O `data` retornado segue o modelo Product: `id`, `externalId`, `name`, `description`, `imageUrl`, `hasFile`, `price`, `currency`, `status`, `cycle`, `trialDays`, `createdAt`, `updatedAt`, etc.

## Arquivo para download

Vincule um PDF ao produto passando `fileUrl` na criação. A AbacatePay baixa e armazena o arquivo internamente — o link original não é exposto.

* `fileUrl` aceita qualquer URL pública de PDF. Tamanho máximo: **20 MB**.
* Após o pagamento, o comprador recebe acesso ao download automaticamente.
* O campo `hasFile` na resposta indica se o produto possui arquivo vinculado (`true` / `false`).

**Exemplo (produto com arquivo):**

```json theme={null}
POST /products/create
{
  "externalId": "ebook-001",
  "name": "E-book: Guia Completo",
  "price": 4990,
  "currency": "BRL",
  "fileUrl": "https://exemplo.com/guia-completo.pdf"
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "prod_abc123xyz",
    "externalId": "ebook-001",
    "name": "E-book: Guia Completo",
    "hasFile": true,
    "price": 4990,
    "currency": "BRL",
    "status": "ACTIVE",
    ...
  },
  "success": true,
  "error": null
}
```

<Note>
  O URL do arquivo nunca é exposto pela API. Use `hasFile` para verificar se o produto tem um arquivo vinculado.
</Note>