Nesta seção, você encontra as respostas para as dúvidas mais comuns sobre o uso da API de Logística
Quais eventos estão disponíveis na API de Logística?
São eles: "ACCEPTED", "REJECTED", "ORDER_PICKED", "ORDER_DELIVERED", "READYFORPICKUP", "CANCELLED"
Como solicitar a adição ou alteração de URLs?
As alterações devem ser solicitadas via suporte da API Saipos indicado na introdução da documentação da API. Nosso time interno fará a atualização necessária.
Como solicitar a homologação da integração?
Após receber as credenciais de desenvolvimento, o parceiro de entrega também receberá um arquivo de checklist de homologação.
Preencha o arquivo com as informações solicitadas e envie o arquivo preenchido pelo canal de acesso indicado na introdução da documentação da API, com o assunto de "Homologação da Integração".
Nosso time interno irá avaliar as informações e retornará com o resultado da homologação ou eventuais ajustes necessários necessárias.
Por que as URLs de comunicação da Saipos não seguem o padrão da OpenDelivery?
Atualmente, todos os eventos devem ser enviados para o endpoint /delivery-tracking/tracking-event-webhook
O módulo de webhook da Saipos foi criado antes da OpenDelivery definir um padrão oficial nesse contexto. Por isso, a padronização completa ainda não foi aplicada, embora siga em nosso roadmap.
Como a Saipos define se um pagamento é ONLINE ou OFFLINE?
Essa definição acontece no cadastro da forma de pagamento dentro da Saipos.
Pagamentos OFFLINE são enviados com method: "OFFLINE" e o campo offlineMethod preenchido com o tipo e valor.
Pagamentos ONLINE são enviados com method: "ONLINE" e o campo offlineMethod vazio.
Qual informação devo repassar no campo X-App-Id?
Esse campo aceita qualquer string. Recomendamos usar o nome da empresa ou algo que facilite a rastreabilidade em logs.
É possível combinar entregas para o mesmo entregador no parceiro de entrega
No momento não é possível, não está disponível na API de Logística da Saipos o campo combinedOrdersIds disponível na OpenDelivery
A Saipos permite que a taxa de entrega seja calculada pelo parceiro de entrega?
Não. Atualmente, os pedidos já são enviados aos parceiros com a taxa definida na Saipos, e não há possibilidade de alterá-la pelo lado do parceiro.
O que fazer quando um entregador é substituído ou rejeita a entrega?
É necessário reenviar o evento ACCEPTED para indicar a aceitação do novo entregador. Em seguida, enviar o evento PICKUP_ONGOING com o deliveryPerson atualizado para refletir a troca
Como obter/popular o campo deliveryId?
O deliveryId não é um campo que a Saipos precisa enviar. Ele é gerado e retornado pelo parceiro logístico no momento em que um novo pedido de entrega é solicitado.
O fluxo é o seguinte:
Quando a Saipos solicita uma nova entrega, nossa API repassa essa solicitação ao parceiro logístico.
O parceiro logístico responde com um deliveryId, que é o identificador dele para aquela entrega.
Nossa API armazena internamente a associação entre o orderId (da Saipos) e o deliveryId (do parceiro).
Quando o parceiro envia atualizações de status via webhook, ele já inclui o deliveryId no payload — e nossa API valida se esse par deliveryId + orderId existe.
Ou seja: a Saipos trabalha sempre com o orderId. O deliveryId é de responsabilidade do parceiro logístico, e o vínculo entre ambos é mantido automaticamente pela nossa API.
Assinatura HMAC-SHA256: payload bruto ou processado?
A assinatura deve ser gerada a partir do payload bruto (exatamente o JSON que será enviado no corpo da requisição), usando o clientSecret do merchant como chave.
Qualquer alteração no conteúdo do body após a geração da assinatura — como reordenação de campos, mudança de espaços ou reformatação — invalidará a validação. Portanto, o parceiro deve assinar exatamente o mesmo body que será transmitido na requisição, sem nenhuma transformação posterior.
É esperado que a API apresente timeouts com certa frequência, principalmente em horário comercial??
Não necessariamente durante todo o horário comercial padrão, porém é possível ocorrer aumento de latência e eventuais timeouts (ex.: 504 Gateway Timeout) durante períodos de pico operacional, especialmente nos horários de almoço e jantar, que concentram maior volume de processamento na plataforma da Saipos.
Nesses períodos, a priorização do processamento transacional dos restaurantes pode impactar temporariamente a API de dados. Adicionalmente, o tempo de atualização das informações pode ultrapassar o padrão esperado (inclusive podendo ser superior a D+1 em cenários específicos de alta demanda).
Para mitigar impactos em rotinas de integração, recomendamos:
Implementar retry com backoff exponencial para falhas transientes (5xx e timeout);
Utilizar multiplicador de 2x com jitter aleatório (ex.: 1s, 2s, 4s, 8s);
Registrar todas as tentativas e respostas em logs detalhados;
Preferencialmente realizar consultas em intervalos menores de datas (janelas curtas entre data inicial e final).
É importante ressaltar que, caso o erro persista mesmo após a aplicação dessas boas práticas, os logs completos da requisição (request e response) devem ser encaminhados à equipe da Saipos para que possamos realizar análise técnica aprofundada e dar prosseguimento ao suporte adequado.