Documentação da API de promoções

GET /controla/promotions/list/{:companyId} Buscar promoções de uma companhia

Retorna a lista de promoções de uma companhia.

Parâmetros URL

companyIdobrigatórioID da companhia.

Parâmetros GET (querystring)

limitQuantidade máxima de promoções retornadas. Opcional.

200Sucesso

{
    "code": 200,
    "data": [
        {
            "id": 12,
            "type": "simple",
            "name": "Promoção de Verão",
            "branch_id": 3,
            "show_branch_name": true,
            "featured_in_app": false,
            "card": {
                "uri": "https://cdn.superaudio.com.br/uploads/promotions/card_12.jpg"
            },
            "branch": {
                "name_fantasy": "Rádio Exemplo FM"
            }
        }
    ]
}

404Companhia não encontrada

{
    "code": 404,
    "message": "Companhia não encontrada."
}

500Erro interno

{
    "code": 500,
    "message": "Erro interno do servidor."
}
GET /controla/promotion/{:promotionId} Buscar detalhes de uma promoção

Retorna os detalhes de uma promoção.

Headers

AuthorizationToken do usuário autenticado. Opcional — quando informado, a resposta inclui o campo participating com a situação do cliente autenticado nesta promoção.

Parâmetros URL

promotionIdobrigatórioID da promoção.

Se o promotionId não corresponder a uma promoção ativa, a resposta é 200 com "data": null.

200Sucesso

{
    "code": 200,
    "data": {
        "id": 12,
        "type": "question_answer",
        "name": "Promoção de Verão",
        "question": "Qual sua música preferida?",
        "description": "Participe e concorra a prêmios.",
        "rules": "Regulamento da promoção.",
        "branch_id": 3,
        "company_id": 45,
        "show_branch_name": true,
        "featured_in_app": false,
        "enable_cpf": false,
        "total_participants_init": 1,
        "total_participants_end": 100,
        "enable_random_number_generation": true,
        "card": {
            "uri": "https://cdn.superaudio.com.br/uploads/promotions/card_12.jpg"
        },
        "branch": {
            "name_fantasy": "Rádio Exemplo FM"
        },
        "participating": {
            "is_participating": true,
            "participationNumber": null,
            "participation": {
                "answer": "Minha resposta",
                "alternative_id": null,
                "participationNumber": 7
            }
        }
    }
}

401Não autorizado

{
    "code": 401,
    "message": "Unauthorized"
}

500Erro interno

{
    "code": 500,
    "message": "Erro interno do servidor."
}
GET /controla/promotion/winner/{:promotionId} Buscar o(s) ganhador(es) de uma promoção

Retorna o(s) ganhador(es) de uma promoção. Este endpoint é público — não exige o header Authorization nem qualquer outra autenticação. Note também que a resposta de sucesso tem um formato diferente dos demais endpoints desta API: o corpo é {"promotion": {...}}, sem o wrapper code usado nas outras respostas (o wrapper com code só aparece nas respostas de erro deste endpoint).

Parâmetros URL

promotionIdobrigatórioID da promoção.

200Sucesso

{
    "promotion": {
        "id": 12,
        "name": "Promoção de Verão",
        "type": "question_answer",
        "winners": [
            {
                "id": 501,
                "name_fantasy": "João da Silva",
                "email": "joao@exemplo.com",
                "answer": "Minha resposta",
                "location": {
                    "phone_1": "11999999999"
                }
            }
        ]
    }
}

404Nenhum ganhador encontrado

{
    "code": 404,
    "message": "Não foi encontrado nenhum ganhador"
}

500Erro interno

{
    "code": 500,
    "message": "Erro interno do servidor."
}
POST /controla/promotion/participate/{:promotionId} Participar de uma promoção

Registra a participação do usuário autenticado em uma promoção.

Headers

AuthorizationobrigatórioToken do usuário autenticado.
axios
    .post(url + promotionId, {
        answer: answer,
        alternative_id: alternativeId,
        cpf: cpf
    }, {
        headers: {
            Authorization: 'Bearer ' + token,
        }
    });

Parâmetros URL

promotionIdobrigatórioID da promoção.

Body (JSON)

answerResposta para promoções do tipo "Pergunta e Resposta" (obrigatório para esse tipo; máximo de 700 caracteres).
alternative_idID da alternativa escolhida, para promoções do tipo "Enquete" (obrigatório para esse tipo).
cpfCPF do usuário, obrigatório caso a promoção exija o preenchimento (campo enable_cpf da promoção).

200Sucesso

{
    "code": 200,
    "message": "Você está participando da promoção Promoção de Verão.",
    "participationNumber": 7
}

400Promoção expirada

{
    "code": 400,
    "message": "Promoção expirada"
}

401Não autorizado

{
    "code": 401,
    "message": "Unauthorized"
}

403Usuário não logado

{
    "code": 403,
    "message": "Você não está logado."
}

403Já está participando

{
    "code": 403,
    "message": "Você já está participando desta promoção."
}

404Promoção não encontrada

{
    "code": 404,
    "message": "Promoção não encontrada"
}

410Limite de participantes atingido

{
    "code": 410,
    "message": "Esta promoção atingiu o número maximo de participantes"
}

500Erro interno

{
    "code": 500,
    "message": "Erro interno do servidor."
}
POST /controla/promotion/unsubscribe Cancelar participação em uma promoção

Cancela a participação do usuário autenticado em uma promoção.

Headers

AuthorizationobrigatórioToken do usuário autenticado.
axios
    .post(url, {
        promotion_id: promotionId
    }, {
        headers: {
            Authorization: 'Bearer ' + token,
        }
    });

Body (JSON)

promotion_idobrigatórioID da promoção.

200Sucesso

{
    "code": 200
}

400ID da promoção ausente

{
    "code": 400,
    "message": "promotion id cannot be empty"
}

400Não está participando

{
    "code": 400,
    "message": "Você não está participando desta promoção."
}

400CPF já utilizado

{
    "code": 400,
    "message": "Não é possível cancelar a sua participação nesta promoção quando o CPF foi utilizado."
}

403Usuário não logado

{
    "code": 403,
    "message": "Você não está logado."
}

404Promoção não encontrada

{
    "code": 404,
    "message": "Promoção não encontrada"
}

500Erro interno

{
    "code": 500,
    "message": "Erro interno do servidor."
}
GET /controla/promotion/participating?promotion_id={:promotionId} Verificar se o usuário está participando de uma promoção

Verifica se o usuário autenticado está participando de uma promoção.

Headers

AuthorizationobrigatórioToken do usuário autenticado.
axios
    .get(url, {
        params: {
            promotion_id: promotionId
        },
        headers: {
            Authorization: 'Bearer ' + token,
        }
    });

Parâmetros GET (querystring)

promotion_idobrigatórioID da promoção.

200Sucesso

{
    "code": 200,
    "is_participating": true,
    "participationNumber": null,
    "participation": {
        "answer": "Minha resposta",
        "alternative_id": null,
        "participationNumber": 7
    }
}

400ID da promoção não informado

{
    "code": 400,
    "message": "Não foi informado o ID da promoção."
}

403Usuário não logado

{
    "code": 403,
    "message": "Você não está logado."
}

404Promoção não encontrada

{
    "code": 404,
    "message": "Promoção não encontrada"
}

500Erro interno

{
    "code": 500,
    "message": "Erro interno do servidor."
}