Como funciona a integração de Status/Fluxo de Pedidos?

Existem 2 tipos de usos de "pedidos": Sem status/fluxo e com.

Esses modos são refletidos na interface do usuário. Não existindo status/fluxo, pedidos apenas são digitados e enviados, não existindo nenhuma verificação/posição posterior. Este é o modo mais simples de ser entendido e de ser implementado, e portanto menos útil pois há pouco controle de fluxos. Existindo uma integração, os pedidos apenas são inseridos e nada mais é feito sendo necessário apenas um método para inserção.

Utilizando status/fluxo de pedidos, a interface reflete isto como descrito neste artigo.

Nossa plataforma utiliza um conceito simples de 3 estados:

Antes de ser enviado, um pedido local está apenas no próprio aparelho, sem um "ID" (código) e pode ser editado, removido, e alterado de qualquer forma sem nenhum controle. Um pedido apagado ainda estando local é apenas removido do próprio aparelho localmente, sem fluxos.

Após ser enviado, um pedido recebe um ID único e um estado inicial indefinido (0).

Um pedido pode estar nestes estados:

• Indefinido (0): Apps/integrações seguem verificando status podendo atualizar dados (como mensagens de status, notas, etc.). Na interface, estes pedidos ficam como Edição, A Enviar ou Aguardando. Enquanto em Aguardando, pode ir para Aprovado (1) ou Rejeitado (2). Um pedido Aguardando não pode ser alterado ou removido pois aguarda retorno/posição da integração, garantindo consistência de dados. Os serviços (integrações) não alteram pedidos do usuário/aparelho, apenas rejeitando (2) para reenvio.
• Aprovado/Concluído (1): Apps/integrações terminaram tudo, nada mais é verificado, sendo utilizado para indicar que um pedido está 100% finalizado e concluído. Na interface, atualmente estes pedidos não são exibidos e existem só nos serviços de integração.
• Reprovado (2): Apps/integrações não precisam mais consultar/processar nada, pois o pedido foi indicado como "rejeitado" por algum motivo com alguma mensagem. Neste estado, o pedido pode ser deletado/removido ou editado/reenviado. A ação precisa ser do usuário, pois foi reprovado/rejeitado pela integração.

Os nomes (como Aguardando/Processando, ou Rejeitados/Retornados, etc.) são configuráveis e dependem de cada uso da plataforma, idioma, etc. Outras ações de pedidos como Copiar, Agrupar, entre outras, funcionam considerando estes mesmos estados (por exemplo, é possível Copiar um pedido Aguardando, mas não é possível Agrupar pedidos em Aguardando).

Em resumo:

• Ao ser criado (enviado) um pedido está como indefinido.
• Se indefinido não pode ser alterado (por consistência).
• De indefinido pode ser aprovado e finalizado (terminal).
• De indefinido pode ser reprovado onde retorna ao usuário.
• De reprovado pode ser removido (terminal).
• De reprovado pode ser editado/reenviado e será indefinido.

Não existem outras transições possíveis/suportadas, mantendo o sistema simples em 3 estados além da opção de remoção, que sendo local é uma simples remoção do banco de dados local do aparelho, e sendo remota (pedido já enviado e retornado/rejeitado) é uma indicação que o pedido foi removido/deletado pelo usuário e pode refletir na integração.

Em uma integração, devem existir os seguintes métodos/procedures:

1. Inserir um pedido novo (geralmente sem ID) com os campos e retornar um código (ID) de integração (p.ex., um código do ERP) ou algum erro/mensagem caso ocorra um erro. Falhas de software (exceptions, timeouts, etc.) não devem ser retornadas como rejeição pois não podem ser tratadas pelo usuário. Validações de entrada (saldo, cliente bloqueado, etc.) devem ser indicados e erros (exceptions, timeouts, etc.) devem possuir um fluxo diferente.
2. Reinserir um pedido (geralmente já com ID) que é igual ou parecido a inserir, mas deve receber um ID que foi retornado no método anterior de inserir. Neste caso, é um pedido que foi enviado, retornado/rejeitado, e está sendo reinserido. Geralmente, o inserir e reinserir são iguais, sendo que o primeiro retorna um ID e o segundo recebe este ID.
3. Status de pedido indicando se o pedido está aprovado (1), rejeitado (2) com algum tipo de mensagem/erro, ou simplesmente segue como indefinido (0). Como no caso de inserir ou reinserir, quaisquer falhas (exceptions, timeouts, etc.) devem ser transparentes aos usuários e não podem retornar como uma rejeição.
4. Deletar um pedido, que é o caso de um pedido que foi inserido/reinserido, possui um identificador de integração (ID), mas foi optado pelo usuário para apagar/remover na interface, que significa que o pedido não será mais usado (alterado, copiado, etc.). Neste caso, a integração deve ser informada que o pedido foi apagado e nada mais será feito.

Usuários ou tipos de usuários (ou clientes) diferentes podem ter fluxos completamente diferentes, desde que tenham um suporte a esses 4 métodos. Por exemplo, usuários de mercado interno ou de mercado externo podem ter métodos/procedures diferentes.

Sempre é importante destacar que erros de software (como exceptions, timeouts, constraints, etc.) devem ser transparentes aos usuários pois estes não podem ter controle sobre falhas, e sim apenas sobre retornos/rejeições.

O único método/procedure opcional é deletar. A inserção deve existir e sempre deve retornar um código (ID). O status sempre deve existir e, em algum momento, retornar aprovado (1) ou reprovado (2), neste caso suportando a reinserir e opcionalmente deletar.