Começando
A API de Pedido de Peças permite que o revendedor faça um pedido de Peças, Acessórios e Roupas (PA&A) a partir de seu DMS em vez de ir ao BOSSWeb.
BOSSWeb e a API de Pedido de Peças usam a mesma API interna para criar o pedido no SAP.
A API de Pedido de Peças oferece 6 serviços:
- VALIDAR para validar o pedido antes de criá-lo.
- CRIAR para criar o pedido.
- VERIFICAR para verificar o status de criação de um pedido.
- OBTER para obter um ou muitos pedidos com base em parâmetros de consulta.
- CANCELAR para cancelar um ou muitos itens de linha que ainda não foram processados.
- PEDIDOS EM ATRASO para obter os pedidos de peças com pelo menos uma peça em atraso.
Pedido de Peças no BOSSWeb
Se seus revendedores perguntarem, a API de Pedido de Peças é usada apenas para os Pedidos Diários no BOSSWeb.
Por onde começar? Leia-me primeiro!
Antes de começar a trabalhar nesta API, você precisa ler as seguintes seções se ainda não as tiver consultado:
- Pedido, Fatura e Entrega: A História Completa para obter uma visão geral do processo de pedido e entrega de peças.
Dependências
Para chamar a API de Pedido de Peças, você precisa de uma autenticação de revendedor access_token obtido da API de Autenticação do Revendedor.
Uma autenticação de revendedor access_token é necessária porque a API está trabalhando com pedidos de peças e com 💲💲
A API de Pedido de Peças depende de dados recuperados de outras APIs DCP, nomeadamente:
Há também uma relação entre a API de Pedido de Peças e as seguintes APIs:
Limitações Importantes
Na versão atual da API de Pedido de Peças e com a limitação dos sistemas de backend, há um limite de 25 itens de linha.
Se um pedido de peças tiver mais de 25 a 30 itens de linha, o Validar e Criar serviço retorna um erro 504 Gateway Timeout.
O tempo limite é causado pelo sistema de backend, que leva mais tempo para criar o pedido de peças do que o valor de tempo limite na API de Pedido de Peças (e esse valor de tempo limite não pode ser alterado. Não me faça começar a falar sobre isso.)
Veja a Verificar Fluxo de Dados seção para informações sobre como lidar com o tempo limite.
Pedido de Peças com Kit
A kit (ou BOM na linguagem do BRP) é um número de peça que representa um conjunto de peças que são vendidas e enviadas juntas.
Diferenças Importantes Entre V3 e V4
Existem diferenças pequenas, mas importantes, entre as versões V3 e V4 da API de Pedido de Peças.
ID do Pedido PAC
Na resposta retornada pelo Create serviço, a primeira propriedade é o pac_order_id.
O pac_order_id é o identificador único para o pedido de peças usado pelo SAP.
Na versão V3 o valor GUID fornecido pelo seu DMS na propriedade pac_order_id é usado pelo SAP e retornado nas respostas de Validate e Create .
Na versão V4 o SAP usa o valor GUID fornecido pelo seu DMS na propriedade pac_order_id e o retorna na resposta de Validate .
No entanto, o SAP retorna um valor diferente na resposta de Create.
🛑 O pac_order_id retornado na Create resposta deve ser salvo, pois é necessário para identificar o pedido de peças em uma chamada para os serviços Cancel e Get .
Número do Pedido de Venda
A sales_order_no contém o número do documento de venda que o revendedor pode usar para rastrear o pedido.
Na versão V3, a propriedade sales_order_no é repetida em cada objeto de item.
Na versão V4, a propriedade sales_order_no é encontrada apenas no cabeçalho.
ID do Item Pedido
A propriedade item_id de um item identifica exclusivamente o item no SAP em todos os pedidos.
Na versão V3 o valor GUID fornecido pelo seu DMS na propriedade item_id é usado pelo SAP e retornado nas respostas Validate e Create .
Na versão V4 o SAP usa o valor GUID fornecido pelo seu DMS na propriedade item_id e o retorna na resposta Validate .
No entanto, o SAP retorna um valor diferente na resposta de Create.
🛑 O item_id propriedade retornada na Create resposta deve ser salva, pois é necessária para identificar o pedido de peças em uma chamada para os serviços Cancel e Get .
Fluxo de Dados de Alto Nível
As seções a seguir apresentam o fluxo de dados de alto nível para os serviços que a API de Pedido de Peças fornece.
Esses fluxos de dados são para introduzir os serviços da API de Pedido de Peças; eles não são completos, e muitos detalhes são documentados mais adiante nas outras seções.
A API de Autenticação do Revendedor chamada para autenticar o revendedor não é mostrada nos diagramas.
Fluxo de Dados de Validação/Crição
O diagrama abaixo descreve o fluxo de dados que simula e cria um pedido de peças.
Informações da API de Concessionárias e API de Peças são necessárias para um pedido de peças. Ao criar um pedido de peças, o revendedor deve selecionar um método de envio da lista disponível. A lista de métodos de envio válidos é retornada pela API de Concessionárias.
Custos adicionais de envio serão cobrados para alguns métodos de envio. Outras condições do pedido, como o valor total do pedido, também podem resultar em custos adicionais sendo cobrados.
É por isso que o Validate serviço deve ser chamado antes do Create serviço. O serviço Validate retorna as mesmas informações do pedido de peças que o Create e permite que o revendedor faça alterações antes de enviar o pedido.
A API de Pedido de Peças valida o pedido e, se houver custos adicionais a serem cobrados, a carga útil retornada contém uma ou várias mensagens de aviso, por exemplo:
Custos adicionais de envio serão cobrados com este método de entrega. Seu pedido PAC é inferior a 150,00$, uma taxa de manuseio de 20,00$ será aplicada à fatura.
Essas mensagens de aviso devem ser exibidas ao revendedor. Após visualizar os avisos, o revendedor pode decidir aceitar os custos adicionais e criar o pedido ou cancelar o pedido.
Observe que a API de Pedido de Peças também retorna esses avisos quando o Criar serviço é chamado, mas é tarde demais, pois o pedido já foi criado.
O Validar serviço também permite que o revendedor gerencie peças em atraso.
Por exemplo, a resposta de Validar pode indicar que uma peça está em atraso com a BRP. O revendedor pode decidir usar o API de Inventário de Peças do Revendedor serviço de localizador de peças para tentar encontrar a peça no inventário de um revendedor. Se uma for encontrada, a peça pode ser removida do pedido.
Em resumo, você deve sempre chamar o serviço Validar antes do serviço Criar para validar o pedido e os custos adicionais.
No seu DMS, o botão de enviar/criar não deve estar habilitado se a validação não foi feita para todos os pedidos de peças.
Todas as mensagens de aviso retornadas na carga útil Validar devem ser exibidas ao revendedor. Após as mensagens de aviso serem mostradas, uma confirmação do revendedor deve ser solicitada antes que o pedido seja criado.
Verificar Fluxo de Dados
O Verificar serviço recupera o status de um pedido de peça. A chamada gerencia principalmente o erro 504 Gateway Timeout que a API de Pedido de Peças retorna quando o pedido tem mais de 25 itens.
Quando a API de Pedido de Peças Criar retorna um tempo limite, a ideia é esperar alguns minutos e então chamar o Verificar serviço para verificar se o pedido foi criado.
O tempo de espera pode ser calculado multiplicando o número de itens por 3 segundos.
Se o Verificar serviço retornar um erro, espere por outro período e chame o Verificar serviço novamente até que o pedido seja criado ou você tenha atingido um número máximo de tentativas (para evitar um loop infinito).
Quando o pedido é criado, o Verificar serviço retorna as informações do pedido criado que podem ser salvas em seu banco de dados DMS.
Obter Fluxo de Dados
O serviço Obter recupera um ou muitos pedidos de peças com base em critérios. A busca pode ser feita em:
- O ID do pedido.
- O número do pedido de compra do revendedor.
- O status do pedido.
- A data de criação do pedido.
- O tipo de pedido.
O Obter serviço deve ser usado para atualizar um pedido enquanto ele estiver aberto.
Leva um momento para completar o processamento do pedido no backend, então quando o serviço Criar retorna o payload do pedido, nem todas as informações estão disponíveis.
Por exemplo, as informações de entrega geralmente não estão disponíveis no payload retornado pelo Criar serviço, uma vez que estão disponíveis apenas quando as peças são processadas.
Uma abordagem é chamar o Get serviço para atualizar as informações do pedido quando ele é exibido para o revendedor.
👉Uma chamada para o Get serviço para recuperar uma lista de pedidos de peças, por exemplo, usando um intervalo de datas, também retorna os pedidos de peças criados pelo revendedor no BOSSWeb.
❗❗ O Get serviço é essencial para ajudar o revendedor em seu processo de recepção de pedidos de peças. ❗❗
Se os pedidos de peças não forem carregados e atualizados em seu banco de dados DMS, o API de Entregas e API de Faturas não podem ser usados para vincular as peças recebidas ao pedido de peças.
Cancelar Fluxo de Dados
O Cancel serviço permite que você cancele itens que estão em atraso em um pedido de peças.
Observe que um item de pedido em atraso que foi enviado ou parcialmente enviado não pode ser cancelado via API.
❗ ❗ É importante chamar o Get serviço para atualizar o pedido e exibir ao revendedor as informações mais recentes do pedido ❗ ❗
Lembre-se de que apenas itens em atraso podem ser cancelados.
