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

# Criar Carnê

> Venda um produto em até 12 boletos mensais

## Visão Geral

Cria um carnê e registra **apenas o primeiro boleto**. As parcelas seguintes são emitidas mês a mês, e a venda só se torna real quando a parcela 1 compensa.

<Warning>
  Carnê é **crédito concedido por você**, não parcelamento de cartão. Ninguém garante um boleto: se o comprador parar na parcela 4, você fica com 4 parcelas. Leia o [guia do carnê](/guias/carne) antes de ativar.
</Warning>

<Warning>
  **Envie sempre `X-Idempotency-Key`.** Esta chamada registra um boleto de verdade no banco — uma retentativa sem a chave coloca dois códigos de barras pagáveis na mão do mesmo comprador. A mesma chave devolve o carnê original por 24h.
</Warning>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://garu.com.br/api/v1/installment-plans \
    -H "Authorization: Bearer sk_live_sua_chave" \
    -H "Content-Type: application/json" \
    -H "X-Idempotency-Key: 6c4c2a1e-4c2b-4f1c-9a8d-1b2e3f4a5b6c" \
    -d '{
      "productId": "40381e8e-6ee7-4b8e-9393-766a6e2109d2",
      "customerId": 4821,
      "installments": 12
    }'
  ```

  ```javascript JavaScript theme={null}
  import { Garu } from '@garuhq/node';

  const garu = new Garu({ apiKey: process.env.GARU_API_KEY });

  const carne = await garu.installmentPlans.create({
    productId: '40381e8e-6ee7-4b8e-9393-766a6e2109d2',
    customerId: 4821,
    installments: 12
  });

  console.log(carne.totalScheduled);  // 1560
  console.log(carne.installmentAmount); // 130
  ```

  ```python Python theme={null}
  import os, uuid, requests

  r = requests.post(
      "https://garu.com.br/api/v1/installment-plans",
      headers={
          "Authorization": f"Bearer {os.environ['GARU_API_KEY']}",
          "X-Idempotency-Key": str(uuid.uuid4()),
      },
      json={
          "productId": "40381e8e-6ee7-4b8e-9393-766a6e2109d2",
          "customerId": 4821,
          "installments": 12,
      },
  )
  print(r.json()["totalScheduled"])  # 1560
  ```
</CodeGroup>

## Parâmetros

<ParamField body="productId" type="string" required>
  UUID do produto. O produto precisa ter carnê habilitado.
</ParamField>

<ParamField body="customerId" type="number" required>
  ID numérico do cliente. Clientes já têm um `uuid` público (veja [Clientes](/api-reference/clientes/criar)), mas este endpoint ainda linka pelo id numérico interno — obtenha-o via `POST /api/customers` (API interna) ou no dashboard.
</ParamField>

<ParamField body="installments" type="number" required>
  Número de parcelas, de 2 a 12. Uma parcela só não é carnê. O teto da plataforma é 12 e o vendedor pode definir um menor por produto.
</ParamField>

<ParamField body="firstDueDate" type="string">
  Vencimento da parcela 1 em `YYYY-MM-DD`. Padrão: hoje. Deve cair nos próximos 90 dias. As demais parcelas caem no mesmo dia dos meses seguintes, calculadas a partir dessa âncora — por isso um carnê ancorado em 31/01 não “escorrega” depois de fevereiro.
</ParamField>

<ParamField body="affiliateId" type="number">
  Afiliado que fez a venda. **Fixado no momento da venda**: todas as parcelas seguintes herdam ele, então omitir aqui significa não pagar comissão nenhuma no carnê inteiro. Precisa ter afiliação ativa neste produto — caso contrário a chamada é recusada, em vez de descartar a atribuição em silêncio.
</ParamField>

## Resposta

```json theme={null}
{
  "uuid": "e5d0d8fe-0000-4000-8000-000000000001",
  "status": "pending_activation",
  "installments": 12,
  "installmentsPaid": 0,
  "baseValue": 1200,
  "fator": 1.3,
  "installmentAmount": 130,
  "totalScheduled": 1560,
  "totalCollected": 0,
  "firstDueDate": "2026-09-05",
  "installmentsDetail": [
    {
      "number": 1,
      "amount": 130,
      "dueDate": "2026-09-05",
      "status": "scheduled",
      "boleto": { "barcodeLine": "50990...", "pdfUrl": "https://garu.com.br/..." },
      "reissueCount": 0
    }
  ]
}
```

<Note>
  Só a parcela 1 aparece com boleto. As demais ainda não existem como slip pagável — elas são criadas quando a parcela 1 compensa.
</Note>

## Erros

| Código | Quando                                                                                      |
| ------ | ------------------------------------------------------------------------------------------- |
| `400`  | Produto não aceita carnê, número de parcelas fora de 2..12, ou afiliado sem afiliação ativa |
| `404`  | Produto não encontrado nesta conta                                                          |
| `409`  | Um carnê idêntico acabou de ser criado para este cliente                                    |