Liberação do Token da API – Manual do Sistema Puzzle

Objetivo

Este manual tem como objetivo orientar sobre o processo de geração e uso do token JWT para integração via API com o sistema Puzzle Plan.

Passo a Passo para Gerar o Token

Acesse o menu:
- Plan → Parceiros → Cadastros
Selecione o parceiro desejado ou crie um novo cadastro de parceiro.
Salve o cadastro.
Após salvar, o sistema exibirá o campo:

JWT: Token de autenticação para integração

Este é o token que deverá ser utilizado nas requisições à API.

Aprenda a realizar o cadastro aqui : Cadastro de Parceiro.

Validade e Renovação do Token

O token tem validade de 10 dias.
Após o vencimento, é necessário gerar um novo token, repetindo o processo acima.

Acesso à API

O acesso deve ser realizado através da URL base do ambiente do cliente, no seguinte formato:

http://NOME_DA_EMPRESA-puzzle-plan.techtd.com.br/api/v1/data

🔸 Observação: substitua NOME_DA_EMPRESA pelo identificador correspondente ao ambiente configurado no Puzzle Plan.

Endpoints disponíveis:

/users → Retorna dados de usuários.
/responses → Retorna dados das tarefas.

Autenticação

A autenticação deve ser feita utilizando o JWT, com o método Bearer Token.

Exemplo de cabeçalho:

Authorization: Bearer SEU_TOKEN_AQUI

Parâmetros de Consulta

Os endpoints exigem obrigatoriamente os parâmetros date_init e date_end, com intervalo máximo de 10 dias entre as datas.

Exemplo de requisição:

https://NOME_DA_EMPRESA-puzzle-plan.techtd.com.br/api/v1/data/responses?date_init=2025-04-10&date_end=2025-04-25

Estrutura do Retorno da API

🔹 Endpoint `/responses`

Retorna os dados relacionados às tarefas executadas pelos promotores.

Exemplo de retorno:

[
    {
        "agendamento": "NOME AGENDAMENTO",
        "agendamento_id": 999,
        "promotor_id": 9999,
        "pdv_id": 9999,
        "pdv": "NOME PDV",
        "skus": [
            {
                "item_id": 0,
                "item_type": "TYPE",
                "respostas": [
                    {
                        "questao": "QUESTÃO?",
                        "resposta": "RESPOSTA",
                        "foto": ["LINK IMAGEM"]
                    }
                ]
            }
        ]
    }
]

Descrição dos principais campos:

Campo	Descrição
agendamento	Nome do agendamento vinculado à coleta.
agendamento_id	Identificador único do agendamento.
promotor_id	ID do promotor responsável pela execução.
pdv_id	ID do ponto de venda.
pdv	Nome do ponto de venda.
skus	Lista de itens vinculados à tarefa.
item_id	Identificador do item.
item_type	Tipo do item (ex: produto, supercategoria, categoria e etc.).
respostas	Conjunto de respostas associadas ao item.
questao	Texto da pergunta apresentada ao promotor.
resposta	Resposta registrada no aplicativo.
foto	Lista de links de imagens enviadas como evidência.

🔹 Endpoint `/users`

Retorna informações sobre os atendimentos realizados e os promotores vinculados.

Exemplo de retorno:

[
    {
        "promotor": "NOME DO PROMOTOR",
        "supervisor": "NOME DO SUPERVISOR",
        "data_atendimento": "2025-10-15",
        "pdv_id": 9999,
        "pdv": "NOME DO PDV",
        "bandeira_id": 3,
        "bandeira": "NOME DA BANDEIRA",
        "uf": "ESTADO",
        "cidade_id": 9999,
        "cidade": "NOME CIDADE",
        "checkin": null,
        "checkout": null,
        "marca": "NOME DA MARCA"
    }
]

Descrição dos principais campos:

Campo	Descrição
promotor	Nome do promotor vinculado ao atendimento.
supervisor	Nome do supervisor responsável.
data_atendimento	Data em que o atendimento foi realizado.
pdv_id	Identificador do ponto de venda.
pdv	Nome do ponto de venda.
bandeira_id	Identificador da bandeira associada ao PDV.
bandeira	Nome da bandeira.
uf	Estado onde o PDV está localizado.
cidade_id	Identificador da cidade.
cidade	Nome da cidade.
checkin / checkout	Horários de início e fim do atendimento
marca	Nome da marca associada à visita.

Restrições de Consulta

Há uma limitação de consultas: o intervalo mínimo entre solicitações é de 2 horas.
Consultas realizadas antes desse intervalo serão bloqueadas.

Observações Importantes

O token é gerado diretamente no portal Puzzle Plan, dentro do cadastro de parceiros.
É necessário vincular a indústria desejada ao cadastrar o parceiro para que o token seja disponibilizado.
Sempre verifique se o token ainda está válido antes de realizar novas requisições.

Relativo a