Briefing de implementação — integração Vetor Sistemas ⇄ Revo

Documento enviado à Vetor Sistemas · 2026-08-25

Este é o documento por onde se começa. Ele diz o que construir do lado da Vetor, em que ordem, e como saber que cada pedaço está pronto. Ele não repete a referência da API: essa mora nos dois anexos, que vão junto.

arquivo	o que é
este	o quê, em que ordem, e o critério de pronto
`manual-da-integradora.md`	o contrato: autenticação, fluxo, webhooks, limites, sandbox, homologação
`api-integracao.md`	o dicionário: as rotas campo a campo, com exemplos completos

Para quem for implementar com apoio de I.A.: leia os três antes de escrever a primeira linha. O manual tem uma seção 10 chamada "o que a plataforma ainda NÃO oferece" — ela existe justamente para impedir que se construa contra uma rota imaginada. Se algo que você precisa não estiver nos anexos, não existe; pergunte antes de projetar em cima.

1. O que a Vetor vai construir

Um sincronizador dentro do ERP, que empurra catálogo para a loja e escuta o que a loja responde. São quatro peças, e só a primeira é obrigatória para a loja funcionar:

Envio de cadastro — produto, grade, fotos. POST /catalog/products.
Envio de preço — canal próprio, porque preço muda o dia inteiro. POST /catalog/prices.
Envio de estoque — saldo absoluto por SKU. POST /catalog/stock.
Recebimento de webhooks — um endpoint HTTPS seu, que a Revo chama quando nasce ou muda um pedido.

A quinta peça é humana e não é código: o de/para. A loja não adivinha que a sua categoria 1/6/5 é "Legging Fitness" nem que o seu tamanho P é o P dela. Enquanto não estiver traduzido, o produto entra e fica em quarentena — existe, é editável, e não aparece na vitrine. Isso é comportamento correto, não falha: ver seção 5 do manual.

2. Os valores deste ambiente


Base da API	`https://api.up3esportes.com.br/api/v1/integration`
Autenticação	`X-Api-Key: <chave>` — não é `Authorization: Bearer`
Loja	`X-Tenant-Id: <uuid da loja>`
`origin` (seu slug)	`vetor` — minúsculo, e estável para sempre
Idempotência	`Idempotency-Key: <uuid seu>` em todo POST

Sobre o origin: ele identifica o vocabulário do seu sistema, e o de/para de cada loja é por origem. Trocá-lo depois equivale a apresentar um sistema novo — todo o de/para volta a zero, e todo o catálogo daquela loja volta para a quarentena. Ele já está gravado como vetor nas lojas existentes; não mude.

A chave não vem da Revo. Quem emite é o lojista, no painel dele, em Configurações → Integrações. Ela aparece uma única vez na tela: guarde no cofre do ERP no momento em que aparecer. Se perder, o lojista revoga e emite outra — não há como recuperá-la.

O prefixo diz o mundo em que você está, e a API confere a cada requisição:

revo_test_… → loja de sandbox
revo_live_… → loja de verdade

Chave de um mundo contra loja do outro dá 401, sempre. Não existe endereço de sandbox separado — o que separa os dois é o par (loja, chave).

A sua loja de sandbox já existe — use ELA, não a do cliente

A Revo provisionou a loja de sandbox da Vetor em 25/08/2026. Ela é sua: 30 produtos, 183 variações com preço, estoque e fotos, 27 faixas de frete configuradas, uma chave revo_test_… com os quatro escopos, e um convite de OWNER para o seu contato técnico. O de/para nasce vazio de propósito — é você quem preenche, e é isso que tira a homologação da dependência de um lojista.

O X-Tenant-Id, a chave e o link do convite foram enviados fora deste documento, na mensagem que o acompanha. A chave aparece uma vez só.

Existe também uma chave revo_live_ da Vetor apontando para a loja de PRODUÇÃO da Up3 Esportes — 932 produtos, vitrine no ar. Ela nunca foi usada. Não a use para desenvolver: o primeiro lote escreveria no catálogo real de um cliente real. Ela existe para o dia em que a integração estiver homologada.

Como saber em qual você está, sem adivinhar: GET /ping e leia o storeName. Se disser "Up3 Esportes" quando você queria a sandbox, pare.

O painel da sua loja de sandbox ainda não tem endereço web. O painel publicado (painel.up3esportes.com.br) atende só a loja da Up3. Enquanto o endereço não sai, o de/para se preenche pela API de administração (PUT /api/v1/admin/integration/mappings), com o token do OWNER da sua loja — o que, para quem está automatizando a integração, é até mais direto que a tela.

3. Ordem de construção, com critério de pronto

A ordem não é sugestão. O cadastro é quem apresenta os externalId das variações; preço e estoque só sabem falar de variação que já existe. Mandar preço antes do cadastro devolve variacao_desconhecida para tudo.

Passo 0 — a credencial responde, e você confere CONTRA QUEM

GET /ping com a sua chave e o seu X-Tenant-Id (mande Accept: application/json).

{ "status": "pong", "tenantId": "…", "storeName": "Up3 Esportes",
  "environment": "sandbox", "keyPrefix": "revo_test_a1b2c3d4",
  "scopes": ["catalog:write", "…"] }

Pronto quando: responde 200, o storeName é o nome da loja que você queria, o environment é sandbox e os scopes cobrem tudo o que você vai fazer.

Confira o nome, não o UUID. O X-Tenant-Id é obrigatório e a chave só é aceita se for daquela loja — então o tenantId que volta é sempre o que você digitou. Compará-lo com a sua configuração é comparar a configuração com ela mesma: quem apontou o conector do cliente A para o UUID da loja B recebe B de volta e passa no próprio teste. O nome é o único campo que você não mandou.

Se der 401, o par (loja, chave) está errado; não é problema de rede.

Passo 1 — um produto, duas variações

POST /catalog/products com um item.

Pronto quando: responde 200 e o item vem com result: "em_quarentena". Isso é o esperado: nada está traduzido ainda. A resposta traz pending, com cada termo que falta e o rótulo que você mandou.

Confira agora, não depois: se algum label vier vazio, corrija. É esse texto que o lojista vai ler na tela para decidir a tradução — code sem label é um de/para que ninguém consegue preencher.

Passo 2 — o de/para

GET /mappings?origin=vetor&status=pending lista o que falta. Traduza no painel da sua loja de sandbox.

Pronto quando: o mesmo produto, reenviado, responde criado ou atualizado, e aparece na vitrine. Você não precisa reenviar nada para liberar o que já está preso: mapear solta a quarentena sozinho. Reenviar é só para conferir.

Passo 3 — o catálogo inteiro

Lotes de até 500 itens. Não mande item a item.

Pronto quando: GET /quarantine?origin=vetor volta vazio, ou só com o que você decidiu não vender.

Passo 4 — preço e estoque

Canais separados, cada um com o seu ritmo.

Pronto quando: um preço alterado no ERP aparece na vitrine, e um saldo zerado tira o produto de venda.

Passo 5 — webhooks

Cadastre o seu endpoint no painel (o lojista faz, ou você na sua loja de sandbox). Ao salvar, a tela mostra o segredo de assinatura — uma vez só.

Pronto quando: uma compra na vitrine da sua loja de sandbox faz chegar order.placed no seu endpoint, com assinatura validada, e você responde 2xx.

Para fechar o pedido sem gateway nenhum, o sandbox tem um pagamento de mentira: o e-mail do comprador ou os centavos do total decidem o desfecho (manual, seção 9). É o que destrava os quatro eventos de pedido.

4. As regras que não se negociam

Idempotência. Mande Idempotency-Key em todo POST. Reenviar o mesmo lote com a mesma chave devolve a resposta anterior sem escrever de novo. Sem ela, uma re-tentativa depois de timeout duplica trabalho.

externalId é a sua chave, e é para sempre. A chave real é a trinca (loja, origem, externalId). Você nunca guarda id nosso. Trocar o externalId de um produto cria um produto novo e abandona o antigo.

Estoque é saldo ABSOLUTO, nunca delta. Mande quanto tem, não quanto mudou. Do nosso lado vira lançamento de ledger.

salePrice nulo apaga a promoção. Nulo e zero não são a mesma coisa — mas como os ERPs mandam os dois querendo dizer o mesmo, zero é tratado como ausência. Se a promoção acabou, mande nulo.

200 não significa "tudo entrou". As rotas de escrita respondem 200 mesmo com item rejeitado: o motivo está no resultado de cada item. Um item ruim não derruba o lote — de propósito, porque derrubar obrigaria você a fazer bissecção para achar o produto errado. Leia item por item.

Retry só em 5xx e timeout, com espera crescente. 4xx é erro seu: repetir não conserta. Ver a regra completa na seção 6 do manual.

Fotos: mande a URL final (redirecionamento não é seguido), em host público, até 5 MiB, no máximo 20 por produto. Foto que falha não reprova o produto.

5. O que NÃO existe — não projete em cima

Isto é o resumo; a lista completa e atualizada está na seção 10 do manual.

Não há rota de integração que LEIA um pedido. Os webhooks de pedido carregam o id do pedido na plataforma, e não existe endpoint para buscar o conteúdo dele. Se o seu fluxo precisa importar o pedido para o ERP, isto é um bloqueio — e precisa entrar na conversa agora, não na homologação.
O escopo orders:read existe e hoje não protege nada, justamente por isso.
Não há cadastro público nem autoatendimento: a loja de sandbox é pedida por e-mail.
Não há limite de requisições por minuto implementado. Isso não é permissão para chamar item a item.
Não há endereço sandbox.api.…. O isolamento é o par (loja, chave).

6. Homologação

A seção 11 do manual tem o checklist inteiro. Ele é o critério de aceite: a Vetor aparece no painel de cada lojista com a situação e com até onde foi provada. Uma integradora homologada para catálogo e não exercitada em webhooks aparece exatamente assim, com todas as letras — o lojista precisa saber o que pode prometer.

Hoje a Vetor consta como homologada para cadastro de produtos, preço, estoque e leitura do de/para e da quarentena. Webhooks ainda não foram exercitados ponta a ponta.

7. Suporte

Canal e contato na seção 12 do manual. Ao abrir um chamado, mande sempre:

o origin (vetor), o X-Tenant-Id e o prefixo da chave (nunca a chave inteira);
o batchId que a resposta devolveu;
o corpo que você enviou e o que recebeu de volta.

Com esses quatro, o problema se resolve sem ida e volta.