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

# Criar programação

> Agenda transferência única, recorrente ou automática por saldo.

Veja também o [guia de transferências programadas](/api-reference/guides/pix#transferencias-programadas).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.goatpay.com.br/v1/transfer-scheduled/create' \
    -H 'X-API-Key: gp_live_SUA_CHAVE' \
    -H 'Content-Type: application/json' \
    -d '{
      "label": "Repasse mensal",
      "triggerType": "RECURRING",
      "payload": {
        "method": "pix_padrao",
        "amount": 500,
        "description": "Repasse fornecedor",
        "pixKey": "12345678909",
        "pixKeyType": "CPF"
      },
      "recurrenceRule": {
        "interval": "monthly",
        "time": "09:00",
        "dayOfMonth": 5
      },
      "maxRuns": 12
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "message": "Programação de transferência criada",
    "data": {
      "id": "clx_sched_01",
      "label": "Repasse mensal",
      "amount": 500,
      "method": "PIX Padrão",
      "destination": "123.456.789-09",
      "triggerType": "recurring",
      "scheduleLabel": "Todo dia 5 às 09:00",
      "nextRunAt": "2026-07-05T12:00:00.000Z",
      "lastRunAt": null,
      "runCount": 0,
      "status": "active",
      "coverFee": true
    },
    "requestId": "req_abc123"
  }
  ```

  ```json Error — data inválida theme={null}
  {
    "success": false,
    "message": "A data do agendamento deve ser no futuro",
    "requestId": "req_err001"
  }
  ```

  ```json Error — limite atingido theme={null}
  {
    "success": false,
    "message": "Limite de 20 programações ativas atingido",
    "requestId": "req_err002"
  }
  ```
</ResponseExample>

### Corpo da requisição

<ParamField body="triggerType" type="string" required>
  `ONCE` (agendar data), `RECURRING` (repetir) ou `BALANCE_THRESHOLD` (por saldo).
</ParamField>

<ParamField body="payload" type="object" required>
  Dados da transferência a executar (ver campos abaixo).
</ParamField>

<ParamField body="payload.method" type="string" required>
  `pix_padrao`, `interna` ou `cripto`.
</ParamField>

<ParamField body="payload.amount" type="number" required>
  Valor em reais (mín. R\$ 0,01). Na regra por saldo, é o valor enviado (limitado ao saldo disponível).
</ParamField>

<ParamField body="payload.description" type="string">
  Descrição da transferência.
</ParamField>

<ParamField body="payload.coverFee" type="boolean">
  Padrão `true` em PIX — `amount` é o valor recebido pelo destinatário.
</ParamField>

<ParamField body="payload.pixKey" type="string">
  Chave PIX (quando `method` é `pix_padrao`).
</ParamField>

<ParamField body="payload.pixKeyType" type="string">
  `CPF`, `CNPJ`, `EMAIL`, `TELEFONE` ou `CHAVE_ALEATORIA`.
</ParamField>

<ParamField body="payload.pixKeyOwnerDocument" type="string">
  CPF/CNPJ do titular (opcional/legado).
</ParamField>

<ParamField body="payload.recipientEmail" type="string">
  E-mail da conta destino GoatPay (quando `method` = `interna`).
</ParamField>

<ParamField body="payload.address" type="string">
  Endereço on-chain (quando `method` = `cripto`).
</ParamField>

<ParamField body="payload.payCurrency" type="string">
  Código da moeda/rede (cripto), ex. `usdttrc20`.
</ParamField>

<ParamField body="payload.extraId" type="string">
  Memo/tag (cripto), quando exigido pela rede.
</ParamField>

<ParamField body="payload.subaccountId" type="string">
  ID da subconta merchant (saque PIX da subconta).
</ParamField>

<ParamField body="scheduledAt" type="string">
  ISO 8601 — **obrigatório** para `ONCE`; deve ser no futuro.
</ParamField>

<ParamField body="recurrenceRule" type="object">
  **Obrigatório** para `RECURRING`.
</ParamField>

<ParamField body="recurrenceRule.interval" type="string">
  `daily`, `weekly`, `monthly` ou `custom_days`.
</ParamField>

<ParamField body="recurrenceRule.time" type="string">
  Horário local, ex. `09:00` (padrão `09:00`).
</ParamField>

<ParamField body="recurrenceRule.timezone" type="string">
  Fuso IANA (padrão `America/Sao_Paulo`).
</ParamField>

<ParamField body="recurrenceRule.dayOfWeek" type="integer">
  0=domingo … 6=sábado (recorrência semanal).
</ParamField>

<ParamField body="recurrenceRule.dayOfMonth" type="integer">
  1–31 (recorrência mensal).
</ParamField>

<ParamField body="recurrenceRule.customDays" type="integer">
  Intervalo em dias (quando `interval` = `custom_days`).
</ParamField>

<ParamField body="balanceThreshold" type="number">
  Saldo mínimo em reais — **obrigatório** para `BALANCE_THRESHOLD`.
</ParamField>

<ParamField body="maxRuns" type="integer">
  Limite de execuções (recorrência). Omita para ilimitado (máx. 9999).
</ParamField>

<ParamField body="label" type="string">
  Nome exibido no painel (máx. 120 caracteres).
</ParamField>

<ParamField body="coverFee" type="boolean">
  Padrão `true` — aplica-se à execução PIX quando não definido em `payload.coverFee`.
</ParamField>

<ParamField body="contactId" type="string">
  ID de contato salvo no dashboard (opcional).
</ParamField>

### Campos principais em `data`

| Campo           | Descrição                                        |
| --------------- | ------------------------------------------------ |
| `id`            | ID da programação                                |
| `label`         | Rótulo ou descrição gerada                       |
| `amount`        | Valor configurado no `payload`                   |
| `method`        | Rótulo legível (ex. PIX Padrão, Interna)         |
| `destination`   | Chave, e-mail ou endereço mascarado              |
| `triggerType`   | `once`, `recurring` ou `balance_threshold`       |
| `scheduleLabel` | Texto legível da regra (ex. Todo dia 5 às 09:00) |
| `nextRunAt`     | Próxima execução (ISO) ou `—` em regra por saldo |
| `lastRunAt`     | Última execução (ISO), se houver                 |
| `runCount`      | Quantidade de execuções já realizadas            |
| `status`        | `active`, `paused`, `completed` ou `failed`      |
| `coverFee`      | Se a taxa é absorvida pelo remetente             |

### Exemplos de `triggerType`

**Agendar uma vez**

```json theme={null}
{
  "triggerType": "ONCE",
  "scheduledAt": "2026-06-15T17:00:00.000Z",
  "payload": {
    "method": "interna",
    "amount": 100,
    "description": "Pagamento parceiro",
    "recipientEmail": "parceiro@empresa.com"
  }
}
```

**Por saldo**

```json theme={null}
{
  "triggerType": "BALANCE_THRESHOLD",
  "balanceThreshold": 5000,
  "payload": {
    "method": "pix_padrao",
    "amount": 1000,
    "description": "Sweep automático",
    "pixKey": "contato@email.com",
    "pixKeyType": "EMAIL"
  }
}
```

<Note>
  Limite de **20 programações ativas** por conta. Transferências imediatas continuam em `POST /transfer-pix/create`.
</Note>


## OpenAPI

````yaml POST /transfer-scheduled/create
openapi: 3.1.0
info:
  title: GoatPay API
  description: >
    API pública merchant da GoatPay. Autenticação via header `X-API-Key:
    gp_live_...`.

    Respostas de sucesso usam o envelope `{ success, message, data, requestId
    }`.

    Campos internos (`accountId`, `metadata`, histórico de entregas de webhook,
    etc.) não são expostos.

    `providerTransactionId` aparece como `referenceId`; `providerInfractionId`
    como `infractionId`.

    Rate limit global: 100 requisições por minuto por API key (HTTP 429). Sem
    chave, limite por IP.
  version: 1.0.0
servers:
  - url: https://api.goatpay.com.br/v1
    description: Produção
security:
  - apiKeyAuth: []
tags:
  - name: pix
    description: >-
      Cobranças PIX (receber), reembolsos de depósito recebido e transferências
      PIX (enviar). Alias legado em payouts/* para envios.
  - name: transfer-internal
    description: Transferências entre contas GoatPay
  - name: transfer-scheduled
    description: Transferências programadas (agendar, repetir ou por saldo)
  - name: crypto
    description: Depósitos e transferências em criptomoeda
  - name: billings
    description: >-
      Cobranças avulsas (pagamento único) — boleto, cartão ou PIX na Conta
      Padrão (PF ou PJ)
  - name: subscriptions
    description: >-
      Assinaturas recorrentes com ciclo fixo — boleto, cartão ou PIX na Conta
      Padrão (PF ou PJ)
  - name: account
    description: Saldo e extrato
  - name: subaccount
    description: Subcontas merchant (carteiras lógicas sob a conta principal)
  - name: meds
    description: Disputas MED
  - name: webhooks
    description: Endpoints de webhook de saída
  - name: payouts
    description: Alias de transfer-pix para saques PIX
  - name: customers
    description: Clientes da loja (CRM)
  - name: products
    description: Produtos e entregas digitais
  - name: coupons
    description: Cupons de desconto para links
  - name: payment-links
    description: Links de pagamento e checkout hospedado
paths:
  /transfer-scheduled/create:
    post:
      tags:
        - transfer-scheduled
        - pix
      summary: Criar programação de transferência
      description: >
        Agenda envio único, recorrente ou automático por saldo mínimo.

        O objeto `payload` define o destino (PIX, interna ou cripto) — mesmos
        campos do dashboard.

        Limite de 20 programações ativas por conta.
      operationId: createTransferScheduled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledTransfer'
      responses:
        '200':
          $ref: '#/components/responses/ScheduledTransferSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    CreateScheduledTransfer:
      type: object
      required:
        - triggerType
        - payload
      properties:
        label:
          type: string
          maxLength: 120
        triggerType:
          type: string
          enum:
            - ONCE
            - RECURRING
            - BALANCE_THRESHOLD
          description: |
            ONCE — data/hora única (`scheduledAt`).
            RECURRING — repetição (`recurrenceRule`).
            BALANCE_THRESHOLD — envia quando saldo ≥ `balanceThreshold`.
        payload:
          $ref: '#/components/schemas/ScheduledTransferPayload'
        coverFee:
          type: boolean
          default: true
        scheduledAt:
          type: string
          format: date-time
          description: Obrigatório para ONCE; deve ser no futuro.
        recurrenceRule:
          $ref: '#/components/schemas/ScheduledTransferRecurrenceRule'
        balanceThreshold:
          type: number
          minimum: 0
          description: Saldo mínimo em reais (BALANCE_THRESHOLD).
        maxRuns:
          type: integer
          minimum: 1
          maximum: 9999
          description: Limite de execuções (RECURRING).
        contactId:
          type: string
          description: Contato salvo no dashboard (opcional).
    ScheduledTransferPayload:
      type: object
      required:
        - method
        - amount
      properties:
        method:
          type: string
          enum:
            - pix_padrao
            - interna
            - cripto
        amount:
          type: number
          minimum: 0.01
        coverFee:
          type: boolean
          default: true
        description:
          type: string
        pixRail:
          type: string
          enum:
            - PADRAO
          description: Herdado da API key quando omitido.
        pixKey:
          type: string
        pixKeyType:
          type: string
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - TELEFONE
            - CHAVE_ALEATORIA
        pixKeyOwnerDocument:
          type: string
        recipientEmail:
          type: string
          format: email
          description: Transferência interna GoatPay.
        address:
          type: string
          description: Endereço on-chain (cripto).
        payCurrency:
          type: string
          description: Código da moeda/rede (cripto).
        extraId:
          type: string
          description: Memo/tag (cripto).
        subaccountId:
          type: string
    ScheduledTransferRecurrenceRule:
      type: object
      required:
        - interval
      properties:
        interval:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - custom_days
        time:
          type: string
          example: '09:00'
          description: Horário no fuso `timezone` (padrão America/Sao_Paulo).
        timezone:
          type: string
          default: America/Sao_Paulo
        dayOfWeek:
          type: integer
          minimum: 0
          maximum: 6
          description: 0=domingo … 6=sábado (recorrência semanal).
        dayOfMonth:
          type: integer
          minimum: 1
          maximum: 31
          description: Dia do mês (recorrência mensal).
        customDays:
          type: integer
          minimum: 1
          maximum: 365
          description: Intervalo em dias (quando interval=custom_days).
    PublicScheduledTransfer:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        amount:
          type: number
        method:
          type: string
        destination:
          type: string
        triggerType:
          type: string
          enum:
            - once
            - recurring
            - balance_threshold
        scheduleLabel:
          type: string
        nextRunAt:
          type: string
        lastRunAt:
          type: string
        runCount:
          type: integer
        status:
          type: string
          enum:
            - active
            - paused
            - completed
            - failed
        coverFee:
          type: boolean
    ErrorEnvelope:
      type: object
      required:
        - success
        - message
        - error
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Subconta inativa
        error:
          type: object
          properties:
            code:
              type: string
              example: Bad Request
            statusCode:
              type: integer
              example: 400
        requestId:
          type: string
          example: req_abc123
  responses:
    ScheduledTransferSuccess:
      description: Programação de transferência criada, consultada ou atualizada.
      content:
        application/json:
          schema:
            type: object
            required:
              - success
              - message
              - data
            properties:
              success:
                type: boolean
              message:
                type: string
              data:
                $ref: '#/components/schemas/PublicScheduledTransfer'
              requestId:
                type: string
    Unauthorized:
      description: Chave ausente, inválida ou revogada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Chave sem permissão para este endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Chave `gp_live_...` criada em Integrações → Chaves de API no dashboard.

````