# Use a Stripe CLI

Desenvolva, teste e gerencie sua integração da Stripe da linha de comando.

Para mais detalhes, veja a [Referência à CLI da Stripe](https://docs.stripe.com/cli.md).

O Stripe CLI permite que você crie, teste e gerencie sua integração com a Stripe a partir da linha de comando. Com o CLI, você pode criar e gerenciar recursos da Stripe, acionar eventos de webhook, transmitir logs de solicitações de API em tempo real e encaminhar eventos para seu ambiente de desenvolvimento local.

## Especificar uma versão da API durante a execução de solicitações

Ao chamar as APIs da Stripe no CLI, ele usa a versão padrão da API em todas as solicitações, que você pode [identificar no Workbench](https://docs.stripe.com/workbench/guides.md#view-api-versions). Para testar diferentes versões da API no CLI, use as seguintes sinalizações:

| Sinalizador                          | Descrição                                                                                               | Exemplo                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `--stripe-version 2026-03-25.dahlia` | Use o sinalizador `--stripe-version` em qualquer solicitação do CLI para especificar uma versão da API. | `stripe products create --name=“My Product” --stripe-version 2026-03-25.dahlia` |
| `--latest`                           | Use `--latest` em qualquer solicitação do CLI para especificar a versão mais recente da API.            | `stripe products create --name="My Product" --latest`                           |

Você também pode [ver uma lista de versões da API](https://docs.stripe.com/upgrades.md#api-versions).

## Aprenda sobre opções de comando

Para aprender sobre opções para comandos específicos, adicione `--ajuda` para o comando.

```bash
   stripe listen --help
```

## Transmitir logs de solicitação

Use o comando `stripe logs tail` para transmitir logs de solicitações de API. Mantenha esta janela aberta. Se ocorrer um erro nas suas chamadas de API, este terminal retornará a mensagem de erro da API e o motivo do erro.

```bash
  stripe logs tail
```

## Encaminhe eventos para seu endpoint webhook local

Use o sinalizador `--forward-to` para enviar todos os [eventos da Stripe](https://docs.stripe.com/cli/trigger#trigger-event) em uma **área restrita** para o seu endpoint de webhook local. Para desabilitar a verificação de certificado HTTPS, use o sinalizador `skip-verify`.

```bash
  stripe listen --forward-to localhost:4242/webhooks
```

```bash
  Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

Para encaminhar eventos específicos em uma lista separada por vírgulas, use o sinalizador `--events`.

```bash
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,charge.succeeded,checkout.session.completed,charge.failed \
  --forward-to localhost:4242/webhook
```

Se você já [registou o seu endpoint na Stripe](https://docs.stripe.com/webhooks.md#register-webhook), poderá usar os sinalizadores `--load-from-webhooks-api` e `--forward-to`.

```bash
stripe listen --load-from-webhooks-api --forward-to localhost:4242
```

Este comando encaminha os eventos enviados ao seu endpoint de webhook **público** registrado no Stripe para o seu endpoint de webhook **local**. Ele carrega o endpoint registrado, analisa o caminho e os eventos registrados e, em seguida, anexa o caminho ao seu endpoint de webhook local no caminho `--forward-to`. Se estiver verificando assinaturas de webhook, use o `{{WEBHOOK_SIGNING_SECRET}}` da saída inicial do comando `listen`.

## Listar todos os eventos disponíveis

Use o [sinalizador de ajuda](https://docs.stripe.com/cli/help) (`--help`) para listar todos os eventos possíveis que podem ocorrer para uma categoria de evento. Por exemplo, para listar todos os eventos possíveis para a [página de checkout pré-criada](https://docs.stripe.com/checkout/quickstart.md) do [Stripe Checkout](https://docs.stripe.com/payments/checkout.md):

```bash
  stripe trigger checkout --help
```

## Crie um produto e um preço únicos

1. Faça uma única solicitação de API para [criar um produto](https://docs.stripe.com/api/products/create.md).

   ```bash
   stripe products create \
   --name="My First Product" \
   --description="Created with the Stripe CLI"
   ```

1. Procure o identificador do produto (em `id`) no objeto de resposta. Salve-o para a próxima etapa. Se tudo funcionou, a linha de comando exibirá a seguinte resposta:

   ```json
   {
     "id": "prod_LTenIrmp8Q67sa", // O identificador tem esta aparência.
     "object": "product",
     "active": true,
     "attributes": [],
     "created": 1668198126,
     "default_price": null,
     "description": "Created with the Stripe CLI",
     "identifiers": {},
     "images": [],
     "livemode": false,
     "metadata": {},
     "name": "My First Product",
     "package_dimensions": null,
     "price": null,
     "product_class": null,
     "shippable": null,
     "sku": "my-first-product-10",
     "statement_descriptor": null,
     "tax_code": null,
     "type": "service",
     "unit_label": null,
     "updated": 1668198126,
     "url": null
   }
   ```

1. Chame [Criar um preço](https://docs.stripe.com/api/prices/create.md) para anexar um preço de US$ 30. Troque o espaço reservado em `product` pelo seu identificador de produto (por exemplo, `prod_LTenIrmp8Q67sa`).

   ```bash
   stripe prices create \
     --unit-amount=3000 \
     --currency=usd \
     --product="{{PRODUCT_ID}}"
   ```

1. Se tudo funcionar, a linha de comando exibirá a seguinte resposta:

   ```json
   {
     "id": "price_1KzlAMJJDeE9fu01WMJJr79o", // O identificador tem esta aparência.
     "object": "price",
     "active": true,
     "billing_scheme": "per_unit",
     "created": 1652636348,
     "currency": "usd",
     "livemode": false,
     "lookup_key": null,
     "metadata": {},
     "nickname": null,
     "product": "prod_Lh9iTGZhb2mcBy",
     "recurring": null,
     "tax_behavior": "unspecified",
     "tiers_mode": null,
     "transform_quantity": null,
     "type": "one_time",
     "unit_amount": 3000,
     "unit_amount_decimal": "3000"
   }
   ```

## Acionar um evento de Webhook durante o teste

Acione o evento `checkout.session.completed` para criar os objetos de API que resultam da conclusão de uma sessão de checkout.

```bash
stripe trigger checkout.session.completed
```

Seu terminal `stripe listen` exibe a seguinte saída:

```bash
Setting up fixture for: checkout_session
Running fixture for: checkout_session
Setting up fixture for: payment_page
Running fixture for: payment_page
Setting up fixture for: payment_method
Running fixture for: payment_method
Setting up fixture for: payment_page_confirm
Running fixture for: payment_page_confirm
Trigger succeeded!
```