Referência da API

Autenticação

Política de versão

• Aditiva, entra na v1 sem aviso: rota nova, campo novo na resposta, filtro novo, evento novo, valor novo em campo de texto livre.
• Quebra, só numa versão nova (/v2): tirar ou renomear rota, campo ou evento; mudar o tipo de um campo; tornar obrigatório o que era opcional; mudar o significado de um valor.
• A v1 continua suportada por pelo menos 12 meses depois que a v2 for publicada.
• Escreva o cliente para ignorar campo desconhecido: campo novo não é quebra.

Pedidos

• GET/api/v1/orders

  Lista pedidos

  read_orders
• GET/api/v1/orders/{id}

  Um pedido

  read_orders
• PATCH/api/v1/orders/{id}

  Muda o status de envio

  write_ordersIdempotency-Key aceita
• POST/api/v1/orders/{id}/fulfillments

  Marca o envio com rastreio

  write_ordersIdempotency-Key aceita
• POST/api/v1/orders/{id}/cancel

  Cancela o pedido (sem estorno)

  write_ordersIdempotency-Key aceita
• POST/api/v1/orders/{id}/refunds

  Estorna pelo gateway da cobrança

  write_refundsIdempotency-Key obrigatória

Produtos

• GET/api/v1/products

  Lista produtos (até 50 por página)

  read_products
• POST/api/v1/products

  Cria um produto com variantes

  write_productsIdempotency-Key aceita
• GET/api/v1/products/{id}

  Um produto

  read_products
• PATCH/api/v1/products/{id}

  Altera um produto (a ficha técnica inteira ou campo a campo)

  write_productsIdempotency-Key aceita
• DELETE/api/v1/products/{id}

  Apaga um produto (o pedido antigo fica)

  write_products
• POST/api/v1/products/{id}/variants

  Acrescenta uma variante

  write_productsIdempotency-Key aceita
• POST/api/v1/products/{id}/images

  Acrescenta uma imagem por URL ou por envio

  write_productsIdempotency-Key aceita
• POST/api/v1/products/{id}/images/uploads

  Pede um link para subir a foto direto, sem URL pública

  write_products
• DELETE/api/v1/products/{id}/images/{image_id}

  Tira uma imagem do produto

  write_products
• POST/api/v1/products/{id}/files/uploads

  Pede um link para subir o arquivo técnico direto, sem URL pública

  write_products
• POST/api/v1/products/{id}/files

  Acrescenta um arquivo técnico (manual, diagrama) por URL ou por envio

  write_productsIdempotency-Key aceita
• DELETE/api/v1/products/{id}/files/{file_id}

  Tira um arquivo técnico do produto

  write_products

Variantes e estoque

• PATCH/api/v1/variants/{id}

  Altera uma variante

  write_productsIdempotency-Key aceita
• POST/api/v1/variants/{id}/stock

  Ajusta o estoque

  write_productsIdempotency-Key obrigatória

Categorias

• GET/api/v1/categories/{id}/product-order

  A ordem manual dos produtos na categoria

  read_products
• PUT/api/v1/categories/{id}/product-order

  Grava a ordem manual dos produtos na categoria

  write_productsIdempotency-Key aceita
• GET/api/v1/categories

  Lista categorias na ordem da loja

  read_products
• POST/api/v1/categories

  Cria uma categoria

  write_productsIdempotency-Key aceita
• GET/api/v1/categories/{id}

  Uma categoria

  read_products
• PATCH/api/v1/categories/{id}

  Altera uma categoria

  write_productsIdempotency-Key aceita

Cupons

• GET/api/v1/coupons

  Lista cupons

  read_coupons
• POST/api/v1/coupons

  Cria um cupom

  write_couponsIdempotency-Key aceita
• GET/api/v1/coupons/{id}

  Um cupom

  read_coupons
• PATCH/api/v1/coupons/{id}

  Altera um cupom

  write_couponsIdempotency-Key aceita

Clientes

• GET/api/v1/customers

  Lista clientes

  read_customers
• POST/api/v1/customers

  Cria um cliente

  write_customersIdempotency-Key aceita
• GET/api/v1/customers/{id}

  Um cliente

  read_customers
• PATCH/api/v1/customers/{id}

  Altera um cliente

  write_customersIdempotency-Key aceita

Webhooks

• GET/api/v1/webhooks

  Lista as assinaturas do app

  o próprio app
• POST/api/v1/webhooks

  Cria uma assinatura (o segredo vem uma vez)

  o próprio app
• GET/api/v1/webhooks/{id}

  Uma assinatura

  o próprio app
• PUT/api/v1/webhooks/{id}

  Troca URL e eventos

  o próprio app
• PATCH/api/v1/webhooks/{id}

  Altera URL ou eventos

  o próprio app
• DELETE/api/v1/webhooks/{id}

  Remove uma assinatura

  o próprio app
• POST/api/v1/webhooks/{id}/test

  Manda um webhook.test

  o próprio app
• POST/api/v1/webhooks/{id}/deliveries/{delivery_id}/redeliver

  Reenvia uma entrega

  o próprio app

Eventos de webhook

Standard Webhooks: cabeçalhos webhook-id, webhook-timestamp e webhook-signature (HMAC-SHA256). A ordem não é garantida e pode haver duplicata: descarte pelo webhook-id.

• order.createdpedido criado
• order.paidpagamento confirmado
• order.shippedpedido enviado
• order.deliveredpedido entregue
• order.cancelledpedido cancelado
• cart.abandonedcarrinho abandonado
• customer.createdcliente criado
• customer.updatedcliente alterado (`changed_fields` no envelope)
• product.createdproduto criado
• product.updatedproduto alterado
• product.deletedproduto excluído
• variant.stock_changedestoque da variante mudou
• category.createdcategoria criada
• category.updatedcategoria alterada
• category.deletedcategoria excluída
• app.uninstalledo lojista desinstalou o app
• webhook.testteste pedido pela API
• customer.data_requestLGPD: o titular pediu os dados à loja (obrigatório)
• customer.deletedLGPD: cliente excluído ou anonimizado (obrigatório)
• store.redactLGPD: 30 dias depois da desinstalação, apagar tudo da loja (obrigatório)

Mudanças