Token de integração
Gere uma chave de API restrita às solicitações, com prazo de validade, entregue ao desenvolvedor por link de uso único e revogável a qualquer momento.
O token de integração é uma chave de API que você gera para quem vai desenvolver a integração da sua loja, com permissão limitada e prazo de validade definidos por você.
Ele foi criado para resolver um problema comum: até então, entregar o acesso à API significava entregar a chave da loja inteira, sem prazo e sem como saber quem estava usando. Com o token de integração, o desenvolvedor recebe acesso apenas às solicitações, você acompanha o uso e pode revogar o acesso a qualquer momento, sem mexer no restante da conta.
Criando o token
No painel, abra a área de Integrações e a lista de tokens de API. Clique em Novo token de API e preencha:
Nome da integração: como esse acesso vai aparecer na sua lista. Use um nome que identifique o projeto ou o parceiro, por exemplo "ERP Bling" ou "Agência Tal".
Dados do desenvolvedor: nome, e-mail e site de quem vai usar o token. Serve para você saber a quem pedir explicação caso veja um uso estranho.
Permissões: marque Leitura, Escrita ou as duas, dentro de Solicitações. Escrita inclui criar, alterar e excluir.
Expira em: a data em que o token deixa de funcionar sozinho.
Depois é só clicar em Criar token.
O campo Expira em pode ficar em branco, e nesse caso o token não expira nunca. Recomendamos sempre definir uma data, mesmo que distante. Token sem prazo é token que fica ativo muito tempo depois de o projeto acabar.
Escolhendo as permissões
Marque só Leitura quando a integração apenas consulta solicitações, por exemplo para alimentar um relatório, um BI ou um painel interno.
Marque também Escrita quando a integração precisa agir sobre as solicitações, por exemplo criar solicitações, autorizar postagem, registrar entrega ou finalizar reembolso.
Na dúvida, comece só com Leitura. Se o desenvolvedor precisar de mais, você cria um novo token com Escrita e revoga o antigo.
Entregando o token ao desenvolvedor
Assim que o token é criado, aparece a tela Token criado, com duas formas de entrega.
Copie o token agora. Por segurança ele não será exibido de novo, nem para você. Se perder, o caminho é criar outro token e revogar esse.
Se você mesmo vai usar, copie o token direto do primeiro campo. Ele tem o formato ted_ seguido de uma sequência de letras e números.
Se você vai repassar a um desenvolvedor, use o link seguro do segundo campo. Ele abre uma única vez e evita que o token circule solto por e-mail ou WhatsApp. O próprio modal mostra a data e a hora em que esse link expira.
O link tem este formato:
Quando o desenvolvedor abre, ele vê o nome da loja, o nome da integração, o token e um botão para copiar. A partir daí o link está consumido, e quem tentar abrir de novo vê o aviso de que o link já foi usado.
Porque o link abre uma única vez, não teste o link antes de enviar. Se você abrir para conferir, ele queima, e o desenvolvedor vai receber um link que não mostra mais nada. Nesse caso será preciso criar um token novo.
Usando o token nas chamadas
O token deve ser enviado no header store_token em todas as requisições.
Endpoint da API: https://api.troqueedevolva.com.br
Exemplo de chamada:
A referência completa das rotas, com parâmetros e exemplos de corpo, está em docs.api.troqueedevolva.com.br.
O que o token de integração acessa
O token de integração acessa apenas as rotas de solicitações, ou seja, as rotas /request. Todo o restante continua sendo feito pelo painel.
Com permissão de Leitura:
Listar solicitações
Detalhar uma solicitação
Cotar frete de uma solicitação
Com permissão de Escrita:
Criar e editar solicitações
Criar comentários e anexar arquivos
Autorizar postagem e cancelar a autorização
Registrar postagem e registrar entrega
Rejeitar e arquivar solicitações
Finalizar reembolso em dinheiro, em vale-trocas, no cartão de crédito ou por produto
Cadastrar dados de PIX e perguntar a conta bancária ao cliente
Emitir vale-trocas integrado na plataforma
Enviar uma pergunta ao cliente e registrar respostas de NPS
Não estão disponíveis para o token de integração, e seguem apenas pelo painel: configurações da loja, usuários, endereços de devolução, e-mails transacionais, respostas pré-definidas, perguntas da loja, dados da loja e criação de conta.
Acompanhando e revogando
Na lista de tokens você vê, de cada token:
Token: o começo da chave, o suficiente para identificar qual é
Permissões: se é Leitura, Escrita ou as duas
Último uso: quando aquele token chamou a API pela última vez. Enquanto o desenvolvedor não usar, fica sem registro
Expira em: a data definida na criação
Situação: se o token está ativo
Revogue o token quando o projeto terminar, quando o desenvolvedor deixar de atender a loja ou sempre que suspeitar que a chave vazou. A revogação vale na hora, e as chamadas seguintes passam a ser recusadas.
Um token por integração. Assim, revogar um projeto não derruba os outros, e o campo Último uso mostra de verdade quem ainda está ativo.
Erros mais comuns
403 Forbidden
A rota chamada não é de solicitações. O token de integração só acessa /request. Confira o endereço da chamada na referência da API.
401 Unauthorized
O token foi revogado no painel. É preciso gerar um token novo e reconfigurar a integração com ele.
429 Too Many Requests
O limite de requisições foi ultrapassado. Requisições autenticadas têm limite de 15 por segundo e 1000 por minuto. Respeite o header Retry-After da resposta e distribua as chamadas ao longo do tempo.
Boas práticas
Um token por integração, nunca o mesmo token para dois parceiros.
Sempre defina uma data de expiração.
Conceda só Leitura quando a integração não precisa alterar nada.
Prefira o link seguro para entregar o token, em vez de colar a chave em e-mail, WhatsApp ou ticket.
Revise a lista de tokens periodicamente e revogue o que estiver sem uso.
Se o token vazou, revogue primeiro e crie o substituto depois.
Atualizado