Conector Amazon para Odoo: que credenciais pede a SP-API, que limites de taxa tem e o que deve cobrir

Se procura conector Amazon Odoo ou Amazon SP-API Odoo, a resposta curta é esta: são precisas três credenciais que não vêm do mesmo sítio (uma aplicação SP-API registada por um perfil de programador com as funções aprovadas, umas chaves LWA dessa aplicação e um refresh token por cada vendedor que a autoriza), mais o marketplace id e o endpoint regional. E uma decisão de desenho: os limites são baldes de fichas por operação, pelo que o conector leva fila e backoff, não ciclos.

Tudo o que se segue foi verificado a 13 de setembro de 2026 na documentação oficial da SP-API e no código do nosso Conector Amazon Seller para Odoo, publicado nas ramificações 19.0, 18.0 e 17.0, com 786 testes próprios na do Odoo 19 e 685 em cada uma das outras duas.

O que deve resolver um conector Amazon Odoo

• Importação fiável de encomendas e reservas de stock.
• Mapeamento de SKU, variantes e listagens sem duplicados.
• Sincronização de estados, tracking e confirmações.
• Gestão de preços, incidências e casos de erro.
• Tratamento de FBA quando faz parte da operação.
• Logs e novas tentativas quando falha a Amazon ou a fila interna.

Cada linha entra por uma porta diferente (/orders/v0, /listings/2021-08-01, /feeds/2021-06-30, /reports/2021-06-30) e cada porta tem o seu próprio limite.

Que credenciais pede a SP-API e quem as fornece

1. A aplicação. A SP-API não se abre com o utilizador do Seller Central, mas com uma aplicação registada no Solution Provider Portal por um perfil de programador aprovado. Ao registá-la escolhem-se funções (a Amazon documenta dezoito) e só pode escolher as já aprovadas. Quatro são restritas por tocarem em dados pessoais, entre elas Direct-to-Consumer Shipping. E ter a função não basta: o endereço de entrega pede-se com um restricted data token (POST /tokens/2021-03-01/restrictedDataToken).

2. As chaves LWA. Da aplicação saem um client_id e um client_secret do Login with Amazon. O segredo caduca aos 180 dias: a Amazon avisa 90 dias antes e o antigo aguenta mais sete dias. Passado o prazo, as chamadas falham sem que ninguém tenha mexido em nada, e o sintoma (invalid_client de madrugada) não se parece com a causa; por isso o conector guarda essa data e avisa com um cron diário.

3. O refresh token do vendedor. É a única coisa que não preenche você: é gerado pelo vendedor ao autorizar a app em sellercentral…/apps/authorize/consent, com o application_id e um state próprio; se a app ainda estiver em rascunho acrescenta-se &version=beta, e ao publicá-la é preciso retirá-lo. A Amazon devolve-o ao seu redirect URI com um spapi_oauth_code que se troca em menos de cinco minutos em https://api.amazon.com/auth/o2/token: daí saem um access_token, que caduca à hora, e o refresh_token.

4. Marketplace e região. Uma conta não é um país: é um marketplace id (Espanha A1RKKUPIHCS9HS, França A13V1IB3VIYZZH) a apontar para um endpoint regional, https://sellingpartnerapi-eu.amazon.com na Europa. O nosso conector traz os 23 marketplaces como dados e cada conta aponta para um só, para que stock, impostos e canal saiam do sítio certo.

Limites de taxa: porque é que o conector precisa de fila

A Amazon reparte o tráfego com um balde de fichas: cada operação tem uma taxa (fichas por segundo) e um burst (capacidade), e cada pedido gasta uma ficha. Quando o balde se esvazia chega um 429, que a documentação chama reintentável, e (quando está disponível, o que nem sempre acontece) volta o cabeçalho x-amzn-RateLimit-Limit com o limite do seu par vendedor-aplicação. Os limites são por operação, e os da tabela são os valores por defeito, que a Amazon pode aumentar a quem movimenta mais volume.

Essa tabela explica o desenho. Como getOrders vai a um por minuto, as encomendas leem-se com marca de água (LastUpdatedAfter) e paginação por NextToken a partir de um cron de quinze em quinze minutos, não com um botão. Como os relatórios têm de ser aguardados, o ciclo é criar, sondar e descarregar: sondamos até doze vezes, a cada dez segundos. E como as chamadas de relatórios partilham balde, perante um 429 o conector escreve um arrefecimento partilhado de 90 segundos e o inventário FBA recorre à API em direto.

A nova tentativa vive numa única função: 429 e 500, 502, 503 e 504 voltam a tentar-se, respeita-se Retry-After e, se não vier, espera-se um backoff exponencial a partir de 1,5 segundos com ruído aleatório para que dois crons não voltem ao mesmo tempo. Se a última tentativa também falhar, o erro leva dentro o Retry-After, o cabeçalho de quota e o caminho: o log diz que quota se esgotou, não «erro ao sincronizar».

Daí a regra: o que escreve vai em fila com chave de idempotência; o que lê vai com marca de água. Confirmar o envio pode ficar em fila como «pendente» e então quem envia é um cron de cinco em cinco minutos que apanha no máximo 200 guias dos últimos três dias, com um trinco por guia que impede enviar o mesmo tracking duas vezes. Preços e stock têm a sua própria fila a cada minuto; se uma escrita falhar, outra fila volta a tentá-la a cada 180 segundos, vinte vezes no máximo por SKU.

Porque é que a Amazon quebra operações quando o Odoo não manda

Se o stock sai de vários sítios ou o tracking é gerido fora do ERP, chegam as incidências: encomendas sem mapear, inventário incoerente e pós-venda mais cara. Com os limites à frente vê-se porque é que o canal que publica o stock tem de ser um só: publicá-lo duas vezes custa o dobro de quota. Desenvolvemos isto em stock em tempo real em marketplaces e em vender em vários marketplaces a partir de um só Odoo.

Erros frequentes da Amazon SP-API no Odoo

Quase todas as falhas que vemos vêm dessas três credenciais, não do código: um redirect URI que aponta para outro Odoo e o regresso do vendedor acaba num ecrã que diz que ninguém o esperava; uma autorização com version=beta quando a app já está publicada; o segredo LWA caducado; a função restrita sem aprovar, que não dá erro claro mas endereços vazios; e o ciclo de 429 quando alguém repete à mão enquanto o cron também repete.

Cada um tem um sintoma que não se parece com a sua causa, por isso reunimo-los com o respetivo diagnóstico em Amazon SP-API e Odoo: erros frequentes e como evitá-los. Se o seu caso é a entrada em produção, o percurso está em como integrar a Amazon com o Odoo 19.

Comece pelo que mais custa

Com os limites à frente há uma ordem sensata: encomendas, stock e tracking primeiro, que são as três chamadas que sustentam o armazém; depois listagens, preços, FBA ou devoluções se o negócio o pedir. Os relatórios ficam para o fim: não são difíceis, consomem a quota lenta.

O que deve perguntar antes de comprar

• Que fluxos estão suportados hoje e por que API entra cada um.
• Se a ligação usa a sua aplicação ou a do fornecedor, e quem roda o segredo LWA.
• O que acontece perante um 429: volta a tentar, põe em fila, respeita Retry-After, deixa rasto?
• Como se tratam FBA, devoluções e endereços com dados pessoais.
• Se, ao confirmar duas vezes o mesmo envio, o tracking é enviado duas vezes.
• Se o fornecedor implementa ou só vende licença, e em que versões mantém o módulo.

Se a integração não é com a Amazon mas com o seu próprio programa de gestão, a abordagem é a mesma e explicamo-la em conector Odoo para o seu software; o catálogo está em módulos e o mapa por problema, em soluções.

Perguntas frequentes

Ligações úteis dentro da FlexigoTech

O que fazemos sobre isto