SDK PHP

Use o pacote raims/raims-php para integrar uma aplicação de servidor em PHP à API pública. O SDK organiza os recursos em serviços, com respostas tipadas, paginação por cursor e validação de assinaturas de webhook.

Mantenha a chave de API no backend da integração. Não distribua a credencial em código entregue ao navegador ou em aplicações dos seus clientes.

Instalar o pacote

O SDK requer PHP 8.2 ou superior em 64 bits, Composer 2 e as extensões curl, json e hash. No diretório da aplicação:

composer require raims/raims-php

O pacote está no Packagist. Sem informar a versão, o Composer instala a versão estável mais recente compatível com o projeto e registra a restrição em composer.json. Mantenha o composer.lock da aplicação para repetir a instalação da mesma versão. Confira as extensões e a plataforma com composer check-platform-reqs após instalar. O SDK não exige bibliotecas de terceiros em produção.

Configurar o cliente

Obtenha uma chave em Chaves de API e armazene-a em uma variável de ambiente protegida ou no cofre da aplicação. Empresa, ambiente e permissões são determinados pela credencial validada na API. Sandbox e Produção usam https://api.raims.com.

<?php

require __DIR__ . '/vendor/autoload.php';

use Raims\RaimsClient;

$apiKey = getenv('RAIMS_API_KEY');
if ($apiKey === false || $apiKey === '') {
    throw new RuntimeException('Configure RAIMS_API_KEY.');
}

$raims = new RaimsClient($apiKey);
$customers = $raims->customers->all(['page_size' => 20]);

foreach ($customers as $customer) {
    echo $customer->id, PHP_EOL;
}

Reutilize a instância para aproveitar as conexões HTTP. Os próximos trechos consideram a variável $raims configurada pela aplicação.

Criar um cliente e uma cobrança

$customerTaxId é o CPF ou CNPJ válido do cliente autorizado pela aplicação. $customerIdempotencyKey e $chargeIdempotencyKey são chaves distintas, criadas e persistidas antes das requisições. $chargeDueDate é o vencimento escolhido e persistido para o pedido, em segundos Unix UTC.

$customer = $raims->customers->create([
    'tax_id' => $customerTaxId,
], [
    'idempotency_key' => $customerIdempotencyKey,
]);

$charge = $raims->charges->create([
    'customer_id' => $customer->id,
    'amount_cents' => 15000,
    'due_date' => $chargeDueDate,
    'title' => 'Pedido 1234',
], [
    'idempotency_key' => $chargeIdempotencyKey,
]);

$httpStatus = $charge->getLastResponse()->statusCode;
$requestId = $charge->getLastResponse()->getRequestId();

Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro do cliente é atualizado e mantém seu identificador. 15000 representa R$ 150,00. Consulte os campos e condições em Criar cobrança. Para repetir a mesma intenção após perder a resposta, conserve a chave e todos os parâmetros, inclusive o vencimento. A referência externa do pedido não substitui a idempotência.

Paginação e resultados pendentes

all() busca uma página. Enumerar essa página não faz novas requisições. Use nextPage() e previousPage() para navegar; o SDK conserva os filtros e retorna null quando não há página na direção escolhida.

autoPagingIterator() carrega as próximas páginas durante a enumeração e pode fazer várias requisições. Sair do foreach interrompe novas buscas. Copie os cursores recebidos e mantenha os filtros; não envie after e before juntos. Consulte Listagem e paginação.

Uma resposta HTTP 202 mantém o significado de resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na sua aplicação.

Idempotência e erros

Informe idempotency_key nas opções da requisição somente nos endpoints que aceitam Idempotency-Key. O SDK não cria chaves nem repete POST, PATCH ou DELETE automaticamente. Retries de leitura são opcionais; o padrão é zero.

Trate falhas HTTP por ApiErrorException, usando getHttpStatus() e getErrorCode(). getRequestId() ajuda a identificar a tentativa. O texto de error.message é um diagnóstico humano e não deve ser comparado como código de controle. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Consulte Idempotência e o guia de erros do SDK.

Em atualizações, omitir um campo preserva seu valor. Enviar null limpa somente os campos cujo contrato permite essa ação. Um objeto vazio em uma entrada usa (object) []; um array PHP vazio representa uma lista. Veja as condições de cada endpoint.

Usar o Sandbox

Use uma chave Sandbox para as simulações em $raims->simulations->charges e $raims->simulations->refunds. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. As regras e condições estão na referência de Simulações.

Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração.

Receber webhooks

Leia o corpo original e os headers recebidos pelo seu servidor:

use Raims\Exception\SignatureVerificationException;
use Raims\Webhook;

$payload = file_get_contents('php://input');
if ($payload === false) {
    throw new RuntimeException('Unable to read the request body.');
}

$headers = [
    'webhook-id' => $_SERVER['HTTP_WEBHOOK_ID'] ?? '',
    'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '',
    'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '',
];

try {
    $event = Webhook::constructEvent($payload, $headers, $webhookSecret);
} catch (SignatureVerificationException $error) {
    http_response_code(400);
    exit;
}

$webhookSecret é o secret_key retornado ao criar ou rotacionar o webhook, e não a chave Bearer da API. Preserve os bytes originais e não reserialize o JSON antes de autenticar. Uma falha gera SignatureVerificationException; não processe o corpo nesse caso.

A assinatura válida não elimina duplicidades. Confira tipo e ambiente, deduplique pelo id do evento e grave o trabalho de forma durável antes de responder com sucesso. O header webhook-id identifica a entrega e não substitui o identificador do evento. Consulte Receber eventos.

Atualizar o SDK

Para buscar a versão estável mais recente, execute novamente o comando sem informar um número de versão:

composer require raims/raims-php

O Composer escolhe a restrição com base nas versões disponíveis e atualiza composer.json e composer.lock. Confira as releases e teste os fluxos usados pela sua integração. A versão do SDK é independente da versão HTTP /v1 da API.

Os guias completos e a referência dos serviços estão no repositório do SDK.