Documentação da API v1 (legada)
Para integrações novas, utilize o guia atual de API V2 exibido no início desta página. Integre cobranças Pix no seu site, loja virtual, aplicativo, ERP ou bot do Telegram, usando o back-end do seu sistema.
v1 — API HTTPS, JSON, transações em centavos
AutenticaçãoAPI Key e API Secret por conta/recebedor autorizado. Configure ambos em variáveis de ambiente do seu servidor, nunca em HTML, JavaScript público, aplicativo distribuído ou Telegram.
1. Crie sua conta
Acesse Cadastro ARGUS, selecione pessoa física ou jurídica e forneça os dados solicitados. Após entrar, envie os documentos e acompanhe o status. As credenciais de produção aparecem apenas quando a verificação e a autorização do recebedor estiverem concluídas.
2. Emita API Key e Secret
Em Minha conta, acesse API Key e chave secreta. A Secret aparece apenas uma vez. É possível revogar cada par a qualquer momento. Após a revogação, as integrações que utilizavam esse par deixarão de funcionar.
3. Autenticação e requisições
| Header | Descrição |
|---|---|
X-Argus-Key | API Key pública individual |
X-Argus-Secret | Chave secreta individual, mantida exclusivamente no servidor |
Idempotency-Key | Identificador único da tentativa de cobrança (12–128 caracteres) |
Content-Type | application/json |
4. Gerar uma cobrança Pix
POST /api/v1/pix/charges. Envie o valor em centavos, nome e CPF do pagador e descrição do produto/serviço.
curl -X POST "https://SEU-DOMINIO/api/v1/pix/charges" \
-H "Content-Type: application/json" \
-H "X-Argus-Key: $ARGUS_API_KEY" \
-H "X-Argus-Secret: $ARGUS_API_SECRET" \
-H "Idempotency-Key: pedido-123-20261118" \
-d '{
"amount_cents": 2990,
"payer_name": "Cliente Exemplo",
"payer_document": "CPF_VALIDO_DO_PAGADOR",
"description": "Pedido 123"
}'
Resposta típica após confirmação de criação:
{
"id": "livepix_...",
"merchant_id": "mer_...",
"amount_cents": 2990,
"status": "pending",
"pix_copy_paste": "000201...",
"created_at": "2026-11-18T..."
}O valor de pix_copy_paste é o payload real retornado pela infraestrutura financeira. Construa o QR Code usando uma biblioteca QR local, sem enviar o payload para serviços externos. A cobrança ainda não está paga quando sua criação é confirmada.
5. Consultar cobrança
GET /api/v1/pix/charges/{id} com os mesmos headers de autenticação. Somente cobranças do próprio recebedor são consultáveis.
curl "https://SEU-DOMINIO/api/v1/pix/charges/livepix_ID" \
-H "X-Argus-Key: $ARGUS_API_KEY" \
-H "X-Argus-Secret: $ARGUS_API_SECRET"Status: creating, pending, paid, expired, failed ou unknown. Considere pago apenas o estado conciliado pelo servidor, nunca por mensagem do comprador ou pelo navegador.
6. Exemplo em Node.js para e-commerce
const base = process.env.ARGUS_BASE_URL;
const headers = {
"Content-Type": "application/json",
"X-Argus-Key": process.env.ARGUS_API_KEY,
"X-Argus-Secret": process.env.ARGUS_API_SECRET,
"Idempotency-Key": "order-"+order.id
};
const response = await fetch(base + "/api/v1/pix/charges", {
method: "POST", headers,
body: JSON.stringify({
amount_cents: order.amount_cents,
payer_name: customer.name,
payer_document: customer.cpf,
description: "Pedido "+order.id
})
});
const payment = await response.json();
if (!response.ok) throw new Error(payment.detail || "Cobrança recusada");
// Armazene payment.id. Não marque pedido pago neste momento.
7. Integração com Telegram
Coloque os tokens do Telegram e as credenciais ARGUS no servidor do seu bot. Ao receber um pedido, seu back-end chama a API e envia ao chat o código pix_copy_paste. Consulte o estado do pagamento pelo ID a partir do seu servidor; nunca publique a chave secreta no bot ou em mensagens.
Não existe endpoint público para criar bot Telegram automaticamente: o bot é configurado por você, e as credenciais ARGUS funcionam em chamadas HTTPS server-to-server.
8. Segurança, limites e erros
- 401/403: autenticação inválida, chave revogada ou recebedor sem autorização.
- 409: reutilização incompatível de Idempotency-Key ou cobrança já reservada.
- 422: campos ou documentos inválidos.
- 502/503: integração ou infraestrutura indisponível — não repita cobranças incertas usando outra chave.
- Para cobranças com estado
unknown, preserve o identificador e solicite conciliação antes de refazer. - Durante operação temporária, podem existir limites específicos de valor e condições adicionais de habilitação.
9. Validação de documentos e privacidade
A análise automática inicial verifica CPF/CNPJ, integridade, formato e tamanho do arquivo. A identidade, autenticidade documental, correspondência do titular e elegibilidade financeira exigem avaliação especializada. Arquivos só serão recebidos se houver armazenamento persistente com criptografia ativada.
A geração real de Pix é permitida apenas a contas aprovadas e com integração financeira configurada. Esta documentação não garante habilitação comercial automática. Funções de boleto, cartão, saque, estorno e webhook de cliente não fazem parte desta API v1 publicada; não integre endpoints inexistentes.
