O seu sistema conversando com o Poupa Sola
Integrar quer dizer uma coisa só: o pedido nasce e termina dentro do sistema que você já usa. Ninguém digita duas vezes, ninguém fica olhando tela esperando oportunidade aparecer.
Para quem COMPRA
A necessidade já nasce no seu sistema — e o comparativo volta para dentro dele.
- 1Ordem de serviço aberta, peça em falta, orçamento montado: o seu sistema manda isso para o Poupa Sola. Uma lista de vinte itens sai em segundos, não em vinte digitações.
- 2O seu código de produto viaja junto e volta exatamente igual. Você não traduz nada e não mantém tabela de-para.
- 3Código da peça e foto vão junto — é o dado que você já tem. Fornecedor que sabe qual peça é responde mais rápido e erra menos.
- 4As lojas da região respondem enquanto você trabalha. Quando encerra, o comparativo volta para o seu sistema: quem venceu cada item, o total por fornecedor e o contato de quem respondeu.
Some a digitação dupla — nem para pedir, nem para lançar o resultado. E cada cotação vira histórico de preço dentro da sua base.
Para quem VENDE
A cotação chega no seu sistema. Quem responde primeiro, com preço certo, ganha.
- 1Assim que um comprador da sua região pede peça da sua linha, o Poupa Sola avisa o seu sistema. Ninguém precisa estar olhando o celular.
- 2Você vê o que importa para decidir: categoria, quantos itens, distância, tempo restante, o preço da oportunidade — e a qualidade do pedido (quantos itens vieram com foto e com o código da peça).
- 3A decisão pode ser sua ou automática: o seu sistema compra sozinho pela regra que você definir, por exemplo até um valor e dentro de um raio.
- 4Comprou, recebe tudo: descrição completa, código da peça, foto e os dados do veículo. Isso casa com o seu estoque.
- 5O orçamento sai da sua tabela de preço, não da sua digitação. Respondeu, libera o contato do comprador.
Enquanto o concorrente digita doze itens, você já respondeu — e balcão cheio deixa de ser motivo para perder venda.
São três formas de ligar, e você escolhe pelo tamanho do seu TI: planilha (não precisa de programador, funciona hoje), API (o seu sistema consulta e responde sozinho) e aviso automático (o Poupa Sola chama o seu sistema na hora em que a oportunidade nasce). Dá para começar pela planilha e evoluir — uma não descarta a outra.
Daqui para baixo é a parte técnica — escrita para quem vai programar. Se esse não é o seu papel, mande este link para o seu time de TI ou para quem cuida do seu ERP.
1. Ligar a integração
Em Meus dados, ative “Integração com seu sistema”. Enquanto estiver desligada, os botões de importar/exportar ficam ocultos e as chaves não funcionam — é proposital, para não poluir a tela de quem não integra.
Depois, em Integração, gere a sua chave de API. Ela aparece uma única vez: guarde num cofre de segredos. Se perder, revogue e gere outra.
2. Arquivo (o caminho mais simples)
Não exige desenvolvimento: o comprador exporta a cotação e o fornecedor devolve o orçamento preenchido. Funciona em planilha (.xlsx) e em JSON canônico — o mesmo conteúdo nos dois formatos.
Use a coluna ref_externa para carregar o código do produto no seu sistema. O Poupa Sola não interpreta esse campo: devolve exatamente o que recebeu, e é assim que você reconcilia o item sem depender do nosso identificador.
3. API REST
Autenticação por cabeçalho, em toda chamada:
Authorization: Bearer SUA_CHAVE
A chave é vinculada ao seu perfil (comprador ou fornecedor) e só enxerga os seus próprios dados — as mesmas regras da tela valem aqui.
POST /api/v1/cotacoes
Cria uma cotação a partir do seu ERP (perfil comprador).
GET /api/v1/cotacoes/{id}
Consulta a cotação e as respostas recebidas.
GET /api/v1/leads
Lista as leads disponíveis para a sua loja (perfil fornecedor).
GET /api/v1/leads/{id}
Detalha uma lead.
POST /api/v1/leads/{id}/comprar
Compra a lead — debita PS$ da carteira, como na tela.
Toda lead vem com o bloco qualidade: quantos itens têm foto, quantos têm código da peça, os percentuais vigentes e os itens_equivalentes — o número que multiplica a base do preço. É com ele que você confere, no seu sistema, por que uma lead de 3 itens custou mais que outra de 3 itens. Depois da compra, cada item traz codigo_peca e, quando há imagem, uma URL de foto assinada que vale 1 hora — baixe o arquivo em vez de guardar o link.
POST /api/v1/leads/{id}/responder
Envia o orçamento. A resposta é final: não há reenvio.
Não há idempotência nos POST ainda. Se a rede cair depois de enviar um /comprar, você não tem como saber se ele passou — e repetir pode debitar de novo. Antes de reenviar uma chamada que mexe em dinheiro, consulte o estado pelo protocolo.
4. Webhooks
Em vez de ficar consultando, receba um POST quando algo acontece. Eventos disponíveis:
- lead.nova
- orcamento.recebido
- cotacao.encerrada
Valide a assinatura antes de confiar no corpo. Enviamos o cabeçalho X-PoupaSola-Signature com o HMAC SHA-256 do corpo bruto, usando o segredo do seu endpoint. Sem essa checagem, qualquer um que descubra a sua URL consegue injetar eventos falsos no seu ERP.
Calcule o HMAC sobre os bytes recebidos, antes de qualquer parse de JSON — reserializar muda o conteúdo e a assinatura deixa de bater.
Erros
As respostas de erro seguem o formato { "error": { "code", "message" } }. O code é estável e serve para tratamento automático; a message é texto para humano e pode mudar.