> ## Documentation Index
> Fetch the complete documentation index at: https://fortal-pay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Produtos

> Crie, liste, consulte, atualize e remova produtos do catálogo.

Produtos representam os itens vendidos pelo merchant. O `id` retornado pela API identifica o produto na criação de cobranças.

<CardGroup cols={3}>
  <Card title="Criar produto" icon="package-plus">
    Requer uma API key `FULL_ACCESS`.
  </Card>

  <Card title="Consultar produtos" icon="list">
    Aceita API keys `READ_ONLY` e `FULL_ACCESS`.
  </Card>

  <Card title="Alterar produtos" icon="package-open">
    Atualização e remoção exigem uma API key `FULL_ACCESS`.
  </Card>
</CardGroup>

## Criar um produto

```bash theme={null}
curl --request POST 'https://api-sandbox.fortalpay.tech/v1/products' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalId": "sku-camiseta-001",
    "name": "Camiseta FortalPay",
    "description": "Camiseta de algodão, tamanho M",
    "price": 7990
  }'
```

### Campos da criação

| Campo         | Obrigatório | Regra                                                                                                        |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `externalId`  | Não         | Identificador definido pela sua integração, com até 100 caracteres. Não pode ser alterado depois da criação. |
| `name`        | Sim         | Não pode ser vazio e aceita até 150 caracteres.                                                              |
| `description` | Não         | Descrição livre do produto.                                                                                  |
| `price`       | Sim         | Valor inteiro em centavos, maior ou igual a `500` (R$ 5,00). Para R$ 79,90, envie `7990`.                    |

A criação retorna HTTP `201`. O produto é criado com status `ACTIVE`.

Valores fracionários não são aceitos. O valor é armazenado em centavos e retornado em reais com duas casas decimais. Por exemplo, `1056` é retornado como `10.56`.

<Info>
  `externalId` e `name` devem ser únicos entre os produtos não removidos do merchant. A comparação de nome não diferencia maiúsculas de minúsculas.
</Info>

## Listar produtos

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/products?page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'
```

A resposta contém somente produtos do merchant autenticado que não foram removidos logicamente. Os itens mais recentes são retornados primeiro.

## Consultar pelo identificador

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/products/<product_id>' \
  --header 'Authorization: ApiKey <api_key>'
```

Um identificador inexistente, removido ou pertencente a outro merchant retorna `404`.

## Atualizar um produto

`PUT /products/{id}` substitui os campos editáveis. Nome, preço e status são obrigatórios.

```bash theme={null}
curl --request PUT 'https://api-sandbox.fortalpay.tech/v1/products/<product_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Camiseta FortalPay Premium",
    "description": "Camiseta premium de algodão, tamanho M",
    "price": 8990,
    "status": "ACTIVE"
  }'
```

| Campo         | Obrigatório | Regra                                                                                              |
| ------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `name`        | Sim         | Não pode ser vazio, aceita até 150 caracteres e não pode duplicar outro produto ativo no catálogo. |
| `description` | Não         | Enviar `null` remove a descrição atual.                                                            |
| `price`       | Sim         | Valor inteiro em centavos, maior ou igual a `500` (R$ 5,00). Para R$ 89,90, envie `8990`.          |
| `status`      | Sim         | `ACTIVE` ou `INACTIVE`.                                                                            |

<Note>
  O `externalId` é imutável e, por isso, não faz parte da requisição de atualização.
</Note>

Produtos com status `INACTIVE` continuam disponíveis para consulta, mas não podem ser usados na criação de novas cobranças.

## Remover um produto

```bash theme={null}
curl --request DELETE 'https://api-sandbox.fortalpay.tech/v1/products/<product_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>'
```

A remoção é lógica e retorna HTTP `204` sem corpo. O produto deixa de aparecer na listagem, não pode mais ser consultado e não pode ser usado em novas cobranças. Registros históricos permanecem preservados.

## Campos retornados

| Campo         | Tipo           | Descrição                                                |
| ------------- | -------------- | -------------------------------------------------------- |
| `id`          | UUID           | Identificador público usado nas demais operações da API. |
| `externalId`  | string \| null | Identificador opcional definido na criação.              |
| `name`        | string         | Nome normalizado do produto.                             |
| `description` | string \| null | Descrição opcional.                                      |
| `price`       | decimal        | Preço em reais com duas casas decimais.                  |
| `status`      | enum           | `ACTIVE` ou `INACTIVE`.                                  |
| `createdAt`   | date-time      | Data de criação.                                         |
| `updatedAt`   | date-time      | Data da última atualização.                              |

<Tip>
  Use o `id` do produto no campo `items[].id` de `POST /checkouts`. Não envie o `externalId` nesse campo.
</Tip>