SDKs Node.js, Bun, Python e PHP
Instale o SDK, configure suas credenciais e integre pagamentos no servidor da sua aplicação.
Use o SDK Adila Pay para consultar clientes, preparar seu catálogo, abrir checkouts e gerenciar operações financeiras. O cliente Node.js/Bun tem suporte a JavaScript, TypeScript, ESM e CommonJS; o Python tem clientes síncrono e assíncrono; o PHP se integra ao Laravel.
Distribuição dos pacotes
Node.js/Bun: @adila-sh/pay no npm. Python: adila-pay no PyPI. PHP e Laravel: adila-sh/pay no Packagist. Os três são gerados do mesmo contrato e saem na mesma versão.
Instale no seu projeto
Escolha o gerenciador de pacotes da sua aplicação. Use Node.js 22+ ou Bun:
# npm
npm install @adila-sh/pay
# Bun
bun add @adila-sh/pay
# pnpm
pnpm add @adila-sh/pay
# Yarn
yarn add @adila-sh/payConfigure o cliente
Configure estas variáveis no servidor:
| Variável | Valor |
|---|---|
ADILA_PAY_BASE_URL | Endereço da API: https://api-pay.adila.co no ambiente de teste |
ADILA_PAY_API_KEY | API key Adila Pay vinculada à sua organização |
ADILA_PAY_ORGANIZATION_ID | UUID da organização que vai realizar as operações |
docs.adila.co é o site de documentação. Use o endereço da API no baseUrl. Consulte autenticação e permissões para preparar sua chave.
import { AdilaPayClient } from "@adila-sh/pay";
const baseUrl = process.env.ADILA_PAY_BASE_URL;
const apiKey = process.env.ADILA_PAY_API_KEY;
const organizationId = process.env.ADILA_PAY_ORGANIZATION_ID;
if (!baseUrl || !apiKey || !organizationId) {
throw new Error("Configure as variáveis da integração");
}
const client = new AdilaPayClient({
baseUrl,
apiKey,
timeoutInSeconds: 30,
maxRetries: 2,
});Os exemplos seguintes usam esse client e o organizationId. Em CommonJS, substitua o import por:
const { AdilaPayClient } = require("@adila-sh/pay");Consulte clientes
Sua chave precisa da permissão customers:read:
const customers = await client.customers.list({
organizationId,
limit: 10,
});
const { data, has_more } = customers;
// Use data na aplicação; has_more indica se há outra página.Para continuar uma lista, envie o id do último item como starting_after. Confira se esse identificador é uma string antes de usá-lo:
const lastCustomer = customers.data.at(-1);
if (customers.has_more && typeof lastCustomer?.id === "string") {
const nextPage = await client.customers.list({
organizationId,
limit: 10,
starting_after: lastCustomer.id,
});
// Processe nextPage.data e repita enquanto houver outra página.
}Crie um cliente
Sua chave precisa de customers:write. Persista uma chave de idempotência antes da primeira tentativa e reutilize-a ao repetir a mesma operação:
const customer = await client.customers.create({
organizationId,
"idempotency-key": "cliente-integracao-001",
name: "Cliente de exemplo",
email: "[email protected]",
metadata: { order_id: "pedido-001" },
});Guarde o id retornado para usar o cliente nas próximas operações. Troque a chave de exemplo por uma chave própria para cada nova criação.
Integre os outros recursos
| Objetivo | Métodos do SDK | Guia |
|---|---|---|
| Preparar produtos e preços | client.products.create, client.prices.create | Catálogo |
| Abrir e consultar checkout | client.checkout.create, client.checkout.retrieve | Checkout e assinaturas |
| Consultar e gerenciar assinaturas | client.subscriptions.list, client.subscriptions.retrieve, client.subscriptions.update | Checkout e assinaturas |
| Abrir o portal do cliente | client.billingPortal.create | Checkout e assinaturas |
| Consultar saldo e reembolsar | client.balance.retrieve, client.refunds.create | Referência da API |
Os parâmetros JavaScript e TypeScript mantêm os nomes como starting_after, unit_amount, line_items e "idempotency-key". A referência da API detalha parâmetros e permissões de cada operação.
Trate erros e repetições
import { AdilaPayError } from "@adila-sh/pay";
try {
await client.customers.list({ organizationId, limit: 10 });
} catch (error) {
if (error instanceof AdilaPayError && error.statusCode === 403) {
throw new Error("A API key precisa da permissão customers:read");
}
throw error;
}Confira a credencial em respostas 401 e as permissões em 403. Uma resposta 401 pode ter corpo vazio; use o status para decidir o tratamento. Ajuste timeoutInSeconds e maxRetries de acordo com sua aplicação.
Toda mutação exige uma chave de idempotência de 8 a 255 caracteres. Mantenha a chave e os parâmetros iguais ao repetir a mesma operação. O SDK preserva a chave durante retries. Uma nova operação lógica precisa de outra chave. Consulte idempotência e erros.
Python
O SDK Python oferece clientes síncrono e assíncrono para Python 3.10+:
python -m pip install adila-pay
# ou
uv add adila-payO módulo importado se chama adila_pay. Os parâmetros Python usam snake_case; o cliente converte os nomes para o contrato HTTP.
import os
import httpx
from adila_pay import AdilaPayClient
with httpx.Client(follow_redirects=False) as transport:
client = AdilaPayClient(
base_url=os.environ["ADILA_PAY_BASE_URL"],
api_key=os.environ["ADILA_PAY_API_KEY"],
timeout=30,
max_retries=2,
httpx_client=transport,
)
customers = client.customers.list(
organization_id=os.environ["ADILA_PAY_ORGANIZATION_ID"],
limit=10,
)
customer = client.customers.create(
organization_id=os.environ["ADILA_PAY_ORGANIZATION_ID"],
idempotency_key="cliente-integracao-001",
name="Cliente de exemplo",
metadata={"order_id": "pedido-001"},
)Para aplicações assíncronas:
import asyncio
import os
import httpx
from adila_pay import AsyncAdilaPayClient
async def main():
async with httpx.AsyncClient(follow_redirects=False) as transport:
client = AsyncAdilaPayClient(
base_url=os.environ["ADILA_PAY_BASE_URL"],
api_key=os.environ["ADILA_PAY_API_KEY"],
timeout=30,
max_retries=2,
httpx_client=transport,
)
customers = await client.customers.list(
organization_id=os.environ["ADILA_PAY_ORGANIZATION_ID"],
limit=10,
)
asyncio.run(main())Os contextos httpx.Client e httpx.AsyncClient fecham as conexões ao terminar. O cliente também pode criar seu transporte padrão; passar o transporte permite controlar seu ciclo de vida.
No Python, erros de API expõem status_code em ApiError, importado de adila_pay.core.api_error. Use idempotency_key nas mutações e mantenha a mesma chave em novas tentativas da mesma operação.
PHP e Laravel
O SDK PHP funciona em PHP 8.1+ com qualquer cliente HTTP PSR-18. No Laravel, ele se registra sozinho:
composer require adila-sh/payFora do Laravel, instale também um cliente PSR-18, como guzzlehttp/guzzle. O timeout por requisição exige Guzzle ou Symfony HttpClient. Cada operação recebe um objeto de requisição com os parâmetros em camelCase:
use AdilaPay\AdilaPayClient;
use AdilaPay\Customers\Requests\CreateCustomersRequest;
use AdilaPay\Customers\Requests\ListCustomersRequest;
$client = new AdilaPayClient(getenv('ADILA_PAY_API_KEY'), [
'baseUrl' => getenv('ADILA_PAY_BASE_URL'),
'timeout' => 30,
'maxRetries' => 2,
]);
$customers = $client->customers->list(new ListCustomersRequest([
'organizationId' => getenv('ADILA_PAY_ORGANIZATION_ID'),
'limit' => 10,
]));
$customer = $client->customers->create(new CreateCustomersRequest([
'organizationId' => getenv('ADILA_PAY_ORGANIZATION_ID'),
'idempotencyKey' => 'cliente-integracao-001',
'name' => 'Cliente de exemplo',
'metadata' => ['order_id' => 'pedido-001'],
]));No Laravel, defina ADILA_PAY_API_KEY, ADILA_PAY_BASE_URL e ADILA_PAY_ORGANIZATION_ID no .env. Use o facade AdilaPay ou injete AdilaPayClient, registrado como singleton:
use AdilaPay\Customers\Requests\ListCustomersRequest;
use AdilaPay\Laravel\Facades\AdilaPay;
$customers = AdilaPay::customers()->list(new ListCustomersRequest([
'organizationId' => config('adila-pay.organization_id'),
]));Para ajustar timeout e max_retries, publique a configuração com php artisan vendor:publish --tag=adila-pay-config.
Erros HTTP lançam AdilaPay\Exceptions\AdilaPayApiException, com o status em getCode() e o corpo em getBody(). Falhas de rede e timeouts lançam AdilaPay\Exceptions\AdilaPayException. Nas listas, use $list->data, $list->hasMore e startingAfter.
Atualize o pacote
Para atualizar o SDK com o gerenciador da sua aplicação:
# npm
npm update @adila-sh/pay
# Bun
bun update @adila-sh/pay
# Python
python -m pip install --upgrade adila-pay
# PHP
composer update adila-sh/payConfira a compatibilidade da versão com sua aplicação antes de atualizar em produção.
Prepare a integração para produção
Use API keys somente no servidor. A criação de conta, onboarding e os fluxos de cadastro, requisitos e verificação são realizados por um owner/admin no dashboard.
As requisições são tipadas em TypeScript. As respostas financeiras usam objetos abertos; valide os campos consumidos pela aplicação, como identificadores e URLs. Consulte ambientes, confirmação de pagamentos e produção antes de liberar sua integração.