Skip to main content
GET
/
v1
/
sessions
/
{id}
/
history
Recuperar o histórico da sessão
curl --request GET \
  --url https://api.malga.io/v1/sessions/{id}/history \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>'
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "status": "disabled",
    "createdAt": "2026-05-20T00:00:01.000Z",
    "updatedAt": "2026-05-20T00:00:01.000Z",
    "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
    "merchantId": "660e8400-e29b-41d4-a716-446655440002",
    "action": "sessionExpiredByDueDate",
    "actions": [
      "sessionExpiredByDueDate"
    ],
    "diff": {
      "reason": "expired by due date",
      "expiredAt": "2026-05-19T23:59:59.000Z",
      "changes": {
        "isActive": {
          "from": true,
          "to": false,
          "reason": "sessionExpiredByDueDate"
        }
      }
    }
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "created",
    "createdAt": "2026-05-19T14:30:00.000Z",
    "updatedAt": "2026-05-19T14:30:00.000Z",
    "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
    "merchantId": "660e8400-e29b-41d4-a716-446655440002",
    "action": "paymentSucceeded",
    "actions": [
      "paymentSucceeded"
    ],
    "diff": {
      "changes": {
        "response": {
          "from": null,
          "to": {
            "chargeId": "880e8400-e29b-41d4-a716-446655440099",
            "status": "pending",
            "amount": 5000
          }
        }
      },
      "updatedAt": "2026-05-19T14:30:00.000Z"
    }
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "created",
    "createdAt": "2026-05-19T12:00:00.000Z",
    "updatedAt": "2026-05-19T12:00:00.000Z",
    "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
    "merchantId": "660e8400-e29b-41d4-a716-446655440002",
    "action": "statusChanged",
    "actions": [
      "statusChanged"
    ],
    "diff": {
      "changes": {
        "status": {
          "from": null,
          "to": "created"
        }
      },
      "createdAt": "2026-05-19T12:00:00.000Z"
    }
  }
]
O endpoint GET /v1/sessions/{id}/history retorna um array de eventos em ordem decrescente, com os registros mais recentes primeiro. Cada elemento descreve uma mudança ou um efeito observado (criação, atualização, tentativa de pagamento, confirmação assíncrona, expiração, entre outros).
Use o histórico para auditar o que aconteceu. Para saber se o link ainda aceita pagamentos ou qual é o multiplePayments.status agora, consulte Recuperar detalhes de uma sessão.

​
Quando usar

ObjetivoEndpoint recomendado
Disponibilidade do link 1:N (multiplePayments, contadores)GET /v1/sessions/{id}
Linha do tempo de alterações e pagamentosGET /v1/sessions/{id}/history
Conciliação de uma cobrança específicaHistórico + detalhe da cobrança em Charges
Em sessões 1:N, uma cobrança aprovada não encerra necessariamente a sessão. O histórico registra cada efeito; o estado agregado continua em GET /v1/sessions/{id}.

​
Modelo da resposta

Cada item do array possui os campos abaixo.
CampoDescrição
idIdentificador do registro de histórico, não da sessão.
statusStatus na leitura do produto: created, paid, canceled, voided ou disabled.
createdAt, updatedAtTimestamps do registro (RFC 3339, com milissegundos).
clientId, merchantIdPreenchidos quando gravados na auditoria.
actionAção principal derivada de actions (pode ser null quando dados legados não permitem derivar uma ação semântica com segurança).
actionsLista completa de ações semânticas do evento.
diffObjeto JSON com changes, reason e contexto do fluxo.

​
Status disabled no histórico

O valor disabled não é um status persistido na sessão. Ele aparece no histórico quando o registro representa expiração automática por:
  • vencimento do dueDate (sessionExpiredByDueDate); ou
  • limite de pagamentos em sessão 1:N (sessionExpiredByMaxPayments).
Cancelamento manual pelo integrador continua como canceled.

​
Prioridade do campo action

Quando há várias entradas em actions, a API escolhe uma ação principal nesta ordem:
  1. statusChanged
  2. sessionExpiredByDueDate
  3. sessionExpiredByMaxPayments
  4. paymentExpired
  5. updated (genérico para demais combinações)

​
Catálogo de ações (actions)

As ações abaixo podem aparecer isoladas ou combinadas no mesmo registro.

​
Alterações de sessão

ActionSignificado
statusChangedMudança de status (criação, cancelamento, confirmação paid, voided, etc.).
amountChanged, currencyChangedValor ou moeda alterados.
isActiveChangedLink ativado ou desativado (manualActivation / manualDeactivation no diff).
itemsChanged, itemsRemovedItens do pedido alterados ou removidos.
dueDateChanged, maxPaymentsChangedVencimento ou limite 1:N alterados.
nameChanged, descriptionChanged, captchaEnabledChangedDemais campos de configuração.
splitRulesChangedRegras de split atualizadas (ex.: enriquecimento de recebedor).

​
Pagamentos e estoque 1:N

ActionSignificado
paymentSucceededResposta não falha da tentativa de cobrança HTTP (inclui pending) ou confirmação assíncrona idempotente.
paymentFailedFalha HTTP, erro de transporte ou corpo da resposta com status=failed.
paymentPendingReserva de vaga pendente em sessão 1:N (Pix/boleto assíncrono).
paymentExpiredPagamento pendente expirado; libera a reserva pendente e pode reativar o link.
paymentSucceeded registrado após POST /v1/sessions/{id}/charge documenta a resposta da tentativa de cobrança, não necessariamente a confirmação final na sessão. Um item com diff.changes.response.to.status: pending indica tentativa em andamento. Para estado consolidado, use GET /v1/sessions/{id} ou aguarde a confirmação assíncrona.

​
Expirações e bloqueios

ActionSignificado
sessionExpiredByDueDateLink desativado ao vencer dueDate (status na API: disabled).
sessionExpiredByMaxPaymentsLimite 1:N atingido; link desativado (status na API: disabled).
sessionExpiredByInvalidSellerSeller inválido; sessão encerrada (status: canceled).
captchaBlockedBloqueio por score de captcha.

​
Fluxo de registro (visão geral)

Dois destinos distintos: o histórico registra o que aconteceu; a sessão e as métricas guardam o estado atual do link.

​
Trilha de auditoria

Cada origem abaixo pode acrescentar um evento ao histórico. Consulte o resultado com GET /v1/sessions/{id}/history. As mesmas origens também atualizam contadores e disponibilidade do link. Para o estado atual, use GET /v1/sessions/{id} — não o histórico. Registros com deduplicação por cobrança (paymentPending, paymentSucceeded, paymentExpired em 1:N) evitam reaplicar o mesmo efeito em reprocessamentos. Tentativas HTTP de cobrança não são deduplicadas: cada chamada pode gerar uma nova linha.

​
Estrutura típica do diff

Atualizações manuais costumam seguir: 
{
  "changes": {
    "isActive": {
      "from": true,
      "to": false,
      "reason": "manualDeactivation"
    }
  },
  "updatedAt": "2026-05-19T13:00:00.000Z"
}
Expiração por dueDate: 
{
  "status": "disabled",
  "action": "sessionExpiredByDueDate",
  "diff": {
    "reason": "expired by due date",
    "expiredAt": "2026-05-19T23:59:59.000Z",
    "changes": {
      "isActive": {
        "from": true,
        "to": false,
        "reason": "sessionExpiredByDueDate"
      }
    }
  }
}
O payload do item não inclui chargeId como campo de nível raiz nem metadados de sistema. Quando houver contexto de cobrança, ele pode aparecer dentro de diff, por exemplo em diff.chargeId ou diff.changes.response.to.chargeId.

​
Erros comuns

HTTPCausa
400X-Client-Id ausente ou identificador da sessão ausente no path.
404Sessão inexistente para o par id + X-Client-Id.
500Erro interno inesperado ao recuperar o histórico da sessão.

​
Próximos passos

Sessões

Conceitos de sessão 1:1 e 1:N e acompanhamento de status.

Detalhes da sessão

Estado agregado atual e objeto multiplePayments.

Authorizations

​
X-Client-Id
string
header
required
​
X-Api-Key
string
header
required

Path Parameters

​
id
string<uuid>
required

Identificação da sessão

Response

OK

​
id
string<uuid>
required

Identificador do registro de histórico (não confundir com o id da sessão no path).

​
status
enum<string>
required

Status da sessão na leitura do produto no momento do evento. O valor disabled indica desativação automática por dueDate ou limite de pagamentos 1:N; cancelamento manual permanece canceled.

Available options:
created,
paid,
canceled,
voided,
disabled
​
createdAt
string<date-time>
required

Data de criação do registro (RFC 3339, com precisão de milissegundos).

​
updatedAt
string<date-time>
required

Data da última atualização do registro.

​
clientId
string<uuid>

Identificador do cliente Malga associado ao registro, quando preenchido.

​
merchantId
string<uuid>

Identificador do merchant associado ao registro, quando preenchido.

​
action
string | null

Ação principal derivada de actions, com prioridade documentada (ex.: statusChanged, sessionExpiredByDueDate, paymentSucceeded). Pode ser omitida (null) quando o diff indica expiração por dueDate mas actions não lista sessionExpiredByDueDate.

​
actions
string[]

Lista completa de ações semânticas do evento. Valores possíveis incluem statusChanged, amountChanged, isActiveChanged, paymentSucceeded, paymentPending, paymentExpired, sessionExpiredByDueDate, sessionExpiredByMaxPayments, splitRulesChanged, entre outros.

​
diff
object

Objeto JSON com mudanças (changes.*), razões estáveis (reason, changes.isActive.reason) e contexto (ex.: maxPaymentsContext, resposta da tentativa de cobrança em changes.response). A estrutura varia conforme o fluxo.