Pular para o conteúdo
Última atualização

Cancelamento e Reembolso

1. Cancelamento

Toda solicitação de cancelamento leva:

  • reason — texto livre;
  • code — motivo (enum abaixo);
  • mode — AUTO ou MANUAL.

Fluxo de cancelamento

POST /v1/orders/{orderId}/requestCancellation responde 202, que significa só "pedido recebido para análise". O pedido só está cancelado quando chegar o evento CANCELLED. Dependendo do momento, a Keeta pode consultar o cliente antes de aceitar.

Códigos de cancelamento (v1.0.7+)

codeSignificadoUso típico
SYSTEMIC_ISSUESProblemas sistêmicosFalha de PDV/integração
DUPLICATE_APPLICATIONPedido duplicadoCliente fez o mesmo pedido duas vezes
UNAVAILABLE_ITEMItem indisponívelAcabou o produto; informe em outOfStockItems
RESTAURANT_WITHOUT_DELIVERY_PERSONRestaurante sem entregadorEntrega própria sem motoboy disponível
OUTDATED_MENUCardápio desatualizadoDesativa os itens listados em invalidItems
ORDER_OUTSIDE_THE_DELIVERY_AREAFora da área de entregaEndereço fora do raio
BLOCKED_CUSTOMERCliente bloqueadoHistórico de fraude/problemas
OUTSIDE_DELIVERY_HOURSFora do horário de entregaPedido chegou após o fechamento
INTERNAL_DIFFICULTIES_OF_THE_RESTAURANTDificuldades internasFalta de energia, cozinha parada
RISK_AREAÁrea de riscoEndereço em área considerada insegura
DELIVERY_PROBLEMProblema na entregaFalha logística

Códigos antigos (legado, ainda aceitos): INSUFFICIENT_DISHES, SUSPENSION_OF_BUSINESS, INSUFFICIENT_MANPOWER, OTHERS. Atenção: o metadata do evento CANCELLED ainda pode trazer esses valores antigos — trate os dois conjuntos ao ler eventos.

Cancelamentos iniciados pela Keeta:

  • CONSUMER_CANCELLATION_REQUESTED — o cliente pediu (pode não estar habilitado para todo merchant ou só valer antes da confirmação).
  • OTHER_CANCELLATION_REASON — o sistema cancelou (ex.: sem aceite no prazo, nenhum entregador aceitou, entregador reportou loja fechada).

Em ambos os casos o Software Service recebe o evento e deve atualizar o pedido.

2. Reembolso

  1. O cliente pede reembolso total ou parcial no app → a Keeta envia USER_REFUND_REQUEST com itens e valores no metadata.
  2. O merchant responde: aceita → POST /v1/orders/{orderId}/acceptRefund → evento REFUNDED; recusa → POST /v1/orders/{orderId}/rejectRefund → evento REFUND_FAILED.
  • O merchant não consegue iniciar reembolso pela API.
  • Responder pela API ou pelo Merchant Portal dá o mesmo resultado; vale a primeira resposta recebida. Disputas podem ser conduzidas pelo chat (Instant Messenger) do Merchant Portal.

Fluxo de reembolso

Exemplo de metadata de USER_REFUND_REQUEST (adaptado para o Brasil; valores em centavos):

{
  "money": 3790,
  "opTime": 1760380200000,
  "shopId": "159416882",
  "status": 5002,
  "currency": "BRL",
  "isAppeal": 0,
  "partRefund": 1,
  "applyOpType": 10,
  "applyReason": "Item errado",
  "orderViewId": 783441058793308,
  "handleOpType": 20,
  "handleReason": "Merchant concordou com o reembolso",
  "refundProducts": [
      {
          "id": 12053105,
          "name": "Pastel de carne",
          "count": 1,
          "price": 1490,
          "skuId": 8949938,
          "spuId": 9897081,
          "groups": [],
          "currency": "BRL",
          "nameI18n": {
              "pt-BR": "Pastel de carne",
              "default": "Pastel de carne"
          },
          "priceStr": "R$ 14,90",
          "refundType": 1,
          "originPrice": 1490,
          "refundCount": 1,
          "refundPrice": 0,
          "orderProductId": 359379560,
          "skuOpenItemCode": "PDV-2001",
          "spuOpenItemCode": "PDV-2000"
      }
  ],
  "afterSaleOrderId": 783440453161676
}

O metadata é uma string JSON dentro do evento — faça o parse. Os códigos status, applyOpType e handleOpType não têm tabela oficial publicada; trate-os como informativos.

3. Política de transações reversas

ClienteMerchantAtendimento KeetaSistema
CancelamentoEm full service, só antes de o merchant confirmar, sem precisar de aprovaçãoPode cancelar até 48 h após a conclusão, pelo seu sistema ou pelo Order Management da Keeta (neste caso, a Keeta notifica via API)Pode cancelar até 30 dias após a conclusão; o evento é enviado ao Software ServiceCancela pedido não aceito em 5 min; a loja é fechada temporariamente
ReembolsoGera evento e exige aprovação do merchant; o merchant pode tratar disputas pelo Merchant PortalNão pode iniciar reembolso pela APIIgual à coluna do cliente—

Ou seja: a Keeta pode enviar cancelamento ou reembolso a qualquer momento. Decida se o seu sistema acompanha o status da Keeta ou descarta essas notificações em certos estados (ex.: depois de concluído). Se isso gerar divergência de conciliação, o merchant deve acionar o time comercial (BD) da Keeta.