PipSync

Início rápido

Armazene sua chave, chame /v1/me para verificar a autenticação e comece a ler sinais ou negociações. Cinco minutos do zero até a primeira resposta da API.

curl https://app.pipsync.io/api/v1/me \
  -H "Authorization: Bearer $PIPSYNC_KEY"

Toda resposta é encapsulada em { "data": … }. Endpoints paginados também retornam um objeto "meta" com total, page, totalPages e hasMore.

Autenticação

Todas as requisições à API exigem um token bearer no cabeçalho Authorization. As chaves são por ambiente (live / sandbox), por escopo e com limite de tempo apenas se você optar por definir uma expiração.

CabeçalhoAuthorization: Bearer pipsync_live_<32 alnum chars>

Obtendo uma chave de API

O acesso à API exige o plano Enterprise. Uma vez no Enterprise:

1. Navegue até Configurações → Chaves de API no seu workspace.
2. Clique em Criar chave, escolha um nome (ex.: prod-signal-reader) e selecione os escopos necessários.
3. Copie a chave — ela é exibida apenas uma vez. Armazene-a em um gerenciador de segredos (AWS Secrets Manager, Vault, Doppler, etc.).
4. Para rotacionar: crie uma chave substituta, migre o tráfego, revogue a chave antiga. Não há indisponibilidade se você sobrepor por um ciclo de implantação.

Escopos de chave

Escopo	Acesso	Endpoints
signals:read	Somente leitura	GET /v1/signals
trades:read	Somente leitura	GET /v1/trades
reports:read	Somente leitura	GET /v1/reports, GET /v1/reports/trades
account:read	Somente leitura	GET /v1/me, GET /v1/account/usage
webhooks:write	Gravação	Gerenciar assinaturas de webhook (somente painel)

Segurança da chave

⚠

Nunca exponha uma chave live em código no lado do cliente. Chaves incorporadas em bundles de navegador, aplicativos móveis ou repositórios públicos estão comprometidas. Use chaves sandbox para prototipagem. Revogue imediatamente uma chave vazada em Configurações → Chaves de API e crie uma substituta.

Recursos adicionais de endurecimento disponíveis no Enterprise: lista de permissão de IP (restringe quais faixas CIDR podem usar uma chave) e lista de bloqueio de IP. Ambos configurados por chave na mesma página de configurações.

Limites de taxa

Os limites são por chave de API por janela contínua de 60 segundos. Webhooks têm limites de taxa separados na superfície de entrega de entrada.

Plano	Requisições API / min	Webhooks / min	Rajada	Observações
Basic	60	10	1×	Sem margem de rajada
Pro	300	60	2×	Janela de rajada curta (5 s)
Business	1000	200	3×	Rajada de até 3 000 RPM por ≤ 5 s
Enterprise	Personalizado	Personalizado	Personalizado	SLA negociado, concorrência personalizada

Cabeçalhos de resposta

Toda resposta da API inclui cabeçalhos de limite de taxa para que sua integração permaneça dentro dos limites sem tentativa e erro:

Cabeçalho	Valor
X-RateLimit-Limit	Máximo de requisições permitidas na janela atual
X-RateLimit-Remaining	Requisições restantes na janela atual
X-RateLimit-Reset	Carimbo de data/hora ISO 8601 quando a janela é redefinida
Retry-After	Segundos de espera antes de tentar novamente (somente em 429)

ℹ

Respostas 429 podem ser repetidas. Sempre leia Retry-After e respeite-o. Não codifique uma duração fixa de espera — a janela exata depende do seu plano e da carga atual.

Backoff exponencial

Implemente backoff exponencial com jitter sempre que receber um 429. Esse padrão evita problemas de rebanho em estampida se sua frota estiver chamando em paralelo:

async function fetchWithRetry(url, key, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, {
      headers: { Authorization: \`Bearer ${key}\` },
    });
    if (res.status !== 429) return res.json();

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    const backoff = retryAfter * 1000 * Math.pow(2, attempt) + Math.random() * 200;
    await new Promise(r => setTimeout(r, backoff));
  }
  throw new Error("Rate limit retries exhausted");
}

Códigos de erro

Todos os erros usam RFC 7807 Problem Details (application/problem+json):

{
  "type": "https://app.pipsync.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid API key"
}

Status HTTP	Significado	Ação
400	Requisição inválida	Corrija o corpo da requisição / parâmetros de consulta
401	Não autorizado	Verifique o valor da chave e o formato do cabeçalho Authorization
403	Proibido	A chave não possui o escopo necessário para este endpoint
404	Não encontrado	O recurso não existe ou foi excluído
422	Não processável	Passa no esquema, mas a validação de regras de negócio falhou
429	Limite de taxa	Recue e tente novamente (veja Retry-After)
5xx	Erro de servidor	Transitório — repita com backoff; verifique pipsync.io/status

GET /v1/me

Retorna o perfil do proprietário do workspace associado à chave de API.

GET/v1/ me Experimentar ↗

curl https://app.pipsync.io/api/v1/me \
  -H "Authorization: Bearer $PIPSYNC_KEY"

GET /v1/signals

Retorna sinais de negociação analisados para o workspace. Sinais são a saída normalizada do parser — prontos para processamento downstream.

GET/v1/ signals Experimentar ↗

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
since	ISO 8601	Não	Retorna sinais recebidos neste horário ou depois
limit	número	Não	Máximo de resultados por página (padrão 25, máximo 100)
page	número	Não	Número da página (baseado em 1)
instrument	string	Não	Filtrar por instrumento, ex.: EURUSD
status	string	Não	Filtrar por status: parsed | pending | invalid

curl "https://app.pipsync.io/api/v1/signals?limit=10" \
  -H "Authorization: Bearer $PIPSYNC_KEY"

GET /v1/trades

Retorna registros de negociações (posições abertas, fechadas, parcialmente fechadas) para o workspace. Paginado; negociações mais recentes primeiro.

GET/v1/ trades Experimentar ↗

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
since	ISO 8601	Não	Somente negociações abertas neste horário ou depois
limit	número	Não	Máximo de resultados por página (padrão 25, máximo 100)
page	número	Não	Número da página (baseado em 1)
instrument	string	Não	Filtrar por instrumento
status	string	Não	Filtrar por status: open | closed | pending

curl "https://app.pipsync.io/api/v1/trades?limit=25" \
  -H "Authorization: Bearer $PIPSYNC_KEY"

GET /v1/reports

Enumera relatórios de negociação gerados e links de download. Use /v1/reports/trades para obter a exportação detalhada em CSV/PDF por item de linha.

GET/v1/ reports Experimentar ↗

✦

A especificação completa OpenAPI 3.1 (com esquemas de requisição / resposta para cada endpoint) está disponível em /api/v1/openapi.json. Importe-a no Postman, Insomnia ou use o playground interativo para experimentar cada endpoint ao vivo.

Stream em tempo real

Para painéis de navegador e monitoramento ao vivo, assine /api/trading/stream com EventSource. Este é o fallback SSE fornecido quando atualizações WebSocket não estão disponíveis; mantenha webhooks assinados para automação servidor a servidor.

Webhooks

Assine eventos push em Configurações → Webhooks. O PipSync envia um payload JSON assinado para seu endpoint toda vez que um evento ocorre. A entrega é tentada até 5 vezes com backoff exponencial.

POSTyour-server.com/pipsync — assinado por X-PipSync-Signature

Evento	Quando	Tipo de payload
signal.received	Um sinal foi analisado de qualquer fonte	SignalIntent
signal.parsed	O parser normalizou a mensagem de origem	ParsedSignal
trade.opened	Uma posição de corretora foi aberta	TradeOpened
trade.closed	Uma posição de corretora foi fechada	TradeClosed
trade.tp_hit	Take profit foi atingido	TradeClosed
trade.sl_hit	Stop loss foi atingido	TradeClosed
subscription.upgraded	Assinatura movida para um nível superior	Subscription
subscription.canceled	Cancelamento foi agendado	Subscription

Verificando assinaturas

Toda entrega de webhook inclui um cabeçalho X-PipSync-Signature formatado como t=<unix-ts>,v1=<hex-hmac-sha256>. Verifique antes de confiar no payload:

import crypto from "crypto";

export function verifyWebhook(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=")),
  );
  const signed = parts.t + "." + rawBody;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");
  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1 ?? ""),
  );
}

⚡

Sempre verifique o carimbo de data/hora. Rejeite payloads onde t tenha mais de 5 minutos no passado — isso previne ataques de repetição. Compare Math.abs(Date.now() / 1000 - Number(parts.t)) > 300.

Clientes OpenAPI

O contrato fornecido é a especificação OpenAPI 3.1 em /api/v1/openapi.json. Gere um cliente tipado em seu runtime — ou use o playground interativo para requisições ad-hoc.

✦

Prefira o playground interativo para testes ad-hoc com sua chave real. Abrir Playground →