Carrinho, pedidos e produtos

Consulte e atualize produtos, envie produtos, mexa no carrinho e mude o status, a entrega e o pagamento dos pedidos pela API, com valores em centavos.

Guia12 min

Atualizado em 26/10/2026

O E-commerce da NexTags vende pela conversa: o contato vê os produtos, monta o carrinho e fecha o pedido. Pela API, o seu sistema mantém preço e estoque em dia, mexe no carrinho do contato e acompanha o pedido até a entrega e o pagamento. Atenção às unidades: o preço do produto vai em reais, e os totais do carrinho e do pedido, em centavos.

Antes de começar

A chave de API na variável de ambiente NEXTAGS_API_KEY. Veja Autenticação com a chave de API.
Os produtos cadastrados em Ferramentas › Ecommerce. Veja Cadastrar produtos.
Os IDs do produto, do contato e do pedido. A API não lista produtos nem pedidos: veja onde achar cada ID em Contatos, fluxos e outros identificadores.

Passo a passo

Passo 1: Consulte o produto

Use Consultar produto:

Consultar produto

curl "https://app.nextagsai.com.br/api/products/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/products/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/products/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

{
  "id": 6001,
  "name": "Bolo de chocolate",
  "price": 89.9,
  "sale_price": 79.9,
  "category_id": 6101,
  "category_name": "Bolos",
  "stock": 12,
  "short_description": "Serve 12 pessoas",
  "image": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg",
  "created_at": "2026-10-01 12:00:00"
}

O price está em reais: 89.9 é R$ 89,90.

Passo 2: Atualize o preço, o estoque e se está à venda

Use Atualizar produto. Mande só o que muda: price, stock e active (se os contatos podem comprar o produto).

Atualizar produto

curl -X POST "https://app.nextagsai.com.br/api/products/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 94.9,
    "stock": 20,
    "active": true
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    price: 94.9,
    stock: 20,
    active: true,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/products/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "price": 94.9,
        "stock": 20,
        "active": True,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/products/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'price' => 94.9,
        'stock' => 20,
        'active' => true,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true, "updated": true}. Confira na lista de Produtos que o preço ficou R$ 94,90.

Passo 3: Envie produtos ao contato

Use Enviar produtos ao contato. O product_id aceita um ID, uma lista de IDs ou IDs separados por vírgula:

Enviar produtos ao contato

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/products" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": [
      6001,
      6002
    ]
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/products', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product_id: [6001, 6002],
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send/products",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "product_id": [6001, 6002],
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send/products');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'product_id' => [6001, 6002],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

O contrato não descreve a resposta: confira o código HTTP e a conversa na Caixa de Entrada. Como toda mensagem, o envio segue a janela de 24 horas do WhatsApp. Veja A janela de 24 horas.

Passo 4: Ponha um produto no carrinho

Use Adicionar produto ao carrinho. Esta chamada recebe formulário, com a quantidade em quantity:

Adicionar produto ao carrinho

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'quantity=2'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    quantity: 2,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "quantity": 2,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'quantity' => 2,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true}.

Passo 5: Consulte o carrinho

Use Consultar carrinho:

Consultar carrinho

curl "https://app.nextagsai.com.br/api/contacts/123456789/cart" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta (aqui, resumida) traz o order_id, os totais em centavos e os itens, com o price de cada item em reais:

{
  "order_id": "PED-1001",
  "user_id": 123456789,
  "currency": "BRL",
  "total": 17980,
  "subtotal": 17980,
  "total_items": 2,
  "coupon_discount": 0,
  "coupon": "",
  "line_items": [
    {"id": 6001, "name": "Bolo de chocolate", "price": 89.9, "amount": 2}
  ]
}

Campo	Unidade	No exemplo
`total`, `subtotal`, `coupon_discount`	Centavos	`17980` = R$ 179,80
`line_items[].price`	Reais	`89.9` = R$ 89,90
`line_items[].amount`	Quantidade	`2`

Passo 6: Tire um produto ou esvazie o carrinho

Para tirar um produto, use Remover produto do carrinho:

Remover produto do carrinho

curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', {
  method: 'DELETE',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.delete(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Para tirar tudo, use Esvaziar carrinho:

Esvaziar carrinho

curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', {
  method: 'DELETE',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.delete(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

As duas respondem {"success": true}.

Passo 7: Consulte o pedido

Use Consultar pedido, com o ID do pedido. O ID é texto: mande do jeito que veio.

Consultar pedido

curl "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta tem o mesmo formato do carrinho, com os valores em centavos.

Passo 8: Mude o status e a entrega

Use Alterar pedido. O status aceita quatro valores, e os dados de entrega e a nota são opcionais:

Alterar pedido

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 7,
    "name": "Ana Souza",
    "phone": "5511988776655",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310-100",
    "address": "Avenida Paulista, 1000",
    "note": "Saiu para entrega."
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 7,
    name: 'Ana Souza',
    phone: '5511988776655',
    city: 'São Paulo',
    state: 'SP',
    zip_code: '01310-100',
    address: 'Avenida Paulista, 1000',
    note: 'Saiu para entrega.',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "status": 7,
        "name": "Ana Souza",
        "phone": "5511988776655",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310-100",
        "address": "Avenida Paulista, 1000",
        "note": "Saiu para entrega.",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'status' => 7,
        'name' => 'Ana Souza',
        'phone' => '5511988776655',
        'city' => 'São Paulo',
        'state' => 'SP',
        'zip_code' => '01310-100',
        'address' => 'Avenida Paulista, 1000',
        'note' => 'Saiu para entrega.',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

`status`	No contrato	Na tela
`6`	Em processamento	Aceito
`7`	Enviado	Entregando
`10`	Concluído	Concluído
`13`	Cancelado	Cancelado

Os dados de entrega são name, phone, email, country, state, city, zip_code, address, street_1 e street_2, e note guarda uma nota do pedido. A resposta é {"success": true}.

Passo 9: Marque o pedido como pago

Use Marcar pedido como pago. Esta chamada recebe formulário, com o valor pago em centavos em amount_received:

Marcar pedido como pago

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'amount_received=17980'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    amount_received: 17980,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "amount_received": 17980,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'amount_received' => 17980,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true}. O valor não pode ser menor que o total do pedido.

Pronto: como conferir

Consultar pedido mostra o pedido com os valores certos.
Na Caixa de Entrada, o painel do contato lista os Pedidos, com o valor, a data e a situação. Veja Carrinho e pedidos na conversa.

Se não funcionou

401 com "No valid API key provided."

A chave não chegou ou não vale. Veja Autenticação com a chave de API.

Alterar pedido: 400 com "Order status must be 6, 7, 10, or 13"

O status não é um dos quatro aceitos. Use 6, 7, 10 ou 13, como número.

Alterar pedido: 402

O pedido já está nesse status. Consulte o pedido antes e só mande o status quando ele mudar.

Marcar pedido como pago: 400

O amount_received é menor que o total do pedido. Confira se mandou em centavos: R$ 179,80 é 17980, não 179.80.

Marcar pedido como pago: 402

O pagamento não foi concluído. O contrato descreve assim: o contato recebe uma mensagem no Messenger com o motivo da falha do checkout. Consulte o pedido e a conversa do contato para entender o caso.

404 com "The order ID doesn't existe"

O ID do pedido não existe para esse contato. Confira o order_id e o ID do contato: os dois vão no caminho.

O preço do produto ficou cem vezes maior

O price do produto vai em reais, não em centavos. Para R$ 94,90, mande 94.9.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

Leia https://docs.nextags.com.br/guias/carrinho-e-pedidos.md.

Quero manter o E-commerce da NexTags em dia com [o seu sistema, por exemplo: o ERP da loja]: atualizar preço e estoque dos produtos quando mudarem, mudar o status do pedido quando [eventos de entrega] e marcar como pago quando [o pagamento for aprovado]. Escreva, em [linguagem], o código com a conversão certa de unidades (preço do produto em reais; totais e valor pago em centavos) e o tratamento dos erros 400, 402 e 404. A chave vem da variável de ambiente NEXTAGS_API_KEY.

Obrigado! Sua resposta ajuda a melhorar a central.