# SDKs Z.PAY para assistentes de IA

Referência: https://zpaysolution.com/docs/#sdk
Índice da API: https://zpaysolution.com/llms.txt
Produto: https://zpaysolution.com/llm.txt
Versão dos SDKs: 0.1.0. JavaScript/TypeScript (Node.js 18+), Python 3.10+,
PHP 8.1+ (cURL/JSON) e Go 1.20+. Uso exclusivamente no servidor.
Cada cliente cobre os mesmos 46 métodos. A lista abaixo usa a sintaxe JavaScript;
consulte as diferenças de instalação e sintaxe das outras linguagens ao final.

## Instalação e disponibilidade

Instalação principal: npm install @isnouu/zpay-sdk
O pacote @isnouu/zpay-sdk 0.1.0 está disponível no npm.
Você também pode instalar pelo arquivo alternativo abaixo.
Distribuição por arquivo: https://zpaysolution.com/downloads/zpay-sdk-0.1.0.tgz
Após baixar o arquivo, execute: npm install ./zpay-sdk-0.1.0.tgz
O pacote contém cliente, tipos index.d.ts, README e exemplo Pix.
Os arquivos e endpoints descritos precisam estar publicados na Z.PAY usada.

## Autenticação

import { ZPay, ZPayError } from '@isnouu/zpay-sdk';
const zpay = new ZPay({
  clientId: process.env.ZPAY_CLIENT_ID,
  clientSecret: process.env.ZPAY_CLIENT_SECRET,
  timeoutMs: 30000,
});

CommonJS: const { ZPay, ZPayError } = require('@isnouu/zpay-sdk');
Base padrão: https://zpaysolution.com/api/v1
baseUrl opcional deve incluir /api/v1. HTTPS obrigatório, exceto localhost.
O SDK envia client-id e client-secret como headers; não coloque segredos em URLs.
Não use token zadm_ nem JWT do login como clientSecret.
Nunca coloque as credenciais no frontend, app distribuído ou repositório público.
O SDK não fornece autenticação nem operações de conta por token zadm_.

## Pix

const payment = await zpay.payments.create({
  amount: 19.90,
  payerName: 'Cliente',
  description: 'Pedido 123',
  idempotencyKey: 'pedido-123',
});
// Retorno: paymentId, status, copyPaste, qrCodeBase64 e demais campos da API.
const current = await zpay.payments.get(payment.paymentId);
// Entregue o produto somente após confirmação de status paid.

Salve a referência do pedido antes de criar a cobrança. Não gere outra referência
após timeout. O SDK exige idempotencyKey nos métodos que oferecem esse campo.

## Métodos disponíveis

account.stats(filtros?), account.fees()
payments.create(dados), payments.get(id), payments.payer(id)
donations.list(filtros?), donations.top(filtros?)
checkouts.create(dados), checkouts.get(id)
withdrawals.create({amount, idempotencyKey, subaccountId?})
withdrawals.get(idOuReferencia), withdrawals.list(filtros?)
cashouts.create({amount, pixKey, pixKeyType, idempotencyKey, subaccountId?})
cashouts.create({qrCode, amount?, idempotencyKey, subaccountId?}), cashouts.get(id)
refunds.create({transactionId})
transfers.recipient(destino), transfers.create({to, amount, idempotencyKey, description?})
boletos.create({amount, payerName, payerEmail, payerDocument, idempotencyKey, dueDays?})
billPayments.preview({line, amount?})
billPayments.create({line, amount?, idempotencyKey, description?})
billPayments.list(filtros?), billPayments.get(id)
meds.list(filtros?), meds.get(id)
subaccounts.create({name, externalId, email?, metadata?})
subaccounts.list(), subaccounts.get(id), subaccounts.update(id, dados)
subaccounts.block(id), subaccounts.unblock(id), subaccounts.delete(id)
subaccounts.transactions(id, filtros?)
subaccounts.fund(id, {amount, idempotencyKey, description?})
subaccounts.transfer(id, {to, amount, idempotencyKey, description?})
subaccounts.payout(id, {amount, idempotencyKey, description?})
subaccounts.withdraw(id, {amount, idempotencyKey, description?})
splits.create({value, type, amount, split_account, payerName?, description?})
splits.pix({value, splits, ...outrosCamposDocumentados}), splits.get(id)
crypto.createPayment(dados), crypto.getPayment(paymentId)
crypto.balance(), crypto.summary(), crypto.operation(id)
crypto.swap(dados), crypto.withdraw(dados)

Use somente métodos desta lista e campos descritos nos tipos do pacote e na API.
Não invente zpay.balance(), pix.create(), payments.approve(), verifyWebhook(),
webhooks.verifySignature() ou classes de sandbox não implementadas.
Para operações não cobertas pelo SDK, use HTTP nos endpoints documentados.
Cartão: use checkout hospedado; não receba número de cartão pelo SDK.

## Unidades e respostas

amount é em reais, exceto crypto.withdraw(), onde representa LTC.
splits.create(): value é em centavos; amount é percentual inteiro no modo
percentage ou centavos no modo fixed. Não converta todas as quantias para centavos.
O SDK devolve as respostas da API sem transformar seus status.
HTTP 202, pending, dispatching e review não significam pagamento concluído.
Listas paginadas não são percorridas automaticamente.
Cada método aceita {signal: AbortSignal} como último argumento opcional.
O cliente não cria loops de polling e não repete requisições automaticamente.

## Cripto pela Purin

const charge = await zpay.crypto.createPayment({
  requestId: 'ltc-pedido-123', amount: 50,
  currency: 'brl', payCurrency: 'ltc', payerName: 'Cliente',
});
// Mostre charge.payAddress e charge.payAmount, preservando oito casas LTC.

const swap = await zpay.crypto.swap({
  requestId: 'swap-pedido-456', amount: 100,
  address: carteiraConfirmadaPeloUsuario,
  confirmNotCoinbase: true, acceptProviderRate: true,
  // totpCode: codigo2faDaConta, quando exigido
});
const updated = await zpay.crypto.operation(swap.id);

Recebimento novo: somente LTC na rede Litecoin, valor solicitado em BRL.
USDT BEP20 está disponível na saída: swap do saldo BRL, não do saldo LTC.
Não use /payments/usdt para criar uma cobrança nova. Saldo legado USDT é separado.
Não invente uma cotação antecipada: a Purin define a taxa de conversão no envio.
Exiba receiveUSDT e rateBRLPerUSDT somente quando presentes no retorno.
Custos da Purin dependem da conta e precisam estar confirmados no Admin.
O SDK não libera KYC, telefone, 2FA, limites nem a carteira configurada no provedor.
requestId cripto: de 8 a 120 caracteres, letras, números, ponto, dois-pontos,
hífen ou sublinhado; salve a referência antes de enviar.

## Erros e operações com resultado incerto

ZPayError expõe status, code, details, retryAfter e outcomeUnknown.
Timeout ou cancelamento após envio pode deixar outcomeUnknown=true.
Consulte a operação/referência original antes de tentar novamente; não gere outra
idempotencyKey ou requestId para contornar uma resposta incerta.
Cancelar a requisição não cancela o pagamento, envio ou saque na Z.PAY.
Checkouts e splits não oferecem idempotência de criação nesta versão da API.
Não repita suas criações automaticamente. Reembolsos usam a transação original.
Nenhum teste de integração deve movimentar fundos reais sem instrução do usuário.

## Prompt sugerido

Leia https://zpaysolution.com/sdk.txt e https://zpaysolution.com/llms.txt.
Integre meu projeto Node.js/TypeScript à Z.PAY com o SDK @isnouu/zpay-sdk documentado.
Instale com npm install @isnouu/zpay-sdk ou use a distribuição por arquivo como alternativa.
Guarde credenciais somente nas variáveis de ambiente do backend. Crie cobranças
com zpay.payments.create e consulte zpay.payments.get. Persista idempotencyKey e
paymentId. Trate ZPayError sem reenvio automático após resultado incerto. Use os
eventos e endpoints de webhook documentados, com deduplicação. Não invente métodos,
não confirme uma venda com status pending e não envie fundos reais durante testes.


## SDK Python via pip

Python 3.10+, sem dependências de execução. Ainda não publicado no PyPI.
Repositório: https://github.com/Felix404snow/zpay-sdk-python
Download público: https://github.com/Felix404snow/zpay-sdk-python/releases/download/v0.1.0/zpay_sdk-0.1.0-py3-none-any.whl
Instalação: python -m pip install https://github.com/Felix404snow/zpay-sdk-python/releases/download/v0.1.0/zpay_sdk-0.1.0-py3-none-any.whl
Importação: from zpay import ZPay, ZPayError
Cliente: client = ZPay(os.environ['ZPAY_CLIENT_ID'], os.environ['ZPAY_CLIENT_SECRET'])
Exemplo: client.payments.create({'amount': 19.9, 'payerName': 'Cliente', 'idempotencyKey': 'pedido-123'})
Consulta: client.payments.get(payment['paymentId'])
Grupos em snake_case: bill_payments. Cripto: create_payment e get_payment. Os demais grupos e métodos mantêm os nomes em minúsculas, como withdrawals.create e subaccounts.fund.
Campos de API continuam camelCase (idempotencyKey/requestId). Respostas são dicionários.
Erros ZPayError: status, code, details, retry_after, outcome_unknown.
Construtor: base_url opcional, timeout em segundos (padrão 30) e transport para testes.
Não invente uma publicação PyPI: o comando público instala o wheel da versão GitHub, sem exigir conta PyPI.

## SDK PHP via Composer

PHP 8.1+, cURL e JSON; ainda não publicado no Packagist.
Download: https://zpaysolution.com/downloads/zpay-sdk-php-0.1.0.tar.gz
Repositório público: https://github.com/Felix404snow/zpay-sdk-php
Configure: composer config repositories.zpay vcs https://github.com/Felix404snow/zpay-sdk-php
Instale: composer require isnouu/zpay-sdk:^0.1
Cliente: $client = new \ZPay\Client(getenv('ZPAY_CLIENT_ID'), getenv('ZPAY_CLIENT_SECRET'));
Exemplo: $client->payments->create(['amount' => 19.9, 'payerName' => 'Cliente', 'idempotencyKey' => 'pedido-123']);
Grupos/métodos camelCase como JavaScript, via propriedades PHP: billPayments, crypto->createPayment.
Respostas são arrays associativos. Erros ZPay\ZPayError: status, errorCode, details, retryAfter, outcomeUnknown.
Timeout em segundos (padrão 30), baseUrl opcional. Não invente publicação Packagist.

## SDK Go

Go 1.20+, somente biblioteca padrão. Repositório público e tag v0.1.0 publicados.
Download: https://zpaysolution.com/downloads/zpay-sdk-go-0.1.0.tar.gz
Repositório e module path: github.com/Felix404snow/zpay-sdk-go
Instale: go get github.com/Felix404snow/zpay-sdk-go@v0.1.0
Importe zpay "github.com/Felix404snow/zpay-sdk-go" no seu código.
Cliente: client, err := zpay.New(os.Getenv("ZPAY_CLIENT_ID"), os.Getenv("ZPAY_CLIENT_SECRET"), nil)
Exemplo: client.Payments.Create(ctx, zpay.Object{"amount": 19.9, "payerName": "Cliente", "idempotencyKey": "pedido-123"})
Métodos/grupos exportados em PascalCase: Account.Fees, BillPayments.Preview, Crypto.CreatePayment, Crypto.Swap, Crypto.Operation. Contexto é sempre o primeiro argumento.
Respostas Object (map[string]any), números preservados como json.Number; Query é map[string]string.
Use errors.As para *zpay.Error; campos Status, Code, Message, Details, RetryAfter, OutcomeUnknown.
Opções BaseURL, Timeout (time.Duration), HTTPClient. Cancelamento por context não cancela a operação na API.

Todos os clientes exigem referências persistentes nos métodos suportados e nunca reenviam automaticamente. Não convertem unidades nem interpretam pending/202 como pagamento concluído. As versões GitHub v0.1.0 já estão públicas e suas instalações foram verificadas. Os links alternativos no domínio Z.PAY dependem da publicação da atualização do site.