Criar Promoção

Introdução

Esta seção descreve o processo de criação de promoções no ambiente de sandbox da Open API Magalu.

Pré-requisitos

Antes de criar uma promoção, certifique-se de atender aos seguintes requisitos:

• Utilizar um token válido no header Authorization;
• Informar um channel.id válido para o ambiente de sandbox;
• Enviar datas de vigência em UTC (Z) e com início no futuro.

Exemplo de Requisição

Abaixo, um exemplo de chamada utilizando cURL para criação de uma promoção:

curl --request POST \
  --url https://api-sandbox.magalu.com/samples/v1/promotions \
  --header 'authorization: ******' \
  --header 'content-type: application/json' \
  --data '{
  "name": "Black Friday Promo",
  "type": {
    "id": "PERCENTAGE_DISCOUNT"
  },
  "scope": "FULL_CATALOG",
  "channel": {
    "id": "5f62650a-0039-4d65-9b96-266d498c03bd"
  },
  "validity": {
    "starts_at": "2027-11-20T00:00:00Z",
    "ends_at": "2027-11-30T23:59:59Z",
    "subscription_deadline": "2027-11-19T23:59:59Z"
  },
  "benefits": {
    "investment": {
      "seller": {
        "total": {
          "type": "percentage",
          "normalizer": 100,
          "value": 1500
        }
      },
      "channel": {
        "type": "percentage",
        "normalizer": 100,
        "value": 500
      }
    },
    "payment_methods": [
      {
        "id": "visa"
      }
    ]
  }
}'

Neste exemplo:

• type.id: tipo da promoção (ex.: PERCENTAGE_DISCOUNT);
• scope: abrangência da promoção (FULL_CATALOG, SELLER_CHOICE ou ADMIN_CHOICE);
• channel.id: identificador do canal de sandbox;
• validity: período de vigência e prazo final para adesão;
• benefits: regras de investimento da promoção.

Cenário de Sucesso

{
  "id": "promo-123"
}

Cenários de Erro

Estes são exemplos de respostas de erro que podem ser retornadas durante a execução de requisições no ambiente de sandbox.

Cenário de Erro	Código HTTP	Como simular o cenário
PromotionMappingError	400	Envie payload com valores incompatíveis com o mapeamento esperado da promoção.
Unauthorized	401	Utilize um token inválido ou ausente no cabeçalho da requisição.
Internal Server Error	500	Ocorre quando há falha inesperada após a criação da promoção (ex.: erro ao vincular seller).