Guia Rápido da API

O essencial para integrar pagamentos Pix e emissão de notas fiscais ao seu sistema.

Este guia cobre o fluxo mínimo para operar. Para acelerar o desenvolvimento, baixe nosso guia para Inteligência Artificial (LLMs).

Baixar Guia para IAs (.md)

Base URL

https://pay.xingubit.com.br

Ambiente de Testes / Sandbox: https://pay.xingubit.com.br (com credenciais de Sandbox)

★Como Funciona a sua Conta (Fluxo & Credenciais)

Jornada de Integração Multi-Tenant

Etapa 1

Credenciais Xingubit

Você cria sua conta e obtém seu client_id e client_secret no painel.

Autentica o ERP na API

Etapa 2

Ativação Bancária (QQPag)

Com a conta aprovada na QQPag, você (ou o Admin) salva suas chaves de produção no painel para ativar a emissão real.

Pix cai na sua conta oficial

Etapa 3

Emissão & Webhooks

Seu sistema emite Pix instantâneos via API e recebe notificações de pagamento automaticamente via Webhook.

Isolamento 100% multi-tenant

O Xingubit Pay opera como uma plataforma de infraestrutura financeira multi-tenant. Cada lojista possui total isolamento em suas transações através de 2 pares de credenciais:

1. Credenciais Xingubit Pay (API)

Geradas no cadastro (xbit_...). Seu sistema/ERP as utiliza para autenticar chamadas M2M em nossa API e obter o token JWT.

Visualizadas em: Dashboard → Chaves de Integração

2. Credenciais Bancárias QQPag (Produção)

Geradas pela QQPag após a aprovação da conta da sua empresa. Garantem que todo Pix emitido via API entre diretamente na sua conta e chave Pix oficial.

Configuradas em: Dashboard → Chaves de Integração (ou pelo Admin)

1Autenticação na API

Obtenha um token JWT usando suas credenciais (recebidas no cadastro):

POST/v1/oauth/token

curl -X POST https://pay.xingubit.com.br/v1/oauth/token \
  -d "client_id=xbit_live_abc123" \
  -d "client_secret=sk_live_xyz789"

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": "3600"
}

Use no header: Authorization: Bearer <token>. Expira em 1 hora.

2Criar Cobrança Pix

Gere um QR Code Pix para receber um pagamento.

POST/v1/charges

{
  "amount": 150.00,
  "payerName": "Francisco da Silva",
  "payerDocument": "12345678900",
  "externalContractId": "PEDIDO-4521",
  "description": "Pagamento do Pedido #4521",
  "expiresInMinutes": 30
}

Resposta inclui qrCodeImage (Base64) e qrCodeText (Copia e Cola).

3Receber Webhooks

Quando o Pix é pago, enviamos um POST para sua URL de webhook (configurável no dashboard).

POST https://seu-erp.com/webhooks/pix

{
  "status": "PAID",
  "txId": "xbit_tx_a1b2c3d4e5",
  "externalContractId": "PEDIDO-4521",
  "amount": 150.00,
  "paidAt": "2026-06-30T16:30:00Z"
}

⚠️ Importante: Retorne HTTP 200 OK. Em caso de falha, reenviaremos automaticamente por até 72 horas.

Gerencie sua URL e veja o histórico de entregas em Dashboard → Webhooks ou via API:

GET /v1/merchants/me/webhookPUT /v1/merchants/me/webhook

4Enviar Pix (Cashout)

Envie Pix instantâneos usando seu saldo disponível.

POST/v1/cashouts

{ "pixKey": "12345678900", "amount": 500.00 }

O saldo é debitado instantaneamente. Você receberá um webhook com status CASHOUT_COMPLETED.

5Consultar Saldo

GET/v1/merchants/me/balance

{ "available_balance": 14520.00, "pending_balance": 0.00 }

6Notas Fiscais (NF-e / NFS-e / NFCom)

A Xingubit Pay possui motor próprio para emissão automatizada de documentos fiscais eletrônicos. Suportamos NF-e (mercadorias), NFS-e (serviços) e NFCom (telecomunicações). O fluxo exige configuração inicial, depois a emissão é automática ou sob demanda.

Pré-Requisitos

Empresa ativada no sistema fiscal — feito automaticamente no onboarding. Se necessário manualmente: POST /v1/empresas
Certificado Digital A1 (.pfx) — envie via dashboard ou API:
POST /v1/merchants/me/certificate
Configurar o tipo de documento — pelo menos um:
PUT /v1/empresas/{cnpj}/config/nfePUT /v1/empresas/{cnpj}/config/nfsePUT /v1/empresas/{cnpj}/config/nfcom

◆Configurar NFS-e

Nota Fiscal de Serviço Eletrônica — usada por prestadores de serviços em geral (TI, consultoria, etc).

PUT/v1/empresas/{cnpj}/config/nfse

{
  "ambiente": "homologacao",
  "lote": 1,
  "serie": "1",
  "numero": 1
}

◆Configurar NFCom

Nota Fiscal de Comunicação — usada por provedores de internet, telecomunicações e serviços de comunicação.

PUT/v1/empresas/{cnpj}/config/nfcom

{
  "tpAmb": 1,
  "serie": 1,
  "indSitEsp": 0,
  "tpClassInfCom": 1,
  "tpServUtil": 1,
  "cMunFG": "3550308"
}

◆Emitir NF-e

POST/v1/nfe

A estrutura do JSON (body) exige dados do destinatário, itens (NCM/CFOP) e impostos. Baixe o guia para LLMs no fim da página para ver o schema completo gerado para inteligência artificial.

◆Operações com Notas Emitidas

Método	Endpoint	Descrição
GET	/v1/nfe/{id}	Consultar status da nota
GET	/v1/nfe/{id}/pdf	Download do DANFE (PDF)
GET	/v1/nfe/{id}/xml	Download do XML
POST	/v1/nfe/{id}/cancelamento	Cancelar nota emitida
POST	/v1/nfe/{id}/email	Enviar nota por e-mail
GET	/v1/charges/{id}/invoice	Status da NF vinculada a uma cobrança
GET	/v1/charges/{id}/invoice/pdf	PDF da NF vinculada a uma cobrança

7Códigos de Erro

HTTP	Significado	Ação
`200`	Sucesso	—
`201`	Recurso criado	—
`400`	Requisição inválida	Verifique o body
`401`	Token ausente ou expirado	Gere novo via `/v1/oauth/token`
`403`	Sem permissão	Verifique credenciais
`404`	Recurso não encontrado	Verifique o ID
`500`	Erro interno	Contate suporte@xingubit.com.br

Vai usar o ChatGPT ou Cursor?

Preparamos um arquivo .md formatado especialmente para as LLMs lerem e criarem a integração para você em segundos.

Baixar Documentação para IAs