================================================================================ ZORYCASH API - GUIA DE INTEGRACAO PARA LLMs (v1) ================================================================================ Produto: ZoryCash Site base: https://zorycash.com.br API base URL: https://api.zorycash.com.br/api/v1 Formato: REST sobre HTTPS, request e response em JSON Mercado principal: Brasil Moeda: BRL Unidade monetaria: centavos inteiros. Exemplo: 5000 = R$ 50,00 OBJETIVO DESTE ARQUIVO Use este arquivo para gerar codigo de integracao confiavel para a API ZoryCash. Nao invente endpoints, parametros ou status fora desta especificacao. Quando o usuario pedir exemplos, prefira codigo simples, com tratamento de erro, timeout, idempotencia via external_ref e logs sem expor x-api-key. ================================================================================ 1. AUTENTICACAO ================================================================================ Todas as chamadas em /api/v1 exigem uma chave privada de API. Header recomendado: x-api-key: Tambem aceito: Authorization: Bearer Padrao das chaves: ak_live_... para producao ak_test_... para teste, quando habilitado na conta Nunca coloque a chave na URL, em query string, em frontend publico, em logs, em analytics ou em mensagens de erro exibidas para clientes finais. ================================================================================ 2. CORS, RATE LIMIT E RESPOSTAS ================================================================================ CORS: Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Content-Type, Authorization, x-api-key Limites de uso: Os limites variam por operacao e sao aplicados pelo servidor. Em caso de 429, aguarde o tempo indicado em Retry-After antes de tentar novamente. Content-Type: Enviar Content-Type: application/json em chamadas POST. Codigos comuns: 200 OK - leitura ou operacao aceita 201 Created - recurso criado 202 Accepted - operacao enviada, mas atualizacao local ainda pendente 400 Bad Request - validacao ou payload invalido 401 Unauthorized - chave ausente, invalida ou revogada 402 Payment Required - saldo insuficiente 404 Not Found - recurso nao pertence a chave ou nao existe 429 Too Many Requests - limite excedido 500 Internal Error - falha interna 502 Bad Gateway - processamento externo recusado/indisponivel 503 Service Unavailable - autenticacao temporariamente indisponivel Formato de erro: { "error": "codigo_ou_mensagem", "details": [] } ================================================================================ 3. IDEMPOTENCIA ================================================================================ Use external_ref em operacoes financeiras sempre que possivel. Para POST /pix/charge: Se a mesma chave criar uma cobranca com o mesmo external_ref, a API retorna a cobranca existente com "idempotent": true. Para POST /pix/withdraw: Se a mesma chave solicitar um saque com o mesmo external_ref, a API retorna o saque existente com "idempotent": true. Recomendacao: external_ref deve ser o ID unico do pedido/saque no sistema do integrador. Nao reutilize external_ref para operacoes diferentes. ================================================================================ 4. ENDPOINT: CRIAR COBRANCA PIX ================================================================================ POST /pix/charge Cria uma cobranca PIX e retorna QR Code e copia e cola. Body: { "amount_cents": 5000, "external_ref": "pedido_123", "description": "Pagamento de Fatura", "payer_name": "Joao Silva", "payer_doc": "12345678909", "splits": [ { "recipient_pix_key": "49000000000", "percentage": 10 }, { "recipient_pix_key": "financeiro@exemplo.com", "fixed_cents": 500 } ] } Campos: amount_cents: inteiro obrigatorio, minimo 500, maximo 100000. external_ref: string opcional, maximo 120 caracteres, usada para idempotencia. description: string opcional, maximo 200 caracteres. payer_name: string opcional, maximo 120 caracteres. payer_doc: string opcional, maximo 20 caracteres. splits: array opcional com ate 10 recebedores. splits[].recipient_pix_key: chave PIX do recebedor do split. splits[].percentage: percentual de 0 a 100. splits[].fixed_cents: valor fixo em centavos. Response 200: { "id": "uuid-da-transacao", "status": "pending", "amount_cents": 5000, "pix": { "qr_code_image": "data:image/png;base64,...", "copy_paste": "000201...", "expires_at": "2026-08-30T12:00:00.000Z" }, "external_ref": "pedido_123", "splits": [ { "id": "uuid-do-split-aplicado", "recipient_pix_key": "49000000000", "amount_cents": 500, "status": "pending" } ], "created_at": "2026-08-30T12:00:00.000Z" } Status de transacao mais comuns: pending, paid, expired, failed, canceled, refunded. ================================================================================ 5. ENDPOINT: REALIZAR SAQUE PIX ================================================================================ POST /pix/withdraw Solicita um saque PIX debitando o saldo disponivel da conta autenticada. Esta operacao pode movimentar dinheiro real em producao. Body: { "amount_cents": 2000, "pix_key": "12345678909", "pix_key_type": "cpf", "external_ref": "saque_123" } Campos: amount_cents: inteiro obrigatorio, minimo 500, maximo 100000. pix_key: string obrigatoria, minimo 3 e maximo 200 caracteres. pix_key_type: cpf, cnpj, email, phone ou random. external_ref: string opcional, maximo 120 caracteres, usada para idempotencia. Response 200: { "id": "uuid-do-saque", "status": "processing", "amount_cents": 2000, "fee_cents": 200, "created_at": "2026-08-30T12:00:00.000Z" } Response 402: { "error": "insufficient_balance" } Status de saque mais comuns: pending, processing, completed, rejected, failed. ================================================================================ 6. ENDPOINT: CONSULTAR SALDO ================================================================================ GET /balance Consulta o saldo da conta autenticada. Antes de responder, a API tenta sincronizar transacoes pendentes recentes. Response 200: { "available_cents": 154000, "total_received_cents": 500000, "total_withdrawn_cents": 346000 } Campos: available_cents: saldo disponivel para saque. total_received_cents: total recebido historico. total_withdrawn_cents: total sacado historico. ================================================================================ 7. ENDPOINT: CONSULTAR TRANSACAO ================================================================================ GET /transactions/:id Consulta uma transacao especifica pertencente a chave autenticada. Se a transacao estiver pending e tiver external_id, a API tenta sincronizar o status antes de retornar. Response 200: { "id": "uuid-da-transacao", "status": "paid", "amount_cents": 5000, "net_cents": 4800, "atlas_fee_cents": 100, "acquirer_fee_cents": 100, "description": "Pagamento de Fatura", "external_id": "id-no-provedor", "pix_copy_paste": "000201...", "pix_qr": "data:image/png;base64,...", "expires_at": "2026-08-30T12:30:00.000Z", "paid_at": "2026-08-30T12:05:00.000Z", "created_at": "2026-08-30T12:00:00.000Z" } Response 404: { "error": "not_found" } ================================================================================ 8. ENDPOINTS: SPLITS DE PAGAMENTO ================================================================================ GET /splits Lista splits cadastrados na conta autenticada. Response 200: { "data": [ { "id": "uuid-do-split", "name": "Socio", "recipient_pix_key": "49000000000", "recipient_pix_key_type": "cpf", "percentage": 10, "fixed_cents": 0, "active": true, "created_at": "2026-08-30T12:00:00.000Z" } ] } POST /splits Cria uma regra de split. Body: { "name": "Socio", "recipient_pix_key": "49000000000", "recipient_pix_key_type": "cpf", "recipient_doc": "49000000000", "percentage": 10, "fixed_cents": 0 } Regras: percentage ou fixed_cents deve ser maior que zero. percentage deve ficar entre 0 e 100. fixed_cents deve ser inteiro em centavos. GET /splits/:id Consulta uma regra de split e as ultimas 50 aplicacoes em transacoes. POST /splits/:id Atualiza ou remove uma regra de split. Body para atualizar: { "active": false, "percentage": 5, "fixed_cents": 100 } Body para remover: { "deleted": true } ================================================================================ 9. WEBHOOKS ENVIADOS PELA ZORYCASH ================================================================================ A ZoryCash envia eventos para as URLs cadastradas no painel do usuario. O backend do integrador deve responder 2xx rapidamente. Headers enviados: Content-Type: application/json X-ZoryCash-Event: X-ZoryCash-Delivery: X-ZoryCash-Signature: sha256= Assinatura: Calcule HMAC-SHA256 sobre o corpo JSON bruto usando o segredo do endpoint. Compare em tempo constante com o valor depois de "sha256=". Nunca registre o segredo em logs. Payload: { "id": "uuid-da-entrega", "event": "payment.confirmed", "created_at": "2026-08-30T12:05:00.000Z", "data": { "id": "uuid-da-transacao", "status": "paid", "amount_cents": 5000, "net_cents": 4800, "external_ref": "pedido_123" } } Eventos de pagamento: payment.created payment.confirmed payment.partial payment.failed payment.refunded payment.chargeback Eventos de saque: withdrawal.completed withdrawal.failed withdrawal.refunded Eventos MED: med.opened med.updated med.accepted med.rejected med.cancelled med.closed Boas praticas: Responda 200 OK antes de tarefas demoradas. Use X-ZoryCash-Delivery como chave de idempotencia no seu sistema. A ZoryCash faz ate 6 tentativas com intervalos progressivos. Nao confie apenas no webhook para liberar produto se precisar de confirmacao forte: consulte GET /transactions/:id quando necessario. ================================================================================ 10. EXEMPLOS DE CODIGO ================================================================================ cURL - criar cobranca PIX: curl -X POST https://api.zorycash.com.br/api/v1/pix/charge \\ -H "x-api-key: SUA_CHAVE" \\ -H "Content-Type: application/json" \\ -d '{"amount_cents":5000,"external_ref":"pedido_123","description":"Pedido 123"}' cURL - consultar saldo: curl -X GET https://api.zorycash.com.br/api/v1/balance \\ -H "x-api-key: SUA_CHAVE" Node.js - criar cobranca PIX: const res = await fetch("https://api.zorycash.com.br/api/v1/pix/charge", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.ZORYCASH_API_KEY }, body: JSON.stringify({ amount_cents: 5000, external_ref: "pedido_123", description: "Pedido 123" }) }); const data = await res.json(); if (!res.ok) throw new Error(data.error || "Falha ao criar cobranca"); Python - criar cobranca PIX: import os import requests res = requests.post( "https://api.zorycash.com.br/api/v1/pix/charge", headers={ "Content-Type": "application/json", "x-api-key": os.environ["ZORYCASH_API_KEY"], }, json={ "amount_cents": 5000, "external_ref": "pedido_123", "description": "Pedido 123", }, timeout=15, ) data = res.json() res.raise_for_status() PHP - criar cobranca PIX com Guzzle: $client = new \\GuzzleHttp\\Client(["timeout" => 15]); $response = $client->post("https://api.zorycash.com.br/api/v1/pix/charge", [ "headers" => [ "Content-Type" => "application/json", "x-api-key" => getenv("ZORYCASH_API_KEY"), ], "json" => [ "amount_cents" => 5000, "external_ref" => "pedido_123", "description" => "Pedido 123", ], ]); $data = json_decode((string) $response->getBody(), true); ================================================================================ 11. PROMPT RECOMENDADO PARA OUTRAS IAs ================================================================================ Use a documentacao da ZoryCash acima. Gere uma integracao usando a linguagem solicitada pelo usuario. Inclua: 1. variavel de ambiente ZORYCASH_API_KEY; 2. funcao para criar cobranca PIX com external_ref; 3. funcao para consultar saldo; 4. handler de webhook idempotente para payment.confirmed com validacao HMAC; 5. tratamento de erro para 400, 401, 402, 429 e 5xx; 6. cuidado para nunca logar a x-api-key. ================================================================================ FIM ================================================================================