Integração de parceiro

É o canal pelo qual um parceiro do cliente cadastra participantes e envia notas direto para a campanha, sem passar pelo hotsite. São três operações: emitir o token, cadastrar participante e cadastrar nota. É comunicação entre servidores, com credencial própria.

Este artigo cobre só o que um parceiro integra. As rotas administrativas do painel e as plataformas parceiras de comunidade, que têm contrato próprio, não fazem parte desse canal.

O token

O parceiro troca uma credencial de duas partes (identificador e segredo) por um token de integração. Credencial inválida ou parceiro inativo recusam com não autorizado.

O cliente e a campanha vêm dentro do token. Não há identificador de cliente nem de campanha na chamada — o token já diz a quem ele pertence. Isso é o que impede um parceiro de alcançar a campanha de outro.

A emissão do token tem o mesmo limite de tentativas apertado das escritas públicas, como proteção contra tentativa de adivinhar o segredo. O parceiro recebe a credencial; ele não a emite.

Cadastro de participante

As regras são as mesmas do cadastro público, porque elas valem para quem participa e não para o canal da inscrição:

• idade: campanha que não permite menor de idade (o padrão) exige data de nascimento e 18 anos completos; permitindo menor, exige a idade mínima configurada. Em CNPJ não se aplica;
• CNPJ: razão social é obrigatória; data de nascimento e sexo são opcionais;
• estado: campanha com validação de estado ligada, ou restrita a alguns estados, exige o estado. Na campanha restrita, o estado tem de ser um dos estados dela;
• CEP e estado: quando os dois vêm preenchidos, precisam ser do mesmo estado. Um CEP de um estado com o estado de outro é recusado;
• aceite do regulamento: na campanha com aceite obrigatório, o cadastro sem o aceite dos termos é recusado. O parceiro envia os aceites junto com o cadastro;
• campos do formulário: os campos obrigatórios do formulário do participante são exigidos, e o valor tem de servir ao tipo do campo. Campo personalizado é respondido pela chave; chave fora do formulário é ignorada, não recusa o pedido. A conferência é sobre o estado final do cadastro — o que já foi respondido numa inscrição anterior conta. A recusa lista todos os pendentes de uma vez, pelo rótulo da tela.

Documento já cadastrado no cliente: a inscrição é aberta no cadastro existente e os dados enviados só preenchem o que ele ainda não tem. Aqui sem conferir senha, porque o cadastro do parceiro não tem uma — o token do parceiro é a credencial. (No hotsite, a mesma situação confere a senha.)

Inscrição repetida é conflito. Já existe cadastro daquele documento naquela campanha.

Chance por cadastro: quando a campanha tem regra de base Cadastro ativa no Sorteio, os números da sorte da inscrição são emitidos na mesma operação do cadastro — ou tudo entra, ou nada entra. A inscrição repetida não gera de novo; ela é recusada antes.

Cadastro de nota

A nota do parceiro passa pelas mesmas conferências do cadastro pelo hotsite. O canal não muda as regras. Algumas merecem atenção de quem integra:

• aceite pendente: se a campanha exige o aceite e a participação ainda não tem, a nota é recusada com a mensagem pedindo o aceite na área logada. Quem resolve é o próprio participante, pelo hotsite: consentimento não é dado por terceiro. Isso acontece com quem se inscreveu antes de a campanha passar a exigir o termo. O participante criado pelo parceiro não tem senha e não entra no hotsite, então nesse caso ele fica sem como aceitar;
• estado: com a validação de estado ligada, o estado da nota é obrigatório e tem de ser o do cadastro do participante. Na campanha restrita a alguns estados, ele tem de ser um dos estados da campanha;
• limites de notas: as regras de geração podem limitar quantas notas o participante cadastra por dia e na campanha inteira, e a excedente é recusada. Envios simultâneos do mesmo participante são contados um de cada vez, então mandar várias notas em paralelo não fura o limite;
• loja: loja bloqueada na campanha recusa a nota, pelo CNPJ ou pela loja informada.

Sobre os campos do formulário da nota: os obrigatórios são exigidos e o valor tem de servir ao tipo. Campo personalizado vai nos dados extras da nota, pela chave; chave fora do formulário é ignorada. A obrigatoriedade do anexo vem do campo correspondente do formulário, e é cumprida pelo arquivo ou, na ausência dele, pelo endereço de consulta do cupom — ler o QR Code basta. A recusa lista todos os pendentes de uma vez, pelo rótulo da tela.

Nota já cadastrada é conflito, com a mensagem de nota já cadastrada. Isso vale para o retry da integração, e é o comportamento desejado: reenviar não duplica.

Com a configuração de validar chave ou número ligada na campanha, a nota precisa de chave ou número, e a nota sem chave é identificada por CNPJ e número ignorando a série. Consequência direta para quem integra: mandar a mesma nota em séries diferentes recebe conflito na segunda.

O participante é localizado por CPF ou pela referência do parceiro. Participante não encontrado recusa.

A integração de parceiro é um caminho de entrada paralelo ao hotsite, com credencial própria, em que o parceiro cadastra participantes e envia notas direto na campanha. O cliente e a campanha ficam amarrados no token, então o parceiro não alcança outra campanha.

O ponto mais importante para alinhar com o cliente: o canal não muda as regras da campanha. Idade, razão social, estado, CEP, aceite do regulamento, campos obrigatórios do formulário, duplicidade da nota e limites de notas valem exatamente como no hotsite.

Isso tem uma consequência prática que é a principal causa de integração quebrando em campanha no ar: ligar a validação de estado, restringir a campanha a alguns estados, ligar o aceite obrigatório ou tornar um campo obrigatório no formulário passa a exigir aquele dado do parceiro também. Antes de ligar qualquer uma dessas numa campanha com integração ativa, confirme com o cliente que o parceiro manda o dado — senão os cadastros passam a ser recusados. No caso do aceite há um cuidado a mais: quem já estava inscrito antes precisa aceitar pela área logada antes de ter novas notas aceitas, e o participante criado pelo parceiro, que não tem senha, não consegue entrar para isso. Ligar o aceite obrigatório no meio de uma campanha com integração pede alinhamento antes.

Duas diferenças do hotsite que vale registrar: o cadastro criado pelo parceiro não tem senha (então aquele participante não entra pelo hotsite nem recupera senha — quem o gerencia é o parceiro), e, quando o documento já existe, a inscrição é aberta sem conferir senha, porque a credencial é o token.

Sobre reenvio: se o parceiro repetir uma nota, a resposta é conflito, não duplicação. Isso é desenhado para o retry da integração ser seguro.

• Falha: os cadastros do parceiro passaram a ser recusados numa campanha que funcionava.
• Possivel causa: a validação de estado ou a restrição por estados foi ligada na campanha, o aceite passou a ser obrigatório, ou algum campo passou a ser obrigatório no formulário do participante. Tudo isso vale para o canal do parceiro.
• Como orientar: confirme com o cliente o que mudou na configuração da campanha e alinhe com o parceiro o envio do dado. Essa é a causa mais comum de integração quebrando em campanha no ar.
• Quando escalar: se o parceiro estiver mandando todos os campos exigidos e a recusa continuar, acionar o time de desenvolvimento urgentemente e abrir issue no Jira (projeto DEV) com as evidências.

• Falha: as notas do parceiro passaram a ser recusadas pedindo o aceite do regulamento.
• Possivel causa: a campanha passou a exigir o aceite, e os participantes inscritos antes disso ainda não aceitaram.
• Como orientar: explique que o aceite é dado pelo próprio participante, na área logada do hotsite. Enquanto ele não aceitar, as notas dele são recusadas por qualquer canal. Atenção: o participante criado pelo parceiro não tem senha e não entra no hotsite, então ele não tem como dar esse aceite sozinho.
• Quando escalar: se o participante já tiver aceitado e a recusa continuar, ou se o participante sem senha criado pelo parceiro precisar do aceite, abrir issue no Jira (projeto DEV) com as evidências.

• Falha: o cadastro do parceiro é recusado dizendo que o CEP é de outro estado.
• Possivel causa: o CEP e o estado enviados apontam para estados diferentes.
• Como orientar: oriente o parceiro a conferir o par CEP e estado na origem dos dados. Os dois precisam ser do mesmo estado.
• Quando escalar: se o CEP for de fato do estado enviado e a recusa continuar, abrir issue no Jira (projeto DEV) com o CEP e o estado.

• Falha: o parceiro reenviou a mesma nota e recebeu conflito.
• Possivel causa: é o comportamento esperado. Nota já cadastrada responde conflito, o que torna o retry seguro.
• Como orientar: explique que o reenvio não duplica. Oriente o parceiro a tratar o conflito como sucesso idempotente no retry.
• Quando escalar: não é falha.

• Falha: o parceiro mandou a mesma nota em duas séries diferentes e a segunda foi recusada.
• Possivel causa: com a validação de chave ou número ligada, a nota sem chave é identificada por CNPJ e número, ignorando a série.
• Como orientar: oriente o parceiro a enviar a chave de acesso de 44 dígitos, que identifica a nota sem ambiguidade. Essa é a solução definitiva para o caso.
• Quando escalar: se a nota tiver chave e a recusa continuar, acionar o time de desenvolvimento urgentemente e abrir issue no Jira (projeto DEV) com as evidências.

• Falha: o parceiro mandou várias notas do mesmo participante de uma vez e parte delas foi recusada por limite.
• Possivel causa: os envios simultâneos do mesmo participante são contados um de cada vez, e os que passaram do limite de notas foram recusados.
• Como orientar: explique que o limite de notas vale para cada nota, mesmo enviadas em paralelo. As recusadas não foram gravadas.
• Quando escalar: não é falha.

• Falha: o parceiro recebeu recusa dizendo que o participante não foi encontrado.
• Possivel causa: o CPF ou a referência do parceiro não corresponde a nenhum cadastro naquela campanha.
• Como orientar: confira se o participante foi cadastrado naquela campanha pelo mesmo canal e se a referência usada é a devolvida no cadastro.
• Quando escalar: se o participante existir na campanha e a recusa continuar, abrir issue no Jira (projeto DEV) com as evidências.

• Falha: o participante que veio pelo parceiro não consegue entrar no hotsite nem recuperar a senha.
• Possivel causa: o cadastro criado pela integração não tem senha, e nem a inscrição nova nem a recuperação criam um acesso que nunca existiu.
• Como orientar: explique que quem é gerido pelo parceiro não entra por senha. O atendimento dele é pelo parceiro.
• Quando escalar: não é falha. Se o cliente precisar que esse participante passe a ter acesso próprio, abrir issue no Jira (projeto DEV) descrevendo o caso.

• Falha: o parceiro recebeu não autorizado ao pedir o token.
• Possivel causa: credencial inválida, parceiro inativo, ou muitas tentativas seguidas, que caem no limite da rota.
• Como orientar: confirme com o cliente se o parceiro está ativo e se a credencial em uso é a vigente. O parceiro recebe a credencial, não a emite.
• Quando escalar: se a credencial estiver correta e o parceiro ativo, acionar o time de desenvolvimento e abrir issue no Jira (projeto DEV) com as evidências.

• Falha: a recusa do cadastro lista vários campos de uma vez e o parceiro não entende quais são.
• Possivel causa: a recusa lista todos os pendentes de uma vez, pelo rótulo que a tela mostra, de propósito.
• Como orientar: compare os rótulos listados com os campos obrigatórios do formulário da campanha. Campo personalizado vai pela chave, nos dados extras.
• Quando escalar: se a recusa listar campo que não está obrigatório no formulário, abrir issue no Jira (projeto DEV) com as evidências.