Criar Pedido

Cria um novo pedido associado a produtos.

POST /sellers/orders/

Headers

Header	Valor	Obrigatório
`Content-Type`	`application/json`	Sim
`Authorization`	`Bearer mk_<env>_<token>`	Sim

Campos obrigatórios

Para criar um pedido com produto (items preenchido), envie obrigatoriamente:

Campo	Tipo	Descrição
`customer.name`	`string`	Nome completo do cliente
`customer.tax_id`	`string`	CPF (11 dígitos) ou CNPJ (14 dígitos)
`customer.email`	`string`	Email do cliente
`customer.address`	`object`	Endereço de entrega estruturado (obrigatório quando há produto físico no pedido)
`items[].product_uuid`	`string`	UUID do produto
`items[].quantity`	`integer`	Quantidade do produto

Para criar uma cobrança avulsa sem produto (items omitido ou vazio):

Campo	Tipo	Descrição
`customer.name`, `customer.tax_id`, `customer.email`	—	Mesmos campos do cliente
`payment.gross_amount`	`integer`	Obrigatório neste cenário. Valor bruto da cobrança em centavos.

Valores monetários

Todo campo que termina em _amount é um inteiro, em centavos. Exemplo: 15000 = R$ 150,00.

Parâmetros do Body

Parâmetro	Tipo	Obrigatório	Descrição
`customer`	`object`	Sim	Dados do cliente (ver abaixo)
`items`	`array`	Não	Lista de itens do pedido. Omita ou envie `[]` para criar uma cobrança avulsa sem produto (nesse caso `payment.gross_amount` é obrigatório).
`payment`	`object`	Sim	Dados do pagamento
`postback_url`	`string \| null`	Não	URL de webhook deste pedido. Recebe os eventos `order.` e `order_item.` do pedido. Ver seção Webhook por pedido.

Objeto `customer`

Campo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome completo do cliente
`tax_id`	`string`	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos). Pontuação é ignorada.
`tax_id_type`	`string`	Não	`"CPF"` ou `"CNPJ"`. Se omitido, é deduzido pelo número de dígitos de `tax_id`.
`email`	`string`	Sim	Email do cliente
`phone`	`string`	Não	Telefone do cliente
`address`	`object`	Sim*	Endereço estruturado (ver abaixo)

*Obrigatório para produtos físicos.

Objeto `customer.address`

Campo	Tipo	Obrigatório	Descrição
`street`	`string`	Sim	Logradouro (rua/avenida)
`number`	`string`	Não	Número. Use `"S/N"` quando não houver
`complement`	`string \| null`	Não	Complemento (apto, bloco, etc.)
`neighborhood`	`string`	Sim	Bairro
`city`	`string`	Sim	Cidade
`state`	`string`	Sim	UF em 2 letras maiúsculas (ex.: `SP`)
`postal_code`	`string`	Sim	CEP no formato `12345-678` ou 8 dígitos
`country`	`string`	Não	Código ISO 3166-1 alpha-2. Default: `"BR"`

Endereço no retorno

Pedidos criados via API recebem um endereço gravado em formato canônico ("Rua Exemplo, 123 — Centro, São Paulo - SP, 01000-000, BR") e o retorno dos endpoints de detalhe e listagem expõe o endereço como string única. Uma representação estruturada no output está prevista para uma versão futura.

Objeto `items[]`

Campo	Tipo	Obrigatório	Descrição
`product_uuid`	`string`	Sim	UUID do produto
`quantity`	`integer`	Sim	Quantidade (mínimo 1)

Objeto `payment`

Campo	Tipo	Obrigatório	Descrição
`gross_amount`	`integer`	Condicional	Valor bruto da cobrança em centavos (ex: `15000` = R$ 150,00). Se omitido e `items` preenchido, é calculado automaticamente a partir do total dos itens. Obrigatório quando `items` é vazio ou omitido.
`shipping_amount`	`integer`	Não	Frete em centavos (default `0`)
`discount_amount`	`integer`	Não	Desconto em centavos (default `0`)
`expiration_date`	`string`	Não	Data de expiração
`debtor_name`	`string`	Não	Nome do pagador
`debtor_document`	`string`	Não	Documento do pagador

Webhook por pedido (`postback_url`)

Informe postback_url na criação para receber as atualizações daquele pedido específico em uma URL própria, sem precisar configurar um webhook global.

Eventos entregues: order.created, order.paid, order.expired, order.cancelled, order.refunded, order.chargeback, order_item.shipped e order_item.delivered — sempre escopados a este pedido.
Soma, não substitui: as entregas vão para o postback_url além dos seus webhooks globais (POST /config/webhooks/) já cadastrados. Os webhooks globais continuam recebendo os eventos normalmente.
Formato do payload: idêntico ao dos webhooks globais (mesmo envelope event / occurred_at / data). Ver Eventos de Webhook.

Sem assinatura HMAC

Diferente dos webhooks globais, as entregas para postback_url não incluem o header X-Webhook-Signature (não há secret associado a um postback por pedido). Para garantir a autenticidade:

use sempre HTTPS;
inclua um token secreto na própria URL (ex.: https://seu-site.com/webhooks/pedidos?token=um-token-dificil-de-adivinhar) e valide-o ao receber a chamada.

Exemplo de Requisição

cURL
Python
Node.js

curl -X POST https://api.somosmarcha.com/api/v1/sellers/orders/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "customer": {
      "name": "Maria da Silva",
      "tax_id": "12345678901",
      "email": "[email protected]",
      "phone": "11999998888",
      "address": {
        "street": "Rua Exemplo",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01000-000"
      }
    },
    "items": [
      {
        "product_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "quantity": 1
      }
    ],
    "payment": {
      "gross_amount": 15000
    },
    "postback_url": "https://seu-site.com/webhooks/pedidos?token=um-token-dificil-de-adivinhar"
  }'

import requests

BASE_URL = "https://api.somosmarcha.com/api/v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>",
}

payload = {
    "customer": {
        "name": "Maria da Silva",
        "tax_id": "12345678901",
        "email": "[email protected]",
        "phone": "11999998888",
        "address": {
        "street": "Rua Exemplo",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01000-000"
      },
    },
    "items": [
        {
            "product_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "quantity": 1,
        }
    ],
    "payment": {
        "gross_amount": 15000,
    },
    "postback_url": "https://seu-site.com/webhooks/pedidos?token=um-token-dificil-de-adivinhar",
}

response = requests.post(f"{BASE_URL}/sellers/orders/", json=payload, headers=headers)
print(response.json())

const BASE_URL = "https://api.somosmarcha.com/api/v1";

const response = await fetch(`${BASE_URL}/sellers/orders/`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
  },
  body: JSON.stringify({
    customer: {
      name: "Maria da Silva",
      tax_id: "12345678901",
      email: "[email protected]",
      phone: "11999998888",
      address: {
        street: "Rua Exemplo",
        number: "123",
        neighborhood: "Centro",
        city: "São Paulo",
        state: "SP",
        postal_code: "01000-000",
      },
    },
    items: [
      {
        product_uuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        quantity: 1,
      },
    ],
    payment: { gross_amount: 15000 },
    postback_url: "https://seu-site.com/webhooks/pedidos?token=um-token-dificil-de-adivinhar",
  }),
});

const data = await response.json();
console.log(data);

Resposta de Sucesso

Status: 201 Created

{
  "message": "Pedido criado com sucesso!",
  "data": {
    "uuid": "f9e8d7c6-b5a4-4321-9876-123456789abc",
    "status": "PENDING",
    "gross_amount": 15000,
    "postback_url": "https://seu-site.com/webhooks/pedidos?token=um-token-dificil-de-adivinhar",
    "items": [
      {
        "product_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Plano Premium",
        "quantity": 1,
        "line_total_amount": 15000
      }
    ],
    "customer": {
      "uuid": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "name": "Maria da Silva"
    },
    "pix": {
      "qr_code_id": "qr_abc123",
      "copy_and_paste": "00020126580014br.gov.bcb.pix...",
      "qr_code_image_base64": "iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAA...",
      "transaction_uuid": null
    }
  }
}

Campo pix.qr_code_image_base64

Base64 puro de um PNG do QR Code do PIX, sem o prefixo data:image/png;base64,. O QR Code é gerado pelo backend a partir do copy_and_paste, garantindo o mesmo formato independente do adquirente.

Para renderizar no front, monte a data URI:

<img src={`data:image/png;base64,${pix.qr_code_image_base64}`} />

Será null apenas quando copy_and_paste não estiver disponível.

Respostas de Erro

Status: 400 Bad Request — Erro de validação

{
  "message": "Erro de validação",
  "data": {
    "customer.email": ["Insira um endereço de email válido."],
    "customer.address": ["Endereço obrigatório para produtos físicos."],
    "items": ["Este campo é obrigatório."]
  }
}

Headers​

Campos obrigatórios​

Parâmetros do Body​

Objeto customer​

Objeto customer.address​

Objeto items[]​

Objeto payment​

Webhook por pedido (postback_url)​

Exemplo de Requisição​

Resposta de Sucesso​

Respostas de Erro​