DDI — Versão 14¶

Referência das APIs que sofreram alteração de body ou retorno na versão v14 da DDI (Documentação de Integração).

Migração para a v14

As APIs que não tiveram alteração precisam apenas trocar a versão na URL de dev para v14. As que mudaram estão documentadas abaixo.

Base URL

Todas as chamadas usam o prefixo https://apiapp.zoombox.com.br/v14/.

Integração de Push

O campo pushid presente em várias destas APIs é detalhado no Guia de Push em App de Parceiro/Varejista, incluindo formato Android/iOS e push direcionado.

Resumo das mudanças¶

#	API	O que mudou
1.1	Cadastro de Cliente	Novo campo obrigatório `idmodulo`
1.2	Login do Cliente (Shopper)	Apenas validação interna (sem mudança de estrutura)
1.3	Alterar Cliente (Shopper)	Novo campo obrigatório `idmodulo`
1.4	Buscar Campanhas	Novos campos `solicitaraceitecampanha` e `urlparticipacao`
1.5	Atualiza Aceite por Canal	Nova API de opt-in/out por canal
1.6	Atualiza PushID	Nova API para atualizar apenas o `pushid`

1.1 Cadastro de Cliente¶

Cria o cadastro de um cliente (shopper).

Item	Valor
URL	`https://apiapp.zoombox.com.br/v14/cadastrocliente`
Método	`POST`
Headers	`idvarejista`, `x-api-key`

Novo campo obrigatório: idmodulo

Foi acrescentado o campo idmodulo, de envio obrigatório. Para obter esse valor, cadastre-o no Zoombox Core pelo painel de controle.

Body¶

{
  "cliente": {
    "id": 0,
    "nome": "nome completo do cliente",
    "celular": "17912345678",
    "loja": "Loja 1",
    "idloja": "1",
    "cpfcnpj": "12345678909",
    "rg": "123456",
    "nascimento": "17/07/1981",
    "sexo": "Masculino",
    "idsexo": "2",
    "estadocivil": "CASADO(A)",
    "idestadocivil": "5",
    "email": "email@email.com",
    "cep": "40820285",
    "estado": "BA",
    "cidade": "Salvador",
    "bairro": "Paripe",
    "rua": "Rua São Mateus",
    "numero": "658",
    "complemento": "CON GIRASSOIS BL 03 APT 73",
    "telefone": "1712345678",
    "senha": "1",
    "tipopessoa": "PESSOA FÍSICA",
    "idtipopessoa": "1",
    "razaosocial": null,
    "classificacao": "FÍSICO",
    "idclassificacao": "2",
    "profissao": "AUXILIAR DE PRODUÇÃO",
    "idprofissao": "143",
    "grupofamiliar": "MORO COM ESPOSO(A)",
    "idgrupofamiliar": "2",
    "datahorasincronizacao": "06/07/2019",
    "pushid": "{\"destino\":{\"PushNotificationService\":\"GCM\",\"MobileIdentification\":\"...\"}}",
    "classificacaointerna": false,
    "valorrenda": 180.5,
    "aceiterenda": true,
    "idmodulo": "5010",
    "aceiteemail": true,
    "aceitepush": true,
    "aceitesms": true,
    "emailativo": true,
    "smsativo": true,
    "idmoduloultimaalteracao": 5010,
    "device": "Android 10/Samsung A10"
  }
}

Retornos¶

200 — Sucesso400 — Campo obrigatório inválido453 — Aceite pendente

Retorna o conteúdo informado para salvar o cliente (shopper).

A key corresponde ao id do campo retornado pela API campocadastrocliente.

[
  {
    "key": "1",
    "message": "Deve ser informado o nome completo"
  }
]

O shopper não aceitou os termos e os aceites.

{
  "messageError": {
    "message": "Não aceitou os termos de aceite\n"
  }
}

Erro de aceite (453) — só para aplicações internas

O erro de aceite só é retornado se a x-api-key do varejista for interna. Para saber se a x-api-key é interna, valide o nome da aplicação. As aplicações internas são: zoomboxapp, zoomboxcore, zoomboxdiscovery. Qualquer outra é tratada como aplicação externa.

Efetua o login do cliente (shopper).

Item	Valor
URL	`https://apiapp.zoombox.com.br/v14/login`
Método	`POST`
Headers	`idvarejista`, `x-api-key`

O que mudou

Houve apenas alteração interna de validação. Não houve mudança na estrutura do body nem do retorno.

Retorno (200)¶

Retorna as informações do cliente (shopper), incluindo os aceites e o pushid.

{
  "id": 0,
  "nome": "nome do cliente",
  "celular": "17912345678",
  "cpfcnpj": "12345678909",
  "email": "email@brasil.gs",
  "receberoferta": true,
  "recebernotificacao": true,
  "aceite": true,
  "idmodulo": "5010",
  "aceiteemail": true,
  "aceitepush": true,
  "aceitesms": true,
  "emailativo": true,
  "smsativo": true,
  "idmoduloultimaalteracao": 5010
}

Erro de aceite (453) — só para aplicações internas

Assim como no cadastro, o erro de aceite só é retornado quando a x-api-key é de aplicação interna (zoomboxapp, zoomboxcore, zoomboxdiscovery).

1.3 Alterar Cliente (Shopper)¶

Altera as informações de um cliente (shopper) existente.

Item	Valor
URL	`https://apiapp.zoombox.com.br/v14/alterarcliente`
Método	`POST`
Headers	`idvarejista`, `x-api-key`, `Authorization: Bearer <token JWT>`

Novo campo obrigatório: idmodulo

Assim como no cadastro, o idmodulo passou a ser obrigatório. Obtenha o valor no Zoombox Core pelo painel de controle.

Campo senha opcional

O campo senha não é obrigatório. Envie-o apenas se for alterar a senha do cliente (shopper).

Body¶

{
  "cliente": {
    "id": 10284,
    "nome": "Nome do cliente",
    "celular": "17123456789",
    "cpfcnpj": "12345678909",
    "email": "email@brasil.gs",
    "senha": "1",
    "idmodulo": "5010",
    "aceiteemail": true,
    "aceitepush": true,
    "aceitesms": true,
    "idmoduloultimaalteracao": 5010,
    "device": "Android 10/Samsung A10"
  }
}

Retornos¶

200 — Sucesso400 — Campo obrigatório/valor inválido453 — Aceite pendente

Retorna as informações do cliente (shopper). A propriedade token é a chave (JWT) que deve ser usada nas demais APIs.

Retornado quando falta um campo obrigatório ou um valor está inválido. A key é o id retornado pela API campocadastrocliente.

[
  { "key": "1", "message": "Deve ser informado o nome completo" },
  { "key": "2", "message": "Identidade de gênero obrigatório " }
]

O cliente ainda não aceitou os termos, ou os termos tiveram o conteúdo alterado e geraram um novo termo.

{
  "messageError": {
    "message": "Não aceitou os termos de aceite\n"
  }
}

1.4 Buscar Campanhas¶

Retorna as campanhas disponíveis para o cliente, agrupadas por tipo (sorteio, promocional, fidelidade).

Item	Valor
URL	`https://apiapp.zoombox.com.br/v14/campanha`
Método	`POST`
Headers	`idvarejista`, `x-api-key`, `Authorization: Bearer <token JWT>`

Novos campos no retorno

solicitaraceitecampanha — se true, o shopper deve aceitar a campanha e os benefícios não são exibidos até o aceite. Se false, os benefícios do shopper são retornados normalmente. Configurável na tela de cadastro de campanha no Painel.
urlparticipacao — para campanhas de Raspadinha e Pênalti, retorna a URL do jogo, que pode ser renderizada em uma webview. Só é retornado quando o shopper tem benefício disponível.

Body¶

{
  "idcliente": "13",
  "idclassificacaocliente": "2"
}

Retorno (200)¶

{
  "sorteio": [
    {
      "idcampanha": "253",
      "nome": "CAMPANHA SORTEIO ELETRÔNICO",
      "idcategoria": "5",
      "nomecategoria": "SORTEIO ELETRÔNICO",
      "datainiciocampanha": "26/11/2021",
      "dataterminocampanha": "31/12/2021",
      "beneficio": {},
      "solicitaraceitecampanha": true,
      "urlparticipacao": null
    }
  ],
  "promocional": [
    {
      "idcampanha": "243",
      "nome": "RASPADINHA",
      "idcategoria": "9",
      "nomecategoria": "RASPADINHA",
      "beneficio": {
        "total": "11",
        "utilizado": "7",
        "disponivel": "4",
        "expirado": "0"
      },
      "solicitaraceitecampanha": false,
      "urlparticipacao": "https://bnexgames.s3.us-east-1.amazonaws.com/raspadinha/index.html"
    }
  ],
  "fidelidade": [
    {
      "idcampanha": "185",
      "nome": "1 É POUCO 2 É BOM 3 É...",
      "idcategoria": "1",
      "nomecategoria": "FIDELIDADE",
      "beneficio": {
        "total": "1.0",
        "utilizado": "0.0",
        "disponivel": "1.0",
        "expirado": "0.0"
      },
      "solicitaraceitecampanha": false,
      "urlparticipacao": null
    }
  ]
}

1.5 Atualiza Aceite por Canal (Opt-in/out)¶

Atualiza os aceites por canal de ativação (opt-in/out) sem a necessidade de atualizar todo o cadastro.

Item	Valor
URL	`https://apiapp.zoombox.com.br/v14/atualizaaceitecanal`
Método	`POST`
Headers	`idvarejista`, `x-api-key`, `Authorization: Bearer <token JWT>`

Atualização parcial de canais

Para atualizar o aceite de um único canal, não informe os demais canais no body — os dados omitidos não são alterados.

Body — todos os canais¶

{
  "cpfcnpj": "{{_cpf_do_shopper_}}",
  "aceitesms": true,
  "aceiteemail": true,
  "aceitepush": true,
  "idmoduloultimaalteracao": 3
}

Body — apenas um canal¶

{
  "cpfcnpj": "{{_cpf_do_shopper_}}",
  "aceitesms": false,
  "idmoduloultimaalteracao": 3
}

1.6 Atualiza PushID¶

Atualiza somente o pushid do shopper (device id para notificações push), sem atualizar todo o cadastro.

Item	Valor
URL	`https://apiapp.zoombox.com.br/v14/atualizapushid`
Método	`POST`
Headers	`idvarejista`, `x-api-key`, `Authorization: Bearer <token JWT>`

Body¶

Android (GCM)iOS (APNS)

{
  "cpfcnpj": "{{_cpf_do_shopper_}}",
  "pushid": "{\"destino\":{\"PushNotificationService\":\"GCM\",\"MobileIdentification\":\"...\"}}"
}

{
  "cpfcnpj": "{{_cpf_do_shopper_}}",
  "pushid": "{\"destino\":{\"PushNotificationService\":\"APNS\",\"MobileIdentification\":\"...\"}}"
}

Formato do pushid

O detalhamento do formato do pushid (Android/iOS) e do fluxo de push está no Guia de Push em App de Parceiro/Varejista.

DDI — Versão 14¶

Resumo das mudanças¶

1.1 Cadastro de Cliente¶

Body¶

Retornos¶

1.2 Login do Cliente (Shopper)¶

Retorno (200)¶

1.3 Alterar Cliente (Shopper)¶

Body¶

Retornos¶

1.4 Buscar Campanhas¶

Body¶

Retorno (200)¶

1.5 Atualiza Aceite por Canal (Opt-in/out)¶

Body — todos os canais¶

Body — apenas um canal¶

1.6 Atualiza PushID¶

Body¶