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.
Status do pedido
O campo orderStatus indica o estado atual do pedido e deve ser enviado como um valor inteiro.
| Valor | Status | Descrição |
|---|
0 | Aprovado | Pedido confirmado e pago |
1 | Pendente | Aguardando confirmação de pagamento |
2 | Cancelado | Pedido cancelado |
Enviar o status incorreto impacta diretamente os relatórios de receita da plataforma.
Pedidos com status 1 (Pendente) não são contabilizados como receita aprovada.
Método de pagamento
O campo paymentMethod deve ser enviado como um valor inteiro conforme a tabela abaixo.
| Valor | Método |
|---|
1 | Cartão de Crédito |
2 | Depósito / Transferência Bancária |
3 | Boleto |
4 | PIX |
15 | Outro |
Mapeie os métodos de pagamento da sua loja para os valores acima. Evite enviar 15 (Outro) como fallback genérico,
pois isso prejudica a análise de métodos de pagamento na plataforma.
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:
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.
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.
Os campos productId e variantId são a ponte entre pedidos e produtos na plataforma.
Eles devem ser idênticos aos valores enviados no endpoint de produtos.Por exemplo, se o produto foi cadastrado com variantId: "142", o pedido também deve usar variantId: "142" — e não uma variação como "142_xgg".
Inconsistências nesses campos impedem o cruzamento de dados e fazem com que estatísticas de produto fiquem ausentes. 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áriocustomerId: identificação do cliente na lojaemail: endereço de e-mail usado pelo cliente para fazer a compraphone: 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
