SDK Delphi

O SDK Delphi integra um backend à API pública da Raims por fontes com serviços, parâmetros e respostas tipadas. A distribuição é código-fonte para compilar no alvo da sua aplicação. Confira os requisitos por plataforma ao configurar a instalação. Não incorpore a chave de API em executáveis desktop ou mobile distribuídos.

A referência do SDK lista os métodos e parâmetros de cada recurso.

Instalar o SDK

Baixe os fontes da release atual no GitHub e preserve o diretório src completo. A base dos fontes exige Delphi 10.4; alguns alvos exigem versões posteriores. Consulte os requisitos por plataforma e use uma edição que inclua seu compilador e os SDKs nativos necessários.

No IDE, abra Project, Options e Delphi Compiler. Adicione o caminho para src ao Search path do projeto em cada alvo e configuração usados. Para uma configuração global, a página Library das opções Delphi permite adicionar o diretório ao Library path da plataforma selecionada. A documentação da biblioteca do IDE explica essa seleção. Mantenha os arquivos compilados no diretório de saída da sua aplicação, separados dos fontes.

Use Raims.Client, Raims.Core, Raims.Params e Raims.Models; para webhooks, adicione Raims.Webhooks. O SDK usa System.JSON e System.Net.HttpClient da biblioteca padrão, sem um framework de interface. Os exemplos são trechos de procedimentos Delphi; importe também System.SysUtils e System.JSON.

Configurar o cliente

Obtenha a credencial em Chaves de API e guarde-a no backend. Empresa, ambiente e permissões vêm da chave validada. Sandbox e Produção usam https://api.raims.com.

uses
  System.SysUtils, Raims.Client, Raims.Core, Raims.Models;

var
  Client: TRaimsClient;
  Options: TRaimsClientOptions;
begin
  Options := TRaimsClientOptions.Default;
  Options.TimeoutMilliseconds := 80000;
  Options.MaxNetworkRetries := 0;
  Client := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_API_KEY'), Options);
  try
    // Use Client here.
  finally
    Client.Free;
  end;
end;

Inicialize opções com Default. Timeouts usam milissegundos e se aplicam às fases do transporte nativo, não a um prazo total da operação. As chamadas são síncronas; em uma aplicação visual, execute rede fora da thread da interface. Os próximos trechos usam um Client aberto. Ele é dono dos serviços; a aplicação libera o cliente, os parâmetros e os recursos retornados com try/finally.

Criar um cliente e uma cobrança

CustomerTaxId é o CPF ou CNPJ válido do cliente autorizado. CustomerKey e ChargeKey são strings distintas, persistidas antes de enviar. DueDateUnix é um Int64 com o vencimento em segundos Unix UTC; RequestId é uma string da aplicação. Os tipos usados estão em Raims.Params, Raims.Models e Raims.Core.

var
  CustomerParams: TCreateCustomerParams;
  ChargeParams: TCreateChargeParams;
  Customer: TCustomerCreated;
  Charge: TChargeCreated;
  RequestOptions: TRaimsRequestOptions;
  CustomerId: string;
begin
  CustomerParams := TCreateCustomerParams.Create;
  try
    CustomerParams.SetTaxId(CustomerTaxId);
    RequestOptions := TRaimsRequestOptions.Default;
    RequestOptions.IdempotencyKey := CustomerKey;
    Customer := Client.Customers.Create(CustomerParams, RequestOptions);
    try
      CustomerId := Customer.Id;
    finally
      Customer.Free;
    end;
  finally
    CustomerParams.Free;
  end;

  ChargeParams := TCreateChargeParams.Create;
  try
    ChargeParams.SetCustomerId(CustomerId).SetAmountCents(15000);
    ChargeParams.SetDueDate(DueDateUnix).SetTitle('Pedido 1234');
    RequestOptions := TRaimsRequestOptions.Default;
    RequestOptions.IdempotencyKey := ChargeKey;
    Charge := Client.Charges.Create(ChargeParams, RequestOptions);
    try
      RequestId := Charge.LastResponse.RequestId;
    finally
      Charge.Free;
    end;
  finally
    ChargeParams.Free;
  end;
end;

15000 representa R$ 150,00. Não chamar um setter deixa o campo ausente; SetExternalReferenceNull em TUpdateCustomerParams envia null quando o contrato permite limpar essa referência. UnsetExternalReference remove o campo da entrada. Nas respostas, HasField e IsNull distinguem presença e null antes de interpretar um getter que retorna zero ou string vazia.

Paginação e resultados pendentes

Para listar clientes e percorrer até cem itens:

var
  Page: TCustomerListResponse;
begin
  Page := Client.Customers.List;
  try
    Page.AutoPagingEach(
      procedure(CustomerJson: TJSONObject)
      begin
        ProcessCustomer(CustomerJson);
      end,
      100);
  finally
    Page.Free;
  end;
end;

ProcessCustomer é seu handler. O callback recebe um TJSONObject emprestado: não libere nem altere esse objeto, e copie-o para retê-lo após o callback. AutoPagingEach libera as páginas adicionais; a aplicação libera a primeira. NextPage e PreviousPage retornam páginas novas ou nil; a aplicação é dona dessas páginas. Filtros e opções são preservados.

HTTP 202 aceita uma operação com resultado pendente. Consulte o recurso ou acompanhe o webhook antes de confirmar o efeito financeiro. Preserve LastResponse.StatusCode e RequestId para identificar a tentativa.

Idempotência e erros

var
  Current: TCustomerListItem;
begin
  try
    Current := Client.Customers.Retrieve(CustomerId);
    try
      RequestId := Current.LastResponse.RequestId;
    finally
      Current.Free;
    end;
  except
    on E: ERaimsApiError do
      HandleApiFailure(E.LastResponse.StatusCode, E.Code, E.LastResponse.RequestId);
    on E: ERaimsConnectionError do
      HandleConnectionFailure;
  end;
end;

Os handlers pertencem à aplicação. ERaimsApiError expõe Code, ErrorType, ApiMessage e LastResponse; ERaimsConnectionError representa falhas de transporte. Registre somente os metadados necessários, sem credenciais ou corpos completos. Se acessar ApiError, guarde a cópia retornada e libere-a.

O SDK não gera chaves nem repete escritas automaticamente. Após uma resposta perdida, reconcilie a operação e mantenha chave e parâmetros se o endpoint permitir nova tentativa. MaxNetworkRetries habilita somente retries de leituras elegíveis; o padrão é zero. Retry-After segue a política de espera limitada do SDK. Veja Idempotência.

Usar o Sandbox

Use uma chave Sandbox e uma cobrança criada nesse ambiente:

var
  SandboxClient: TRaimsClient;
  Simulation: TChargeSimulation;
begin
  SandboxClient := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_SANDBOX_API_KEY'));
  try
    Simulation := SandboxClient.Simulations.Charges.ConfirmPayment(SandboxChargeId);
    try
      RequestId := Simulation.LastResponse.RequestId;
    finally
      Simulation.Free;
    end;
  finally
    SandboxClient.Free;
  end;
end;

SandboxChargeId e RequestId são strings da aplicação. A chave define o ambiente; o SDK não o altera por header ou pelo sistema operacional. Simulações financeiras exigem Sandbox. Consulte Simulações. E-mails e webhooks podem alcançar destinos externos; use destinos autorizados.

Receber webhooks

Preserve RawBody como os TBytes originais recebidos pelo servidor. Use WebhookSecret com o secret_key do webhook; os três valores Received... vêm dos headers originais. Antes de montar o array abaixo, rejeite ocorrências duplicadas de qualquer header de assinatura, sem escolher uma delas.

var
  Headers: TArray<TRaimsHeader>;
  Event: TJSONObject;
begin
  SetLength(Headers, 3);
  Headers[0] := TRaimsHeader.Create('webhook-id', ReceivedDeliveryId);
  Headers[1] := TRaimsHeader.Create('webhook-timestamp', ReceivedTimestamp);
  Headers[2] := TRaimsHeader.Create('webhook-signature', ReceivedSignature);
  Event := TRaimsWebhook.ConstructEvent(RawBody, Headers, WebhookSecret);
  try
    PersistEvent(Event);
  finally
    Event.Free;
  end;
end;

Os tipos estão em System.JSON, Raims.Core e Raims.Webhooks. PersistEvent é seu handler e Event pertence ao chamador. ERaimsSignatureError indica falha: não processe o evento nesse caso. Não reserialize o corpo antes da verificação. O padrão de tolerância é de 300 segundos; mantenha o relógio sincronizado.

Após verificar, confira tipo e ambiente, deduplique o id do evento e grave o trabalho de forma durável antes de responder com sucesso. webhook-id identifica a entrega. Veja Receber eventos.

Atualizar o SDK

Revise as notas da release e substitua todas as units pelos fontes da mesma revisão. Preserve o Search path ou Library path escolhido, remova unidades compiladas antigas da saída da aplicação e recompile cada alvo utilizado. Não misture uma unit nova com o restante de uma versão anterior. Confira sua integração no compilador, sistema operacional e configuração usados antes de disponibilizar a aplicação.