API atual/Referência completa/Devoluções e contestações

Contestações

Abre e acompanha contestações de pedidos que não chegaram, vieram errados ou danificados.

A contestação (também chamada de disputa) é o canal para quando o pedido não chegou, chegou diferente ou danificado e o cliente quer uma solução do seller, com prazos e histórico. O cliente abre, o seller responde com uma proposta (reembolso total, reembolso parcial, reenvio ou recusa), e o cliente aceita ou leva o caso à loja. Para quem quer apenas devolver um produto, use a devolução.

Aguardando o seller→Aguardando o cliente→Resolvida

`status`	Significado
`awaiting_seller`	Aberta. O seller tem 48 horas para responder.
`awaiting_buyer`	O seller fez uma proposta; o cliente decide (72 horas).
`escalated`	O caso foi levado à loja (pelo cliente ou por prazo vencido), que decide.
`resolved_refund_full`	Resolvida com reembolso total.
`resolved_refund_partial`	Resolvida com reembolso parcial.
`resolved_reship`	Resolvida com reenvio.
`resolved_rejected`	Resolvida sem reembolso (contestação recusada).
`canceled`	Cancelada.

Regras de abertura: o pedido precisa ser do cliente e ter um seller; só pode haver uma contestação aberta por pedido; e não pode haver devolução ativa (requested, approved ou item_received) para o mesmo pedido.

POST/api/v1/storefront/account/orders/{orderId}/disputesCliente

Abre uma contestação de um pedido

Parâmetros de caminho

orderIduuidobrigatório

Id do pedido do cliente.

Corpo da requisição

reasonstringobrigatório

not_receiveddifferent_from_descriptiondamagedwrong_itemother

Motivo.

descriptionstring

Explicação do cliente, mostrada ao seller.

order_item_iduuid

Linha do pedido, se a contestação é só de um item.

media_idsarray

Ids de arquivos de evidência (fotos) já enviados à loja. Cada um vira um evento evidence_added.

bash

curl -X POST "$BASE_URL/api/v1/storefront/account/orders/$ORDER_ID/disputes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "not_received",
  "description": "O pedido não chegou no prazo."
}'

201Contestação aberta

json

{
  "id": "5102d871-4ecc-4a15-9e06-0df2a6a8d91a",
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "reason": "not_received",
  "status": "awaiting_seller",
  "amount_cents": 5266,
  "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
  "created_at": "2026-10-11T20:57:01.26736Z",
  "events": [
    {
      "actor_type": "buyer",
      "action": "opened",
      "payload": { "description": "Pedido não chegou no prazo.", "media_ids": null },
      "created_at": "2026-10-11T20:57:01.272476Z"
    }
  ]
}

Campos da resposta

iduuid

Id da contestação.

order_iduuid

Pedido contestado. order_item_id aponta a linha, quando informada.

vendor_iduuid

Seller responsável pelo pedido.

reasonstring

not_receiveddifferent_from_descriptiondamagedwrong_itemother

Motivo escolhido.

statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado atual (veja a tabela acima).

amount_centsinteger

Valor do pedido contestado, em centavos.

refund_centsinteger

Valor reembolsado, em centavos, quando a contestação termina em reembolso.

seller_deadline_atstring

Prazo do seller para responder (48 horas depois de aberta). buyer_deadline_at é o prazo do cliente para reagir a uma proposta (72 horas).

resolution_notestring

Texto final de quem resolveu.

thread_iduuid

Conversa associada no centro de mensagens, quando existe.

eventsarray

Histórico: actor_type (buyer, seller, admin ou system), action (opened, evidence_added, responded, escalated...), payload (dados da ação, por exemplo a proposal do seller) e created_at.

Status	Quando	Corpo
400	Corpo que não é JSON, `reason` fora da lista (`invalid reason`), pedido que não é do cliente (`order not found`), pedido sem seller, devolução ativa, ou já existe contestação para o pedido	`{"error":"failed to open dispute","detail":"invalid reason"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`

GET/api/v1/storefront/account/disputesCliente

Lista as contestações do cliente

bash

curl "$BASE_URL/api/v1/storefront/account/disputes" \
  -H "Authorization: Bearer $TOKEN"

200Contestações

json

{
  "items": [
    {
      "id": "5102d871-4ecc-4a15-9e06-0df2a6a8d91a",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "reason": "not_received",
      "status": "awaiting_seller",
      "amount_cents": 5266,
      "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
      "created_at": "2026-10-11T20:57:01.26736Z",
      "events": [
        {
          "actor_type": "buyer",
          "action": "opened",
          "payload": { "description": "Pedido não chegou no prazo.", "media_ids": null },
          "created_at": "2026-10-11T20:57:01.272476Z"
        }
      ]
    }
  ]
}

As contestações vêm da mais nova para a mais antiga, até 500, sem paginação. Cada item tem os campos da resposta de abertura.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha ao listar	`{"error":"failed to list disputes","detail":"..."}`

GET/api/v1/storefront/account/disputes/{id}Cliente

Detalhe de uma contestação

Parâmetros de caminho

iduuidobrigatório

Id da contestação.

bash

curl "$BASE_URL/api/v1/storefront/account/disputes/$DISPUTE_ID" \
  -H "Authorization: Bearer $TOKEN"

Devolve a contestação com a lista completa de events, em ordem cronológica. Para saber qual foi a proposta do seller, procure o último evento responded e leia payload.proposal (refund_full, refund_partial, reship ou reject).

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Inexistente, de outro cliente, ou `id` que não é UUID	`{"error":"dispute not found"}`

POST/api/v1/storefront/account/disputes/{id}/accept-proposalCliente

Aceita a proposta do seller

Fecha a contestação do jeito que o seller propôs: o status passa a resolved_refund_full, resolved_refund_partial, resolved_reship ou resolved_rejected, conforme a proposta. Só funciona depois que o seller respondeu.

Parâmetros de caminho

iduuidobrigatório

Id da contestação.

bash

curl -X POST "$BASE_URL/api/v1/storefront/account/disputes/$DISPUTE_ID/accept-proposal" \
  -H "Authorization: Bearer $TOKEN"

A resposta 200 é a contestação atualizada, no mesmo formato da abertura.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
400	Contestação que não é sua (`dispute not found`), seller ainda sem proposta, ou estado que não permite resolver	`{"error":"failed to accept proposal","detail":"no seller proposal to accept"}`

POST/api/v1/storefront/account/disputes/{id}/escalateCliente

Leva a contestação à loja

Quando o cliente não aceita a proposta (ou o seller não responde), ele pode pedir que a loja decida. O status passa a escalated e a loja resolve. Só é possível enquanto a contestação ainda está em andamento.

Parâmetros de caminho

iduuidobrigatório

Id da contestação.

bash

curl -X POST "$BASE_URL/api/v1/storefront/account/disputes/$DISPUTE_ID/escalate" \
  -H "Authorization: Bearer $TOKEN"

A resposta 200 é a contestação atualizada, com um novo evento escalated.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
400	Contestação que não é sua, ou já resolvida ou já escalada	`{"error":"failed to escalate","detail":"cannot escalate in status escalated"}`

Veja também

Contestações

Abre e acompanha contestações de pedidos que não chegaram, vieram errados ou danificados.

Aguardando o seller→Aguardando o cliente→Resolvida

`status`	Significado
`awaiting_seller`	Aberta. O seller tem 48 horas para responder.
`awaiting_buyer`	O seller fez uma proposta; o cliente decide (72 horas).
`escalated`	O caso foi levado à loja (pelo cliente ou por prazo vencido), que decide.
`resolved_refund_full`	Resolvida com reembolso total.
`resolved_refund_partial`	Resolvida com reembolso parcial.
`resolved_reship`	Resolvida com reenvio.
`resolved_rejected`	Resolvida sem reembolso (contestação recusada).
`canceled`	Cancelada.

POST/api/v1/storefront/account/orders/{orderId}/disputesCliente

Abre uma contestação de um pedido

Parâmetros de caminho

orderIduuidobrigatório

Id do pedido do cliente.

Corpo da requisição

reasonstringobrigatório

not_receiveddifferent_from_descriptiondamagedwrong_itemother

Motivo.

descriptionstring

Explicação do cliente, mostrada ao seller.

order_item_iduuid

Linha do pedido, se a contestação é só de um item.

media_idsarray

Ids de arquivos de evidência (fotos) já enviados à loja. Cada um vira um evento evidence_added.

bash

curl -X POST "$BASE_URL/api/v1/storefront/account/orders/$ORDER_ID/disputes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "not_received",
  "description": "O pedido não chegou no prazo."
}'

201Contestação aberta

json

{
  "id": "5102d871-4ecc-4a15-9e06-0df2a6a8d91a",
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "reason": "not_received",
  "status": "awaiting_seller",
  "amount_cents": 5266,
  "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
  "created_at": "2026-10-11T20:57:01.26736Z",
  "events": [
    {
      "actor_type": "buyer",
      "action": "opened",
      "payload": { "description": "Pedido não chegou no prazo.", "media_ids": null },
      "created_at": "2026-10-11T20:57:01.272476Z"
    }
  ]
}

Campos da resposta

iduuid

Id da contestação.

order_iduuid

Pedido contestado. order_item_id aponta a linha, quando informada.

vendor_iduuid

Seller responsável pelo pedido.

reasonstring

not_receiveddifferent_from_descriptiondamagedwrong_itemother

Motivo escolhido.

statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado atual (veja a tabela acima).

amount_centsinteger

Valor do pedido contestado, em centavos.

refund_centsinteger

Valor reembolsado, em centavos, quando a contestação termina em reembolso.

seller_deadline_atstring

Prazo do seller para responder (48 horas depois de aberta). buyer_deadline_at é o prazo do cliente para reagir a uma proposta (72 horas).

resolution_notestring

Texto final de quem resolveu.

thread_iduuid

Conversa associada no centro de mensagens, quando existe.

eventsarray

Status	Quando	Corpo
400	Corpo que não é JSON, `reason` fora da lista (`invalid reason`), pedido que não é do cliente (`order not found`), pedido sem seller, devolução ativa, ou já existe contestação para o pedido	`{"error":"failed to open dispute","detail":"invalid reason"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`

GET/api/v1/storefront/account/disputesCliente

Lista as contestações do cliente

bash

curl "$BASE_URL/api/v1/storefront/account/disputes" \
  -H "Authorization: Bearer $TOKEN"

200Contestações

json

{
  "items": [
    {
      "id": "5102d871-4ecc-4a15-9e06-0df2a6a8d91a",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "reason": "not_received",
      "status": "awaiting_seller",
      "amount_cents": 5266,
      "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
      "created_at": "2026-10-11T20:57:01.26736Z",
      "events": [
        {
          "actor_type": "buyer",
          "action": "opened",
          "payload": { "description": "Pedido não chegou no prazo.", "media_ids": null },
          "created_at": "2026-10-11T20:57:01.272476Z"
        }
      ]
    }
  ]
}

As contestações vêm da mais nova para a mais antiga, até 500, sem paginação. Cada item tem os campos da resposta de abertura.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha ao listar	`{"error":"failed to list disputes","detail":"..."}`

GET/api/v1/storefront/account/disputes/{id}Cliente

Detalhe de uma contestação

Parâmetros de caminho

iduuidobrigatório

Id da contestação.

bash

curl "$BASE_URL/api/v1/storefront/account/disputes/$DISPUTE_ID" \
  -H "Authorization: Bearer $TOKEN"

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Inexistente, de outro cliente, ou `id` que não é UUID	`{"error":"dispute not found"}`

POST/api/v1/storefront/account/disputes/{id}/accept-proposalCliente

Aceita a proposta do seller

Parâmetros de caminho

iduuidobrigatório

Id da contestação.

bash

curl -X POST "$BASE_URL/api/v1/storefront/account/disputes/$DISPUTE_ID/accept-proposal" \
  -H "Authorization: Bearer $TOKEN"

A resposta 200 é a contestação atualizada, no mesmo formato da abertura.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
400	Contestação que não é sua (`dispute not found`), seller ainda sem proposta, ou estado que não permite resolver	`{"error":"failed to accept proposal","detail":"no seller proposal to accept"}`

POST/api/v1/storefront/account/disputes/{id}/escalateCliente

Leva a contestação à loja

Parâmetros de caminho

iduuidobrigatório

Id da contestação.

bash

curl -X POST "$BASE_URL/api/v1/storefront/account/disputes/$DISPUTE_ID/escalate" \
  -H "Authorization: Bearer $TOKEN"

A resposta 200 é a contestação atualizada, com um novo evento escalated.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
400	Contestação que não é sua, ou já resolvida ou já escalada	`{"error":"failed to escalate","detail":"cannot escalate in status escalated"}`