Sipru — API de parceiros ERP (1.1.0)

Devolve uma URL de uso único, válida por ERP_SSO_TOKEN_TTL_SEC (600 s por padrão). A URL funciona exatamente uma vez: um segundo clique ou um reload da mesma URL responde ERP_SSO_TOKEN_ALREADY_USED. Para testar de novo, gere uma URL nova — esse comportamento é a proteção contra replay, não um defeito.

Faz tudo o que /api/erp/sso/session faz e ainda cria um canal identificado por channelId, com os endpoints para o ERP adicionar produtos e para a tela do vendedor consumir os eventos.

Se cartCallbackUrl for informado, ele tem precedência sobre a configuração de loja em /integracoes/cart-erp para o webhook de item adicionado (ver webhooks).

Resolve o termo no catálogo da loja do canal — com o tenant e a política de preço do próprio canal — e publica o resultado na tela que o vendedor está olhando, junto com substitutos, cross-sell e upsell.

A precedência do termo é productCode → ean → query, porque o código do parceiro é o mais determinístico e o texto livre é o último recurso (cobre o caso de o código não existir no catálogo Sipru).

Quando a cesta é fechada no ERP, o ERP registra no Sipru o que foi fechado, com os itens finais. Credencial de parceiro, como as demais rotas do canal.

Não é uma segunda gravação do pedido: os itens já chegaram ao ERP durante o atendimento. Refechar a cesta sobrescreve o registro anterior em vez de recusar, e o canal continua aberto depois do fechamento.

Campos além de items, no corpo ou em cada linha, são guardados como vieram e nunca recusam o fechamento.

POST /api/erp/channel/{channelId}/orcamento é o nome antigo desta rota, mantido por compatibilidade e com a mesma resposta. Integrações novas usam /cesta.

Quando a venda é concluída no ERP, o ERP informa à Sipru com o número do pedido (orderCode, o mesmo order_code das vendas que o ERP envia para a Sipru). É o que confirma os Sipru Points do vendedor contra as vendas do ERP.

Vale depois do atendimento: com o canal expirado ou encerrado, a venda é aceita se aquele canal já teve uma cesta fechada pelo mesmo parceiro. Chamar de novo sobrescreve a venda do atendimento.

Campos além de items e orderCode, no corpo ou em cada linha, são guardados como vieram e nunca recusam a venda. Um orderCode fora do formato é ignorado.

Registra no Sipru que o atendimento do canal virou cesta.

Não é uma rota de parceiro. Quem chama é a tela do Sipru, com a sessão do vendedor dono do canal — sem Authorization: Bearer e sem X-Sipru-Partner-Id. O ERP fecha a cesta por POST /api/erp/channel/{channelId}/cesta.

O caminho guardou o nome antigo do documento (orcamento), que passou a se chamar cesta em 11/09/2026: a rota é a mesma e o documentType da resposta volta como cesta.

Quando o vendedor clica em "adicionar" na tela do Sipru, o Sipru faz POST no endpoint do parceiro. O destino é resolvido nesta ordem:

1. cartCallbackUrl do canal, quando enviado na criação;
2. cartCallbackUrl cadastrada para a loja em /integracoes/cart-erp;
3. erpBaseUrl + orderEndpointPath da mesma configuração.

Sem nenhum dos três, o clique não vira POST.

Contrato esperado do parceiro: responder 2xx. O Sipru tenta 2 vezes, com timeout de 8 s, e só repete em status transitório (408, 429, 5xx) — um 4xx não transitório recusa o item de vez. Deduplique por Idempotency-Key, que também vem no corpo como idempotencyKey.