Recuperar o histórico da sessão

Consulte a trilha de auditoria de alterações, pagamentos e expirações de uma sessão.

GET /v1/sessions/{id}/history

Recuperar o histórico da sessão

cURL

curl --request GET \
  --url https://api.malga.io/v1/sessions/{id}/history \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://api.malga.io/v1/sessions/{id}/history"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Client-Id': '<api-key>', 'X-Api-Key': '<api-key>'}};

fetch('https://api.malga.io/v1/sessions/{id}/history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.malga.io/v1/sessions/{id}/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>",
    "X-Client-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.malga.io/v1/sessions/{id}/history"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.malga.io/v1/sessions/{id}/history")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.malga.io/v1/sessions/{id}/history")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

200

[
  {
    "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"
    }
  }
]

{
  "error": {
    "code": 123,
    "declinedCode": "<string>",
    "key": "<string>",
    "businessCode": "<string>",
    "message": "<string>",
    "details": "<array>"
  }
}

{
  "error": {
    "code": 123,
    "declinedCode": "<string>",
    "key": "<string>",
    "businessCode": "<string>",
    "message": "<string>",
    "details": "<array>"
  }
}

{
  "error": {
    "code": 123,
    "declinedCode": "<string>",
    "key": "<string>",
    "businessCode": "<string>",
    "message": "<string>",
    "details": "<array>"
  }
}

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

Objetivo	Endpoint recomendado
Disponibilidade do link 1:N (multiplePayments, contadores)	GET /v1/sessions/{id}
Linha do tempo de alterações e pagamentos	GET /v1/sessions/{id}/history
Conciliação de uma cobrança específica	Histó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.

Campo	Descrição
id	Identificador do registro de histórico, não da sessão.
status	Status na leitura do produto: created, paid, canceled, voided ou disabled.
createdAt, updatedAt	Timestamps do registro (RFC 3339, com milissegundos).
clientId, merchantId	Preenchidos quando gravados na auditoria.
action	Ação principal derivada de actions (pode ser null quando dados legados não permitem derivar uma ação semântica com segurança).
actions	Lista completa de ações semânticas do evento.
diff	Objeto 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

Action	Significado
statusChanged	Mudança de status (criação, cancelamento, confirmação paid, voided, etc.).
amountChanged, currencyChanged	Valor ou moeda alterados.
isActiveChanged	Link ativado ou desativado (manualActivation / manualDeactivation no diff).
itemsChanged, itemsRemoved	Itens do pedido alterados ou removidos.
dueDateChanged, maxPaymentsChanged	Vencimento ou limite 1:N alterados.
nameChanged, descriptionChanged, captchaEnabledChanged	Demais campos de configuração.
splitRulesChanged	Regras de split atualizadas (ex.: enriquecimento de recebedor).

Pagamentos e estoque 1:N

Action	Significado
paymentSucceeded	Resposta não falha da tentativa de cobrança HTTP (inclui pending) ou confirmação assíncrona idempotente.
paymentFailed	Falha HTTP, erro de transporte ou corpo da resposta com status=failed.
paymentPending	Reserva de vaga pendente em sessão 1:N (Pix/boleto assíncrono).
paymentExpired	Pagamento 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

Action	Significado
sessionExpiredByDueDate	Link desativado ao vencer dueDate (status na API: disabled).
sessionExpiredByMaxPayments	Limite 1:N atingido; link desativado (status na API: disabled).
sessionExpiredByInvalidSeller	Seller inválido; sessão encerrada (status: canceled).
captchaBlocked	Bloqueio 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.

Estado agregado do link

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

HTTP	Causa
400	X-Client-Id ausente ou identificador da sessão ausente no path.
404	Sessão inexistente para o par id + X-Client-Id.
500	Erro 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

200

application/json

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.