Bem-vindo à documentação técnica da Qesh!
Tudo que você precisa para integrar com a API da Qesh: guias de início rápido, glossário, referências e canais de suporte.
Seja bem-vindo à documentação técnica da Qesh! Aqui você encontrará tudo o que precisa para integrar o seu sistema com a nossa plataforma de pagamentos Pix.
Sobre a Qesh
A Qesh é uma plataforma de pagamentos instantâneos que oferece uma API robusta para operações Pix. Com ela, você pode:
- Receber pagamentos — Gere cobranças via QR Code dinâmico;
- Enviar pagamentos — Realize transferências Pix por chave, QR Code ou dados bancários;
- Acompanhar movimentações — Consulte saldo, extrato e status de transações em tempo real;
- Receber notificações — Configure webhooks para ser informado sobre eventos automaticamente.
Primeiros Passos
Se esta é a sua primeira vez integrando com a Qesh, recomendamos seguir os guias na ordem abaixo:
| # | Guia | Descrição |
|---|---|---|
| 1 | Guia de Autenticação | Obtenha credenciais e gere tokens JWT para acessar a API |
| 2 | Guia de Pix Avulso | Entenda a visão geral dos fluxos e escolha o caso de uso correto |
| 3 | Guia de Cobrança com QR Code | Implemente recebimento Pix com QR Code dinâmico |
| 4 | Guia de Pagamento com Chave Pix | Implemente envio Pix por chave (CPF/CNPJ/EMAIL/PHONE/EVP) |
| 5 | Guia de Pagamento com QR Code (Pix Copia e Cola) | Implemente envio Pix via EMV (Pix Copia e Cola) |
| 6 | Guia de Pagamento com Dados Bancários | Implemente envio Pix por conta bancária |
| 7 | Guia de Devoluções Pix | Inicie e acompanhe devoluções de transações recebidas |
| 8 | Guia de Webhooks | Configure notificações com validação de assinatura e processamento seguro |
Para detalhes técnicos de cada endpoint, consulte a API Reference.
Ambientes
| Ambiente | Host | Descrição |
|---|---|---|
| IAM | iam.qesh.ai | Autenticação e gerenciamento de identidade |
| API | api.qesh.ai | Operações Pix (cobranças, transferências, saldo) |
Todas as chamadas devem ser feitas exclusivamente via HTTPS.
Canais de Comunicação
Se você precisar de ajuda durante a integração, estamos disponíveis nos seguintes canais:
| Canal | Contato | Quando usar |
|---|---|---|
| Suporte Técnico | [email protected] | Dúvidas técnicas sobre a API e integração |
| Documentação | docs.qesh.ai | Referência da API, guias e exemplos |
Ao entrar em contato com o suporte, sempre informe orequest_idretornado na resposta da API. Isso permite que nossa equipe localize exatamente o que aconteceu nos logs internos.
Glossário
Termos comuns utilizados ao longo da documentação:
| Termo | Descrição |
|---|---|
| JWT | JSON Web Token — padrão de token utilizado para autenticação e autorização nas chamadas à API. |
| Client Credentials | Fluxo OAuth 2.0 onde a aplicação se autentica com client_id e client_secret para obter um token de acesso. |
| Bearer Token | Tipo de token enviado no cabeçalho Authorization para autenticar requisições à API. |
| QR Code Dinâmico | Código QR gerado sob demanda para uma cobrança específica, com valor e vencimento definidos. |
| EMV | Padrão de representação textual de um QR Code Pix (Pix Copia e Cola), contendo os dados codificados da transação. |
| End To End ID (E2E) | Código de 32 caracteres alfanuméricos que identifica de forma única uma transação Pix no ecossistema bancário. |
| TXID | Transaction Identification — identificador da transação Pix atribuído pelo recebedor no momento da cobrança. |
| ISPB | Identificador do Sistema de Pagamentos Brasileiro — código numérico de 8 dígitos que identifica cada instituição financeira. |
| externalID | Identificador opcional definido por você para facilitar a conciliação com o seu sistema interno. |
| HMAC | Hash-based Message Authentication Code — método de verificação de integridade e autenticidade de mensagens usando uma chave secreta. |
| Webhook | Mecanismo de notificação em tempo real onde a Qesh envia uma requisição HTTP ao seu sistema quando um evento relevante ocorre. |
| Envelope | Padrão de resposta da API que encapsula os dados (data) ou erros (error) junto com metadados (meta). |
| request_id | Identificador único de cada requisição retornado no campo meta, utilizado para rastreamento e suporte. |
| Idempotência | Propriedade que garante que uma operação produz o mesmo resultado mesmo quando executada múltiplas vezes. |
Padrão de Respostas da API
Todas as respostas seguem um padrão de envelope consistente:
Resposta de sucesso
{
"success": true,
"data": {
// Dados do recurso
},
"meta": {
"request_id": "c9d911a41d7bc806696be43c4410e65a",
"timestamp": "2026-01-01T15:25:55.249438496Z"
}
}Resposta de erro
{
"success": false,
"error": {
"code": "ERR001",
"message": "An error occurred"
},
"meta": {
"request_id": "12345",
"timestamp": "2026-01-01T12:00:00Z"
}
}Referência Rápida dos Endpoints
Autenticação (iam.qesh.ai)
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /v1/iam/users/login | Gerar token de autorização |
| GET | /v1/iam/public-key | Consultar chave pública de assinatura |
Pix Avulso (api.qesh.ai)
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /v1/connect/charge | Criar cobrança via QR Code |
| GET | /v1/connect/charge/list | Listar cobranças |
| GET | /v1/connect/charge/{id} | Consultar cobrança por ID |
| GET | /v1/connect/charge/txid/{txid} | Consultar cobrança por TXID |
| GET | /v1/connect/charge/external-id/{externalId} | Consultar cobrança por ID externo |
| POST | /v1/connect/transfer/key | Iniciar transferência via chave Pix |
| POST | /v1/connect/transfer/manual | Iniciar transferência via dados bancários |
| POST | /v1/connect/transfer/qrcode | Iniciar transferência via QR Code/EMV |
| GET | /v1/connect/transfer/list | Listar transferências |
| GET | /v1/connect/transfer/id/{id} | Consultar transferência por ID |
| GET | /v1/connect/transfer/external-id/{externalId} | Consultar transferência por ID externo |
| GET | /v1/connect/transfer/end-to-end-id/{endToEndId} | Consultar transferência por E2E |
| POST | /v1/connect/refund | Iniciar devolução |
| GET | /v1/connect/refund/list | Listar devoluções |
| GET | /v1/connect/balance | Consultar saldo |
| GET | /v1/connect/transactions/list | Gerar extrato analítico |
Webhooks (api.qesh.ai)
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /v1/webhook/endpoints | Criar endpoint de webhook |
| GET | /v1/webhook/endpoints/list | Listar endpoints |
| GET | /v1/webhook/endpoints/{id} | Consultar endpoint por ID |
| PUT | /v1/webhook/endpoints/{id}/disable | Desabilitar endpoint |
| PUT | /v1/webhook/endpoints/{id}/enable | Habilitar endpoint |
| GET | /v1/webhook/endpoints/{id}/statistics | Consultar estatísticas do endpoint |
Convenções da Documentação
Ao longo dos guias e da API Reference, utilizamos os seguintes callouts para destacar informações importantes:
Nota — Informações complementares e dicas úteis.
Atenção — Avisos importantes que podem impactar a integração.
Importante — Informações críticas que exigem ação ou cuidado especial.
Alerta — Advertências sobre comportamentos que podem causar problemas.
Próximos Passos
Comece pela autenticação e siga os guias sequencialmente:
- Guia de Autenticação — Configure suas credenciais e gere seu primeiro token.
- Guia de Pix Avulso — Escolha o fluxo ideal por caso de uso.
- Guia de Cobrança com QR Code — Implemente seu primeiro recebimento.
- Guia de Webhooks — Feche o ciclo com confirmação automática de eventos.
Updated 8 days ago
What’s Next