Nerva API Documentação

1. Autenticação

Todas as requisições autenticadas devem incluir sua API Key no header x-api-key. A chave é gerada no painel do seller em Integrações > API Keys.

# Inclua em todas as requisições autenticadas
x-api-key: sk_live_a1b2c3d4e5f6g7h8i9j0...

2. Criar Cobrança PIX

Cria uma cobrança PIX instantânea. Retorna o código PIX “Copia e Cola” e o QR Code para o pagador. A cobrança expira em 24 horas por padrão (configurável via expirationInSeconds).

Parâmetros do Body

POST /sales
x-api-key: sk_live_...
Content-Type: application/json

{
  "amount": 100.00,
  "description": "Plano Premium",
  "expirationInSeconds": 1800,
  "customer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "joao@email.com",
    "phone": "11999999999"
  },
  "items": [
    { "description": "Plano Premium", "quantity": 1, "unitPrice": 100.00 }
  ],
  "postbackUrl": "https://meucheckout.com/webhooks/pagamentos"
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "amount": 100.00,
  "fee": 8.98,
  "netAmount": 91.02,
  "pixCode": "00020101021226580014br.gov.bcb...",
  "pixQrCode": "https://pixnerva.com.br/api/...",
  "transactionId": "gw_tx_abc123"
}

Idempotência

Para evitar cobranças duplicadas em caso de retentativa de rede ou timeout, envie o header idempotency-key ao criar uma cobrança. Se a chave já foi processada, a API devolve a resposta original (mesmo PIX, mesmo ID) sem criar nova cobrança.

POST /sales
x-api-key: sk_live_...
idempotency-key: pedido-12345
Content-Type: application/json

{
  "amount": 100.00,
  "customer": { "document": "12345678901" }
}

Tracking de Marketing

Inclua o objeto tracking no body do POST /sales com UTMs, click IDs e cookies do pixel. Quando a venda for paga, a plataforma dispara automaticamente eventos para a Meta Conversions API e TikTok Events API (se a integração estiver ativa no painel do seller). Tudo opcional.

Campos do objeto tracking

{
  "amount": 100.00,
  "customer": { "document": "12345678901" },
  "tracking": {
    "utmSource": "facebook",
    "utmCampaign": "black-friday-2026",
    "fbclid": "IwAR2...",
    "fbp": "fb.1.1700000000000.123456789",
    "fbc": "fb.1.1700000000000.IwAR2...",
    "clientUserAgent": "Mozilla/5.0 (...)",
    "clientIpAddress": "201.10.20.30"
  }
}

3. Consultar Cobrança

Retorna os detalhes completos de uma cobrança específica, incluindo o código PIX e o status do pagamento.

GET /sales/a1b2c3d4-e5f6-7890-abcd-ef1234567890
x-api-key: sk_live_...

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "paid",
  "amount": 100.00,
  "fee": 8.98,
  "netAmount": 91.02,
  "description": "Plano Premium",
  "pixCode": "00020101021226580014br.gov.bcb...",
  "pixQrCode": "https://pixnerva.com.br/api/...",
  "payerName": "João Silva",
  "payerEmail": "joao@email.com",
  "payerDocument": "12345678901",
  "payerPhone": "11999999999",
  "paymentMethod": "PIX",
  "transactionId": "gw_tx_abc123",
  "createdAt": "2026-03-23T10: 00: 00Z",
  "updatedAt": "2026-03-23T10: 05: 00Z"
}

4. Listar Cobranças

Retorna a lista paginada de cobranças da sua empresa, com filtros por status, data e busca.

Parâmetros de Query

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "status": "paid",
      "amount": 100.00,
      "fee": 8.98,
      "netAmount": 91.02,
      "payerName": "João Silva",
      "paymentMethod": "PIX",
      "createdAt": "2026-03-23T10: 00: 00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}

Produtos

O produto é o que você vende, independente de onde vende. Ele guarda duas coisas que o rastreio usa: os prazos de cada etapa da entrega e o conteúdo da área de membros, liberado quando o pedido é entregue. Cadastre uma vez por produto — não a cada pedido.

Parâmetros do Body

POST /products
x-api-key: sk_live_...
Content-Type: application/json

{
  "name": "Kit Completo",
  "externalRef": "SKU-001",
  "tracking": {
    "postedAfterHours": 24,
    "inTransitAfterHours": 72,
    "outForDeliveryAfterHours": 168,
    "deliveredAfterHours": 192
  }
}

{
  "data": {
    "id": "9c81f2ab-4d5e-6789-abcd-ef0123456789",
    "name": "Kit Completo",
    "externalRef": "SKU-001",
    "description": null,
    "coverUrl": null,
    "tracking": {
      "postedAfterHours": 24,
      "inTransitAfterHours": 72,
      "outForDeliveryAfterHours": 168,
      "deliveredAfterHours": 192
    },
    "memberArea": {},
    "createdAt": "2026-09-24T12: 00: 00.000Z"
  }
}

Demais endpoints

Quem casa com quem

São três identificadores, e cada um nasce num lugar. Usando os dois primeiros você nunca precisa guardar um ID da plataforma.

Rastreio de Pedidos

Cadastre o código de rastreio de uma venda paga e o comprador acompanha a entrega numa timeline pública, com a sua marca. As etapas são fixas (Pedido confirmado → Postado → Em trânsito → Saiu para entrega → Entregue) e os tempos entre elas são configurados por produto — no painel ou pela API, na seção Produtos. Se o rastreio estiver vinculado a um produto com área de membros, o acesso do comprador é liberado automaticamente na entrega.

A venda não conhece o produto. O POST /sales não tem campo de produto: venda e produto só se encontram aqui, no cadastro do rastreio. Por isso esta chamada recebe os dois — a venda por saleId ou externalId, e o produto por productId ou productRef.

Parâmetros do Body

POST /trackings
x-api-key: sk_live_...
Content-Type: application/json

{
  "code": "BR123456789XX",
  "externalId": "pedido-1042",
  "productRef": "SKU-001"
}

{
  "data": {
    "id": "f3e2d1c0-b9a8-7654-3210-fedcba987654",
    "code": "BR123456789XX",
    "saleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "9c81f2ab-...",
    "currentStage": "confirmed",
    "startedAt": "2026-09-23T14: 00: 00Z",
    "timeline": [
      { "stage": "confirmed", "label": "Pedido confirmado", "at": "2026-09-23T14: 00: 00Z", "reached": true, "current": true },
      { "stage": "posted", "label": "Postado", "at": "2026-09-24T14: 00: 00Z", "reached": false, "current": false },
      { "stage": "in_transit", "label": "Em trânsito", "at": "2026-09-26T14: 00: 00Z", "reached": false, "current": false },
      { "stage": "out_for_delivery", "label": "Saiu para entrega", "at": "2026-09-30T14: 00: 00Z", "reached": false, "current": false },
      { "stage": "delivered", "label": "Entregue", "at": "2026-10-01T14: 00: 00Z", "reached": false, "current": false }
    ]
  }
}

Demais endpoints

5. Consultar Saldo

Retorna o saldo total, o valor retido (retenção de segurança) e o saldo disponível para saque.

GET /withdrawals/balance
x-api-key: sk_live_...

{
  "data": {
    "available": 150000,
    "withheld": 7500
  }
}
// Valores em centavos (150000 = R$ 1.500,00)

6. Solicitar Saque

Solicita um saque do saldo disponível. O saque passa por aprovação antes do processamento. Valor mínimo: R$ 1,00.

Parâmetros do Body

POST /withdrawals
x-api-key: sk_live_...
Content-Type: application/json

{
  "amount": 500.00,
  "method": "pix",
  "pixKeyType": "cpf",
  "pixKey": "12345678901",
  "reference": "pedido-saque-789"
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 500.00,
  "fee": 0,
  "status": "pending",
  "method": "pix",
  "pixKeyType": "cpf",
  "pixKey": "12345678901",
  "reference": "pedido-saque-789",
  "createdAt": "2026-03-23T14: 30: 00Z"
}

Listar Saques

Lista os saques da sua conta com filtros e paginação.

Query Parameters

GET /withdrawals/my-withdrawals?page=1&limit=20&status=completed
x-api-key: sk_live_...

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "amount": 500.00,
      "fee": 0,
      "status": "completed",
      "method": "pix",
      "pixKey": "12345678901",
      "reference": "pedido-saque-789",
      "createdAt": "2026-03-23T14: 30: 00Z"
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 20
}

Buscar Saque por ID

Retorna os detalhes de um saque específico pelo ID.

GET /withdrawals/my-withdrawals/a1b2c3d4-...
x-api-key: sk_live_...

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 500.00,
    "fee": 0,
    "status": "completed",
    "method": "pix",
    "pixKeyType": "cpf",
    "pixKey": "12345678901",
    "reference": "pedido-saque-789",
    "createdAt": "2026-03-23T14: 30: 00Z",
    "updatedAt": "2026-03-23T14: 35: 00Z"
  }
}

7. Webhooks

Configure uma URL de webhook no painel para receber notificações em tempo real quando o status de um pagamento mudar. A plataforma envia um POST com payload JSON assinado.

Headers enviados pela plataforma

Eventos disponíveis

Payload de exemplo (sale.paid)

{
  "event": "sale.paid",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "paid",
    "amount": 100.00,
    "fee": 8.98,
    "netAmount": 91.02,
    "payerName": "João Silva",
    "payerEmail": "joao@email.com",
    "payerDocument": "12345678901",
    "paymentMethod": "PIX",
    "transactionId": "gw_tx_abc123",
    "createdAt": "2026-03-23T10: 00: 00Z",
    "paidAt": "2026-03-23T10: 02: 30Z"
  }
}

Identificadores para reconciliação: id (nosso), transactionId (adquirente), externalId (o número do pedido que você enviou) e endToEndId (E2E do PIX). O webhook cashout.completed retorna os mesmos identificadores (id, transactionId, externalId, endToEndId) mais os dados do beneficiário (beneficiaryName, pixKey).

Pagador e recebedor (disponível mediante habilitação)

Em contas habilitadas, as transações pagas trazem os objetos payer (quem pagou) e receiver (quem recebeu), cada um com name, document, bankIspb, bankAccount, bankBranch e bankName. Os dois objetos vêm sempre com as seis chaves; campo que a instituição de pagamento não informou vem null. Em contas não habilitadas os campos payer e receiver não aparecem.

• sale.paid e GET /sales/:id (status paid): payer = pagador, conforme informado pela instituição de pagamento (o documento pode vir mascarado, ex.: 123****8901); receiver = sua empresa.
• cashout.completed, withdrawal.completed, GET /cashout/:id e GET /withdrawals/my-withdrawals/:id (status completed): payer = sua empresa; receiver = beneficiário, conforme informado pela instituição de pagamento.
• POST /cashout: quando a instituição confirma o PIX na própria chamada, a resposta já vem com status: "completed", endToEndId, payer e receiver. O webhook cashout.completed é enviado mesmo assim. Caso contrário a resposta segue processing e as partes chegam no webhook cashout.completed, que exige a URL de webhook de saque configurada no painel.
• customer.document passa a ser opcional no POST /sales. Algumas instituições de pagamento exigem o documento do pagador: sem ele, a cobrança pode ser recusada — envie customer.document sempre que tiver.

{
  "event": "sale.paid",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "paid",
    "endToEndId": "E12345678202603231002abcdefghijk",
    "payer": {
      "name": "Maria Santos",
      "document": "12345678909",
      "bankIspb": "12345678",
      "bankAccount": "00098765",
      "bankBranch": "0001",
      "bankName": "Banco do Pagador"
    },
    "receiver": {
      "name": "Sua Empresa LTDA",
      "document": "11222333000181",
      "bankIspb": null,
      "bankAccount": null,
      "bankBranch": null,
      "bankName": null
    }
  }
}

Verificação de assinatura (HMAC-SHA256)

Para garantir que o webhook foi enviado pela plataforma e não foi adulterado, verifique a assinatura HMAC-SHA256 usando o secret do webhook.

1. Extraia o timestamp e a signature dos headers
2. Monte a string: timestamp.body (timestamp + ponto + body raw)
3. Gere o HMAC-SHA256 usando seu secret
4. Compare o resultado com a signature recebida
5. Rejeite se o timestamp for maior que 5 minutos (proteção contra replay attack)

const crypto = require("crypto");

function verifyWebhook(req, secret) {
  const timestamp = req.headers["x-pixnerva-timestamp"];
  const signature = req.headers["x-pixnerva-signature"];
  const body = JSON.stringify(req.body);

  // Proteção contra replay attack (5 min)
  const age = Date.now() / 1000 - Number(timestamp);
  if (age > 300) return false;

  // Gerar HMAC e comparar
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

8. Códigos de Erro

A API retorna códigos HTTP padrão. Erros incluem um corpo JSON com message e statusCode.

{
  "message": "Saldo insuficiente para realizar o saque",
  "statusCode": 400
}