OpenAPI e SDK

A especificação é gerada a partir da própria API e está sempre atualizada. É a mesma spec em dois formatos.

Download

URLs: /api/public/v1/openapi.json e /api/public/v1/openapi.yaml.

Importar em ferramentas

Postman: Import → Link → cole a URL do JSON. A coleção é criada com todos os endpoints.
Insomnia: Create → Import From → URL → cole a URL do YAML ou do JSON.
Geradores de SDK: aponte o gerador para a spec e gere o cliente na sua linguagem.

openapi-generator

npx @openapitools/openapi-generator-cli generate \
  -i https://pitra.com.br/api/public/v1/openapi.json \
  -g typescript-fetch \
  -o ./pitra-sdk

SDK oficial

Cliente mínimo, pronto para copiar, usando exatamente a autenticação e as rotas atuais da API.

// Node.js 18+ (fetch nativo)
const PITRA_API_KEY = process.env.PITRA_API_KEY;
const BASE = "https://pitra.com.br/api/public/v1";

async function pitra(path, { method = "GET", body, idempotencyKey } = {}) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${PITRA_API_KEY}`,
      "Content-Type": "application/json",
      ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error?.code ?? "request_failed");
  return data;
}

const cobranca = await pitra("/payments/pix", {
  method: "POST",
  idempotencyKey: "pedido-1042",
  body: { amount: 49.9, description: "Pedido 1042", external_id: "pedido-1042", expires_in: 1800 },
});
console.log(cobranca.id, cobranca.status);

Exemplos completos

Fluxo de ponta a ponta: criar cobrança, consultar e registrar o webhook.

# 1. criar cobrança
curl -X POST https://pitra.com.br/api/public/v1/payments/pix \
  -H "Authorization: Bearer $PITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{"amount":49.90,"description":"Pedido 1042","external_id":"pedido-1042","expires_in":1800}'

# 2. consultar pelo seu identificador
curl https://pitra.com.br/api/public/v1/payments/pix/external/pedido-1042 \
  -H "Authorization: Bearer $PITRA_API_KEY"

# 3. registrar o webhook
curl -X POST https://pitra.com.br/api/public/v1/webhooks \
  -H "Authorization: Bearer $PITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-sistema.com/webhooks/pitra","events":["pix.paid","pix.expired"]}'