Documentação da API

Gere cobranças PIX pela API do negocios.social. Todas as requisições usam HTTPS e são autenticadas com sua api-key e secret (geradas no seu cadastro; a secret aparece uma única vez).

Base URL

https://api.negocios.social

Todos os endpoints do gateway começam com /gateway.

Autenticação

Use HTTP Basic Auth: a api-key como usuário e a secret como senha (enviadas no cabeçalho Authorization, sobre HTTPS). Nunca exponha a secret no navegador ou no app — use-a apenas no seu servidor.

curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/pix/charge/...

Limite de 60 requisições por minuto por api-key. Ao exceder, a API responde 429. Se sua chave tiver uma lista de IPs permitidos, requisições de outros IPs recebem 403.

Criar cobrança PIX

POST /gateway/pix/charge

Parâmetros (corpo JSON)

Campo	Tipo	Descrição
`amount`	inteiro	Obrigatório. Valor em centavos (ex.: `10000` = R$ 100,00).
`description`	texto	Descrição exibida ao pagador.
`external_reference`	texto	Seu identificador do pedido (para conciliação).
`expires_in`	inteiro	Validade do QR em segundos. Padrão `172800` (48h).
`payer.name`	texto	Nome do pagador.
`payer.document`	texto	CPF (11) ou CNPJ (14) do pagador.

Envie o cabeçalho opcional Idempotency-Key para evitar cobranças duplicadas em caso de reenvio — a mesma chave devolve a mesma cobrança.

Requisição

curl -X POST https://api.negocios.social/gateway/pix/charge \
  -u "ak_sua_apikey:sk_sua_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "amount": 10000,
    "description": "Pedido #1234",
    "external_reference": "1234",
    "expires_in": 172800,
    "payer": { "name": "Fulano de Tal", "document": "12345678900" }
  }'

Resposta

{
  "success": 1,
  "id": "66a4f0c2e1b2a3d4e5f60718",
  "status": "pending",
  "amount": 10000,
  "qr_code": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "expires_at": "2026-07-03T18:00:00.000Z"
}

Use qr_code (PIX copia-e-cola) ou qr_code_base64 (imagem PNG pronta para exibir) para apresentar o pagamento ao seu cliente.

Consultar cobrança

GET /gateway/pix/charge/:id

Consulte periodicamente (polling) para saber quando o pagamento foi confirmado. Quando o status virar paid, o valor é creditado no seu saldo.

curl -u "ak_sua_apikey:sk_sua_secret" \
  https://api.negocios.social/gateway/pix/charge/66a4f0c2e1b2a3d4e5f60718

{
  "success": 1,
  "id": "66a4f0c2e1b2a3d4e5f60718",
  "status": "paid",
  "amount": 10000,
  "external_reference": "1234",
  "paid_at": "2026-07-01T18:05:00.000Z",
  "expires_at": "2026-07-03T18:00:00.000Z"
}

Listar cobranças por período

GET /gateway/pix/charges?from=YYYY-MM-DD&to=YYYY-MM-DD

Datas obrigatórias. Janela máxima de 30 dias. Filtro opcional status.

curl -u "ak_sua_apikey:sk_sua_secret" \
  "https://api.negocios.social/gateway/pix/charges?from=2026-07-01&to=2026-07-15"

Status & erros

Valores possíveis de status:

pending — aguardando pagamento
paid — pago (creditado no saldo)
expired — expirado sem pagamento

Toda resposta traz success (1 ou 0). Em erro, vem também error com a mensagem, e o código HTTP apropriado (400 dados inválidos, 401 credenciais, 403 IP, 429 limite, 502 provedor).

{ "success": 0, "error": "Credenciais inválidas." }

Valores monetários são sempre inteiros em centavos.