API atual/Referência completa/Pagamentos

Disputas

Mediação entre cliente e seller: listar as disputas e decidir com reembolso, reenvio ou recusa.

Quando o cliente diz que não recebeu o pedido, que veio errado ou danificado, ele abre uma disputa na loja. O seller tem 48 horas para responder com uma proposta; o cliente tem 72 horas para aceitar. Se não houver acordo, ou o prazo vencer, a disputa vai para a mediação do operador (escalated) e é aqui que o administrador decide.

Estado	Significado
`opened`	Aberta pelo cliente.
`awaiting_seller`	Aguardando a resposta do seller.
`awaiting_buyer`	O seller propôs algo; aguardando o cliente.
`escalated`	Em mediação do operador.
`resolved_refund_full`	Resolvida com reembolso total.
`resolved_refund_partial`	Resolvida com reembolso parcial.
`resolved_reship`	Resolvida com reenvio.
`resolved_rejected`	Recusada.
`canceled`	Cancelada.

Listar disputas

Lista as disputas, da mais recente à mais antiga, até 500. Não há paginação. A fila de trabalho do operador é o estado escalated.

GET/api/v1/admin/disputesAdmin

Lista as disputas entre clientes e sellers

Autenticação: Authorization: Bearer <token> de um administrador. Não exige privilégio específico além de ser administrador.

Parâmetros de consulta

statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado exato, em palavra.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/disputes?status=escalated" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Disputas devolvidas

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": "escalated",
      "amount_cents": 5266,
      "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
      "created_at": "2026-10-11T20:57:01.26736Z",
      "events": []
    }
  ]
}

Campos da resposta

itemsarray

Disputas.

items[].iduuid

Identificador da disputa.

items[].order_iduuid

Pedido contestado.

items[].order_item_iduuid

Item contestado, quando a disputa é sobre um item. Omitido nas demais.

items[].customer_iduuid

Cliente que abriu.

items[].vendor_iduuid

Seller do pedido.

items[].reasonstring

not_receiveddifferent_from_descriptiondamagedwrong_itemother

not_received, different_from_description, damaged, wrong_item ou other.

items[].statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado da disputa (veja a tabela na página).

items[].amount_centsinteger

Valor em disputa, em centavos. É o teto do reembolso.

items[].refund_centsinteger

Reembolso decidido, em centavos. Só depois de resolvida.

items[].thread_iduuid

Conversa entre as partes ligada à disputa, se houver.

items[].seller_deadline_atstring

Prazo de resposta do seller (48 horas após abrir).

items[].buyer_deadline_atstring

Prazo de resposta do cliente (72 horas), quando aplicável.

items[].resolution_notestring

Nota de quem resolveu.

items[].created_atstring

Abertura, RFC 3339 em UTC.

items[].eventsarray

Linha do tempo (actor_type, action, payload, created_at). Na listagem vem sempre vazia; só a resposta de resolve a traz preenchida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
500	Falha na consulta	`{"error":"failed to list disputes","detail":"..."}`

Resolver uma disputa

O operador decide a disputa: reembolso total, reembolso parcial, reenvio do produto ou recusa. Se há reembolso, a plataforma também cobra o valor do seller (ajustando a divisão do pagamento, ou lançando uma dívida se o repasse já saiu) e tenta devolver o dinheiro ao cliente pelo gateway; se isso não for possível, registra que o estorno precisa ser feito manualmente.

POST/api/v1/admin/disputes/{id}/resolveAdmin

Decide uma disputa

Autenticação: Authorization: Bearer <token> de um administrador. Não exige privilégio específico além de ser administrador.

Parâmetros de caminho

iduuidobrigatório

Identificador da disputa.

Corpo da requisição

resolutionstringobrigatório

resolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejected

Decisão.

refund_centsintegerpadrão: 0

Valor a reembolsar, em centavos, de 0 até amount_cents. Em resolved_refund_full é ignorado e vale amount_cents.

notestring

Justificativa, guardada em resolution_note.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/disputes/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/resolve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "resolved_refund_partial",
    "refund_cents": 2000,
    "note": "Produto chegou com avaria parcial"
  }'

Resposta

200Disputa resolvida

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": "resolved_refund_partial",
  "amount_cents": 5266,
  "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
  "created_at": "2026-10-11T20:57:01.26736Z",
  "events": [
    {
      "actor_type": "admin",
      "action": "resolved",
      "payload": {
        "resolution": "resolved_refund_partial",
        "refund_cents": 2000,
        "note": "Produto chegou com avaria parcial"
      },
      "created_at": "2026-10-11T21:30:00Z"
    }
  ],
  "refund_cents": 2000,
  "resolution_note": "Produto chegou com avaria parcial"
}

Campos da resposta

iduuid

Identificador da disputa.

order_iduuid

Pedido contestado.

order_item_iduuid

Item contestado, quando a disputa é sobre um item. Omitido nas demais.

customer_iduuid

Cliente que abriu.

vendor_iduuid

Seller do pedido.

reasonstring

not_receiveddifferent_from_descriptiondamagedwrong_itemother

not_received, different_from_description, damaged, wrong_item ou other.

statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado da disputa (veja a tabela na página).

amount_centsinteger

Valor em disputa, em centavos. É o teto do reembolso.

refund_centsinteger

Reembolso decidido, em centavos. Só depois de resolvida.

thread_iduuid

Conversa entre as partes ligada à disputa, se houver.

seller_deadline_atstring

Prazo de resposta do seller (48 horas após abrir).

buyer_deadline_atstring

Prazo de resposta do cliente (72 horas), quando aplicável.

resolution_notestring

Nota de quem resolveu.

created_atstring

Abertura, RFC 3339 em UTC.

eventsarray

Linha do tempo (actor_type, action, payload, created_at). Na listagem vem sempre vazia; só a resposta de resolve a traz preenchida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
400	Corpo inválido; `resolution` fora da lista; reembolso acima do valor; transição não permitida a partir do estado atual; disputa inexistente	`{"error":"failed to resolve dispute","detail":"refund exceeds order amount"}`

Veja também

API atual/Referência completa/Pagamentos

Disputas

Mediação entre cliente e seller: listar as disputas e decidir com reembolso, reenvio ou recusa.

Estado	Significado
`opened`	Aberta pelo cliente.
`awaiting_seller`	Aguardando a resposta do seller.
`awaiting_buyer`	O seller propôs algo; aguardando o cliente.
`escalated`	Em mediação do operador.
`resolved_refund_full`	Resolvida com reembolso total.
`resolved_refund_partial`	Resolvida com reembolso parcial.
`resolved_reship`	Resolvida com reenvio.
`resolved_rejected`	Recusada.
`canceled`	Cancelada.

Listar disputas

Lista as disputas, da mais recente à mais antiga, até 500. Não há paginação. A fila de trabalho do operador é o estado escalated.

GET/api/v1/admin/disputesAdmin

Lista as disputas entre clientes e sellers

Autenticação: Authorization: Bearer <token> de um administrador. Não exige privilégio específico além de ser administrador.

Parâmetros de consulta

statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado exato, em palavra.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/disputes?status=escalated" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Disputas devolvidas

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": "escalated",
      "amount_cents": 5266,
      "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
      "created_at": "2026-10-11T20:57:01.26736Z",
      "events": []
    }
  ]
}

Campos da resposta

itemsarray

Disputas.

items[].iduuid

Identificador da disputa.

items[].order_iduuid

Pedido contestado.

items[].order_item_iduuid

Item contestado, quando a disputa é sobre um item. Omitido nas demais.

items[].customer_iduuid

Cliente que abriu.

items[].vendor_iduuid

Seller do pedido.

items[].reasonstring

not_receiveddifferent_from_descriptiondamagedwrong_itemother

not_received, different_from_description, damaged, wrong_item ou other.

items[].statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado da disputa (veja a tabela na página).

items[].amount_centsinteger

Valor em disputa, em centavos. É o teto do reembolso.

items[].refund_centsinteger

Reembolso decidido, em centavos. Só depois de resolvida.

items[].thread_iduuid

Conversa entre as partes ligada à disputa, se houver.

items[].seller_deadline_atstring

Prazo de resposta do seller (48 horas após abrir).

items[].buyer_deadline_atstring

Prazo de resposta do cliente (72 horas), quando aplicável.

items[].resolution_notestring

Nota de quem resolveu.

items[].created_atstring

Abertura, RFC 3339 em UTC.

items[].eventsarray

Linha do tempo (actor_type, action, payload, created_at). Na listagem vem sempre vazia; só a resposta de resolve a traz preenchida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
500	Falha na consulta	`{"error":"failed to list disputes","detail":"..."}`

Resolver uma disputa

POST/api/v1/admin/disputes/{id}/resolveAdmin

Decide uma disputa

Autenticação: Authorization: Bearer <token> de um administrador. Não exige privilégio específico além de ser administrador.

Parâmetros de caminho

iduuidobrigatório

Identificador da disputa.

Corpo da requisição

resolutionstringobrigatório

resolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejected

Decisão.

refund_centsintegerpadrão: 0

Valor a reembolsar, em centavos, de 0 até amount_cents. Em resolved_refund_full é ignorado e vale amount_cents.

notestring

Justificativa, guardada em resolution_note.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/disputes/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/resolve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "resolved_refund_partial",
    "refund_cents": 2000,
    "note": "Produto chegou com avaria parcial"
  }'

Resposta

200Disputa resolvida

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": "resolved_refund_partial",
  "amount_cents": 5266,
  "seller_deadline_at": "2026-10-13T20:57:01.267155Z",
  "created_at": "2026-10-11T20:57:01.26736Z",
  "events": [
    {
      "actor_type": "admin",
      "action": "resolved",
      "payload": {
        "resolution": "resolved_refund_partial",
        "refund_cents": 2000,
        "note": "Produto chegou com avaria parcial"
      },
      "created_at": "2026-10-11T21:30:00Z"
    }
  ],
  "refund_cents": 2000,
  "resolution_note": "Produto chegou com avaria parcial"
}

Campos da resposta

iduuid

Identificador da disputa.

order_iduuid

Pedido contestado.

order_item_iduuid

Item contestado, quando a disputa é sobre um item. Omitido nas demais.

customer_iduuid

Cliente que abriu.

vendor_iduuid

Seller do pedido.

reasonstring

not_receiveddifferent_from_descriptiondamagedwrong_itemother

not_received, different_from_description, damaged, wrong_item ou other.

statusstring

openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled

Estado da disputa (veja a tabela na página).

amount_centsinteger

Valor em disputa, em centavos. É o teto do reembolso.

refund_centsinteger

Reembolso decidido, em centavos. Só depois de resolvida.

thread_iduuid

Conversa entre as partes ligada à disputa, se houver.

seller_deadline_atstring

Prazo de resposta do seller (48 horas após abrir).

buyer_deadline_atstring

Prazo de resposta do cliente (72 horas), quando aplicável.

resolution_notestring

Nota de quem resolveu.

created_atstring

Abertura, RFC 3339 em UTC.

eventsarray

Linha do tempo (actor_type, action, payload, created_at). Na listagem vem sempre vazia; só a resposta de resolve a traz preenchida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
400	Corpo inválido; `resolution` fora da lista; reembolso acima do valor; transição não permitida a partir do estado atual; disputa inexistente	`{"error":"failed to resolve dispute","detail":"refund exceeds order amount"}`