Docs
Verificando conta Raims
Integrações

SDK Delphi

Adicione os fontes ao projeto Delphi e configure serviços, paginação e webhooks no seu backend.

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 o ZIP dos fontes e o SHA256SUMS. Confira o hash, extraia o arquivo 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. A primeira consulta abaixo é um programa console completo; os demais exemplos são trechos de procedimentos.

Configurar o cliente

  1. Prepare a credencial

    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.

    Para esta primeira consulta, use uma chave Sandbox com Consultar clientes. A requisição lê somente uma página; não cria clientes nem solicita e-mails.

  2. Salve o exemplo de consulta

    Crie um projeto Console Application de backend e substitua seu .dpr pelo arquivo abaixo. Use o Search path configurado na instalação.

    ReadCustomers.dpr
    pascal
    program ReadCustomers;
    
    {$APPTYPE CONSOLE}
    
    uses
      System.SysUtils, System.JSON,
      Raims.Client, Raims.Core, Raims.Params, Raims.Models;
    
    var
      Client: TRaimsClient;
      Options: TRaimsClientOptions;
      Params: TListCustomersParams;
      Customers: TCustomerListResponse;
      Items: TJSONArray;
    begin
      Options := TRaimsClientOptions.Default;
      Options.TimeoutMilliseconds := 80000;
      Options.MaxNetworkRetries := 0;
      Client := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_API_KEY'), Options);
      try
        Params := TListCustomersParams.Create;
        try
          Params.SetPageSize(10);
          Customers := Client.Customers.List(Params);
          try
            Items := Customers.GetArray('list');
            Writeln('HTTP status: ', Customers.LastResponse.StatusCode,
              '; items: ', Items.Count);
          finally
            Customers.Free;
          end;
        finally
          Params.Free;
        end;
      finally
        Client.Free;
      end;
    end.
  3. Execute e confira o resultado

    Compile e execute o projeto console no IDE, no computador do backend. Items é emprestado da resposta: não o libere separadamente. Os blocos finally liberam os recursos próprios.

    Uma consulta bem-sucedida imprime HTTP status: 200 e a quantidade de itens desta página. items: 0 é um resultado vazio válido na empresa e no ambiente da chave. Não significa falha de autenticação.

O que conferir

O SDK lê o envelope list e page abaixo. Na página vazia, has_next: false indica que não há próxima página. Uma página preenchida também retorna os cadastros; o programa imprime somente a quantidade.

Trecho do exemplo de resposta HTTP 200GET /v1/customers

Nenhum cliente encontrado

JSON
{
  "list": [],
  "page": {
    "page_size": 10,
    "has_next": false,
    "has_previous": false,
    "next_after": null,
    "previous_before": null
  }
}

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

Este é um trecho do backend, depois de carregar o pedido no armazenamento da aplicação. Separe a chave do cliente da chave da cobrança. Salve o payload completo, incluindo valor e título, antes de enviar; nos retries, leia esses dados em vez de gerar novos valores. O trecho usa o Client já aberto; declare as entradas de texto salvas como string, DueDateUnix como Int64 e RequestId como string.

Entrada do pedido salvoOrigem e uso
CustomerTaxIdCPF ou CNPJ do cliente já autorizado e salvo pela aplicação.
CustomerKeyChave da criação deste cliente, salva antes da primeira requisição.
ChargeKeyOutra chave, exclusiva desta cobrança, salva junto do pedido.
DueDateUnixVencimento escolhido e salvo, em segundos Unix UTC.
pascal
var
  CustomerParams: TCreateCustomerParams;
  ChargeParams: TCreateChargeParams;
  Customer: TCustomerCreated;
  Charge: TChargeCreated;
  RequestOptions: TRaimsRequestOptions;
  CustomerId, ChargeId: string;
  HttpStatus: Integer;
  Pending: Boolean;
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
      ChargeId := Charge.Id;
      HttpStatus := Charge.LastResponse.StatusCode;
      RequestId := Charge.LastResponse.RequestId;
      Pending := HttpStatus = 202;
    finally
      Charge.Free;
    end;
  finally
    ChargeParams.Free;
  end;
end;

Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu ID.

Persista no pedido o ID do cliente e o ID da cobrança retornados antes de responder com sucesso ao seu chamador. O ID da cobrança permite retomar a consulta abaixo; as variáveis do SDK não são armazenamento durável.

ResultadoPróximo passo
HTTP 201A cobrança foi criada. Guarde seu ID; a criação não confirma pagamento. Este trecho não solicita e-mail nem emissão de pagamento.
HTTP 202 em uma criação que solicita emissão de pagamentoGuarde o mesmo ID retornado e mantenha o pedido pendente. Consulte essa cobrança; não crie outra para resolver a pendência.
Erro ou ausência de respostaTrate o erro estruturado. Se a execução for incerta, preserve a intenção e reconcilie antes de repetir com a chave e o payload originais.

O exemplo canônico de criação abaixo exibe somente os campos de ID e status:

Trecho do exemplo de resposta HTTP 201POST /v1/charges

Cobrança sem link ou envio de e-mail

JSON
{
  "id": "ch_1Q2W3E4R5T6Y7U8I9O0P",
  "status": 0
}

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:

O trecho de backend abaixo conta até 100 clientes entre as páginas, sem registrar seus cadastros. Mantenha o cliente configurado aberto durante a iteração.

pascal
var
  Page: TCustomerListResponse;
  Visited: Integer;
begin
  Page := Client.Customers.List;
  try
    Visited := Page.AutoPagingEach(
      procedure(CustomerJson: TJSONObject)
      begin
        // Count only; do not store customer data in this example.
      end,
      100);
    Writeln('Items visited: ', Visited);
  finally
    Page.Free;
  end;
end;

Items visited: 0 indica que a consulta não encontrou clientes. 100 indica que o limite escolhido foi atingido; não comprova o fim dos cadastros. Um erro de página interrompe a contagem. Se o seu job precisar retomar depois, salve o progresso somente após processar uma página completa.

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 mantém o resultado pendente. Não confirma pagamento e o SDK não inicia polling. Ao retomar o pedido salvo, carregue ChargeId do armazenamento e consulte essa mesma cobrança uma vez:

pascal
var
  Current: TCharge;
begin
  Current := Client.Charges.Retrieve(ChargeId);
  try
    Writeln('HTTP status: ', Current.LastResponse.StatusCode,
      '; charge status: ', Current.Status);
  finally
    Current.Free;
  end;
end;

HTTP 200 aqui confirma que a consulta funcionou. Interprete status e payment_information retornados pela referência da cobrança; um GET bem-sucedido não significa que ela foi paga ou que a emissão terminou. Se a emissão continuar pendente, preserve o mesmo ID. Consultas repetidas não aceleram o processamento nem emitem outro pagamento; contate o suporte se a condição persistir.

Idempotência e erros

pascal
var
  Current: TCustomerListResponse;
  Details: TJSONArray;
  Detail: TJSONObject;
  I: Integer;
begin
  try
    Current := Client.Customers.List;
    try
      Writeln('HTTP status: ', Current.LastResponse.StatusCode,
        '; items: ', Current.GetArray('list').Count);
    finally
      Current.Free;
    end;
  except
    on E: ERaimsApiError do
    begin
      Writeln('HTTP status: ', E.LastResponse.StatusCode,
        '; code: ', E.Code, '; Request-Id: ', E.LastResponse.RequestId);
      Details := E.Details;
      try
        if Details <> nil then
          for I := 0 to Details.Count - 1 do
            if Details.Items[I] is TJSONObject then
            begin
              Detail := TJSONObject(Details.Items[I]);
              Writeln('field: ', Detail.GetValue<string>('field', ''),
                '; code: ', Detail.GetValue<string>('code', ''));
            end;
      finally
        Details.Free;
      end;
    end;
    on E: ERaimsConnectionError do
      Writeln('No conclusive response. Reconcile any uncertain write before retrying.');
  end;
end;

ERaimsApiError.Code retorna error.code; use-o com o status HTTP e LastResponse.RequestId para tratar a falha. ApiMessage contém o texto de diagnóstico da API, enquanto Message é a mensagem genérica da exceção. Nenhuma das mensagens deve controlar a integração. ERaimsConnectionError representa falhas de transporte.

Details retorna um clone de TJSONArray, ou nil quando os detalhes de campos estão ausentes ou são inválidos. Cada cópia pertence ao chamador: guarde-a em uma variável e libere-a em finally, como no exemplo acima. Use System.JSON para ler field e code de cada detalhe. ApiError também retorna uma cópia que o chamador deve liberar. Registre somente os metadados necessários, sem credenciais ou corpos completos.

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.

Por exemplo, se a consulta acima receber HTTP 403 com API_KEY_PERMISSION_DENIED, falta acesso à listagem de clientes na chave. Habilite Consultar clientes na chave apropriada e refaça a leitura. Repetir com as mesmas permissões não resolve esse erro.

Consulte Códigos HTTP das respostas para as demais falhas.

Em uma escrita incerta, recupere a chave salva e todo o payload original. Se recebeu o ID da cobrança, consulte esse ID primeiro. Durante o prazo de retenção da idempotência, um retry compatível pode devolver o resultado preservado, inclusive um 202 pendente. Uma chave com parâmetros diferentes pode ser recusada; não troque o vencimento nem crie outra chave para contornar a incerteza. Após o prazo, reconcilie antes de outra escrita.

Usar o Sandbox

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

pascal
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.

pascal
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.