Pedidos

Um pedido criado pela API entra no Vamo como uma venda confirmada: o estoque dos produtos do catálogo baixa no mesmo instante, o pedido aparece nos pedidos do contato no Vamo e conta no total gasto dele.

POST /ordersCopiar link desta seção

Cria um pedido para um contato. Acesso: chave secreta com Leitura e escrita.

Cabeçalho opcional: Idempotency-Key, até 200 caracteres (veja Repetir com segurança).

Cada item:

Um item sem productId é avulso (frete, instalação, embalagem para presente): entra no total e não mexe no estoque.

curl -X POST https://vamo.ai/api/v1/orders \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-pedido-1042" \
  -d '{
    "storeId": "7b1e2c3d-4a5f-4b6c-8d7e-9f0a1b2c3d4e",
    "contactId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
    "notes": "Entregar depois das 18h",
    "items": [
      {
        "productId": "4d5e6f70-8192-4a3b-9c4d-5e6f708192a3",
        "variantId": "6f708192-a3b4-4c5d-8e6f-708192a3b4c5",
        "productName": "iPhone 15",
        "quantity": 1,
        "unitPrice": 459900
      },
      { "productName": "Frete", "quantity": 1, "unitPrice": 2500 }
    ]
  }'

Resposta 201

{
  "data": {
    "id": "8192a3b4-c5d6-4e7f-9a8b-92a3b4c5d6e7",
    "storeId": "7b1e2c3d-4a5f-4b6c-8d7e-9f0a1b2c3d4e",
    "contactId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
    "conversationId": null,
    "total": 462400,
    "currency": "BRL",
    "status": "confirmed",
    "source": "api",
    "notes": "Entregar depois das 18h",
    "needsReview": false,
    "externalOrderId": null,
    "reservationExpiresAt": null,
    "createdAt": "2026-10-31T14:10:00.000Z",
    "updatedAt": "2026-10-31T14:10:00.000Z",
    "items": [
      {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "productId": "4d5e6f70-8192-4a3b-9c4d-5e6f708192a3",
        "productName": "iPhone 15",
        "variantId": "6f708192-a3b4-4c5d-8e6f-708192a3b4c5",
        "variantName": "128 GB Azul",
        "quantity": 1,
        "unitPrice": 459900,
        "total": 459900
      },
      {
        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "productId": null,
        "productName": "Frete",
        "variantId": null,
        "variantName": null,
        "quantity": 1,
        "unitPrice": 2500,
        "total": 2500
      }
    ]
  }
}

Dispara o webhook order.created, com o pedido e os itens.

EstoqueCopiar link desta seção

• Tudo ou nada. Cada produto do catálogo precisa ser da loja, estar ativo e ter estoque para a quantidade pedida (somando itens repetidos). Se um item falhar, nenhum pedido é criado e nenhum estoque muda.
• Na hora e sem vender duas vezes. O estoque baixa junto com a criação do pedido. Se outra venda levou a última unidade um instante antes, o seu pedido responde 409 out_of_stock.
• Variações. Num produto com variações (cor, memória, tamanho), cada item indica a variação em variantId, e é o estoque dela que baixa. Sem variantId: 400 variant_required.
• Estoque que a loja não conta. Um produto marcado só como "em estoque" ou "sem estoque" (sem quantidade) vende qualquer quantidade enquanto estiver em estoque, e nada é baixado.
• Catálogo do WhatsApp. Quando o estoque muda, o catálogo do WhatsApp da loja é atualizado em seguida.

Diferenças para os pedidos da IACopiar link desta seção

Repetir com segurançaCopiar link desta seção

Uma falha de rede no meio do caminho deixa a dúvida: o pedido foi criado? Envie sempre o cabeçalho Idempotency-Key com um valor único por venda (o número do pedido no seu sistema, por exemplo). Repetindo a requisição com a mesma chave, o Vamo não cria outro pedido nem baixa o estoque de novo: responde 200 com o pedido que já existe, sem disparar outro webhook. Isso vale mesmo que o corpo seja diferente.

A chave vale só dentro da sua organização. Mais de 200 caracteres: 400 invalid_idempotency_key.

GET /ordersCopiar link desta seção

Lista os pedidos, do mais novo para o mais antigo, sem os itens. Acesso: chave secreta (leitura).

curl "https://vamo.ai/api/v1/orders?status=confirmed&contactId=2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE"

Responde { "data": [ … ], "pagination": { … } }.

GET /orders/:idCopiar link desta seção

Um pedido com os itens, no mesmo formato da criação. Acesso: chave secreta (leitura). 404 (Order not found) se não existir na sua organização.

curl https://vamo.ai/api/v1/orders/8192a3b4-c5d6-4e7f-9a8b-92a3b4c5d6e7 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE"

source diz quem criou: ai (o agente de IA), human (a equipe no painel), api, ou null em pedidos antigos.

PATCH /orders/:idCopiar link desta seção

Muda o status ou as observações. Acesso: chave secreta com Leitura e escrita.

Pelo menos um dos dois.

curl -X PATCH https://vamo.ai/api/v1/orders/8192a3b4-c5d6-4e7f-9a8b-92a3b4c5d6e7 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "status": "shipped" }'

Responde 200 com o pedido (sem os itens) e dispara order.updated.

As etapasCopiar link desta seção

Um pedido anda uma etapa por vez e pode ser cancelado até ser entregue:

Pular uma etapa (confirmed → delivered) responde 409 invalid_transition, com from e to no corpo. Enviar o status que o pedido já tem não muda nada.

• Cancelar devolve o estoque de um pedido pending ou confirmed, na hora (o da variação, quando o item tem uma). Um pedido shipped cancelado não devolve: as unidades já saíram da loja.
• Pedido da loja conectada. Um pedido que está na sua Shopify ou WooCommerce muda de status lá, não no Vamo: 409 order_managed_by_store (o corpo traz platform). As observações continuam editáveis.
• Pedido esperando aprovação. Um pedido da IA marcado para revisão só muda de status depois que a equipe aprova ou recusa: 409 order_in_review.

ErrosCopiar link desta seção

Os erros vêm no formato de sempre: { "error": { "code": "…", "message": "…" } }, com os detalhes ao lado.

{
  "error": {
    "code": "out_of_stock",
    "message": "Not enough stock for \"iPhone 15 (128 GB Azul)\"",
    "productName": "iPhone 15 (128 GB Azul)",
    "available": 0
  }
}