> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solomon.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Pedidos

> Sincronize a criação e atualização de pedidos na sua loja com a Solomon

## 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                    |

<Warning>
  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.
</Warning>

## 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                             |

<Tip>
  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.
</Tip>

***

## 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`.

<CodeGroup>
  ```py Python theme={null}
  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()}")
  ```

  ```js Javascript theme={null}
  const res = await fetch("https://admin-api.solomon.com.br/admin/v1/order", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      orderid: "ord_123456789",
      number: 10234,
      name: "Pedido #10234"
      // ...
    })
  });

  const data = await res.json();
  res.status, data

  console.log(`Status: ${res.status}`);
  console.log(`Response: ${data}`);
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Solomon {

      public static void main(String[] args) throws Exception {
          HttpClient client = HttpClient.newHttpClient();

          String jsonBody = """
          {
            "orderid": "ord_123456789",
            "number": 10234,
            "name": "Pedido #10234"
          }
          """;

          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create("https://admin-api.solomon.com.br/admin/v1/order"))
                  .header("Authorization", "Bearer YOUR_API_KEY")
                  .header("Content-Type", "application/json")
                  .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                  .build();

          HttpResponse<String> response =
                  client.send(request, HttpResponse.BodyHandlers.ofString());

          System.out.println("Status: " + response.statusCode());
          System.out.println("Response: " + response.body());
      }
  }
  ```

  ```php PHP  theme={null}
  <?php

  $ch = curl_init("https://admin-api.solomon.com.br/admin/v1/order");

  $payload = [
    "orderid"  => "ord_123456789",
    "number"   => 10234,
    "name"     => "Pedido #10234"
    // ...
  ];

  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
  ]);

  $response = curl_exec($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

  echo "Status: " . $httpCode . PHP_EOL;
  echo "Response: " . $response . PHP_EOL;
  ```
</CodeGroup>

## 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.

<Warning>
  O timestamp de atualização do pedido **deve estar sempre em UTC**, garantindo um padrão de consistência
  para o tratamento desse dado.
</Warning>

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.

<Tip>
  Neste caso, porém, você pode enviar na lista de itens do pedido apenas o objeto de item a ser atualizado.
</Tip>

## 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.

<Warning>
  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](/store/products).

  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.
</Warning>

## 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](/events/concepts), 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