Produtos

O catálogo da sua loja na Pitra. Campos internos nunca são expostos.

O objeto produto

{
  "object": "product",
  "id": "6f1b1c9e-6a0a-4a2f-9d0c-2b1c4a5e7f10",
  "codigo": "PRD-0007",
  "nome": "Curso de Node",
  "slug": "curso-de-node",
  "descricao": "12 módulos em vídeo.",
  "imagem": "https://cdn.exemplo.com/curso.png",
  "preco": 197.9,
  "ativo": true,
  "checkout_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "link_acesso": "https://area.exemplo.com/curso",
  "garantia": "7 dias",
  "order_bump_enabled": false,
  "order_bump_product_id": null,
  "order_bump_title": null,
  "order_bump_description": null,
  "delivery_email_subject": "Seu acesso chegou",
  "delivery_email_body": "Olá! Aqui está o seu acesso.",
  "created_at": "2026-07-30T12:00:00.000Z",
  "updated_at": "2026-07-30T12:00:00.000Z"
}

updated_at hoje espelha created_at: use-o apenas como referência de criação, não como marca de última alteração.

Listar produtos

GET/api/public/v1/productsscope products:read

Query	Tipo	Descrição
`limit`	integer	1–100, padrão 20.
`starting_after`	string	Cursor da página anterior.
`ativo`	boolean	true ou false.
`codigo`	string	Código exato do produto.
`slug`	string	Slug exato do produto.

Qualquer outro parâmetro devolve 400 invalid_request.

curl "https://pitra.com.br/api/public/v1/products?ativo=true&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Resposta 200:

{ "object": "list", "data": [ /* produtos */ ], "has_more": false, "next_cursor": null }

Erros: 400 invalid_request · 401 · 403 insufficient_scope · 404 not_found · 429 rate_limited · 500 internal_error

Criar produto

POST/api/public/v1/productsscope products:write

Headers: Content-Type: application/json e, opcionalmente, Idempotency-Key.

Campo	Tipo	Obrigatório	Regras
`nome`	string	Sim	1–120 caracteres.
`preco`	number	Sim	0 a 1.000.000.
`slug`	string	Não	1–60 caracteres. Gerado a partir do nome se omitido.
`descricao`	string \| null	Não	Até 4000 caracteres.
`imagem`	string \| null	Não	Até 1000 caracteres.
`ativo`	boolean	Não	Padrão do sistema quando omitido.
`link_acesso`	string \| null	Não	Até 1000 caracteres.
`garantia`	string \| null	Não	Até 500 caracteres.
`checkout_id`	uuid \| null	Não	Precisa pertencer à sua loja.
`order_bump_enabled`	boolean	Não	—
`order_bump_product_id`	uuid \| null	Não	Produto da própria loja.
`order_bump_title`	string \| null	Não	Até 120 caracteres.
`order_bump_description`	string \| null	Não	Até 500 caracteres.
`delivery_email_subject`	string \| null	Não	Até 160 caracteres.
`delivery_email_body`	string \| null	Não	Até 3000 caracteres.

Campos fora desta lista são rejeitados com 400 invalid_request. codigo é gerado pela Pitra e não pode ser enviado.

curl -X POST https://pitra.com.br/api/public/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: produto-curso-node" \
  -d '{"nome":"Curso de Node","preco":197.9,"ativo":true}'

Resposta 201: o objeto produto.

Erros: 400 invalid_request · 401 · 403 insufficient_scope · 404 not_found · 429 rate_limited · 500 internal_error · 409 idempotency_conflict

Consultar produto

GET/api/public/v1/products/{id}scope products:read

Parâmetro de rota: id (uuid).

curl https://pitra.com.br/api/public/v1/products/6f1b1c9e-6a0a-4a2f-9d0c-2b1c4a5e7f10 \
  -H "Authorization: Bearer sk_live_..."

Resposta 200: o objeto produto. Produtos de outra loja devolvem 404.

Atualizar produto

PATCH/api/public/v1/products/{id}scope products:write

Aceita os mesmos campos editáveis da criação, todos opcionais. Envie somente o que quer mudar.

curl -X PATCH https://pitra.com.br/api/public/v1/products/6f1b1c9e-6a0a-4a2f-9d0c-2b1c4a5e7f10 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"preco":149.9}'

Resposta 200: o produto atualizado.

Arquivar produto

POST/api/public/v1/products/{id}/archivescope products:write

Arquivar significa tornar o produto inativo (ativo: false). O produto continua existindo e pode ser reativado com PATCH { "ativo": true }.

curl -X POST https://pitra.com.br/api/public/v1/products/6f1b1c9e-6a0a-4a2f-9d0c-2b1c4a5e7f10/archive \
  -H "Authorization: Bearer sk_live_..."

Resposta 200: o produto com ativo: false.