Cancelar resgate

O endpoint de Cancelar resgate permite que parceiros revertam um resgate previamente processado, reacreditando as milhas na conta do membro. Esta operação também é chamada de recrédito.

O processamento é assíncrono: uma resposta 201 Created indica que a requisição foi aceita, não que o recrédito foi concluído. O resultado final é entregue via notificação por webhook.

Tanto cancelamentos totais quanto parciais são suportados. Um cancelamento parcial reacredita apenas as milhas especificadas; as milhas restantes do resgate original não são afetadas.

Importante

Apenas resgates com status PROCESSED são elegíveis para cancelamento.
Um cancelamento parcial só pode ser realizado uma vez por correlation ID. Múltiplos cancelamentos parciais para o mesmo correlation ID não são suportados.

Requisição

Endpoint

POST https://api.latampass.com/sandbox/v1/customer/eloyalty/partner/redeem/cancel

Corpo da requisição

Campo	Tipo	Obrigatório	Restrições	Descrição
`correlationId`	String (UUID)	Sim	Deve ser um UUID válido	Correlation ID do resgate a cancelar. Deve referenciar um resgate com status `PROCESSED`.
`description`	String	Sim	Máx. 500 caracteres	Descrição do motivo do cancelamento.
`miles`	Number	Sim	Mín.: `0.001` / Máx.: total de milhas do resgate original	Milhas a reacreditar. Valores decimais são arredondados para o inteiro mais próximo internamente.

Exemplo — cancelamento total

curl https://api.latampass.com/sandbox/v1/customer/eloyalty/partner/redeem/cancel \
  --request POST \
  --header 'x-latam-test: LatamPass' \
  --header 'Access_token: <YOUR_UUID_ACCESS_TOKEN>' \
  --header 'client_id: <YOUR_CLIENT_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationId": "<YOUR_CORRELATION_ID>",
    "description": "Customer requested cancellation",
    "miles": 15
  }'

Exemplo — cancelamento parcial

curl https://api.latampass.com/sandbox/v1/customer/eloyalty/partner/redeem/cancel \
  --request POST \
  --header 'x-latam-test: LatamPass' \
  --header 'Access_token: <YOUR_UUID_ACCESS_TOKEN>' \
  --header 'client_id: <YOUR_CLIENT_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationId": "<YOUR_CORRELATION_ID>",
    "description": "Partial refund for returned item",
    "miles": 5
  }'

Cabeçalhos

Um fluxo de autenticação é aceito para este endpoint.

Fluxo B — Credenciais de cliente do Portal API

Cabeçalho	Valor
`Content-Type`	`application/json`
`x-latam-test`	`LatamPass` (somente sandbox)
`Access_token`	`<UUID_ACCESS_TOKEN>`
`client_id`	`<YOUR_CLIENT_ID>`

Regras de negócio

Apenas resgates com status PROCESSED são elegíveis para cancelamento. Tentar cancelar um resgate com status PROCESSING, ERROR ou CANCELLED retorna 422.
O correlationId deve ser um UUID válido obtido de uma resposta 201 anterior de Criar resgate.
O campo miles deve ser positivo (mínimo 0.001) e não pode exceder o total de milhas do resgate original.
Valores decimais de milhas são arredondados para o inteiro mais próximo internamente antes do processamento.
O cancelamento pode ser total (milhas originais completas) ou parcial (qualquer valor até o total original).
Uma resposta 201 retorna o mesmo correlationId do resgate original — nenhum novo correlation ID é gerado.
Se um cancelamento já estiver em andamento para o correlationId informado, um 422 é retornado para evitar processamento duplicado.
O resultado final do recrédito é entregue exclusivamente via notificação por webhook:

Status	Significado
`REFUNDED`	Milhas foram reacreditadas com sucesso na conta do membro.
`CANCELLED`	Recrédito não pôde ser concluído (não recuperável).
`ERROR`	Recrédito falhou — veja `errorException` no payload do webhook para detalhes.

Resposta

201 Created — Requisição aceita

{
  "trace": {
    "correlationId": "<YOUR_CORRELATION_ID>",
    "returnedDateTime": "2026-03-04 10:30:00.000+0000"
  },
  "error": null
}

O correlationId na resposta corresponde ao correlation ID do resgate original. O status final do recrédito não está disponível de forma síncrona — ele é entregue via webhook.

Erros comuns

400 — Erro de validação (payload inválido)

{
  "message": "Request payload has problems with validation",
  "code": 400,
  "instructions": null,
  "details": {
    "correlationId": "correlationId must be UUID valid"
  },
  "issueDateTime": "2026-03-04T15:54:25.044344Z"
}

400 — Resgate não encontrado

{
  "message": "Redeem not found for correlation ID: ec909ee0-d890-44f4-b3f9-01797d591bc2",
  "code": 400,
  "instructions": null,
  "details": null,
  "issueDateTime": "2026-03-04T15:55:00.000000Z"
}

400 — Valor de cancelamento excede o total original

{
  "message": "Cancellation amount cannot be greater than the total amount",
  "code": 400,
  "instructions": [
    { "field": "miles", "message": "Invalid amount" }
  ],
  "details": null,
  "issueDateTime": "2026-03-04T15:56:00.000000Z"
}

422 — Resgate não elegível para cancelamento

Retornado quando o resgate existe, mas seu status atual não permite cancelamento (ex.: PROCESSING, ERROR ou CANCELLED).

{
  "message": "Redeem is not eligible for cancellation. Current status: PROCESSING",
  "code": 31,
  "instructions": [
    { "field": "correlationId", "message": "Invalid status" }
  ],
  "details": null,
  "issueDateTime": "2026-03-04T15:57:00.000000Z"
}

422 — Cancelamento já em andamento

Retornado quando uma requisição de cancelamento para o mesmo correlationId já está sendo processada. Não tente novamente até que a operação atual seja concluída.

{
  "message": "Cancellation already in progress for this correlationId.",
  "code": 31,
  "instructions": [
    { "field": "correlationId", "message": "Cancellation conflict" }
  ],
  "details": null,
  "issueDateTime": "2026-03-04T15:57:00.000000Z"
}

405 — Method Not Allowed

{
  "timestamp": "2026-03-04T15:57:12.663+00:00",
  "status": 405,
  "error": "Method Not Allowed",
  "path": "/v1/customer/eloyalty/partner/redeem/cancel"
}

500 — Internal Server Error

Tente novamente a requisição com o exato mesmo payload.

{
  "message": "Internal server error on processing cancel redeem.",
  "code": 33,
  "instructions": [
    { "field": "error", "message": "Please try again later or contact support if the issue persists" }
  ],
  "details": null,
  "issueDateTime": "2026-03-04T15:58:00.000000Z"
}

Se o erro persistir após as tentativas, entre em contato com o LATAM Pass Support e forneça o issueDateTime e o correlationId usado na requisição.