Integrar com qualquer sistema
O SharkPay é uma API HTTP/JSON comum: qualquer sistema que faça requisições HTTPS e receba webhooks consegue integrar, em qualquer linguagem, sem SDK obrigatório nem plataforma de terceiros.
O padrão de integração (vale para todos)
1. Servidor guarda as chaves
Chave secreta em variável de ambiente/cofre, nunca no cliente.
2. Servidor cria a cobrança
Com Idempotency-Key derivada do pedido; grava a reference junto do pedido.
3. Cliente paga
Exibindo QR Code/copia-e-cola, boleto, ou na página do checkout hospedado.
4. Webhook confirma
Receptor verifica a assinatura, deduplica pelo id e atualiza o pedido; um job concilia pendências.
Cenários
| Sistema | Como integrar | Atenção |
|---|---|---|
| Loja virtual / e-commerce | Plugin ou módulo do seu back-end chama POST /api/pix/create (ou usa o checkout hospedado) ao fechar o pedido; webhook marca como pago. | Valor e tx_ref vêm do carrinho no servidor, nunca do navegador. |
| Sistema próprio / SaaS | Serviço de pagamentos interno encapsula a API; assinaturas recorrentes geram uma cobrança por ciclo (agendador seu). | A API não possui assinaturas/recorrência nativas. |
| App móvel | O app chama o SEU backend; o backend chama o SharkPay e devolve QR/copia-e-cola. | Nunca embuta a chave secreta no app. |
| ERP / CRM | Job de conciliação usa GET /api/invoices com start_date/end_date e baixa títulos pagos; boletos via /api/boleto/create. | Respeite 60 req/min; pagine com limit ≤ 50. |
| Marketplace | Uma cobrança por pedido; a divisão entre vendedores é feita no seu sistema, com saques via /api/pixout/create. | Não existe split nativo. |
| Automações (n8n, Zapier, scripts) | Nós HTTP com Bearer; receptor de webhook com verificação de assinatura. | Guarde segredos no cofre da ferramenta. |
| Agentes de IA | Ferramentas restritas que chamam a API oficial. | Veja a seção de IA; sem acesso irrestrito a credenciais. |
Conciliação
Além do webhook, rode um job periódico: liste as cobranças PENDING mais antigas que alguns minutos e consulte-as por GET /api/invoice/ref/{ref_id}. Isso cobre indisponibilidade do seu receptor além das 8 tentativas.
Mapeando pedido ↔ cobrança
- Use invoice_no = id do seu pedido (busca parcial em GET /api/invoices?invoice_no=).
- Guarde reference (INV-…) devolvida; ela é o identificador de consulta.
- Use Idempotency-Key = "pix-" + id_do_pedido para que reenvios do seu job não dupliquem cobranças.
Qualquer linguagem
Exemplos prontos em cURL, Node.js, Python e PHP estão em Exemplos. Para outras linguagens (Java, C#, Go, Ruby…), gere um cliente a partir do OpenAPI com qualquer gerador aberto (por exemplo, OpenAPI Generator) ou importe a coleção Postman. O OpenAPI é servido pelo próprio SharkPay, sem dependência externa.