> ## 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.

# Criar um produto

> Permite que você crie um novo produto que pode ser usado em cobranças.
Produtos podem ser avulsos (pagamento único) ou de assinatura; use o campo opcional `cycle` para definir a recorrência (`WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`). Quando `cycle` é omitido ou `null`, o produto é avulso.

**Alternativa**: Você também pode criar e gerenciar seus produtos pelo [Dashboard da AbacatePay](https://app.abacatepay.com/produtos).


Cria um produto no seu catálogo para usar em checkouts, assinaturas e links de pagamento.

<Card title="Obrigatórios" horizontal>
  `externalId` (único no seu sistema), `name`, `price` (em centavos) e `currency` (sempre `"BRL"`).
</Card>

**Produto digital com arquivo para download** (passe `fileUrl` com a URL pública de um PDF):

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

<Note title="fileUrl" horizontal>
  `fileUrl` deve apontar para um PDF público acessível. Tamanho máximo: 20 MB. O arquivo é armazenado pela AbacatePay e o comprador recebe acesso após o pagamento. O campo `hasFile: true` na resposta confirma o vínculo.
</Note>

**Produto avulso** (pagamento único — omita `cycle`):

```json theme={null}
{
  "externalId": "prod-123",
  "name": "Camiseta Premium",
  "price": 8990,
  "currency": "BRL",
  "description": "Camiseta 100% algodão"
}
```

**Produto de assinatura** (defina `cycle`):

```json theme={null}
{
  "externalId": "plano-mensal",
  "name": "Plano Mensal",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY"
}
```

**Produto de assinatura com período de teste gratuito** (defina `trialDays`):

```json theme={null}
{
  "externalId": "plano-mensal-trial",
  "name": "Plano Mensal com 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7
}
```

**Valores de `cycle`:** `WEEKLY` · `MONTHLY` · `QUARTERLY` · `SEMIANNUALLY` · `ANNUALLY`

<Note title="trialDays" horizontal>
  `trialDays` exige `cycle`. Valor inteiro entre 1 e 90. O cliente não é cobrado durante o período de teste — a primeira cobrança ocorre ao final do trial.
</Note>

<Tip title="ID retornado" horizontal>
  Guarde o `data.id` retornado — é ele que você passa como `items[].id` ao criar checkouts e assinaturas.
</Tip>


## OpenAPI

````yaml POST /products/create
openapi: 3.1.0
info:
  title: API AbacatePay
  description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
  version: 1.0.0
servers:
  - url: https://api.abacatepay.com/v2
    description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
  /products/create:
    post:
      summary: Criar um produto
      description: >
        Permite que você crie um novo produto que pode ser usado em cobranças.

        Produtos podem ser avulsos (pagamento único) ou de assinatura; use o
        campo opcional `cycle` para definir a recorrência (`WEEKLY`, `MONTHLY`,
        `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`). Quando `cycle` é omitido ou
        `null`, o produto é avulso.


        **Alternativa**: Você também pode criar e gerenciar seus produtos pelo
        [Dashboard da AbacatePay](https://app.abacatepay.com/produtos).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Dados necessários para criar um produto.
              required:
                - externalId
                - name
                - price
                - currency
              additionalProperties: false
              example:
                externalId: prod-123
                name: Produto Exemplo
                price: 10000
                currency: BRL
              properties:
                externalId:
                  type: string
                  description: Identificador único do produto no seu sistema.
                  example: prod-123
                name:
                  type: string
                  description: Nome do produto.
                  example: Produto Exemplo
                price:
                  type: number
                  description: Preço do produto em centavos.
                  minimum: 1
                  example: 10000
                currency:
                  type: string
                  description: Moeda do produto.
                  default: BRL
                  example: BRL
                description:
                  type: string
                  description: Descrição opcional do produto.
                  example: Descrição do produto
                  x-mint:
                    hidden: true
                imageUrl:
                  type: string
                  format: uri
                  nullable: true
                  description: URL da imagem do produto. Opcional.
                  example: null
                fileUrl:
                  type: string
                  format: uri
                  description: >
                    URL pública de um PDF a ser vinculado ao produto. Opcional.
                    O arquivo é baixado e armazenado pela AbacatePay — máximo 20
                    MB. Após o pagamento, o comprador recebe acesso ao download
                    do arquivo.
                  example: https://exemplo.com/meu-ebook.pdf
                cycle:
                  type: string
                  nullable: true
                  description: >
                    Opcional. Indica se o produto é uma assinatura. Quando
                    omitido ou `null`, o produto é avulso (pagamento único).

                    Valores possíveis: `WEEKLY`, `MONTHLY`, `QUARTERLY`,
                    `SEMIANNUALLY`, `ANNUALLY`.
                  enum:
                    - WEEKLY
                    - MONTHLY
                    - QUARTERLY
                    - SEMIANNUALLY
                    - ANNUALLY
                  example: null
      responses:
        '200':
          description: Produto criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
      security:
        - bearerAuth: []
components:
  schemas:
    Product:
      type: object
      description: >
        Os dados do seu produto.

        O campo `cycle` indica se o produto é uma assinatura (subscription).
        Quando `null`, o produto é avulso (pagamento único). Valores possíveis
        definem a recorrência da assinatura.

        A moeda (`currency`) é sempre `BRL`.
      required:
        - externalId
        - name
        - description
        - price
        - devMode
        - currency
        - createdAt
        - updatedAt
        - status
        - id
      additionalProperties: false
      properties:
        externalId:
          type: string
          description: Identificador único do produto no seu sistema
          example: prod-123
        name:
          type: string
          description: Nome do produto
          example: Produto Exemplo
        description:
          type: string
          description: Descrição do produto
          example: Descrição do produto
        imageUrl:
          type: string
          format: uri
          nullable: true
          description: URL da imagem do produto
          example: null
        price:
          type: number
          description: Preço do produto em centavos
          example: 10000
        devMode:
          type: boolean
          description: Indica se o produto foi criado em ambiente de testes
          example: false
        currency:
          type: string
          description: Moeda do produto (sempre BRL)
          enum:
            - BRL
          example: BRL
        createdAt:
          type: string
          format: date-time
          description: Data de criação do produto
          example: '2024-11-04T18:38:28.573Z'
        updatedAt:
          type: string
          format: date-time
          description: Data de atualização do produto
          example: '2024-11-04T18:38:28.573Z'
        status:
          type: string
          description: Status atual do produto (ProductStatus)
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        id:
          type: string
          description: Identificador único público do produto
          example: prod_abc123xyz
        cycle:
          type: string
          nullable: true
          description: >
            Indica se o produto é uma assinatura (ProductCycle). Quando `null`,
            o produto é avulso (pagamento único).

            Valores possíveis definem a recorrência da assinatura.
          enum:
            - WEEKLY
            - MONTHLY
            - QUARTERLY
            - SEMIANNUALLY
            - ANNUALLY
          example: null
        hasFile:
          type: boolean
          description: >
            Indica se o produto possui um arquivo PDF vinculado para download.
            Quando `true`, o comprador recebe acesso ao arquivo após o
            pagamento.
          example: false
    Success:
      type: boolean
      description: Se a requisição obteve sucesso ou não.
      example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Todas as requisições devem incluir sua chave de API no header
        Authorization usando o formato `Bearer <abacatepay-api-key>`. Sem esse
        header a requisição será rejeitada.


        Saiba mais sobre como criar e usar chaves de API na [documentação de
        autenticação](/pages/authentication).

````