Perguntas Manual Técnico Integração TikTok Shop

Comunicação entre Panza, Bling e TikTok Shop1. ObjetivoEste documento descreve o funcionamento técnico da integração implementada no clientedo Panza.O Bling atua como intermediário entre o SFI/Panza e o TikTok Shop. O Panza não realiza chamadas diretamente à API do TikTok Shop.O Panza é responsável por:

• Criar e atualizar categorias no Bling;
• Criar e atualizar produtos;
• Enviar saldo de estoque;
• Consultar produtos;
• Importar pedidos;
• Importar contatos relacionados aos pedidos;
• Atualizar, quando aplicável, a situação de pedidos já processados pelo SFI.

A comunicação entre Bling e TikTok Shop depende exclusivamente das configurações, vínculos e regras existentes no próprio Bling.2. Configuração do cliente BlingNa configuração serializada de, defina:Essa configuração instancia o cliente:Os principais parâmetros utilizados são:ConfiguraçãoValor ou comportamento atualdo aplicativo Blingdo aplicativo Bling, utilizada nas operações de escrita (,e), utilizada nas operações de leitura ()Endpoints marcadose/ou, conforme a carga que será transmitidaDefine a origem utilizada no cálculo do estoqueParticipa da regra utilizada para cálculo do saldoDefine a tabela utilizada para obtenção do preço dos produtosTransação padrão utilizada na criação do orçamento/venda no SFITransação financeira padrãoCondição de pagamento aplicada ao documento criado no SFIVendedor utilizado na criação do documentoDefine se o orçamento importado será reservadoQuando maior que zero, é associado ao novo cliente criado no SFIDe-para entre a descrição da forma de pagamento no Bling e a operação financeira do SFIHabilita o registro do corpo JSON enviado e das respostas HTTP no progresso

Observação:

URLEntrada

e

URLSaida

existem por herança de outros integradores. Para o Bling, ambas devem apontar para a mesma URL da API v3.

O código atual não valida nem preenche essas URLs automaticamente.3. Autenticação OAuth 2.03.1. Autorização inicialApós salvar a configuração, quando o cliente selecionado for Bling, a tela principal permite executar ou refazer a autorização.O fluxo implementado é:

1. O Panza abre no navegador padrão:

com os parâmetros:

1. O operador entra na conta Bling desejada.
2. O operador autoriza o aplicativo.
3. O Bling redireciona para a URL cadastrada no aplicativo.

A instrução exibida atualmente pelo Panza utiliza:

1. A página apresenta o

   code

   de autorização.
2. O operador copia:
   • apenas o

     code

     ; ou
   • a URL completa de retorno.
3. O valor é colado no Panza.
4. Caso uma URL completa tenha sido informada, o Panza extrai automaticamente o parâmetro

   code

   .
5. O Panza executa:

utilizando HTTP Basic:e o corpo:

1. Se a resposta contiver

   access_token

   , os tokens são armazenados e a autorização é considerada concluída.

Considerações sobre o fluxo OAuthO parâmetroé gerado na URL de autorização, porém a implementação atual:

• Não persiste o valor;
• Não compara o valor recebido no retorno;
• Não valida o

  state

  .

Também não existe:

• Listener HTTP local;
• Servidor HTTP temporário;
• Callback em

  localhost

  .

Oé copiado manualmente pelo operador a partir da página de redirecionamento.

O

authorization_code

deve ser utilizado imediatamente. A interface informa uma validade aproximada de um minuto.

3.2. Armazenamento dos tokensOs tokens são armazenados na tabela, utilizando:O conteúdo armazenado é um JSON contendo:O horário de expiração é calculado utilizando:Essa margem de 60 segundos evita utilizar um token muito próximo da expiração.Quandonão estiver presente na resposta, o código utiliza como fallback:equivalente a aproximadamente seis horas.Atualmente não são persistidos:

• scope

  ;

• token_type

  ;

• expires_in

  original;
• Data/hora da autorização inicial.

3.3. Renovação automáticaAntes das operações autenticadas, o métodocarrega o token salvo.Casoindique que o token expirou, o Panza solicita uma renovação no endpoint OAuth:Quando a renovação é concluída, o novo:substitui o par anteriormente armazenado em.Recuperação após HTTP 401Existe também tratamento específico para respostas:Nesse cenário:

1. O Panza tenta renovar o token;
2. A chamada HTTP original é executada novamente;
3. Essa repetição ocorre somente uma vez.

Se a renovação falhar, o progresso orienta o operador a executar novamente a autorização pelo botão:Autorizar Bling3.4. RevogaçãoO Panza atualmente não possui:

• Endpoint próprio de revogação;
• Botão para revogar tokens diretamente no Bling.

A revogação é tratada como um evento externo.Uma nova autorização será necessária em situações como:

• Token ausente;

• refresh_token

  recusado;
• Aplicativo removido da conta;
• Acesso revogado;
• Alteração de escopos ou permissões.

Importante: ao alterar escopos ou permissões do aplicativo Bling, os tokens anteriormente emitidos são revogados. Uma nova autorização deve ser realizada antes de retomar a sincronização.

4. Permissões necessáriasO cliente não envia o parâmetrona URL de autorização e também não contém identificadores de escopo definidos diretamente no código.Os escopos devem, portanto, ser configurados no cadastro do aplicativo Bling.A autorização concedida precisa permitir, no mínimo, as seguintes operações:RecursoAcesso utilizado pelo PanzaProdutosLeitura, criação e alteraçãoCategorias de produtosCriação e alteraçãoEstoquesLançamento de saldoDepósitosLeituraPedidos de vendaLeitura, consulta de detalhes e alteração de situaçãoContatosLeitura por IDFormas de pagamentoLeitura5. Cabeçalhos e autenticação das chamadasAs chamadas normais à API utilizam:HTTP Basic é utilizado exclusivamente no endpoint responsável pela obtenção e renovação dos tokens.6. Endpoints utilizadosMétodoEndpoint relativo à API v3FinalidadeCriar categoriaAtualizar categoria vinculadaCriar produtoAtualizar produto vinculadoDefinir saldo absoluto do produto no depósitoObter o depósito utilizado no lançamento de estoqueResolver o ID da forma de pagamento para sua descriçãoListar pedidos por período de alteração, página e limiteConsultar os detalhes de um pedidoAlterar a situação de um pedidoObter os dados do contato associado ao pedidoListar produtos na tela de consultaConsultar e exibir o JSON bruto de um produto6.1. Controle de requisiçõesProdutos e categorias são enviados individualmente.Entre cada registro existe uma pausa de:O objetivo é manter a carga abaixo de aproximadamente:As consultas de produtos utilizam paginação por:Quando existe filtro por alteração, também é enviado:7. CategoriasO envio considera categorias marcadas com:O payload contém:e, quando existir uma categoria superior:Após uma criação bem-sucedida, o ID retornado pelo Bling é armazenado em:A categoria associada ao produto é determinada pelo primeiro vínculo elegível encontrado em:O produto recebe a referência no formato:Compartilhamento doO campo:também é utilizado pelo integrador WooCommerce.A implementação atual pressupõe que Bling e WooCommerce não sejam utilizados simultaneamente na mesma base para as mesmas categorias.8. Produtos8.1. Identificação e vínculoO SQL de produtos utiliza a tabela de vínculo:com:O comportamento depende da existência de um ID remoto:A resposta deve fornecer o ID remoto em:ou, alternativamente:na raiz do retorno.Após o envio, esse ID é associado aolocal.8.2. Campos enviadosAtualmente são enviados, entre outros:CampoOrigem/comportamentodo SFINome fantasia ou descrição do produtoGTIN cadastradoObtido deutilizando aconfiguradaPeso bruto cadastradoOs produtos são tratados como produtos simples.

Não existe suporte implementado para variações.

9. Imagens dos produtosO cliente tenta enviar as imagens cadastradas no SFI através do payload:Os links utilizados são gerados a partir do FTP ou armazenamento configurado no Panza.Entretanto, existe atualmente uma limitação conhecida:

As imagens dos produtos não estão sendo enviadas corretamente do SFI para o Bling.

Por esse motivo, a imagem deve ser cadastrada manualmente no Bling antes de continuar o fluxo de publicação para o TikTok Shop.10. EstoqueApós a criação ou atualização de um produto, o Panza envia o estoque em uma chamada separada:A operação utilizada é:onderepresenta um balanço.Isso significa que o Panza informa o saldo absoluto do produto.Não se trata de uma movimentação incremental de:

• Entrada;
• Saída;
• Ajuste positivo;
• Ajuste negativo.

10.1. Seleção do depósitoO depósito utilizado é obtido através de:O ID encontrado é armazenado emutilizando:Depois disso, o valor é reutilizado nas próximas operações.Limitação atualAtualmente, o sistema utiliza automaticamente:

o primeiro depósito retornado pela API do Bling.

Não existe configuração no Panza para selecionar manualmente outro depósito.11. Importação de pedidos11.1. ConsultaO Panza consulta:utilizando:Para cada pedido listado, é realizada uma segunda consulta:para obter os dados completos antes da importação.11.2. Controle de duplicidadeO identificador utilizado no SFI é:Esse valor é armazenado ou consultado em:e é utilizado para impedir que o mesmo pedido seja incluído mais de uma vez.11.3. Período consultado atualmenteO código mantém em:Entretanto, a implementação atual substitui temporariamente esse valor pelo início do dia corrente antes da consulta.Na prática, isso significa que são buscados somente pedidos alterados desde:Apesar de existir um marcador persistente de última busca, ele não é efetivamente utilizado como período inicial nesse fluxo.11.4. Ausência de filtro por lojaNão existe atualmente filtro por loja TikTok na consulta.Consequentemente:

Toda venda retornada pela conta Bling dentro dos critérios de consulta pode entrar no processamento do Panza.

Isso exige atenção em contas Bling integradas simultaneamente com múltiplos canais de venda.12. Itens dos pedidosOs itens utilizam:como referência ao:do SFI.Também são utilizados:Se o código do produto:

• Estiver vazio; ou
• Não existir na tabela

  produto

  ;

o pedido não será incluído.Quando a inclusão ocorre com sucesso, a rotina pode:

• Reservar o orçamento, conforme

  ReservarOrcamento

  ;
• Criar uma notificação de faturamento;
• Executar a impressão configurada.

13. Atualização da situação do pedido no BlingRegistros pendentes em:com:são considerados para atualização.O Panza tenta executar:Após isso, o controle local é marcado como enviado.AtençãoO método responsável peloregistra falhas no progresso, porém o chamador atualmente não valida o retorno booleano antes de marcar o registro de controle como enviado.Essa condição deve ser considerada durante investigações de divergência entre situação local e situação registrada no Bling.14. Importação de clientesPara cada pedido, o Panza utiliza:como identificação do contato no Bling.Primeiro é consultado o vínculo local:Se não houver vínculo, o Panza executa:14.1. Localização do cliente no SFIO cliente é procurado utilizando:Se não houver uma conta correspondente, é criada uma nova.Os dados utilizados incluem:

• Nome;
• Documento;
• Tipo de pessoa física ou jurídica;
• CEP;
• Cidade;
• UF;
• Endereço;
• Número;
• Complemento;
• Bairro.

Quando houver e-mail no retorno, são gravadas informações adicionais em:Se:também é criado o vínculo correspondente em:Ao final do processo é armazenada a associação entre:em:Direção da integração de clientesO fluxo atualmente implementado é somente:durante a importação dos pedidos.O Panza não envia clientes do SFI para o Bling nesse fluxo.15. Formas de pagamentoO pedido precisa possuir:Para cada parcela, o Bling fornece:O Panza consulta:e mantém em memória um cache:Se determinado ID não estiver no cache, é realizada uma atualização da lista uma vez.A descrição obtida é utilizada como chave para procurar o correspondente em:15.1. Configuração deO formato esperado é:O valor à esquerda deve ser exatamente igual à descrição retornada pelo Bling, respeitando:

• Acentos;
• Espaços;
• Maiúsculas e minúsculas;
• Texto completo.

Por exemplo, se o Bling retornar:a configuração correta será:e não:15.2. Diagnóstico de forma não mapeadaQuando uma forma de pagamento não estiver configurada, o progresso registra:Utilize a descrição exibida nessa mensagem como chave de.15.3. Fallbacks internosA implementação contém também alguns mapeamentos internos:Descrição BlingCódigo///

Esses fallbacks não substituem a configuração explícita. Recomenda-se cadastrar em

OpFinanceiras

todas as formas utilizadas pela empresa.

O código resultante deve possuir no máximo:Caso contrário, a importação do pedido falha.16. Parcelas e condição de pagamentoCada parcela retornada pelo Bling gera um pagamento no SFI contendo:Casonão esteja disponível, é utilizada a data de emissão.A condição de pagamento aplicada ao documento vem da configuração fixa:Ela não é calculada com base nas parcelas recebidas do Bling.17. Tratamento de erros e diagnóstico HTTPO métodoregistra:Quandoestiver habilitado, também registra:Em erros HTTP é registrado:O conteúdo de:é preservado para que mensagens e JSONs de validação retornados pelo Bling possam ser analisados.17.1. Tratamento de HTTP 401Em uma resposta:o fluxo é:Não são realizadas novas tentativas após essa repetição.17.2. Demais falhasFalhas de transporte ou outras exceções são registradas como:Na carga de categorias e produtos, as exceções são capturadas e registradas no progresso.O método não fornece uma confirmação transacional global para cada registro processado.Na importação de pedidos, um pedido inválido é registrado no log e o processamento continua com os demais registros retornados pela API.18. Arquivos de diagnósticoOs seguintes artefatos podem auxiliar na investigação de problemas:ArtefatoConteúdoPayload individual enviado para categoria ou produtoResposta correspondente ao envioRespostas de consultas realizadas porListagens consultadasDetalhes dos pedidos consultadosProgresso/log de depuraçãoInformações sobre autorização, renovação, HTTP, parcelas, vínculos e erros de importação18.1. Validação específica do estoqueUma resposta de estoque é considerada bem-sucedida somente quando:

• Contém

  data

  ;
• Não contém

  error

  .

Falhas de validação são registradas juntamente com a resposta da API.19. Segurança das informaçõesNunca registrar, enviar em chamados ou adicionar a documentos de suporte:Essas informações devem ser tratadas como credenciais sensíveis.20. Limitações conhecidasA implementação atual possui as seguintes limitações:LimitaçãoComportamento atualImagens de produtosA imagem do SFI não chega corretamente ao Bling e precisa ser cadastrada manualmenteTikTok ShopO Panza não realiza integração direta nem valida publicação ou vínculo no canalPeríodo de pedidosConsulta temporariamente apenas alterações ocorridas no dia correnteLoja/canal do pedidoNão existe filtro por loja TikTok ou outro canalDepósitoO primeiro depósito retornado pelo Bling é utilizado automaticamenteFormas de pagamentoA consulta utilizae não implementa paginaçãoVariaçõesProdutos com variações não são suportadosOAuthO valor é gerado, porém não é validado no retornoRevogação OAuthNão existe revogação de token pela API dentro do PanzaEscopos OAuthOs identificadores não são definidos pelo código e dependem do cadastro do aplicativoSituação dos pedidosO mapeamento Bling → Panza devolve atualmente apenas o próprio ID da situação como textoDe-para de situaçõesNão existe configuração específica de mapeamento21. Fluxo operacional completoA sequência recomendada para configuração e utilização é:Procedimento resumido

1. Configure a integração com o TikTok Shop dentro do Bling, incluindo vínculos, categorias, regras de estoque e depósitos.
2. Configure o cliente Bling no Panza, incluindo URLs, credenciais, tabela de preço, estoque e demais parâmetros.
3. Configure todas as formas de pagamento necessárias em

   OpFinanceiras

   .
4. Execute a autorização OAuth através do navegador.
5. Cole o

   code

   de autorização no Panza.
6. Envie categorias antes dos produtos quando houver dependência entre eles.
7. Cadastre o produto no SFI e envie-o ao Bling.
8. Confira código, preço, categoria e estoque no Bling.
9. Cadastre ou corrija manualmente a imagem do produto no Bling.
10. Finalize no Bling os vínculos e requisitos necessários para publicação no TikTok Shop.
11. Realize testes controlados de estoque.
12. Monitore a importação dos primeiros pedidos.
13. Verifique formas de pagamento, depósitos, produtos não encontrados e respostas da API.
14. Utilize os arquivos de diagnóstico e o modo

    Debug

    sempre que houver divergências entre SFI, Bling e TikTok Shop.