# Criar programação

Programe uma transferência única, recorrente ou condicionada ao saldo.

POST`/transfer-scheduled/create`

Try it

## Corpo da requisição

[label](#request-label)stringrequired

Nome da programação, até 120 caracteres.

[triggerType](#request-triggerType)stringrequired

ONCE, RECURRING ou BALANCE_THRESHOLD.

[payload](#request-payload)objectrequired

Dados do envio: method (pix_padrao ou interna), amount e destino.

[scheduledAt](#request-scheduledAt)string

Data e hora ISO futuras. Obrigatório em ONCE.

[recurrenceRule](#request-recurrenceRule)object

Regra para RECURRING. Use o fuso America/Sao_Paulo.

[balanceThreshold](#request-balanceThreshold)number

Saldo disponível mínimo para BALANCE_THRESHOLD.

[maxRuns](#request-maxRuns)integer

Limite opcional de execuções, entre 1 e 10.000.

## Headers

[Idempotency-Key](#headers-Idempotency-Key)stringrequired

Identificador único de até 128 caracteres. Preserve a chave e o corpo ao repetir a operação.

## Autorização

[X-API-Key](#auth-X-API-Key)stringrequired

Chave VibeCash com permissão para esta operação.

## Resposta

201 application/json

[success](#response-success)booleanrequired

Indica se a operação foi concluída pela API.

[message](#response-message)stringrequired

Mensagem da operação.

[data](#response-data)objectrequired

Dados retornados pela operação.

Show child attributes[id](#response-data-id)string

Identificador da programação.

[status](#response-data-status)string

Situação atual da programação.

[runCount](#response-data-runCount)integer

Quantidade de execuções registradas.

[nextRunAt](#response-data-nextRunAt)string | null

Data da próxima execução.

[requestId](#response-requestId)string

Identificador da requisição.

## Execução e estados

Programações dependem do serviço de execução ativo e de dois fatores habilitado na conta. Estados: `active`, `paused`, `processing`, `completed`, `failed` e `canceled`.

Recorrências aceitam `daily`, `weekly`, `monthly` e `custom_days`, no fuso `America/Sao_Paulo`. Em `custom_days`, informe `customDays` como lista dos dias da semana: 0 (domingo) a 6 (sábado).

## Erros

As falhas retornam o envelope com `success: false`. Consulte [erros e códigos HTTP](/docs/api-reference/guides/errors) para interpretar validação, permissão, conflito e saldo insuficiente.

## Exemplo de requisição

```bash
curl --request POST \
  --url 'https://seu-dominio/v1/transfer-scheduled/create' \
  --header 'X-API-Key: tp_live_SUA_CHAVE' \
  --header 'Idempotency-Key: operacao-unica-123' \
  --header 'Content-Type: application/json' \
  --data '{"label":"Pagamento programado","triggerType":"ONCE","scheduledAt":"2030-12-01T15:00:00.000Z","payload":{"method":"pix_padrao","amount":5,"coverFee":true,"pixKey":"recebedor@exemplo.com","pixKeyType":"EMAIL"}}'
```

## Exemplo de resposta

```json
{
  "success": true,
  "message": "Operação concluída",
  "data": {
    "id": "schedule_exemplo",
    "label": "Pagamento programado",
    "amount": 5,
    "method": "PIX",
    "destination": "recebedor@exemplo.com",
    "status": "active",
    "triggerType": "once",
    "nextRunAt": "2030-12-01T15:00:00.000Z",
    "lastRunAt": null,
    "runCount": 0,
    "maxRuns": null,
    "lastError": null
  },
  "requestId": "req_exemplo"
}
```
