# Campos obrigatórios para criar um Pix Automático

> Quais campos a API exige para criar um Pix Automático, quais são opcionais e se o endereço do pagador é obrigatório.

Fonte: https://ajuda.woovi.com/hc/duvidas-frequentes/articles/1793063295-campos-obrigatorios-para-criar-um-pix-automatico
Categoria: Pix Automático
Atualizado em: 2026-10-28

Para criar um Pix Automático pela API, use o endpoint de assinaturas `POST /api/v1/subscriptions` com `type: PIX_RECURRING`. Abaixo estão os campos que a API exige e os que são opcionais.

Antes de começar: o Pix Automático precisa estar habilitado na sua conta. Se não estiver, a API responde com o erro "Pix Automatic not enabled for this company, talk with our support". Nesse caso, fale com o nosso suporte pelo chat.

## Campos obrigatórios

| Campo | O que enviar |
| --- | --- |
| `value` | Valor da assinatura **em centavos** (ex.: `1990` para R$ 19,90). Mínimo de 1 centavo. |
| `type` | Sempre `PIX_RECURRING`. Sem esse campo, a API cria uma assinatura comum, não um Pix Automático. |
| `customer.name` | Nome do pagador. Obrigatório quando o pagador ainda não existe na sua conta. |
| `customer.taxID` | CPF ou CNPJ do pagador. É por ele que a Woovi identifica o cliente. |
| `pixRecurringOptions.journey` | A jornada escolhida: `ONLY_RECURRENCY` (jornada 2) ou `PAYMENT_ON_APPROVAL` (jornada 3). |
| `pixRecurringOptions.retryPolicy` | Política de retentativa: `NON_PERMITED` (sem retentativa) ou `THREE_RETRIES_7_DAYS` (até 3 retentativas em 7 dias). |

## Campos opcionais

| Campo | O que acontece se não enviar |
| --- | --- |
| `frequency` | Usa `MONTHLY` (mensal). Aceita `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY` e `ANNUALLY`. `BIMONTHLY` não é aceito no Pix Automático. |
| `dayGenerateCharge` | Usa o dia 5. Aceita um dia do mês (1 a 31) ou uma data ISO 8601. |
| `dayDue` | Quantos dias a cobrança fica válida (de 3 a 7). |
| `comment` | Texto do contrato da recorrência. Se enviar, use até 30 caracteres. |
| `name` | Nome da assinatura, para você identificar no painel. |
| `correlationID` | Seu identificador da assinatura. Não pode repetir. |
| `pixRecurringOptions.minimumValue` | Só para valor variável. Veja o link no fim do artigo. |
| `customer.email` e `customer.phone` | Recomendados, mas não obrigatórios. |
| `customer.address` | Não é obrigatório. Veja a seção abaixo. |

## Regras de data por jornada

- **Jornada 3 (`PAYMENT_ON_APPROVAL`)**: o `dayGenerateCharge` precisa ser o dia de hoje, porque o pagador paga a primeira parcela ao autorizar.
- **Jornada 2 (`ONLY_RECURRENCY`)**: o `dayGenerateCharge` precisa estar pelo menos 3 dias à frente de hoje.

Se o dia informado já passou no mês atual, a primeira cobrança fica para o mês seguinte.

## Endereço do pagador

O `customer.address` pode ser omitido. Você consegue criar a assinatura só com nome, CPF/CNPJ e e-mail.

Se decidir enviar o endereço, ele precisa estar **completo**: `zipcode`, `street`, `number`, `neighborhood`, `city` e `state` (o `complement` é opcional). Endereço incompleto faz a API recusar o pedido.

Se não tiver o endereço completo do pagador, não envie o campo `address`.

## Pagador que já existe

A Woovi procura o pagador pelo CPF/CNPJ (`taxID`) dentro da sua conta:

- **Já existe**: o cadastro é reaproveitado e o `name` não precisa ser reenviado. Se você mandar um endereço, ele atualiza o do cliente.
- **Não existe**: um novo cliente é criado com os dados enviados.

## Se a API recusar

Quando falta um campo obrigatório ou algum valor é inválido, a API responde com **erro 400** e uma mensagem dizendo o que corrigir. Nesse caso, nada é criado e não há cobrança de tarifa.

## Exemplo mínimo

```json
{
  "value": 1990,
  "type": "PIX_RECURRING",
  "frequency": "MONTHLY",
  "customer": {
    "name": "Maria Silva",
    "taxID": "12345678909",
    "email": "maria@exemplo.com"
  },
  "pixRecurringOptions": {
    "journey": "PAYMENT_ON_APPROVAL",
    "retryPolicy": "NON_PERMITED"
  }
}
```

Na jornada 3, como no exemplo, você pode omitir o `dayGenerateCharge` só se hoje for dia 5. Nos outros dias, envie o dia de hoje.

## Links úteis

- [Como criar um Pix Automático (documentação da API)](https://developers.woovi.com/docs/pix-automatic/pix-automatic-how-to-create)
- [Qual jornada do Pix Automático escolher](https://developers.woovi.com/docs/pix-automatic/pix-automatic-how-to-choose-journey)
- [Pix Automático com valor variável](https://developers.woovi.com/docs/pix-automatic/pix-automatic-dynamic-value)