# Contexto da API NxGate (para IA)

Fonte: documentação oficial da NxGate (nxgate.com.br/doc). Use este texto como a especificação da integração; não invente campos, rotas ou eventos que não estão aqui.

## Básico
- Base URL: https://api.nxgate.com.br (só HTTPS). Para testar sem dinheiro de verdade existe o sandbox: https://sandbox.nxgate.com.br com a chave de teste nxg_test_… (veja "Sandbox" abaixo).
- Todas as rotas são POST, com corpo JSON e header Content-Type: application/json.
- Autenticação: campo "api_key" no corpo JSON (não existe header de autenticação).
- Escopos de chave: full (tudo), cashin (cobrança e consulta), cashout (saque), saldo (saldo).
- A api_key é segredo de servidor: variável de ambiente, nunca no front-end, no app ou no repositório. Chamadas de navegador são bloqueadas (CORS).
- Valores em dinheiro são decimais na moeda (150.50 = R$ 150,50). Exceção: split fixo, em centavos.
- Moedas liberadas agora: BRL.

## Sandbox (testes, sem dinheiro de verdade)
- Base URL: https://sandbox.nxgate.com.br, com a chave de teste nxg_test_… (gerada no painel em API → Sandbox). A chave de teste recebe 401 na produção, e a chave de produção recebe 401 no sandbox.
- Mesmas rotas, respostas, erros e webhooks da produção (mesmo payload, headers e assinatura). No sandbox o segredo HMAC do webhook é a própria chave de teste.
- A instrução de pagamento é fictícia e nada acontece sozinho: simule com POST /v2/sandbox/simular {"api_key", "transaction_id", "resultado"} (transaction_id = idTransaction da cobrança ou internalreference do saque).
  - Cobrança: "pago" (webhook QR_CODE_COPY_AND_PASTE_PAID), "expirado", "estornado", "disputa" (esses três sem webhook, como na produção).
  - Saque: "pago" (PIX_CASHOUT_PAID), "erro" (PIX_CASHOUT_ERROR; "motivo" opcional: generico, chave_invalida, documento, recusado, indisponivel), "estornado" (PIX_CASHOUT_REFUND).
  - Resposta: 200 com "webhook": "disparado" | "sem_url" | "nao_se_aplica"; 404 transação de outra chave; 409 mudança que não vale; 422 resultado inválido.
- /saldo e /pix/sacar não exigem IP liberado no sandbox (na produção exigem).
- Limites baixos: 30 req/min por IP; por chave, 20/min no total, 5 cobranças/min, 5 simulações/min, 2 saques/min, 10 consultas+saldo/min e 200 operações/dia. Acima disso: 429 com Retry-After.
- Para ir à produção, troque só a URL base e a chave (deixe as duas em variáveis de ambiente) e remova as chamadas a /v2/sandbox/simular.

## Idempotência
- Header X-Idempotency-Key com um UUID v4 novo por operação em POST /v2/cobranca e /pix/gerar (vale 5 min) e /pix/sacar (vale 10 min). Guarde a chave junto do pedido/saque.
- Mesma chave depois de uma resposta HTTP 200: a API devolve a mesma resposta (nada novo é criado).
- Mesma chave enquanto a primeira ainda processa: 409 {"status": "error", "message": "Requisicao com esta X-Idempotency-Key ainda esta sendo processada. Aguarde a resposta da requisicao original."}.
- Se a primeira falhou: em /v2/cobranca e /pix/gerar use uma chave nova (a antiga fica presa por até 60 s); em /pix/sacar a chave é liberada, exceto "Saldo insuficiente", que fica guardado por 10 min.
- A chave vale para a API inteira: nunca reuse a mesma chave em operações diferentes.

## POST /v2/cobranca — criar cobrança (escopo cashin)
Corpo:
- api_key (string, obrigatório)
- valor (number, obrigatório): decimal na moeda (COP 10000 = dez mil pesos). Mínimo e máximo por cobrança: BRL 1.00 a 100000.00 (e o limite de cobrança da conta); MXN 20.00 a 5000.00; COP 10000 a 500000; ARS 2000 a 1000000; BOB 10 a 10000. Fora disso: 422.
- moeda (string, opcional): "BRL" (padrão), "MXN", "ARS", "COP" ou "BOB" — use só as liberadas.
- metodo (string, opcional): BRL "PIX"; MXN "SPEI" (padrão); ARS "BANK_TRANSFER"; COP "BREB" (padrão; NEQUI em breve); BOB "QR".
- nome_pagador, email_pagador, descricao (string, opcionais, até 255 caracteres); celular (string, opcional, até 20).
- documento_pagador (string, opcional): BRL = CPF (11) ou CNPJ (14), com ou sem pontuação; sem ele a API usa o CPF/CNPJ da conta. COP e BOB = documento do pagador no país (obrigatório). MXN e ARS = não usado.
- COP e BOB exigem celular, documento_pagador e email_pagador (sem eles: 422).
- webhook (string, opcional): URL pública http(s) — prefira HTTPS; porta 80 a 443 ou de 3000 em diante; localhost e IP privado são recusados.
- magic_id (string, opcional, até 255): seu ID (ex.: do pedido); volta no webhook de pago em data.magic_id.
- split_users (array, opcional): [{"username": "revendedor1", "type": "percentage", "value": 20}, {"username": "parceiro_fixo", "type": "fixed", "value": 500}] — "percentage" = % do valor; "fixed" = centavos inteiros. Total de até 90% do valor (50% abaixo de 2 unidades). A parte de um username inexistente é descontada do vendedor e não vai para ninguém (em BRL).

Resposta 200 (BRL):
```json
{"status": "success", "message": "ok", "paymentCode": "00020101021226850014br.gov.bcb.pix...6304A1B2", "idTransaction": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90", "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAQ4AAAEOCAYAAAB4sfmn...", "currency": "BRL", "paymentMethod": "PIX", "paymentInstruction": {"type": "pix", "pixCopyAndPaste": "00020101021226850014br.gov.bcb.pix...6304A1B2"}}
```
- Guarde idTransaction (texto opaco; o formato varia).
- Mostre paymentCode (copia-e-cola, com botão de copiar) e gere o QR Code a partir dele. Em COP/BREB, mostre também um botão para BAIXAR a imagem do QR: quem compra e paga no mesmo celular salva o QR e lê pela galeria no app do banco. Em BRL, paymentCodeBase64 pode ser a imagem PNG em base64 OU o próprio copia-e-cola em base64, conforme a rede — não dependa dele. Em outras moedas é null.
- paymentInstruction.type: "pix" (pixCopyAndPaste) · "clabe" (clabe; MXN/SPEI) · "cvu" (cvu, beneficiary, bankName; ARS) · "redirect" (url; COP/NEQUI, em breve) · "qr" (qr; BOB e COP/BREB) · "pendente" (instrução ainda sendo gerada: paymentCode null — consulte /v2/consultar em alguns segundos). Tipo desconhecido: mostre o paymentCode.
- Em BRL, /v2/cobranca é a /pix/gerar (mesma taxa e regras) + currency, paymentMethod e paymentInstruction.

Resposta 200 (MXN):
```json
{"status": "success", "message": "ok", "paymentCode": "646180157000000004", "idTransaction": "8f1c2d3e-4b5a-4c6d-8e7f-90a1b2c3d4e5", "paymentCodeBase64": null, "currency": "MXN", "paymentMethod": "SPEI", "paymentInstruction": {"type": "clabe", "clabe": "646180157000000004"}}
```

## POST /v2/consultar — consultar cobrança (escopo cashin)
Corpo: {"api_key": "nx_live_sua_chave_aqui", "transaction_id": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90"}
Resposta 200:
```json
{"status": "paid", "transaction_id": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90", "currency": "BRL", "amount": 150.5, "payment_method": "PIX", "paid_at": "2026-10-05T12:30:00.000Z", "payment_instruction": null}
```
- status: "paid" ou "waiting". Só "paid" confirma. "waiting" = ainda não confirmado (aguardando pagamento ou em análise).
- Enquanto "waiting", payment_instruction traz a instrução (em BRL: {"type": "pix", "pix_copy_and_paste": "..."}); depois de pago, null.
- paid_at: ISO 8601 em UTC (com "Z"), em qualquer moeda; null enquanto não pago.
- Outras moedas: amount_brl (quanto a venda virou em reais no saldo) e converted_at (ISO UTC) depois da conversão para reais; null antes disso e sempre em BRL.
- transaction_id aceita o idTransaction e, em BRL, também o transaction_id do webhook PIX Pendente.
- Erros: 400 {"error": "api_key e transaction_id sao obrigatorios"} · 401 {"error": "API Key invalida"} · 403 {"error": "esta API Key nao tem permissao de geracao de PIX"} · 404 {"error": "Transacao nao encontrada"} · 429 {"error": "Muitas tentativas. Aguarde."}.

## Rotas v1 (continuam valendo, só BRL)
- POST /pix/gerar: mesmo corpo da /v2/cobranca sem moeda e metodo. Resposta: {"status": "success", "message": "ok", "paymentCode": "00020101021226850014br.gov.bcb.pix...6304A1B2", "idTransaction": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90", "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAQ4AAAEOCAYAAAB4sfmn..."}
- POST /pix/consultar: mesmo corpo da /v2/consultar. Resposta: {"status": "paid", "transaction_id": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90"} — não acha cobranças em outras moedas.

## Webhooks (a NxGate faz POST na URL do campo "webhook")
- Headers em todos: User-Agent: NXGATE-Webhook/1.0, Content-Type: application/json, X-NXGate-Timestamp (Unix, segundos), X-NXGate-Signature ("sha256=<hex>"). Os de cobrança também trazem Accept e X-Idempotency-Key (identificador da entrega; muda a cada envio).
- IP de origem de todos os webhooks: 56.125.57.117 (fixo; liberar no firewall é opcional, a assinatura é a garantia).
- Multi-cliente x 1 conta: antes de escrever o código, pergunte ao usuário se a plataforma é multi-cliente (cada cliente cadastra a própria api_key) ou usa 1 conta só (uma api_key). Multi-cliente NÃO valida HMAC: confirma o pagamento só pela consulta (/v2/consultar com a api_key do cliente dono do pedido). A assinatura abaixo é só para integrações de 1 conta.
- Assinatura (só 1 conta): hex = HMAC-SHA256(segredo, X-NXGate-Timestamp + "." + corpo bruto). Segredo = "Segredo de assinatura de webhook (HMAC)" em Painel → API (se não aparecer, é a API key Interna da conta). Compare em tempo constante e recuse timestamp com mais de 300 s de diferença.
- Responda 2xx em até 12 s (cobrança) ou 10 s (saque). Não há reenvio automático; há reenvio manual em Painel → Webhooks. O mesmo evento pode chegar de novo: processe de forma idempotente.
- Não existe webhook de MED/estorno de cobrança.

PIX Pendente (logo após criar a cobrança; não tem "type"):
```json
{"status": "pending", "transaction_id": "1b4e28ba-2fa1-4d2b-9c3e-6f1a2b3c4d5e", "amount": 150.5, "message": "PIX gerado, aguardando pagamento", "adquirente": "nxgate"}
```
- Em BRL, transaction_id é o ID interno da NxGate (diferente do idTransaction; as consultas aceitam os dois). "adquirente" é informativo (pode mudar; não use em regras).
- Em outras moedas: transaction_id = idTransaction, message "Cobranca gerada, aguardando pagamento" e mais "currency" e "payment_method".

PIX Pago:
```json
{"type": "QR_CODE_COPY_AND_PASTE_PAID", "data": {"amount": 150.5, "amount_chargeback": 0, "base_64_image": null, "base_64_image_url": null, "account_number": null, "agency_number": null, "debtor_document": "12345678901", "debtor_institution": null, "debtor_institution_number": null, "debtor_name": "João Silva", "due_date": null, "end_to_end": "E00000000202610051530abcdefghijk", "expiration_date": null, "fee": 0, "fine": null, "fine_date": null, "payment_date": "2026-10-05T15:30:00.000Z", "pix_copy_and_paste": "00020101021226850014br.gov.bcb.pix...6304A1B2", "qr_code_id": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90", "status": "PAID", "tag": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90", "tx_id": "e3f1c6a2-58b4-4d0e-9a7c-2b6d4f8e1a90", "type_document": "CPF", "type_fine": "NONE", "worked": true, "magic_id": "pedido-123"}}
```
- Case por data.tx_id (= idTransaction). data.magic_id = o seu magic_id.
- Antes de liberar o pedido, confirme com POST /v2/consultar (transaction_id = data.tx_id) e libere só com "paid". Se a consulta ainda disser "waiting", o pagamento está em análise: não peça para pagar de novo; consulte mais tarde.
- Outras moedas: mesmo formato + data.currency e data.payment_method; campos que só existem no PIX vêm null. Moeda = data.currency ?? "BRL".
- Contas gateway (liberação pelo suporte) recebem depois, na mesma URL, 1 webhook por venda em moeda estrangeira: {"type": "CURRENCY_CONVERTED", "data": {"status": "CONVERTED", "tx_id", "tag", "qr_code_id", "magic_id", "currency", "payment_method", "amount", "net_amount", "amount_brl", "exchange_rate", "converted_at", "conversion_id"}}. NÃO é novo pagamento: não libere o pedido de novo; use amount_brl (reais que entraram no saldo) para creditar o seller. Quem não usa, responde 200 e ignora.

Saques (case por idTransaction = internalreference do /pix/sacar):
```json
{"amount": 500, "end_to_end": "E00000000202610051530abcdefghijk", "fee": 0, "key": "joao@email.com", "payment_date": "2026-10-05T15:31:02.418Z", "status": "saque-pago", "transaction_id": "4f8a2c1e9b7d", "idTransaction": "7d9f2c1a-4b3e-4f6a-9c8d-1e2f3a4b5c6d", "type": "PIX_CASHOUT_PAID", "worked": true, "message": "Saque realizado"}
```
- PIX_CASHOUT_PAID: status "saque-pago", worked true, message "Saque realizado". amount = valor enviado ao recebedor.
- PIX_CASHOUT_ERROR: status "saque-falhou", worked false, campo "error" com o motivo.
- PIX_CASHOUT_REFUND: status "saque-estornado", worked false, campo "message" com o motivo. Pode chegar depois do PAID.
- Em ERROR e REFUND, o valor debitado (valor + taxa) volta para o saldo NxGate.
- transaction_id é a referência da rede de pagamento (pode vir null).

## POST /pix/sacar — saque PIX (escopo cashout)
- Só é aceito vindo de um IP cadastrado em Painel → API → IP Seguro para Saques; senão 403 {"status": "error", "message": "IP nao autorizado."}. Se o servidor sair por IPv6, cadastre o IPv6 ou force IPv4.
- Corpo: api_key; valor (number, de R$ 1,00 a R$ 50.000,00 e dentro do limite de saque da conta); chave_pix (string); tipo_chave ("CPF", "CNPJ", "PHONE", "EMAIL" ou "RANDOM"); documento (opcional, CPF/CNPJ do recebedor); webhook (opcional, até 255 caracteres).
Resposta 200:
```json
{"status": "success", "message": "Saque enviado para processamento automatico.", "internalreference": "7d9f2c1a-4b3e-4f6a-9c8d-1e2f3a4b5c6d", "valores": {"solicitado": 500, "taxa": 7.5, "valor_liquido": 500, "total_debitado": 507.5}}
```
- Guarde internalreference: é o idTransaction dos webhooks de saque.
- HTTP 200 com "status": "error" = recusado: "Campos invalidos ou ausentes." (com "erros") ou "Saldo insuficiente para cobrir o valor do saque + taxas." (com "detalhes"). Sempre confira status == "success".
- Se o saldo cobre o valor mas não valor + taxa, a taxa sai do valor enviado (valor_liquido = valor − taxa; total_debitado = valor).
- Outros erros: 403 (IP, escopo, saque desabilitado, conta), 422 {"status": "error", "message": "Valor maximo por saque excedido"} e outros limites, 503 (saques temporariamente indisponíveis), 409, 429, 500.

## POST /saldo — saldo da conta (escopo saldo; exige o mesmo IP liberado do saque)
```json
{"status": "success", "data": {"account_id": "1042", "username": "minhaloja", "moeda": "BRL", "disponivel": 1523.47, "congelado": 0, "congelado_med": 0, "total_vendas": 98420.1, "total_saques": 96890, "consultado_em": "2026-10-05T17:05:00.000Z"}}
```

## Erros
- Formatos: {"error": "..."} ou {"status": "error", "message": "..."}; validação da cobrança: {"error": "Dados invalidos", "detalhes": []}.
- 400 requisição malformada · 401 api_key ausente/inválida/revogada · 403 conta, escopo, permissão ou IP · 404 não encontrado · 409 X-Idempotency-Key em processamento · 422 dados ou regra de negócio · 429 limite · 500/503 falha.
- 422 comuns na cobrança BRL: "Valor minimo por transacao e R$ 1,00", "Valor maximo por transacao excedido", "Documento do pagador deve conter 11 ou 14 digitos", "URL de webhook invalida ou nao permitida", "Split excede o teto de 90% do valor (maximo R$ ...)".
- Limites por minuto: cobrança 10.000 por api_key e 5.000 por IP; consulta 10.000 por IP; saque 100 por api_key e 60 por IP; saldo 60 por api_key e 120 por IP; geral 20.000 por IP. O contador por IP é único para todas as rotas e cada chamada soma 2. Em 429, espere o X-RateLimit-Reset (Unix, segundos).

## Conector MCP (assistentes de IA)
- Endereço: https://mcp.nxgate.com.br/mcp (OAuth com a conta NxGate; o dono da conta autoriza).
- Ferramentas: saldo, vendas, vendas_por_dia, comparar_faturamento, melhor_horario, top_produtos, transacoes, consultar_venda, ultimo_saque, taxas, status_conta e gerar_pix.
- Nenhuma ferramenta faz saque nem tira dinheiro da conta; gerar_pix só cria uma cobrança que cai na própria conta.

---
Versão navegável com exemplos de código: https://nxgate.com.br/doc