🚀 Introdução
A Premify API permite integrar seu sistema com nossa plataforma de promoções e sorteios. Este guia apresenta o fluxo completo de integração, desde a autenticação até a geração de números da sorte.
Fluxo de Integração
1. Autenticação
→
2. Cadastro do Participante
→
3. Geração do Número da Sorte
🔐 Autenticação
Primeiro passo é obter o token de autenticação usando suas credenciais da campanha.
POST
https://promo.talkall.com.br/Api/Cliente/login
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| RotaCampanha | string | Sim | Rota específica da sua campanha |
| login | string | Sim | Seu login de acesso |
| senha | string | Sim | Sua senha de acesso |
Exemplo de Requisição
curl --location 'https://promo.talkall.com.br/Api/Cliente/login' \
--form 'RotaCampanha="{{SUA_ROTA}}"' \
--form 'login="{{SEU_LOGIN}}"' \
--form 'senha="{{SUA_SENHA}}"'
Resposta de Sucesso
{
"token": "138c50b60b6936c0f66e7d9d2a2aa085",
"validade": "2024-12-31 23:59:59"
}
⚠️ Importante
Armazene o token retornado, pois ele será necessário para todas as próximas chamadas da API.
👤 Cadastro do Participante
Após obter o token, você pode cadastrar participantes na promoção.
POST
https://promo.talkall.com.br/Api/Cliente/CadastrarParticipanteAPI
Cabeçalhos
| Cabeçalho | Valor |
|---|---|
| Authorization | Bearer {{SEU_TOKEN}} |
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| RotaCampanha | string | Sim | Rota da campanha |
| Nome | string | Sim | Nome completo do participante |
| Cpf | string | Sim | CPF do participante (apenas números) |
| string | Opcional | Email do participante | |
| Telefone | string | Opcional | Telefone do participante |
| Estado | string | Opcional | Estado (sigla - ex: SP, RJ) |
| Cidade | string | Opcional | Cidade do participante |
| Senha | string | Sim | Senha de acesso do participante |
| Sexo | int | Opcional | 1 = Masculino, 2 = Feminino |
| AceitoTermosPromocao | boolean | Sim | Aceite dos termos da promoção |
| AceitoContato | boolean | Sim | Aceite para contato |
| AceitoContatoPropagandas | boolean | Opcional | Aceite para receber propagandas |
| DataNascimento | date | Opcional | Data de nascimento (YYYY-MM-DD) |
Exemplo de Requisição
curl --location --request POST 'https://promo.talkall.com.br/Api/Cliente/CadastrarParticipanteAPI?RotaCampanha={{SUA_ROTA}}&Nome={{NOME_PARTICIPANTE}}&Cpf={{CPF_PARTICIPANTE}}&Rg={{RG_PARTICIPANTE}}&Endereco={{ENDERECO}}&Numero={{NUMERO}}&Telefone={{TELEFONE}}&Cep={{CEP}}&Estado={{ESTADO}}&Cidade={{CIDADE}}&Email={{EMAIL}}&Senha={{SENHA}}&Sexo={{SEXO}}&AceitoTermosPromocao={{ACEITO_TERMOS}}&AceitoContato={{ACEITO_CONTATO}}&AceitoContatoPropagandas={{ACEITO_PROPAGANDAS}}&DataNascimento={{DATA_NASCIMENTO}}' \
--header 'Authorization: Bearer {{SEU_TOKEN}}'
Resposta de Sucesso
{
"msg": "Cadastro efetuado com Sucesso!",
"participante": {
"IdParticipante": "N0anqb4NuDXKqo_c2_S2B5fQtcPr2O_a0_Eloc",
"Nome": "{{NOME_PARTICIPANTE}}",
"Cpf": "{{CPF_PARTICIPANTE}}",
"Email": "{{EMAIL}}"
},
"GerarPosicaoCadastro": false,
"Chances": {}
}
📝 Importante
Armazene o IdParticipante retornado na resposta, pois será necessário para gerar números da sorte.
GerarPosicaoCadastro: Quando true, indica que a campanha gera números da sorte automaticamente no cadastro. Neste caso, os números estarão no campo Chances.
🎲 Geração do Número da Sorte
Última etapa da integração: gerar números da sorte para o participante. Disponibilizamos duas opções para geração dos números:
Opção 1: Por Compra
Gere números da sorte baseado em compras ou ações específicas do participante.
Opção 2: Por Nota Fiscal
Gere números da sorte através do cadastro de uma nota fiscal específica.
📦 Opção 1: Geração por Compra
Use esta opção para gerar números da sorte baseado em compras ou ações específicas.
POST
https://promo.talkall.com.br/Api/Cliente/GerarNumeroDaSorteAPI
Cabeçalhos
| Cabeçalho | Valor |
|---|---|
| Authorization | Bearer {{SEU_TOKEN}} |
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| RotaCampanha | string | Sim | Rota da campanha |
| ProdutoID | string | Sim | ID do produto relacionado |
| IdParticipante | string | Sim | ID do participante (obtido no cadastro) |
| QuantidadeProduto | string | Sim | Quantidade do produto comprado |
| ValorCompra | int | Sim (Para campanhas que for por valor) | Valor total da compra |
| Info | string | Opcional | Informações adicionais (ex: CNPJ, nota fiscal) |
Exemplo de Requisição
curl --location 'https://promo.talkall.com.br/Api/Cliente/GerarNumeroDaSorteAPI' \
--header 'Authorization: Bearer {{SEU_TOKEN}}' \
--form 'RotaCampanha="{{SUA_ROTA}}"' \
--form 'ProdutoID="{{PRODUTO_ID}}"' \
--form 'IdParticipante="{{ID_PARTICIPANTE}}"' \
--form 'QuantidadeProduto="{{QUANTIDADE}}"' \
--form 'ValorCompra="{{VALOR_COMPRA}}"' \
--form 'Info="{{INFORMACOES_ADICIONAIS}}"'
Resposta de Sucesso
{
"msg": "Número da sorte gerado com sucesso!",
"numerosSorte": [
{
"numero": "000123456",
"posicao": 1
}
],
"totalChances": 1
}
🧾 Opção 2: Geração por Nota Fiscal
Use esta opção para gerar números da sorte através do cadastro de uma nota fiscal específica.
POST
https://promo.talkall.com.br/Api/Cliente/CadastrarNotaFiscalAPI
Cabeçalhos
| Cabeçalho | Valor |
|---|---|
| Authorization | Bearer {{SEU_TOKEN}} |
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| RotaCampanha | string | Sim | Rota da campanha |
| ProdutoID | string | Sim | ID do produto relacionado |
| TokenParticipante | string | Sim | Token/ID do participante (obtido no cadastro) |
| Quantidade | string | Sim | Quantidade do produto na nota fiscal |
| Valor | string | Sim | Valor total da nota fiscal |
| Cnpj | string | Sim | CNPJ do estabelecimento emissor da nota |
| Origem | string | Sim | Origem da nota fiscal (0 = Sistema) |
| NumeroNota | string | Sim | Número da nota fiscal |
Exemplo de Requisição
curl --location 'https://promo.talkall.com.br/Api/Cliente/CadastrarNotaFiscalAPI' \
--header 'Authorization: Bearer {{SEU_TOKEN}}' \
--form 'RotaCampanha="{{SUA_ROTA}}"' \
--form 'ProdutoID="{{PRODUTO_ID}}"' \
--form 'TokenParticipante="{{TOKEN_PARTICIPANTE}}"' \
--form 'Quantidade="{{QUANTIDADE}}"' \
--form 'Valor="{{VALOR}}"' \
--form 'Cnpj="{{CNPJ}}"' \
--form 'Origem="{{ORIGEM}}"' \
--form 'NumeroNota="{{NUMERO_NOTA}}"'
Resposta de Sucesso
{
"msg": "Nota fiscal cadastrada com sucesso!",
"numerosSorte": [
{
"numero": "000789123",
"posicao": 1
}
],
"totalChances": 1,
"notaFiscal": {
"id": "12345",
"numero": "{{NUMERO_NOTA}}",
"cnpj": "{{CNPJ}}",
"valor": "{{VALOR}}"
}
}
🔍 Diferenças entre as Opções
- Opção 1 (Por Compra): Ideal para campanhas baseadas em compras gerais ou ações específicas
- Opção 2 (Por Nota Fiscal): Específica para campanhas que exigem comprovação fiscal detalhada
- Parâmetros únicos da Nota Fiscal: CNPJ, Número da Nota e Origem são obrigatórios
- TokenParticipante vs IdParticipante: Use o mesmo valor obtido no cadastro do participante
📚 Resumo da Integração
🔄 Fluxo Completo
- Autenticação: Obter token usando credenciais da campanha
- Cadastro: Registrar participante e obter IdParticipante
- Número da Sorte: Escolher entre geração por compra ou nota fiscal
🔑 Pontos Importantes
- Sempre inclua o token de autorização no cabeçalho das requisições
- Armazene o IdParticipante para futuras operações
- Verifique o campo GerarPosicaoCadastro para campanhas que geram números automaticamente
- Escolha a opção de geração de números mais adequada para sua campanha
- Para campanhas com nota fiscal, certifique-se de ter CNPJ e número da nota válidos
- Trate adequadamente os erros e respostas da API
⚡ Dicas de Implementação
- Ambiente de Teste: Use https://localhost:44315 para testes locais
- Ambiente de Produção: Use https://promo.talkall.com.br para produção
- Validação de CPF: Envie apenas números, sem pontuação
- Tratamento de Erros: Implemente retry logic para falhas temporárias
- Logs: Registre todas as chamadas da API para facilitar debugging