Español
English
Català
Deutsch
Français
Italiano
Nederlands
Polski
SP-API são as siglas de Selling Partner API: a interface com que a Amazon permite que um programa externo leia e escreva na sua conta do Seller Central. Substituiu a MWS e mudou bastante mais do que o nome. Do lado do Odoo, a API em si é a parte fácil: são pedidos HTTP com JSON. O que decide se a integração aguenta um novembro são três coisas que não se veem na documentação de um endpoint: como se autoriza, quantas chamadas lhe deixam fazer e que dados chegam tarde por desenho.
A autorização assina-se no Seller Central, não no Odoo
O fluxo é sempre o mesmo: existe uma aplicação registada com um perfil de programador e o vendedor autoriza-a a partir da sua conta. Dessa autorização sai um refresh token de longa duração, que o Odoo guarda; com ele, o Odoo pede, sempre que precisa, um token de acesso que dura uma hora. Se alguém lhe pedir as credenciais do Seller Central para «configurar», algo está errado: ninguém precisa da sua palavra-passe para isto. E se revogar a autorização, a integração para de imediato, que é exatamente o que deve acontecer.
Os dados do comprador passam por uma porta à parte
O nome, a morada e o telefone do comprador são dados pessoais e a Amazon trata-os como tal: não vêm na resposta normal de uma encomenda. É preciso pedir um token restrito para essa consulta concreta, e a permissão para o fazer é concedida por função, não por defeito. Consequência prática no Odoo: pode ter encomendas a importar na perfeição e guias de remessa que não se podem expedir porque falta a morada. Não é uma falha do conector; é a permissão que não está aprovada.
Os limites de chamadas são um orçamento, não uma velocidade
Cada operação da SP-API tem o seu próprio limite e funciona como um depósito que se enche a um ritmo fixo e admite uma rajada curta acima desse ritmo. Enquanto houver saldo, vai-se depressa; quando se esgota, a Amazon responde 429 e é preciso esperar. Isto tem uma leitura direta para o Odoo: não se podem percorrer 4 000 referências chamando uma a uma «porque é mais simples». É preciso agrupar, respeitar o cabeçalho de limite que a própria API devolve e repetir com espera crescente. E é preciso que a sincronização manual e a ação agendada partilhem o mesmo travão, porque o orçamento é da conta inteira, não de cada processo.
Relatórios versus chamadas em direto: por que razão o seu stock vai sempre com atraso
A SP-API tem duas formas de lhe dar dados. Uma é a chamada direta: pergunta por encomendas desde uma data e responde no momento. A outra é o sistema de relatórios, que é assíncrono: solicita o relatório, a Amazon prepara-o quando pode, consulta se já está pronto e depois descarrega um ficheiro comprimido. O inventário FBA e as liquidações vão por aí. Isso significa que o stock que vê no Odoo é o da última descarga, não o deste segundo, e nenhuma frequência de ação agendada resolve isso. A resposta certa não é chamar mais: é publicar com margem de segurança e assumir o desfasamento.
O sandbox da SP-API devolve respostas fixas preparadas pela Amazon. Serve para verificar que assina bem os pedidos e pouco mais: todas as suas operações partilham o mesmo limite, pelo que não reproduz o de cada operação em produção, nem lhe devolve uma encomenda pendente sem morada, nem o obriga a renovar um token a meio de uma sincronização longa. Um conector verde no sandbox não está testado. Contamo-lo em testes verdes e falha em produção.
Os erros que só aparecem em produção
São sempre os mesmos e nenhum aparece no primeiro dia. Encomendas em estado pendente que chegam sem valores nem morada e que é preciso voltar a ler mais tarde. Paginação: a primeira página entra e o resto perde-se se ninguém seguir o token de continuação. Janelas de datas mal calculadas por fuso horário, que deixam um buraco de encomendas mesmo na mudança de dia. Tokens que expiram durante uma sincronização longa e que é preciso renovar a meio. E a região errada: a aplicação é global, mas a conta de vendedor não, e pedir as encomendas da Alemanha ao endpoint da América do Norte não responde «região incorreta», responde «Access to requested resource is denied». Parece um problema de permissões, pelo que se regeneram credenciais que estavam boas enquanto a falha continua no URL.
Onde isto tem de viver dentro do Odoo
Uma chamada à Amazon não pode depender da validação de uma guia de remessa. Se a API demorar, o utilizador fica a olhar para uma roda e, se falhar, perde o trabalho feito. O lugar destas chamadas é uma ação agendada ou uma fila de tarefas, com a sua repetição, o seu registo do que se pediu e do que a Amazon respondeu, e com operações idempotentes: repetir uma sincronização não pode criar a encomenda duas vezes. Esse registo é o que depois lhe permite discutir com o suporte da Amazon com dados, em vez de com impressões. O resto do padrão, aplicado às encomendas que não aparecem, está em por que razão as encomendas da Amazon não entram no Odoo.
Quando não precisa de construir nada
Se vende num único marketplace, com poucas referências e só precisa que as encomendas entrem, o conector da Amazon que o Odoo Enterprise traz de série pode bastar. Vale a pena experimentá-lo antes de pagar por seja o que for. A conversa muda quando há vários países com os seus impostos, stock partilhado com outros canais, liquidações para acertar ou confirmações de envio com prazo. É aí que o nosso conector da Amazon para o Odoo faz o trabalho: SP-API com controlo de limites, relatórios, FBA e FBM, no Odoo 17, 18, 19 e 20.
Perguntas frequentes
É preciso uma conta de programador da Amazon para usar a SP-API?
A aplicação tem de estar registada sob um perfil de programador, mas quem autoriza é o próprio a partir do seu Seller Central. A autorização é sua e pode revogá-la quando quiser.
Pode consultar-se o stock da Amazon em tempo real?
Não como as pessoas imaginam. O inventário chega sobretudo por relatório, que é assíncrono, pelo que há sempre um desfasamento de minutos. Por isso a margem de segurança importa mais do que a frequência de sincronização.
O que acontece se a Amazon me devolver 429 em plena campanha?
Nada de grave se a integração repetir com espera crescente e puser em fila o que está pendente. É grave se o processo morrer e ninguém se aperceber até faltarem encomendas: por isso o registo e o alerta importam tanto como a chamada.
Ligações úteis dentro da FlexigoTech
O que fazemos sobre isto
A sua integração com a SP-API falha e não sabe por onde começar?
Diga-nos em que marketplaces vende, se usa FBA, FBM ou ambos, e que erro concreto vê no registo. Verificamos se é autorização, limites de chamadas ou uma janela de datas mal calculada. Escreva para comercial@flexigobe.com ou agende uma chamada.