Neste manual

Editar registos

É igualmente possível, pela REST API, alterar os registos, podendo facilitar na manipulação de estados de pagamento de acordo com o que soluções terceiras pretendam com os dados.

Para editar um registo existente, primeiro é necessário obter a versão atual do registo a editar. Este processo inicia-se com a construção de um URL específico que utiliza o identificador público do registo (o valor de PID - anteriormente public_id). Em seguida, é feita uma requisição GET a essa URL, utilizando cURL, para obter os detalhes do registo, incluindo a sua versão atual. Após confirmar que a versão do registo foi corretamente obtida, os dados a serem atualizados são preparados em formato JSON, incluindo campos personalizados como URL (anteriormente paymentFormUrl), OID (anteriormente order_id), CPM (anteriormente chosen_payment_method), PS (anteriormente payment_status), e URL_S (anteriormente url_status). Um novo URL é então construído para a requisição PUT, que envia os dados preparados para atualizar o registo. Finalmente, a requisição PUT é executada, e o sistema verifica o código de resposta HTTP para assegurar que a atualização foi bem-sucedida. Em caso positivo, o processo de edição está concluído, e o registo é atualizado conforme os novos dados fornecidos.

Explicação do código exemplificado

Função getRecordVersion:
- Obtém a versão atual do registo usando uma requisição GET.
- Utiliza cURL para fazer a requisição e retorna a versão obtida do registo.
Função updatePaymentStatus:
- Atualiza o estado de pagamento do registo utilizando uma requisição PUT.
- Prepara os dados necessários no formato JSON e envia a requisição PUT com cURL.
Execução do Processo:
- Verifica se os parâmetros necessários estão presentes.
- Obtém a versão do registo usando getRecordVersion.
- Atualiza o estado de pagamento usando updatePaymentStatus.
- Exibe uma mensagem de sucesso ou erro conforme o resultado das operações.
Parâmetros de Exemplo:
- Os parâmetros fornecidos no exemplo ($public_id, $paymentFormUrl, $REF, $paybylink_ID, etc.) devem ser substituídos pelos valores reais obtidos dinamicamente no seu código. Chama-se a atenção para o facto de que, na atualização de um registo, se necessita de passar todos os custom field id por forma a se poder inserir o dado a atualizar. Apesar de se obter o número da versão do registo, o mesmo só é passado, sendo que o incremento é feito pela plataforma e não do lado de quem programa, como mostrado no exemplo.

Este exemplo mostra como obter a versão de um registo e, em seguida, atualizar o seu estado de pagamento, garantindo que todas as operações sejam realizadas corretamente e que os erros sejam tratados adequadamente.

Apesar de se obter o número da versão do registo, o mesmo só é passado, sendo que o incremento do número do registo é feito pela plataforma e não do lado de quem programa.

Exemplos

PHP

Exemplo em PHP 7.1

// Função para obter a versão do registo

function getRecordVersion($recordID) {

// Define o URL para obter a versão do registo

$url_get_version = CYCLOS_BASE_URL . "records/" . $recordID .

"/data-for-edit?fields=record.version";

// Define os cabeçalhos da requisição HTTP

$headers = [

Accept: application/json',

'Authorization: Basic

'. base64_encode(USERNAME . ':'. PASSWORD),

'Content-Type: application/json

];

// Inicia uma sessão cURL para o pedido GET

$ch_get = curl_init($url_get_version);

cur1_setopt($ch_get, CURLOPT_HTTPHEADER, $headers);

curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);

cur1_setopt($ch_get, CURLOPT_SSL_VERIFYPEER, false);

cur1_setopt($ch_get, CURLOPT_SSL_VERIFYHOST, 2);

// Executa a requisição e armazena a resposta na variável $response

$response_get = curl_exec($ch_get);

$httpcode_get = curl_getinfo($ch_get, CURLINFO_HTTP_CODE);

cur1_close($ch_get);

// Verifica se a requisição foi bem sucedida

if ($httpcode_get == 200) {

$data = json_decode($response_get, true);

return $data['record']['version'] ?? null;

} else {

error_log("Erro ao obter a versão do registo. HTTP Status:

$httpcode_get);

return null;

// Funcao para atualizar o estado de pagamento
function updatePaymentStatus($recordID, $version, $paymentFormUrl,
Surl_id, SorderId, Semail, $chosen_payment_method, $payment_status)

// Prepara os dados para o pedido PUT
$dados = [
"customValues" => [
"URL" => $_SESSION['paymentFormUr1'],
"OID" => $_SESSION['orderId'],
"PE" => $_SESSION['ema1l'],
"CPM" => $mpagamento_escolhido,
"SD" => $start_date,
"ED" => $final_date,
"pS" => "pending",
"URL_S" => "active",

'version' => $version

// Define o URL para o pedido PUT
$url_put = CYCLOS_BASE_URL . 'records/' . $recordID;

// Define os cabecalhos da requisicao HTTP
$headers - [
'Accept: application/json',
Authorization: Basic ' . base64_encode(USERNAME
PASSWORD),
'Content-Type: application/json'

// Inicia uma sessao cURL para o pedido PUT
$ch_put = curl_init($url_put);
curl_setopt($ch_put, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch_put, CURLOPT_POSTFIELDS, json_encode($dados));
curl_setopt($ch_put, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch_put, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch_put, CURLOPT_SSL_VERIFYPEER, 2);
curl_setopt($ch_put, CURLOPT_SSL_VERIFYHOST, 2);

// Executa a requisicao e armazena a resposta na variavel $response_pu
$response_put = curl_exec($ch_put);
$httpcode_put = curl_getinfo($ch_put, CURLINFO_HTTP_CODE);
curl_close($ch_put);

// Verifica se a requisicao foi bem-sucedida
if ($httpcode_put == 200 || $httpcode_put == 204) {
return true;
}else {
error_log("Erro ao atualizar os dados: " . $response_put);
return false;

// Parâmetros de exemplo (estes seriam dinamicamente obtidos no seu codigo real)
$publicIdentifier = $_SESSION['publicIdentifier'] ?? "';
$paymentFormUr1 = $_SESSION['paymentFormUr1'] ?? '';
$paybylink_ID = $_SESSION['paybylink_ID'] ?? "';
$orderId = $_SESSION['orderId'] ?? ";
$email = $_SESSION['email'] ?? '';
$chosen_payment = $_SESSION['chosen_payment' ] ?? 'multibanco';
$payment_status = 'paid'; // Exemplo de novo estado de pagamento
$recordID = '5741493202915805803'; // Exemplo de ID de registo

// Verifica se os parâmetros necessários estão presentes
if ($publicIdentifier && $paymentFormUrl && $paybylink_ID) {
// Obtém a versão do registo
$version = getRecordVersion($recordID);
if ($version !== null) {
// Atualiza o estado de pagamento
$atualizacao_sucesso = updatePaymentStatus($recordID, $version,
$paymentFormUr1, $paybylink_ID, $orderId, $email, $mpagamento_escolhido,
$payment_status);
if ($atualizacao_sucesso) {
echo "Estado de pagamento atualizado com sucesso.";
} else {
echo "Erro ao atualizar o estado de pagamento.";

} else {
echo "Erro ao obter a versao do registo.";

} else {
echo "Parametros necessarios não fornecidos.";
}