Criar campanhas a partir de links

Recebe de 1 a 50 links de produto e, para cada link, gera a promoção (texto, imagem e link de afiliado, com as integrações da sua conta) e cria uma campanha no segmento informado. O trabalho é assíncrono: a resposta é um pedido de promoção (id_promotion_job) com o estado de cada link em items.

201 — o pedido terminou dentro de wait_seconds.
202 — o pedido segue em andamento: acompanhe pelo header Location (GET /api/external/info-promotion-job/<id_promotion_job>).
200 — mesma Idempotency-Key e mesmo corpo: devolve o pedido original, sem criar nada de novo.

O header Idempotency-Key é obrigatório. A mesma chave com outro corpo devolve 422 com idempotency_key_reused.

A falha de um link não vira erro HTTP: o link aparece em items com status: failed e error.code. Com on_error: all_or_nothing, nenhuma campanha é criada se algum link falhar.

App de parceiro (OAuth): exige promotions:write e campaigns:send; o código e o link do cupom aplicado voltam mascarados.

Modo de teste (sk_test_): respostas sintéticas, sem gerar nem criar nada. Use id_segment: segment_test_1; sandbox_error e sandbox_warning simulam falha e aviso.

Authorization

x-api-key<token>

Chave de API no formato sk_live_..., no header x-api-key.

In: header

Query Parameters

sandbox_error?string

Só no modo de teste (sk_test_): o último link do pedido falha com este código de erro de item (ex.: link_invalid). Ignorado com credencial real.

sandbox_warning?string

Só no modo de teste (sk_test_): os links criados recebem este aviso (ex.: outside_sending_window). Ignorado com credencial real.

Header Parameters

Idempotency-Key*string

Chave de idempotência, obrigatória neste endpoint. Use um valor único por pedido (ex.: um UUID) e repita o MESMO valor ao re-tentar: o pedido original é devolvido e nenhuma campanha é criada em dobro.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Corpo de create-campaign/promotion. Campo fora desta lista é recusado (unknown_field).

id_segment*string

Segmento que recebe as campanhas. Precisa ter ao menos um canal conectado.

Lengthlength <= 100

links*array<>

Links http(s) de produto das lojas suportadas pelo gerador de promoções do painel. O mesmo link repetido no pedido é gerado uma vez só; a repetição volta skipped com duplicate_link.

Items1 <= items <= 50

template?

Qual template monta a mensagem. Sem este campo, vale mode: default.

coupon?

Cupom aplicado a todos os links do pedido. Um tipo por pedido.

discount?

Desconto usado no preço da mensagem. Quando enviado, vale no lugar do desconto do cupom salvo.

schedule?

Quando as campanhas saem. Sem este campo, vale mode: now.

on_error?string

skip = cria as campanhas dos links que deram certo; all_or_nothing = só cria se todos os links derem certo.

Default"skip"

Value in

"skip"
"all_or_nothing"

name_prefix?string

Prefixo do nome das campanhas (padrão: "Promoção API"). O nome leva também o título do produto.

Lengthlength <= 60

wait_seconds?integer

Quanto tempo a resposta espera o pedido terminar. Padrão 30 com 1 link e 0 com vários.

Range0 <= value <= 45

allow_duplicate?boolean

true permite repetir um link já enviado ao mesmo segmento nos últimos 10 minutos. Sem isso, o link volta skipped com recent_duplicate.

Defaultfalse

mode?"create"

Só create por enquanto.

Default"create"

Value in

"create"

Response Body

`application/json`

curl -X POST "https://example.com/api/external/create-campaign/promotion" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "id_segment": "segment_xxx",    "links": [      "https://shopee.com.br/produto-exemplo-i.123456.7890123"    ]  }'

{  "success": true,  "id_promotion_job": "string",  "status": "queued",  "mode": "create",  "id_segment": "string",  "on_error": "skip",  "summary": {    "total": 0,    "queued": 0,    "processing": 0,    "generated": 0,    "created": 0,    "failed": 0,    "skipped": 0,    "cancelled": 0,    "expired": 0  },  "items": [    {      "index": 0,      "link": "string",      "store": "string",      "status": "queued",      "id_campaign": "string",      "campaign_status": "string",      "scheduled_at": "2019-08-24T14:15:22Z",      "product": {        "title": "string"      },      "message": "string",      "link_url": "string",      "template_applied": {        "mode": "id",        "id_template": "string"      },      "coupon_applied": {        "code": "string",        "link": "string"      },      "discount_applied": true,      "error": {        "code": "string",        "message": "string",        "retryable": true      },      "warnings": [        "string"      ]    }  ],  "created_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z"}

{  "success": true,  "id_promotion_job": "promotion_job_6f1c2d3e-0000-4000-8000-000000000000",  "status": "completed",  "mode": "create",  "id_segment": "5b7e1a2c-0000-4000-8000-000000000000",  "on_error": "skip",  "summary": {    "total": 1,    "queued": 0,    "processing": 0,    "generated": 0,    "created": 1,    "failed": 0,    "skipped": 0,    "cancelled": 0,    "expired": 0  },  "items": [    {      "index": 0,      "link": "https://shopee.com.br/produto-exemplo-i.123456.7890123",      "store": "shopee",      "status": "created",      "id_campaign": "campaign_9a0b4c1d-0000-4000-8000-000000000000",      "campaign_status": "pending",      "scheduled_at": null,      "product": {        "title": "Fone de ouvido sem fio"      },      "message": "🔥 Fone de ouvido sem fio\nDe R$ 199,90 por R$ 149,90\nhttps://exemplo.com/s/abc123",      "link_url": "https://exemplo.com/s/abc123",      "template_applied": {        "mode": "id",        "id_template": "2c4d8e0f-0000-4000-8000-000000000000"      },      "coupon_applied": null,      "discount_applied": false,      "warnings": []    }  ],  "created_at": "2026-09-15T12:00:00.000Z",  "finished_at": "2026-09-15T12:00:14.000Z"}

{  "success": true,  "id_promotion_job": "string",  "status": "queued",  "mode": "create",  "id_segment": "string",  "on_error": "skip",  "summary": {    "total": 0,    "queued": 0,    "processing": 0,    "generated": 0,    "created": 0,    "failed": 0,    "skipped": 0,    "cancelled": 0,    "expired": 0  },  "items": [    {      "index": 0,      "link": "string",      "store": "string",      "status": "queued",      "id_campaign": "string",      "campaign_status": "string",      "scheduled_at": "2019-08-24T14:15:22Z",      "product": {        "title": "string"      },      "message": "string",      "link_url": "string",      "template_applied": {        "mode": "id",        "id_template": "string"      },      "coupon_applied": {        "code": "string",        "link": "string"      },      "discount_applied": true,      "error": {        "code": "string",        "message": "string",        "retryable": true      },      "warnings": [        "string"      ]    }  ],  "created_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z"}

{  "success": false,  "error": "Bad Request",  "code": "unsupported_link",  "message": "O link na posição 2 não é um link http(s) de loja suportada.",  "field": "links[2]"}

{  "success": false,  "error": "Unauthorized",  "message": "Chave de API inválida ou ausente."}

{  "success": false,  "error": "Forbidden",  "code": "plan_feature_locked",  "message": "Seu plano permite 1 link por pedido. Para vários links de uma vez é preciso o Multi Sender.",  "feature": "multi_sender"}

{  "success": false,  "error": "Not Found",  "code": "promotion_job_not_found",  "message": "Pedido de promoção não encontrado."}

{  "success": false,  "error": "Payload Too Large",  "code": "payload_too_large",  "message": "O corpo do pedido passa de 256 KB."}

{  "success": false,  "error": "Unprocessable Entity",  "code": "coupon_expired",  "message": "Este cupom está vencido.",  "field": "coupon.id_coupon"}

{  "success": false,  "error": "Too Many Requests",  "code": "too_many_active_jobs",  "message": "Esta conta já tem 3 pedidos de promoção em andamento. Aguarde um terminar."}

{  "success": false,  "error": "Internal Server Error",  "code": "internal_error",  "message": "Erro interno ao processar o pedido de promoção."}

{  "success": false,  "error": "Service Unavailable",  "code": "service_paused",  "message": "A geração de promoções pela API está pausada no momento. Tente novamente mais tarde."}

Criar campanhas a partir de links

Authorization

Query Parameters

Header Parameters

Request Body

Response Body

200application/json

201application/json

202application/json

400application/json

401application/json

403application/json

404application/json

413application/json

422application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`