# Documentação - [Saq — Documentação](/docs): Documentação da API Saq. - Pix Processamento - [Saq](/docs/pix-processamento): API REST de alta performance para operações Pix em produção. Cobre cobranças, saques, transferências internas e callbacks, com processamento em tempo real, 24/7. - **COMEÇAR** - [Conceitos](/docs/pix-processamento/concepts): Antes de fazer a primeira chamada, vale entender o que a API cobre, como os endpoints são agrupados e o que representa uma transação na Saq. Esta página é o mapa mental que você vai usar em todas as outras. - [Primeiros passos](/docs/pix-processamento/getting-started): Em menos de 10 minutos você cria conta, gera credenciais, faz a primeira chamada autenticada e recebe um callback de teste. Este é o caminho mais curto da Saq até a primeira transação Pix funcionando no seu sistema. - [Autenticação](/docs/pix-processamento/authentication): Toda chamada à Saq usa Bearer token. Esta página mostra como enviar, onde guardar com segurança e o que fazer quando aparecer um 401 ou 403. Token é como senha, trata como tal. - Endpoints da API - [Endpoints da API](/docs/pix-processamento/endpoints): 29 endpoints da Saq agrupados em 7 áreas funcionais. Cada endpoint tem schema completo, exemplos em curl/Node/Python/Go/PHP e try-it interativo. - [API Endpoints](/docs/pix-processamento/endpoints/index.en): 29 Saq endpoints grouped into 7 functional areas. Each endpoint has complete schema, examples in curl/Node/Python/Go/PHP and interactive try-it. - [API Endpoints](/docs/pix-processamento/endpoints/index.zh): Saq 的 29 个 endpoints 分为 7 个功能领域。每个 endpoint 包含完整 schema、curl/Node/Python/Go/PHP 示例和交互式 try-it。 - Conta - [Conta](/docs/pix-processamento/endpoints/account): Endpoints para consultar dados da conta autenticada e saldo disponível em tempo real. - [Account Info](/docs/pix-processamento/endpoints/account/get_user): Account profile, permissions, limits and fee rules. - [Account Balance](/docs/pix-processamento/endpoints/account/get_user_balance): Available and blocked balances. - Callbacks - [Callbacks](/docs/pix-processamento/endpoints/callbacks): Inspecionar histórico de callbacks enviados, reenviar manualmente uma entrega individual ou em lote. Útil para auditoria, debug e reprocessamento de falhas. - [List Callbacks](/docs/pix-processamento/endpoints/callbacks/get_user_callbacks): Returns a paginated list of webhook callback logs for the user's transactions. - [Get Callback](/docs/pix-processamento/endpoints/callbacks/get_user_callback_by_id): Returns the details of a specific callback log. - [Re-send callback (single)](/docs/pix-processamento/endpoints/callbacks/resend_user_callback_single): Resend the callback of a single transaction. - [Re-send callbacks (bulk)](/docs/pix-processamento/endpoints/callbacks/resend_user_callbacks): Resend callbacks in bulk for transactions matching the given filters. - Infrações (MED) - [Infrações (MED)](/docs/pix-processamento/endpoints/infractions): Endpoints para lidar com disputas Pix abertas via Mecanismo Especial de Devolução (MED) do Bacen. Listar infrações, ver detalhe, submeter defesa e acompanhar histórico de defesas. - [List Infractions](/docs/pix-processamento/endpoints/infractions/get_infractions): List all infractions for the authenticated user with pagination and filters. - [Get Infraction](/docs/pix-processamento/endpoints/infractions/get_infractions_by_id): Get a specific infraction by ID. - [Create Defense](/docs/pix-processamento/endpoints/infractions/post_infractions_defense): Create a defense for a specific infraction. - [List Defenses](/docs/pix-processamento/endpoints/infractions/get_infractions_defenses): List all defenses for a specific infraction. **Requires support privileges**. - [Get Defense](/docs/pix-processamento/endpoints/infractions/get_infractions_defense_by_id): Get a specific defense for an infraction. **Requires support privileges**. - Transferência interna - [Transferência interna](/docs/pix-processamento/endpoints/internal-transfer): Move saldo entre duas contas Saq sem passar pelo Pix tradicional. Liquidação instantânea, identificação por accountNumber. Ideal para repasses matriz/filial, marketplaces e payouts entre clientes Saq. - [Create internal transfer](/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer): Send funds to another Saq account using its 6-digit accountNumber. Settles instantly within Saq. - [Get internal transfer](/docs/pix-processamento/endpoints/internal-transfer/get_internal_transfer): Retrieve an internal transfer by id or clientReference Use apenas um destes parâmetros: id, clientReference. Combinar mais de um retorna erro. - Cobranças Pix - [Cobranças Pix](/docs/pix-processamento/endpoints/pix-operations): Endpoints para criar cobranças Pix dinâmicas (depósitos), consultar status, renderizar QR Code e baixar comprovante. - [Create Charge (Pix deposit)](/docs/pix-processamento/endpoints/pix-operations/post_pix): Create a new Pix **deposit** (charge). Returns QR Code and transaction details. - [Retrieve Charge](/docs/pix-processamento/endpoints/pix-operations/get_pix): Get the latest status and details for a Pix **deposit (charge)**. Provide **one** of `id`, `clientReference`, or `endToEndId`. Use apenas um destes parâmetros: id, clientReference, endToEndId. Combinar mais de um retorna erro. - [Render Pix QR code (PNG)](/docs/pix-processamento/endpoints/pix-operations/get_pix_qrcode): Render the Pix QR Code of a deposit as a binary PNG image - [Get Transaction Receipt](/docs/pix-processamento/endpoints/pix-operations/get_proof): Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique pra exibir ou salvar como `.pdf`. - Relatórios - [Relatórios](/docs/pix-processamento/endpoints/reports): Histórico de transações, relatórios assíncronos em CSV e consulta individual. Use a listagem para tela e conciliação curta, o relatório assíncrono para janelas grandes e BI. - [List Transactions](/docs/pix-processamento/endpoints/reports/get_user_transactions): Paginated list of account transactions with filters. - [List transaction details](/docs/pix-processamento/endpoints/reports/get_user_transaction_by_id): Retrieve a single transaction with its callback log and linked infractions. - [Generate transactions report](/docs/pix-processamento/endpoints/reports/post_user_report): Queue an asynchronous job that generates a CSV report of transactions for the given period and filters. - [List report jobs](/docs/pix-processamento/endpoints/reports/list_user_reports): List report jobs created by the authenticated user. - [List report job status](/docs/pix-processamento/endpoints/reports/get_user_report): List report jobs created by the authenticated user. - [Download report](/docs/pix-processamento/endpoints/reports/download_user_report): Returns a short-lived signed URL to download the CSV file. - Saques - [Saques](/docs/pix-processamento/endpoints/withdrawals): Endpoints para enviar Pix da conta Saq para destinatários externos, por chave Pix ou por leitura de QR Code. Inclui consulta DICT, leitura de QR e download de comprovante. - [Create Withdrawal (Pix key)](/docs/pix-processamento/endpoints/withdrawals/post_withdraw): Send a Pix **cash out** to the specified Pix key. - [Retrieve Withdrawal](/docs/pix-processamento/endpoints/withdrawals/get_withdraw): Get the latest status and details for a **withdrawal**. You can provide any **one** of the following parameters: `id`, `clientReference`, or `endToEndId`. All three are optional and you can use any one of them to retrieve the withdrawal. Use apenas um destes parâmetros: id, clientReference, endToEndId. Combinar mais de um retorna erro. - [Create Withdrawal using QR Code](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode): Cash out using a **Pix QR Code** (static/dynamic). If `amount` is not provided, the QR Code's embedded value will be used. No momento a Saq só suporta QR Code dinâmico. QR estático ainda não é processado. - [Dict Pix Key Lookup](/docs/pix-processamento/endpoints/withdrawals/get_pix_key): Query the DICT (Diretório de Identificadores de Contas Transacionais) to retrieve information about a Pix key before sending a payment. Returns the key owner's details and associated financial institution. - [Read QR Code](/docs/pix-processamento/endpoints/withdrawals/post_pix_qrcode_read): Decode and extract information from a Pix QR Code (EMV format) before making a payment. Returns the parsed data including receiver details, amount (if present), and other QR Code metadata. No momento a Saq só suporta QR Code dinâmico. QR estático ainda não é processado. - [Get Withdrawal Receipt](/docs/pix-processamento/endpoints/withdrawals/get_withdraw_proof): Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique pra exibir ou salvar como `.pdf`. - **GUIAS** - Tutoriais - [Tutoriais](/docs/pix-processamento/tutoriais): Fluxos reais de produção combinando os endpoints da Saq, desde receber um Pix simples até lidar com uma disputa MED. Cada tutorial tem código pronto em curl, Node, Python, Go e PHP. - [Receber pagamento Pix](/docs/pix-processamento/tutoriais/receive-pix): Fluxo completo para receber dinheiro de um cliente via Pix. Você cria a cobrança, exibe o QR Code, processa o callback de COMPLETED e implementa polling como fallback. Código pronto em curl, Node, Python, Go e PHP. - [Enviar Pix](/docs/pix-processamento/tutoriais/send-pix): Dois caminhos para enviar Pix da sua conta Saq para um destinatário externo. Saque por chave Pix (com validação DICT) ou pagar QR Code. Inclui acompanhamento de status e download de comprovante. - [Transferência interna](/docs/pix-processamento/tutoriais/internal-transfer): Quando origem e destino são contas Saq, você pode mover saldo entre elas sem passar pelo Pix tradicional. Liquidação instantânea, identificação por accountNumber. Ideal para repasses internos entre matriz/filial ou pagar parceiros Saq. - [Conciliação](/docs/pix-processamento/tutoriais/reconciliation): Mesmo com callbacks confiáveis, todo sistema sério bate as transações da Saq com o banco interno diariamente. Aqui você aprende a listar transações em tempo real, gerar relatórios assíncronos para janelas grandes e usar clientReference para fechar o ciclo. - [Infrações (MED)](/docs/pix-processamento/tutoriais/infractions): O MED é o processo do Bacen para contestar Pix em casos de fraude ou erro do pagador. Quando uma cobrança recebida vira disputa, a Saq cria uma infração e você tem prazo curto para responder com defesa. - [Webhooks](/docs/pix-processamento/webhooks): O sistema de webhooks da Saq envia notificações em tempo real sobre mudanças de status de transações. Ao criar uma transação e fornecer um callbackUrl, atualizamos automaticamente sua aplicação a cada mudança. Inclui retry com backoff exponencial de até 72 tentativas. - Boas práticas - [Boas práticas](/docs/pix-processamento/best-practices): Padrões testados em produção que separam uma integração que dura uma semana de uma que aguenta produção. Idempotência, multi-tenant, callbacks, paginação, dinheiro, segurança, tratamento de erros e checklist final. - [Idempotência](/docs/pix-processamento/best-practices/idempotency): clientReference é a sua chave de idempotência e callbacks chegam mais de uma vez. Como combinar os dois para que retries não viram cobranças duplicadas nem baixas em dobro. - [Multi-tenant com virtualAccount](/docs/pix-processamento/best-practices/multi-tenant): Uma só conta Saq pode atender N tenants (lojas, filiais, marketplaces) usando virtualAccount. Volta em todo callback, permite filtrar listagens e dispensa criar contas filhas. - [Lidando com callbacks](/docs/pix-processamento/best-practices/callbacks): Responda em menos de 5 segundos, enfileire o processamento pesado, deduplique por id + status e teste localmente com ngrok. O retry da Saq é robusto, mas só funciona se o seu handler se comportar bem. - [Paginação](/docs/pix-processamento/best-practices/pagination): Endpoints de listagem (transações, callbacks, infrações) usam paginação clássica por page + limit com flag hasNextPage. Para janelas grandes prefira o relatório assíncrono em CSV. - [Dinheiro e precisão](/docs/pix-processamento/best-practices/money): A Saq Pix API usa reais com casas decimais, não centavos. Como armazenar internamente sem perder precisão, converter na borda e respeitar os limites mínimos de cada operação. - [Segurança](/docs/pix-processamento/best-practices/security): Token Bearer é a única credencial da Saq. Trate como senha. Esta página cobre armazenamento, rotação, mascaramento em log, proteção do webhook por IP e validação DICT antes de pagar. - [Consulta DICT](/docs/pix-processamento/best-practices/dict): O DICT é o banco central do Bacen que guarda todas as chaves Pix registradas no Brasil. Consultar antes de pagar valida que a chave existe, mostra o titular para confirmação e reduz pagamentos para destinatários errados. - [Tratamento de erros](/docs/pix-processamento/best-practices/errors): 4xx é erro seu (não retentar), 5xx é da Saq (retry com backoff), 429 é rate limit (aguardar) e timeout exige cuidado especial porque a operação pode ter sido aplicada. Esta página tem helper de retry e estratégia de logging. - [Checklist de produção](/docs/pix-processamento/best-practices/checklist): Lista verificável dos itens que sua integração precisa antes de receber tráfego real. Cobre idempotência, callbacks, dinheiro, segurança, conciliação e observabilidade. - **SEGURANÇA** - [2FA (Autenticação em dois fatores)](/docs/pix-processamento/two-factor): A 2FA é obrigatória para criar tokens de API e processar saques pelo dashboard. Use qualquer app autenticador TOTP (Google Authenticator, Microsoft Authenticator, 1Password, Authy ou similar) para gerar os códigos de 6 dígitos. - [TrueHolder](/docs/pix-processamento/trueholder): Trava de segurança que valida a titularidade do documento (CPF/CNPJ) antes de processar a transação. Funciona tanto em cash-in (depósito) quanto em cash-out (saque), bloqueando movimentações fora do titular autorizado. - [MED (Mecanismo Especial de Devolução)](/docs/pix-processamento/med): Procedimento do Bacen para proteger usuários Pix em casos de fraude, golpe ou transações não autorizadas. Quando uma atividade suspeita é identificada, a instituição do pagador abre um processo formal pedindo o estorno do valor. - **REFERÊNCIA** - [Tipos de chave Pix](/docs/pix-processamento/pix-key-types): Tipos de chave Pix aceitos pela API Saq, formato esperado de cada um e regras de validação. - [Glossário](/docs/pix-processamento/glossary): Termos, siglas, status e campos que aparecem na Saq. Se você ficou travado em uma sigla do Bacen ou um campo da API, é aqui. Tudo em PT com o nome original quando relevante. - [Para IAs (LLMs)](/docs/pix-processamento/for-ai): Toda a documentação da Saq disponível em formato consumível por modelos de linguagem. Copie o conteúdo direto, baixe o dump completo, ou use as URLs específicas por página. Funciona com ChatGPT, Claude, Gemini, Cursor, Copilot, etc. - **VISUALIZAR API** - [Scalar](https://docs.saq.processamento.com/api-scalar) - [Swagger UI](https://docs.saq.processamento.com/api-swagger) - [OpenAPI JSON](https://docs.saq.processamento.com/openapi.json)