Cria uma campanha no sistema. Possibilita a adição de anúncios.

O 'request' deve ser realizado com o método POST

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Requisitos: 

Antes de criar uma campanha, devem estar registrados no sistema:

• O anunciante. (É necessário saber seu identificador)

• O(s) site(s) onde será publicada a campanha. É necessário saber seus identificadores.

• O(s) espaço(s) onde será publicada a campanha. É necessário saber seus identificadores.

• Se a otimização por eCPM para alguma prioridade estiver ativada, isto deve ser levado em consideração ao carregar uma campanha que possua prioridade com otimização por eCPM, já que neste caso deverão ser indicados, obrigatoriamente, os parâmetros prioridade_prova e quantidade_impressões_prova, assim como o preço da campanha. É possível averiguar quais prioridades estão ativadas para otimização por eCPM nas preferências do sistema. 

Parâmetros obrigatórios:

• nome: nome da campanha. Deve respeitar as condições para nomes válidos (ver mais adiante). Não pode haver campanhas do mesmo anunciante com o mesmo nome, mesmo que tenham sido excluídas.

• site_id: identificador do anunciante.

• ordem_id: identificador da ordem (A ordem com qual se quer associar a nova campanha deve ser do mesmo Anunciante)

• tipovenda_id: tipo de comercialização. Ver valores possíveis em 'Referências'.

• cpa_tracer_id: Somente para os casos em que se tenha optado por CPA como tipo de comercialização, deve-se informar o identificador do código de conversão relacionado.

• pauta_tracer_id: se optou por CPA como tipo de comercialização, deve indicar neste campo, obrigatoriamente, o mesmo valor inserido em cpa_tracer_id.

• quantidade_total: quantidade de impressões, cliques ou conversões, segundo o tipo de comercialização da campanha. O parâmetro é opcional no caso de campanhas Sponsor e não deve ser incluído no caso de campanhas onde se indica a quantidade de ações espaço por espaço (ver parâmetro ações_por_espaço abaixo).

• prioridade: prioridade da campanha em relação a outras que competem pelo mesmo espaço. Valores possíveis: de 1 a 10.

• peso: peso da campanha em relação a outras que competem pelo mesmo espaço. Valores possíveis: de 1 a 100.

• intervalo_ativação: identificador do intervalo de ativação da campanha. Ver valores possíveis em 'Referências' - Intervalos de ativação de campanhas. De acordo com o valor informado, devem ser inseridos também os seguintes parâmetros:

Para campanhas com data de início e data de finalização:

- data_início: data de início da campanha, no formato definido para o usuário na interface (DD/MM/AAAA ou MM/DD/AAAA).

- hora_início: horário de início da campanha, em HH:MM:SS.

- data_fim: data de finalização da campanha. Deve ser posterior à data de início.

- hora_fim: horário de finalização da campanha.

Para campanha com múltiplas datas de início e fim:

- data_início_0, data_início_1, ... até data_início_9: datas de início (é obrigatório informar pelo menos uma). Não podem se sobrepor.

- data_fim_0, data_fim_1, ... até data_fim_9: datas de finalização correspondentes a cada uma das datas de início inseridas.

Para campanhas com horário semanal:

- target_horário_semanal_0: horário para a segunda-feira. Deve-se indicar cada uma das horas nas quais estará ativa a campanha na segunda-feira. Ex: “9 10 11 12 13 14 15 16” para uma campanha que estará ativa de 9:00 a 16:59.

- target_horário_semanal_1 a 6: idem, para terça-feira a domingo.

• ptmodo_id: para campanhas não sponsor, deve-se especificar o modo de distribuição das impressões, cliques ou conversões. Ver valores possíveis em 'Referências' – Modos de distribuição de campanhas.

• target_site_id: listagem de sites, separados por espaços, onde será publicada a campanha. Utilizar os identificadores.

• target_espaço_id: identificadores dos espaços onde será publicada a campanha. 

• ação_atraso_data_fim: somente para campanhas não Sponsor, deve-se indicar como proceder quando a campanha chega à data de finalização sem ter atingido a quantidade estabelecida. Ver valores possíveis em 'Referências' – Ação ao atrasar uma Campanha.

Se a prioridade estabelecida tem a otimização por eCPM ativada, também são obrigatórios os seguintes atributos:

- prioridade_prova: prioridade da campanha durante o período de prova

- quantidade_impressões_prova: quantidade de impressões que deve publicar a campanha durante o período de prova

Parâmetros opcionais:

Estes são apenas alguns dos parâmetros opcionais e não representam todos os que estão disponíveis através da interface online. A customização completa da campanha pode ser realizada através da interface online.

• numero_oc: número da ordem de compra, utilizado como identificador. Pode conter, no máximo, 16 caracteres.  

• data_oc: data da ordem de compra. Somente pode ser especificada se o numero_oc também for especificado. Caso contrário será ignorada.

• ações_por_espaço: 0 ou 1. Se for 1, permite especificar a quantidade de ações (impressões, cliques ou conversões) espaço por espaço. Ex: a campanha publica 40.000 impressões no espaço A e 20.000 no espaço B. Se for indicado 1, deve-se especificar, para cada espaço, o parâmetro:

- quantidade_total_<espaço_id>: quantidade de ações para o espaço <espaço_id>.

• max_impressões_usuário: quantidade máxima de vezes que cada usuário pode ver a campanha. Número entre 1 e 254.

• max_impressões_sessão: quantidade máxima de vezes que cada usuário pode ver a campanha em uma sessão.  Número entre 1 e 254.

• intervalo_sessões: intervalo entre sessões, em horas. Número entre 1 e 720.  Ver o Manual do Usuário para obter uma explicação destes últimos três parâmetros.

• stop_after_click: insira 1 se deseja que uma campanha não seja mais mostrada a um usuário que já tenha clicado na mesma.

• max_ações_hora: quantidade máxima de ações a serem mostradas por hora. Por exemplo, se a campanha é por impressões e o número 1.000 é inserido neste parâmetro, a mesma não exibirá mais de 1.000 impressões por hora. Se é por cliques, não exibirá mais a campanha uma vez atingidos os 1.000 cliques por hora.

• max_ações_dia: idem anterior, mas por dia.

• max_ações_semana: idem, por semana

• max_ações_mes: idem, por mês.

• optim_banners_ctr: insira 1 se deseja que o peso dos anúncios da campanha seja otimizado automaticamente.

• cobrança_anunciante_tpreço_modalidade: modalidade de preços. Permite inserir preços globais para toda a campanha (todos os espaços têm o mesmo preço) ou preços por espaço (cada espaço tem um preço diferente). Ver valores possíveis em 'Referências' - Modalidades de preços. É obrigatório especificar um valor se deseja indicar o preço da campanha. Além disso, se foi definido nas preferências do sistema que é obrigatório indicar preços para todas as campanhas, ou se você estiver criando uma campanha com otimização por eCPM, é obrigatório especificar um valor para este atributo.

Se optou pela modalidade de preços global:

• cobrança_anunciante_tpreço_venda: forma de comercialização da campanha com o anunciante. Ver valores possíveis em 'Referências' - Tipo de comercialização de campanha. Não é necessário que o valor seja o mesmo que tipovenda_id. tipovenda_id determina quantas vezes será exibida a campanha. Este parâmetro determina como será cobrada.

•  cobrança_anunciante_moeda_id: identificador da moeda na qual se vende a campanha ao anunciante. Ver valores possíveis em 'Referências' - Moedas.

• cobrança_anunciante_vpreço: preço da campanha para o anunciante. Se a campanha é vendida por impressões, indique o preço por CPM. Se for por cliques (CPC), indique o preço por clique. Se for sponsor, indique o preço total da campanha.

 
Se optou pela modalidade de preços por espaço, por cada espaço_id selecionado devem-se especificar os seguintes parâmetros, substituindo <espaço_id> pelo código do espaço:

• cobrança_anunciante_tpreço_venda_<espaço_id>: forma de comercialização para o espaço. Idem cobrança_anunciante_tpreço_venda.

• cobrança_anunciante_moeda_id_<espaço_id>: moeda de comercialização do espaço. Ver valores possíveis em 'Referências' - Moedas.

• cobrança_anunciante_preço_<espaço_id>: preço para o espaço.

Se deseja ativar Concorrência à campanha, devem ser adicionados os seguintes parâmetros:

• campanha_concorrente_self: o valor será sempre 'on'. Isto indicará que deseja ativar a concorrência consigo mesma.
• campanhas_concorrentes: especificar se a concorrência será 'Individual' ou por 'Grupos' (Valores possíveis: 1 - Individual // 2 - Grupos)
• campanhas_concorrentes_id_target: especificar o identificador da campanha que se estabelecerá como concorrência Individual (se deseja ativar mais de uma, separar os identificadores com um espaço)
• concor_gcampanha_id: especificar o identificador do Grupo que se estabelecerá como concorrência (se deseja ativar mais de um, separar os identificadores com um espaço)

Se deseja segmentar a campanha para um ou mais países, deverão ser acrescentados os seguintes parâmetros:

• target_ccountries: listagem de códigos ISO-3166 de países, separados por espaço (ex: “US CA MX”)

• target_country: inserir 1 para segmentação positiva (a campanha é exibida se o usuário está em algum dos países indicados) ou -1 para segmentação negativa (a campanha é exibida se o usuário NÃO está em nenhum dos países indicados).

Se deseja segmentar a campanha por Palavras-Chave, os seguintes parâmetros deverão ser acrescentados:

•  target_keyword: inserir sempre o valor 1

• target_keyword_type: deve-se enviar este parâmetro se a segmentação selecionada contém duas ou mais 'Palavras-Chave'. Inserir '67108864', se todas devem coincidir, ou '134217728', se ao menos uma deve coincidir.

• ptk_used_<tkeyword_id>: inserir sempre 'on'.

• ptk_op_<tkeyword_id>: é um número de 1 a 5 que se refere ao tipo de configuração selecionado para os valores da 'Palavra-Chave'

          '1' Coincidência exata para Palavras-Chave de tipo texto com opções, tabela de dados, texto livre e numéricas (somente no caso de selecionar lista de valores) 

          '5' Coincidência parcial para Palavras-Chave de tipo texto com opções, tabela de dados, texto livre

          '2' Valor mínimo para Palavras-Chave de tipo números inteiros e decimais. 

          '3' Valor máximo para Palavras-Chave de tipo números inteiros e decimais. 

          '4' Valor mínimo e máximo para Palavras-Chave de tipo números inteiros e decimais.

• ptk_max_value_<tkeyword_id>: indica o valor mínimo do intervalo selecionado, para o caso de 'Palavras-Chave' de tipo numérico.

• ptk_min_value_<tkeyword_id>: indica o valor máximo do intervalo selecionado, para o caso de 'Palavras-Chave' de tipo numérico.

• kwv_<tkeyword_id>: indica os valores da Palavra-Chave. Para o caso de 'Palavras-Chave' texto livre e numéricas (somente no caso de selecionar lista de valores), os valores devem ser enumerados separados por vírgula ','. Ex: 'casa,cachorro' '10,20'. Para o caso de 'Palavras-Chave' de tipo Tabela de Dados ou Texto com Opções, devem ser especificados os valores expressos no id do sistema separados pelo sinal de adição '+'. Ex: '988+986'.

*Para saber os id do sistema, sugere-se 'inspecionar' os elementos da Segmentação por Palavra-Chave dentro do formulário de Registro de Campanha utilizando Firebug.

VEJA OS EXEMPLOS DE REQUEST NO FINAL DO ARTIGO

Parâmetros opcionais, disponíveis em interface de agência ou network:

pagamento_site_tpreço_modalidade: modalidade de preço – global ou por espaço. idem cobrança_anunciante_tpreço_modalidade.

Se optou por preços globais:

- pagamento_site_tpreço_venda: forma em que a campanha pagará ao site. Idem cobrança_anunciante_tpreço_venda.

- pagamento_site_moeda_id: moeda na qual se pagará ao site. Ver valores possíveis em 'Referências' - Moedas. 

- pagamento_site_preço: preço que será pago ao site. Ver valores possíveis em 'Referências' - cobrança_anunciante_preço.

Se optou pela modalidade de preços por espaço, por cada espaço_id selecionado devem-se especificar os seguintes parâmetros, substituindo <espaço_id> pelo código do espaço:

- pagamento_site_tpreço_venda_<espaço_id>: forma de comercialização para o espaço. Idem cobrança_anunciante_tpreço_venda.

- pagamento_site_moeda_id_<espaço_id>: moeda de comercialização do espaço. Ver valores possíveis em 'Referências' - Moedas.

- pagamento_site_preço_<espaço_id>: preço para o espaço. 

Exemplo de request:

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros:

Explicação dos parâmetros:

• nome: Teste CPM
• site_id: 52432 – o identificador do anunciante dono da campanha
• tipovenda_id: 1 (campanha por CPM)
• quantidade_total: 100000 impressões
• prioridade: 1
• peso: 1
• intervalo_ativação: data de início e data de finalização
• data_início: 23/03/2006
• data_fim: 23/04/2006
• hora_início: 15:00:00
• hora_fim: 23:59:59
• ptmodo_id: 1 – distribuição uniforme de impressões
• target_site_id: 13212 – o identificador do site onde será publicada a campanha.
• target_espaço_id: 45234, 541, 426. A campanha será publicada em 3 espaços.
• ação_atraso_data_fim: 0 – continuar até atingir o total da campanha.
• cobrança_anunciante_tpreço_modalidade: 3 – preços diferentes por espaço
• cobrança_anunciante_tpreço_venda_45234, cobrança_anunciante_moeda_id_45234, cobrança_anunciante_preço_45234: o espaço 45234 se vende por CPM, em moeda 1 (dólares) a um preço de 3,50 o CPM.
• cobrança_anunciante_tpreço_venda_541, cobrança_anunciante_moeda_id_541, cobrança_anunciante_preço_541: o espaço 541 se vende por CPM, em moeda 1 (dólares) a um preço de 2,50 o CPM.
• cobrança_anunciante_tpreço_venda_4256, cobrança_anunciante_moeda_id_4256 cobrança_anunciante_preço_4256: o espaço 4256 se vende por CPC, em moeda 1 (dólares) a um preço de 0,20 o clique. 

Resposta:

Contém um objeto <operação> que, por sua vez, contém uma tag <resultado>. O valor de resultado pode ser 1 (operação bem-sucedida) ou 0 (operação malsucedida).

Se a operação for malsucedida, é adicionada, também, uma listagem de erros mediante tags <erro> que contêm o atributo - que especifica o nome do atributo com erro - e mensagem, com a mensagem de erro.

Exemplo de resposta sem erros

Exemplo de resposta com erros

Exemplo de request utilizando PALAVRAS-CHAVE:

CASO 1: Segmentação por Palavra-Chave 'Idade' tipo Numérica (Valores selecionados 10 e 20)

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros:

&sitio_id=2943&nombre=test+api+kw+9&tipoventa_id=1&cpa_tracer_id=&prioridad=1&cantidad_total=10000&peso=100&target_sitio_id=10199&target_espacio_id=183181&intervalo_activacion=1&fecha_inicio=21%2F03%2F2013&hora_inicio=22%3A00%3A00&fecha_fin=20%2F04%2F2013&hora_fin=23%3A59%3A59&ptmodo_id=3&cobro_anunciante_tprecio_modo=1&cobro_anunciante_tprecio_venta=1&cobro_anunciante_precio=1&cobro_anunciante_moneda_id=5&accion_retraso_fecha_fin=0&target_keyword=1&ptk_used_496=0n&ptk_op_496=1&kwv_496=10,20

CASO 2: Segmentação por Palavra-Chave 'Idade' tipo Numérica (Valores selecionados Mín 10 e Máx 20)

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros:

&sitio_id=2943&nombre=test+api+kw+8&tipoventa_id=1&cpa_tracer_id=&prioridad=1&cantidad_total=10000&peso=100&target_sitio_id=10199&target_espacio_id=183181&intervalo_activacion=1&fecha_inicio=21%2F03%2F2013&hora_inicio=22%3A00%3A00&fecha_fin=20%2F04%2F2013&hora_fin=23%3A59%3A59&ptmodo_id=3&cobro_anunciante_tprecio_modo=1&cobro_anunciante_tprecio_venta=1&cobro_anunciante_precio=1&cobro_anunciante_moneda_id=5&accion_retraso_fecha_fin=0&target_keyword=1&ptk_used_496=0n&ptk_op_496=4&ptk_max_value_496_4=20&ptk_min_value_496_4=10

CASO 3: Segmentação por Palavra-chave 'Moeda' tipo Texto com Opções (Valores selecionados 'Dólar' e 'Peso', cujos ids no sistema são '151719' e '151721', respectivamente)

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros:

&sitio_id=2943&nombre=test+api+kw+7&tipoventa_id=1&cpa_tracer_id=&prioridad=1&cantidad_total=10000&peso=100&target_sitio_id=10199&target_espacio_id=183181&intervalo_activacion=1&fecha_inicio=21%2F03%2F2013&hora_inicio=22%3A00%3A00&fecha_fin=20%2F04%2F2013&hora_fin=23%3A59%3A59&ptmodo_id=3&cobro_anunciante_tprecio_modo=1&cobro_anunciante_tprecio_venta=1&cobro_anunciante_precio=1&cobro_anunciante_moneda_id=5&accion_retraso_fecha_fin=0&target_keyword=1&ptk_used_425=0n&ptk_op_425=1&kwv_425=151719+151721

CASO 4: Segmentação por Palavra-Chave 'Categoria' tipo Tabela de Dados (Valores selecionados 'Esportes' e 'Música' cujos ids no sistema são '838' e '840' respectivamente)

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros:

&sitio_id=2943&nombre=test+api+kw+10&tipoventa_id=1&cpa_tracer_id=&prioridad=1&cantidad_total=10000&peso=100&target_sitio_id=10199&target_espacio_id=183181&intervalo_activacion=1&fecha_inicio=21%2F03%2F2013&hora_inicio=22%3A00%3A00&fecha_fin=20%2F04%2F2013&hora_fin=23%3A59%3A59&ptmodo_id=3&cobro_anunciante_tprecio_modo=1&cobro_anunciante_tprecio_venta=1&cobro_anunciante_precio=1&cobro_anunciante_moneda_id=5&accion_retraso_fecha_fin=0&target_keyword=1&ptk_used_67=0n&ptk_op_67=1&kwv_67=838+840

CASO 5: Segmentação por Palavra-chave 'Buscador' tipo Texto Livre (Valores selecionados 'Maçã' e 'Pera')

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros:

&sitio_id=2943&nombre=test+api+kw+11&tipoventa_id=1&cpa_tracer_id=&prioridad=1&cantidad_total=10000&peso=100&target_sitio_id=10199&target_espacio_id=183181&intervalo_activacion=1&fecha_inicio=21%2F03%2F2013&hora_inicio=22%3A00%3A00&fecha_fin=20%2F04%2F2013&hora_fin=23%3A59%3A59&ptmodo_id=3&cobro_anunciante_tprecio_modo=1&cobro_anunciante_tprecio_venta=1&cobro_anunciante_precio=1&cobro_anunciante_moneda_id=5&accion_retraso_fecha_fin=0&target_keyword=1&ptk_used_499=0n&ptk_op_499=5&kwv_499=manzana,naranja

CASO 6: Segmentação por duas Palavras-Chave 'Buscador' tipo Texto Livre (Valores selecionados 'Maçã' e 'Pera') e 'Idade' tipo Numérica (valores selecionados mín 10 e máx 20)

URL: /admin/adnet/pub/admin/pautas.html?op=a&o=xml

Parâmetros: