API Reference

💳 Ofertas

Rotas para listar, criar, editar e desvincular as ofertas dos grupos da plataforma. Os campos completos de cada rota, com exemplos, estão nas páginas de referência desta seção.

Headers obrigatórios

  • Authorization: Bearer {token}
  • X-Requested-With: XMLHttpRequest

(Os mesmos do “Getting Started”.)

As quatro rotas exigem as ofertas habilitadas na plataforma e, cada uma, o seu recurso de plano.

RotaRecurso de plano
GET /groups/{groupId}/offersPublic API – List Group Offers
POST /groups/{groupId}/offersPublic API – Create Offer
PATCH /offers/{offerId}Public API – Update Offer
DELETE /groups/{groupId}/offers/{offerId}Public API – Detach Group Offer

Como uma oferta é organizada

  • O tipo de pagamento (payment_type) é unique (pagamento único), recurrent (assinatura) ou carne (carnê).
  • Pagamento único e carnê têm uma cobrança, sem frequência.
  • A recorrente tem uma cobrança por frequência: monthly, quarterly, semiannual ou annual. Cada frequência tem o seu valor.
  • Cada cobrança vinculada a um grupo tem o seu link de checkout. Uma assinatura mensal e anual no mesmo grupo tem dois links.

Os campos da resposta têm o mesmo nome dos campos da criação e da edição. O que a listagem devolve pode ser reenviado na edição.

📋 Listar as ofertas de um grupo

GET https://sua-plataforma.ensinio.cloud/public/api/v1/groups/{groupId}/offers

Retorna todas as ofertas vinculadas ao grupo, sem paginação. Cada oferta traz os links de checkout que tem neste grupo. Order bumps não aparecem.

Exemplo de resposta

{
  "data": [
    {
      "id": 346,
      "title": "Clube do Livro",
      "description": "Um livro por mês",
      "payment_type": "recurrent",
      "price": 49.9,
      "carne_delinquency_condition": null,
      "payment_methods": ["credit_card", "pix"],
      "visibility": "public",
      "enable_expiration": false,
      "expiration_type": null,
      "expiration_date": null,
      "expiration_count": null,
      "expiration_interval": null,
      "redirect_type": "custom",
      "redirect_url": "https://minhaescola.com/obrigado",
      "checkout_format": "onepage",
      "checkout_links": [
        {
          "group_id": 12,
          "frequency": "monthly",
          "price": 49.9,
          "max_installments": 1,
          "free_installments": 1,
          "url": "https://sua-plataforma.ensinio.com/payment/g/aK29dLq0ZpX7m"
        },
        {
          "group_id": 12,
          "frequency": "annual",
          "price": 499,
          "max_installments": 12,
          "free_installments": 3,
          "url": "https://sua-plataforma.ensinio.com/payment/g/Rt5nWc8yHe1Vo"
        }
      ]
    }
  ]
}

price é o valor da oferta. Na recorrente com mais de uma frequência, é o da primeira, na ordem mensal, trimestral, semestral e anual. O valor de cada frequência está no link dela.

➕ Criar uma oferta no grupo

POST https://sua-plataforma.ensinio.cloud/public/api/v1/groups/{groupId}/offers

Cria a oferta ativa e já vinculada ao grupo. Responde 201 com a oferta criada, no mesmo formato da listagem, incluindo o id e o link de checkout.

Campos

CampoTipoObrigatórioPadrãoDescrição
titlestring✅—Título da oferta (até 255 caracteres).
pricenumber✅—Valor, maior que zero e até 100.000.
payment_typestring✅—unique, recurrent ou carne.
frequencystringna recorrente—monthly, quarterly, semiannual ou annual.
max_installmentsintegerno carnê1No cartão, o máximo de parcelas, de 1 a 12. No carnê, o número de parcelas, de 1 a 24, sem nenhuma abaixo de R$ 1.
free_installmentsinteger❌1Parcelas sem juros no cartão, de 1 a 12. Ignorado no carnê, onde toda parcela é sem juros.
carne_delinquency_conditionstringno carnê—all_overdue ou single_overdue: a regra de bloqueio e de volta do acesso por inadimplência.
descriptionstring❌—Descrição.
payment_methodsstring[]❌os trêscredit_card, pix e boleto.
enable_expirationboolean❌falseLiga a expiração do acesso. Sem true, o acesso é vitalício, mesmo que o tipo e o valor venham.
expiration_typestringse a expiração estiver ligadadeduzidofixed_date ou relative_to_start (a partir da compra).
expiration_datedatena data fixa—Data em que o acesso expira (AAAA-MM-DD).
expiration_countintegera partir da compra—Quantidade de expiration_interval depois da compra.
expiration_intervalstringa partir da compra—day, week, month ou year.
visibilitystring❌publicpublic ou restricted.
redirect_typestring❌defaultPágina de obrigado: default (da plataforma) ou custom (externa).
redirect_urlurlse custom—Endereço da página de obrigado externa.
checkout_formatstring❌stepssteps (em etapas) ou onepage (uma página). Só os formatos habilitados na plataforma.

Expiração do acesso

A expiração é a validade do acesso que o aluno compra, e não o período de venda da oferta. Toda oferta criada pela API fica disponível para compra sem prazo.

  • A expiração só vale com enable_expiration: true. Tipo e valor enviados sem ele ficam gravados, mas a expiração continua desligada e o acesso é vitalício.
  • Na data fixa, o acesso termina em expiration_date. A partir da compra, termina expiration_count vezes expiration_interval depois da compra.
  • Quando expiration_type não vem, ele é deduzido: expiration_date indica data fixa, e expiration_count com expiration_interval indicam a partir da compra.
  • A expiração se aplica ao pagamento único e ao carnê. Na recorrente, o acesso dura enquanto a assinatura estiver paga.

Carnê exige o recurso Carnê Digital no plano da plataforma.

Exemplos

Pagamento único, só o obrigatório

{ "title": "Mentoria Individual", "price": 497, "payment_type": "unique" }

Assinatura mensal com página de obrigado externa

{
  "title": "Clube do Livro",
  "price": 49.9,
  "payment_type": "recurrent",
  "frequency": "monthly",
  "payment_methods": ["credit_card", "pix"],
  "redirect_type": "custom",
  "redirect_url": "https://minhaescola.com/obrigado"
}

Pagamento único com acesso por 12 meses

{
  "title": "Curso de Fotografia",
  "price": 600,
  "payment_type": "unique",
  "enable_expiration": true,
  "expiration_count": 12,
  "expiration_interval": "month"
}

Carnê em 12 parcelas

{
  "title": "Formação Completa",
  "price": 1800,
  "payment_type": "carne",
  "max_installments": 12,
  "carne_delinquency_condition": "all_overdue"
}

✏️ Editar uma oferta

PATCH https://sua-plataforma.ensinio.cloud/public/api/v1/offers/{offerId}

Altera só os campos enviados. Os campos são os mesmos da criação, todos opcionais, e as regras valem para o estado final da oferta. Enviar só enable_expiration: true, por exemplo, funciona quando a oferta já tem o tipo de expiração gravado. Ligar ou desligar a expiração vale para as próximas vendas, e os acessos já vendidos não mudam. A resposta traz a oferta atualizada, com os links de todos os grupos dela.

Valor, parcelas e frequência

  • Numa oferta com uma cobrança só, price, max_installments e free_installments alteram essa cobrança.
  • Numa recorrente com mais de uma frequência, informe em frequency qual delas alterar. Sem isso, ou com uma frequência que a oferta não tem, a resposta é 422.
  • Numa recorrente com uma frequência só, enviar outra frequency troca a frequência.
  • Mudar payment_type para recurrent exige frequency. Mudar para unique ou carne deixa a oferta com uma cobrança só.
  • Entrar no carnê exige max_installments, que passa a ser o número de parcelas. Sair do carnê volta as parcelas para 1, a menos que elas venham na requisição.
{ "frequency": "annual", "price": 899 }

Links de checkout na edição

Mudar só o valor ou as parcelas mantém o link de checkout. Mudar a frequência, ou trocar entre recorrente e outro tipo, cria uma cobrança nova e, com ela, um link novo em cada grupo da oferta. O link antigo deixa de funcionar. Quem já comprou mantém o acesso.

🔗 Desvincular uma oferta do grupo

DELETE https://sua-plataforma.ensinio.cloud/public/api/v1/groups/{groupId}/offers/{offerId}

Remove os links de checkout da oferta neste grupo, de todas as frequências. A oferta não é excluída. Ela continua na plataforma e nos outros grupos a que está vinculada, e quem já comprou mantém o acesso.

{
  "message": "Oferta desvinculada do grupo com sucesso.",
  "group_id": 12,
  "offer_id": 345
}

Possíveis respostas

  • 200 OK — listagem, edição ou desvínculo concluídos.
  • 201 Created — oferta criada.
  • 401 Unauthorized — token ausente ou inválido.
  • 403 Forbidden — recurso não habilitado no plano.
  • 404 Not Found — grupo ou oferta não encontrado. Grupo arquivado também responde 404.
  • 405 Method Not Allowed — as ofertas não estão habilitadas na plataforma.
  • 422 Unprocessable Entity — erro de validação, com o nome do campo enviado em errors. No desvínculo, a oferta não está vinculada ao grupo.
  • 429 Too Many Requests — limite de requisições excedido.

Updated 17 days ago

Did this page help you?

Updated 17 days ago

Did this page help you?