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
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.
Salve o exemplo de consulta
Crie um projeto Console Application de backend e substitua seu
.dprpelo arquivo abaixo. Use o Search path configurado na instalação.ReadCustomers.dpr pascalprogram 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.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 blocosfinallyliberam os recursos próprios.Uma consulta bem-sucedida imprime
HTTP status: 200e 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.
Nenhum cliente encontrado
{
"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 salvo | Origem e uso |
|---|---|
CustomerTaxId | CPF ou CNPJ do cliente já autorizado e salvo pela aplicação. |
CustomerKey | Chave da criação deste cliente, salva antes da primeira requisição. |
ChargeKey | Outra chave, exclusiva desta cobrança, salva junto do pedido. |
DueDateUnix | Vencimento escolhido e salvo, em segundos Unix UTC. |
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.
| Resultado | Próximo passo |
|---|---|
HTTP 201 | A 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 pagamento | Guarde 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 resposta | Trate 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:
Cobrança sem link ou envio de e-mail
{
"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.
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:
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
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:
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.