Skip to main content

​
Visão geral

Todos os pedidos da sua loja podem e devem ser enviados para a Solomon sempre que forem criados ou atualizados. A Solomon processa pedidos de forma assíncrona. Cada envio é enfileirado, consolidado e persistido antes de ficar disponível para consulta e uso na plataforma.

​
Processamento assíncrono

  • Cada pedido recebido é enfileirado para processamento
  • A fila de processamento é esvaziada em até 10 minutos
  • Apenas após o processamento o pedido estará disponível na plataforma
  • Quando múltiplas versões de um mesmo pedido são enviadas, prevalece sempre a versão mais recente, com base no campo updatedAt
Essa estratégia garante consistência eventual e tolerância a reenvios e retries.

​
Requisição

A criação e atualização de pedidos são realizadas por meio de uma API REST utilizando o método POST. O mesmo endpoint é utilizado tanto para criação quanto para atualização de pedidos.
O comportamento (create ou update) é determinado exclusivamente pelo campo orderid. 
import requests

res = requests.post("https://admin-api.solomon.com.br/admin/v1/order", json={
  "orderid": "ord_123456789",
  "number": 10234,
  "name": "Pedido #10234"
  # ...
}, headers={"Authorization": "Bearer YOUR_API_KEY"})

print(f"Status: {res.status_code}")
print(f"Response: {res.json()}")

​
Idempotência e atualização

Um pedido na Solomon representa uma transação comercial única e deve ser identificado de forma estável ao longo do tempo pelo campo orderId. A idempotência é garantida pela combinação de:
  • orderId
  • updatedAt
Quando um pedido é reenviado com o mesmo orderId, nossa lógica avalia o timestamp de atualização para decidir se os dados devem ser consolidados.
O timestamp de atualização do pedido deve estar sempre em UTC, garantindo um padrão de consistência para o tratamento desse dado.
Atualizações com updatedAt mais antigo são ignoradas. Essa regra se aplica ao:
  • Pedido
  • Cliente
  • Itens do pedido
Portanto, para atualizar o pedido, é necessário enviá-lo por inteiro com os novos campos atualizados, tal como também para atualizar um item do pedido.
Neste caso, porém, você pode enviar na lista de itens do pedido apenas o objeto de item a ser atualizado.

​
Identificação de itens do pedido

Cada item de um pedido possui três identificadores distintos, com papéis diferentes. O itemId é um identificador único do item dentro do pedido e permite múltiplas entradas da mesma variante com preços ou condições diferentes. Por vez, o variantId identificador da variante do produto e o productId é o próprio identificador do produto. É fundamental que esses identificadores sejam enviados corretamente para garantir consistência dos dados.

​
Cruzamento de dados e jornada do cliente

Alguns campos enviados no pedido podem ser utilizados pela Solomon para reconstruir a jornada do cliente ao longo do tempo. Para a integração direto na API, nós utilizamos como campo principal para este cruzamento o userId como um identificador único do usuário que é enviado junto ao pedido na API e também nos eventos do site. Outros campos comumente utilizados para esse fim, os chamados aliases, incluem:
  • cartToken: serve como um identificador do carrinho, exclusivo daquele usuário
  • customerId: identificação do cliente na loja
  • email: endereço de e-mail usado pelo cliente para fazer a compra
  • phone: telefone usado pelo cliente para fazer a compra
Quanto mais consistente for o envio desses campos, mais precisa será a análise da jornada.

​
Erros comuns

A fim de evitar possíveis insonsistências nos dados, recomendamos que seja garantido do lado da loja que:
  • O campo totalPrice seja igual à soma dos itens + frete − descontos
  • Um mesmo orderId represente sempre um único pedido
  • O updatedAt enviado seja sempre o mais recente disponível
  • Todos os valores monetários estejam na moeda informada no pedido