Devoluções

Lista e consulta devoluções (RMAs) e abre uma devolução em nome do cliente pela equipe da loja.

Uma devolução (RMA, "return merchandise authorization") é o pedido de um cliente para devolver um item comprado: por defeito, por arrependimento ou por erro de envio. Cada devolução passa por uma sequência de situações, do pedido do cliente até o reembolso, e a loja decide a resolução: reembolsar, trocar o produto ou dar crédito na loja.

Use estas operações para sincronizar devoluções com um sistema de logística reversa ou de atendimento. A criação pela v2 é uma ação da equipe (atendimento ou balcão), não do cliente: a devolução nasce ligada ao cliente do pedido.

GET/api/v2/returnsAdmin

Listar devoluções

Da mais nova para a mais antiga. Cada item já traz o número do pedido, o nome e o e-mail do cliente e o nome do produto.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Situação, pelo nome. Um valor desconhecido não gera erro: é tratado como requested.

customer_iduuid

Somente devoluções deste cliente.

vendor_iduuid

Somente devoluções de itens deste seller.

date_fromstring

Criadas a partir desta data (YYYY-MM-DD).

date_tostring

Criadas até o fim deste dia (YYYY-MM-DD, o dia entra inteiro).

fieldsstring

Chaves a devolver em cada item, separadas por vírgula.

GET/api/v2/returns/{id}Admin

Ler uma devolução

Devolve uma devolução com os mesmos campos da lista.

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

POST/api/v2/returnsAdmin

Abrir uma devolução pela equipe

Cria uma devolução na situação requested para um pedido já pago ou entregue. O cliente é o dono do pedido. O pedido precisa estar pago ou entregue/concluído: pedidos cancelados ou reembolsados não aceitam devolução.

Corpo da requisição

order_iduuidobrigatório

Pedido da devolução.

order_item_iduuid

Item do pedido. Sem ele, a devolução vale para o pedido todo.

reason_iduuid

Id de um motivo cadastrado na loja.

reasonstring

Motivo em texto livre.

resolutionstringpadrão: refund

refundreplacementstore_credit

O que a loja oferece: reembolso, troca ou crédito na loja.

quantityintegerpadrão: 1

Quantidade devolvida. Menor que 1 vira 1.

refund_amountinteger

Valor a reembolsar, em centavos.

restock_warehouse_iduuid

Depósito para onde o item volta ao estoque.

bypass_windowbooleanpadrão: false

Registra na devolução que o prazo de devolução foi dispensado, com o id de quem abriu.

Exemplo de requisição

Abrir uma devolução:

Resposta

200Devoluções retornadas

Campos da resposta

data[].iduuid

Id da devolução.

data[].order_iduuid

Pedido de origem.

data[].order_item_iduuid | null

Item devolvido. Ausente quando a devolução é do pedido todo.

data[].customer_iduuid

Cliente dono do pedido.

data[].vendor_iduuid | null

Seller do pedido.

data[].reason_iduuid | null

Motivo cadastrado, quando houve.

data[].reasonstring

Motivo em texto livre.

data[].statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Situação atual, em palavra (não em letra).

data[].admin_notesstring

Observações da equipe. Pode ser vazia.

data[].customer_notesstring

Observações do cliente. Pode ser vazia.

data[].resolutionstring

refundreplacementstore_credit

Resolução escolhida.

data[].refund_amountinteger

Valor reembolsado ou a reembolsar, em centavos.

data[].quantityinteger

Quantidade devolvida.

data[].created_atstring

Criação (RFC 3339, UTC).

data[].updated_atstring

Última alteração (RFC 3339, UTC).

data[].processed_atstring | null

Quando a equipe decidiu.

data[].processed_byuuid | null

Usuário que decidiu ou que abriu a devolução.

data[].order_numberstring

Número do pedido mostrado ao cliente.

data[].customer_namestring

Nome do cliente.

data[].customer_emailstring

E-mail do cliente.

data[].product_namestring

Nome do produto devolvido.

data[].reason_namestring

Nome do motivo cadastrado.

A criação responde 201 com { "data": { ... } }, o mesmo objeto sem os campos de apoio (order_number, customer_name, customer_email, product_name, reason_name) e com processed_by igual ao usuário que abriu.

Erros

Status	Quando	Corpo
400	`order_id` ausente	`{"error":{"code":"bad_request","message":"order_id is required"}}`
400	Corpo que não é JSON	`{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}`
404	Devolução inexistente (`GET` por id)	`{"error":{"code":"not_found","message":"return not found"}}`
409	Já existe devolução ativa para o pedido ou item	`{"error":{"code":"active_return_exists","message":"an active return already exists for this order/item"}}`
500	Falha inesperada	`{"error":{"code":"internal_error","message":"an unexpected error occurred","details":"..."}}`

Veja também

Devoluções

Lista e consulta devoluções (RMAs) e abre uma devolução em nome do cliente pela equipe da loja.

GET/api/v2/returnsAdmin

Listar devoluções

Da mais nova para a mais antiga. Cada item já traz o número do pedido, o nome e o e-mail do cliente e o nome do produto.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Situação, pelo nome. Um valor desconhecido não gera erro: é tratado como requested.

customer_iduuid

Somente devoluções deste cliente.

vendor_iduuid

Somente devoluções de itens deste seller.

date_fromstring

Criadas a partir desta data (YYYY-MM-DD).

date_tostring

Criadas até o fim deste dia (YYYY-MM-DD, o dia entra inteiro).

fieldsstring

Chaves a devolver em cada item, separadas por vírgula.

GET/api/v2/returns/{id}Admin

Ler uma devolução

Devolve uma devolução com os mesmos campos da lista.

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

POST/api/v2/returnsAdmin

Abrir uma devolução pela equipe

Corpo da requisição

order_iduuidobrigatório

Pedido da devolução.

order_item_iduuid

Item do pedido. Sem ele, a devolução vale para o pedido todo.

reason_iduuid

Id de um motivo cadastrado na loja.

reasonstring

Motivo em texto livre.

resolutionstringpadrão: refund

refundreplacementstore_credit

O que a loja oferece: reembolso, troca ou crédito na loja.

quantityintegerpadrão: 1

Quantidade devolvida. Menor que 1 vira 1.

refund_amountinteger

Valor a reembolsar, em centavos.

restock_warehouse_iduuid

Depósito para onde o item volta ao estoque.

bypass_windowbooleanpadrão: false

Registra na devolução que o prazo de devolução foi dispensado, com o id de quem abriu.

Exemplo de requisição

Abrir uma devolução:

Resposta

200Devoluções retornadas

Campos da resposta

data[].iduuid

Id da devolução.

data[].order_iduuid

Pedido de origem.

data[].order_item_iduuid | null

Item devolvido. Ausente quando a devolução é do pedido todo.

data[].customer_iduuid

Cliente dono do pedido.

data[].vendor_iduuid | null

Seller do pedido.

data[].reason_iduuid | null

Motivo cadastrado, quando houve.

data[].reasonstring

Motivo em texto livre.

data[].statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Situação atual, em palavra (não em letra).

data[].admin_notesstring

Observações da equipe. Pode ser vazia.

data[].customer_notesstring

Observações do cliente. Pode ser vazia.

data[].resolutionstring

refundreplacementstore_credit

Resolução escolhida.

data[].refund_amountinteger

Valor reembolsado ou a reembolsar, em centavos.

data[].quantityinteger

Quantidade devolvida.

data[].created_atstring

Criação (RFC 3339, UTC).

data[].updated_atstring

Última alteração (RFC 3339, UTC).

data[].processed_atstring | null

Quando a equipe decidiu.

data[].processed_byuuid | null

Usuário que decidiu ou que abriu a devolução.

data[].order_numberstring

Número do pedido mostrado ao cliente.

data[].customer_namestring

Nome do cliente.

data[].customer_emailstring

E-mail do cliente.

data[].product_namestring

Nome do produto devolvido.

data[].reason_namestring

Nome do motivo cadastrado.

Erros

Status	Quando	Corpo
400	`order_id` ausente	`{"error":{"code":"bad_request","message":"order_id is required"}}`
400	Corpo que não é JSON	`{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}`
404	Devolução inexistente (`GET` por id)	`{"error":{"code":"not_found","message":"return not found"}}`
409	Já existe devolução ativa para o pedido ou item	`{"error":{"code":"active_return_exists","message":"an active return already exists for this order/item"}}`
500	Falha inesperada	`{"error":{"code":"internal_error","message":"an unexpected error occurred","details":"..."}}`