Ofertas, planos e ofertas ocultas

Produto, oferta, plano e oferta de plano

A venda sempre aponta para uma oferta, não para o produto.

Em price e em offer.value, o valor que você envia é sempre em centavos, como número inteiro: 4990 = R$ 49,90. Nas respostas, o valor volta em reais. Veja Valores que você envia.

Meios de pagamento e valor mínimo

Na oferta e na oferta de plano, cada meio de pagamento tem um valor mínimo e é desligado ao salvar quando o preço fica abaixo dele. Veja a regra, os exemplos e a edição em Meios de pagamento e valor mínimo.

Duas formas de apontar a oferta numa cobrança

Nas rotas POST /payments/pix, POST /payments/boleto e POST /payments/credit-card, envie uma destas duas formas:

Enviar as duas ou nenhuma responde 400:

A resposta da cobrança traz offer_identifier com o código da oferta usada.

Os exemplos abaixo mostram só o campo da oferta. O restante do corpo, como customer, é o mesmo nas duas formas. Veja o corpo completo em Vender com PIX ou boleto.

Com offer_identifier

{
  "offer_identifier": "<CODIGO_DA_OFERTA>"
}

Com offer

{
  "offer": {
    "product_id": "c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f",
    "name": "Consultoria avulsa",
    "value": 4990,
    "createOffer": false
  }
}

Oferta informada na hora: reaproveitar ou criar

Com offer, a API procura uma oferta ativa que tenha exatamente:

• o mesmo produto;
• o mesmo nome;
• o mesmo valor;
• a mesma visibilidade (oculta ou não).

Se encontrar, usa essa oferta. Se não encontrar, cria uma nova. Enviar a mesma offer várias vezes não cria ofertas repetidas.

Na criação, a oferta aceita cartão com o maior número de parcelas que respeita a parcela mínima, até 12. Veja A regra da parcela mínima.

Oferta oculta

createOffer decide se a oferta criada fica visível:

A oferta oculta só funciona pela API, enviando offer de novo. Ela não aparece nem funciona nestes lugares:

Use a oferta oculta quando o preço é decidido pelo seu sistema na hora, por exemplo um orçamento, e você não quer essa oferta nas listagens.

Regras conferidas em toda cobrança

Com qualquer uma das duas formas, a API confere a oferta antes de cobrar:

Parcelas: oferta avulsa e oferta de plano

Na oferta avulsa, o máximo é o valor que você definir em max_credit_card_installments, respeitando a parcela mínima. Sem o campo, a API usa 12. Na oferta de plano, só 1: valor maior responde 400.

A assinatura pela API só aceita cartão. A oferta de plano precisa estar com o cartão ligado, senão a resposta é 409.

Guias relacionados