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/pay

Configure o cliente

Configure estas variáveis no servidor:

VariávelValor
ADILA_PAY_BASE_URLEndereço da API: https://api-pay.adila.co no ambiente de teste
ADILA_PAY_API_KEYAPI key Adila Pay vinculada à sua organização
ADILA_PAY_ORGANIZATION_IDUUID 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.

Cliente no servidor
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:

Listar clientes
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:

Próxima página
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:

Criar cliente
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

ObjetivoMétodos do SDKGuia
Preparar produtos e preçosclient.products.create, client.prices.createCatálogo
Abrir e consultar checkoutclient.checkout.create, client.checkout.retrieveCheckout e assinaturas
Consultar e gerenciar assinaturasclient.subscriptions.list, client.subscriptions.retrieve, client.subscriptions.updateCheckout e assinaturas
Abrir o portal do clienteclient.billingPortal.createCheckout e assinaturas
Consultar saldo e reembolsarclient.balance.retrieve, client.refunds.createReferê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

Tratar uma falha da API
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-pay

O 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/pay

Fora 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/pay

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

Nesta página