Integração ERP

O vendedor está com uma cotação aberta no seu ERP. Esta seção descreve como levá-lo ao catálogo Sipru sem pedir login, e como o que ele monta lá volta para o seu sistema.

O ERP nunca encerra o Siprinho

O Siprinho fica aberto o tempo todo, inclusive entre um atendimento e outro. O ERP não deve fechar nem matar o processo do Siprinho, nem ao sair nem para "liberar a tela".

Se o painel atrapalha o usuário — num monitor pequeno ou de resolução baixa, por exemplo —, a solução é ativar o modo Gaveta: o Siprinho recolhe para uma aba fina na borda da tela e volta com um clique. Veja como em Sobreposição com outros apps.

Ambientes

Ambiente	Base URL
Produção	https://app.sipru.ai
Homologação	https://dev.sipru.ai

Independentemente do ambiente Sipru que você chamar, qual banco do seu ERP recebe a gravação do pedido é decidido pelo campo environment do corpo da requisição — e só o literal "prd" seleciona a base real. Campo ausente ou qualquer outro valor significa sandbox. Isso é deliberado: um campo esquecido nunca escreve na sua base de produção.

Módulo de configuração no ERP

Antes de qualquer comunicação com a Sipru, o ERP precisa de um lugar onde o usuário administrador ou o técnico de implantação configure os parâmetros básicos da integração — uma tela de parâmetros, um cadastro, o que for natural no seu sistema. Sem ela, cada ajuste vira uma alteração de código.

A tela abaixo é só um exemplo da ideia; o layout fica a seu critério.

1. Ativar integração com a Sipru e o Siprinho — liga e desliga tudo. Desligada, o ERP não chama a API da Sipru nem abre sessões no Siprinho, e segue funcionando como antes.
2. URL base das APIs da Sipru — o valor de $SIPRU_BASE_URL nos exemplos: https://app.sipru.ai em produção, https://dev.sipru.ai em homologação (ver Ambientes).
3. Partner ID — enviado no header X-Sipru-Partner-Id. Fornecido pela Sipru.
4. Token do parceiro — enviado em Authorization: Bearer. Guarde criptografado, mostre mascarado na tela e deixe só administradores alterarem.
5. Gravar logs de comunicação — liga a gravação descrita a seguir, e a pasta onde os arquivos ficam.

Logs de comunicação

Com a opção ligada, grave cada chamada à Sipru por inteiro: a requisição, a resposta e qualquer erro no meio do caminho (timeout, falha de rede, resposta fora do esperado). É o que permite ao suporte entender um problema sem precisar reproduzi-lo.

Requisição:

[{DATA_HORA}] POST|GET|PUT|DELETE {URL_COMPLETA}
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxx
{HEADERS}
Content-Type: application/json; charset=utf-8
Accept: application/json
Body: {PAYLOAD}

Resposta:

[{DATA_HORA}] {STATUS_HTTP} {URL_COMPLETA} ({DURACAO_MS} ms)
Body: {RESPOSTA}

Erro:

[{DATA_HORA}] ERRO {URL_COMPLETA}
{MENSAGEM_DO_ERRO}

• Nunca grave o token inteiro — mascare como no exemplo (Bearer xxxx…).
• Os corpos trazem dados pessoais (CPF e e-mail do vendedor, CNPJ do cliente). Mantenha os logs na máquina, com acesso restrito e prazo para apagar os antigos.

Headers

Toda chamada HTTP do ERP para a API da Sipru deve enviar os headers abaixo. Authorization e X-Sipru-Partner-Id são obrigatórios: sem eles a chamada não é autenticada. Os demais não bloqueiam a chamada, mas identificam o ERP, a máquina e a loja de onde ela partiu — envie sempre que tiver o dado.

Header	Obrigatório	Descrição
Content-Type	sim	Sempre application/json
Authorization	sim	Bearer $SIPRU_SECRET — token do parceiro, emitido pela Sipru
X-Sipru-Partner-Id	sim	Identificador do parceiro, fornecido pela Sipru
X-ERP-Name	recomendado	Nome do ERP. Use o mesmo slug do esquema sipru_{NOME_DO_ERP}:// registrado — ver Receber produtos do Siprinho
X-ERP-Version	recomendado	Versão do ERP em execução
X-Local-MAC-Address	recomendado	Endereço MAC do dispositivo
X-Local-Machine-Name	recomendado	Nome local da máquina (hostname)
X-CNPJ	recomendado	CNPJ da loja
X-Codigo-Externo-Rede	recomendado	Código externo da rede, no cadastro do ERP
X-Codigo-Externo-Loja	recomendado	Código externo da loja, no cadastro do ERP

Canal ao vivo

O ERP abre um canal por cotação e redireciona o navegador do vendedor. Ele cai no catálogo Sipru já logado na conta real dele, com a cotação e o cliente anexados. Quando o vendedor digita um código no ERP, o ERP avisa o Sipru e o produto aparece sozinho na tela, com as recomendações. O vendedor não digita duas vezes, e cada item que ele adiciona no Siprinho chega ao seu sistema no clique de "adicionar".

1. Abrir o canal — uma vez por cotação.
2. Buscar o produto — a pesquisa por texto no ERP mostra candidatos no Siprinho, sem mexer na cesta.
3. Incluir produto na cesta — o código exato do produto, lançado no ERP ou clicado no Siprinho, entra na cesta.
4. Receber produtos do Siprinho — o que o vendedor adiciona no Siprinho chega ao ERP.
5. Fechar cesta — o ERP registra no Sipru o que foi fechado.

Referência completa

O contrato formal de todos os endpoints está em Referência da API — ver também o contrato OpenAPI.