REST · WebSocket · gRPC

API
referência.

312 endpoints, especificação OpenAPI completa, idempotência em cada mutação e um contrato de tempo de atividade público. Não há caixas pretas.

URL base

api.rozper.com

Versão

v2026.05

Limite de taxa

1000 rotações por minuto

PUBLICAR/v2/chamadas

"color:#22D3EE">curl "color:#22D3EE">-X "cor:#34D399;peso da fonte:600">POSTAR https://api.rozper.com/v2/calls\
  "cor:#22D3EE">-H "Autorização: Portador $ROZPER_API_KEY" \
  "cor:#22D3EE">-H "Tipo de conteúdo: aplicativo/json" \
  "cor:#22D3EE">-d '{
    "para":   "+14155551234",
    "de": "+12025550100",
    "URL":  "https://your.app/voice/answer"
  }'

201Resposta · 84 ms

{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "status": "queued",
  "to":     "+14155551234",
  "from":   "+12025550100",
  "created_at": "2026-05-12T14:23:01Z"
}

§01 · Autenticação

Tokens ao portador.
Escopo. Rotativo.

Cada solicitação carrega uma chave de projeto como token de portador. As chaves têm escopo (leitura, gravação, cobrança), podem ser giradas sem tempo de inatividade e podem ser fixadas por IP no painel.

Chaves por ambiente (teste/ao vivo)
Credenciais de cliente OAuth 2.0 suportadas
TLS mútuo disponível no Enterprise

Cabeçalho de autorização

curvaturaNóPitãoIr

# .env  →  never commit me
ROZPER_API_KEY=sk_live_8FzqQ...XW7p

# request
curl https://api.rozper.com/v2/account \
  -H "Authorization: Bearer $ROZPER_API_KEY"

# 200 OK
{
  "id": "acct_01HXY7ZQ9V3J3X8K5N",
  "scopes": ["calls.write", "messages.write", "numbers.read"],
  "rate_limit": { "limit": 1000, "remaining": 998, "reset": 1715520000 }
}

§02 · Referência

Explore cada endpoint.

chamadasCriar uma chamada

Criar uma chamada

Origine uma chamada PSTN de saída. Retorna imediatamente com um objeto de chamada na fila - ouça nos webhooks as alterações de estado.

PUBLICAR/v2/chamadas

Parâmetros

tocordaobrigatório

Número de destino E.164.

fromcordaobrigatório

Número Rozper verificado ou alugado.

urlcorda

Endpoint HTTPS que retorna instruções de voz quando a chamada é conectada.

recordbooleano

Grave ambas as pernas em seu armazenamento. Padrão falso.

timeoutinteiro

Tempo limite do toque em segundos. Padrão 60.

Solicitar · nó● ao vivo

const call = await rozper.calls.create({
  to:   "+14155551234",
  from: "+12025550100",
  url:  "https://your.app/voice/answer",
})

Resposta · 201 criado84ms

{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "object": "call",
  "created_at": "2026-05-12T14:23:01Z"
}

§03 · Erros

Erros previsíveis e legíveis por máquina.

Cada 4xx e 5xx retorna a mesma forma: um estável code, uma mensagem legível e um ID de solicitação que você pode colar no suporte.

Envelope de erro

{
  "error": {
    "code": "invalid_param",
    "message": "to: must be E.164",
    "request_id": "req_01HXY7…",
    "param_errors": [
      { "param": "to", "reason": "format" }
    ]
  }
}

400

bad_request

Corpo da solicitação malformado ou campo obrigatório ausente.

401

unauthorized

Chave de API ausente, expirada ou revogada.

403

forbidden

A chave não possui o escopo necessário para este recurso.

404

not_found

O ID do recurso não existe para esta conta.

409

conflict

A chave de idempotência colide com uma carga útil diferente.

422

invalid_param

Um parâmetro falhou na validação. Inspecione param_errors[].

429

rate_limited

Backoff usando o cabeçalho Retry-After.

500

server_error

Fomos notificados. Tente novamente chamadas idempotentes.

§04 · Webhooks

Assinado, repetido e protegido contra reprodução.

Cada evento é entregue com uma assinatura HMAC, um ID de evento exclusivo e um carimbo de data/hora UTC. Tentamos novamente com espera exponencial por até 24 horas.

Assinatura HMAC-SHA256 em Rozper-Signature

Até 8 tentativas · Janela de 24h

Envie para vários endpoints simultaneamente

Verifique um webhook · Nó✓ comparação em tempo constante

import { verify } from "@rozper/sdk/webhooks"

app.post("/webhooks/rozper", (req, res) => {
  const ok = verify({
    payload:   req.rawBody,
    signature: req.header("Rozper-Signature"),
    secret:    process.env.ROZPER_WEBHOOK_SECRET,
  })
  if (!ok) return res.status(401).end()

  const event = JSON.parse(req.rawBody)
  switch (event.type) {
    case "call.completed": /* … */
    case "recording.ready": /* … */
  }
  res.json({ received: true })
})

Catálogo de eventos · 32 no total

call.initiated

Chamada de saída aceita pela operadora.

call.ringing

O extremo está tocando.

call.answered

Extremo distante respondido (ou AMD detectada humana).

call.completed

A chamada terminou. Inclui duração, faturamento e metadados de trecho.

recording.ready

Gravação de recurso carregado e URL assinado disponível.

message.delivered

Recibo de entrega da transportadora (quando suportado).

agent.handoff

Agente de IA escalado para uma fila humana.

number.purchased

Aquisição de número concluída.

§05 · Registro de alterações

Cada mudança, em inglês simples.

2026-05-10
v2026.05
- façanhaOs agentes de voz agora oferecem suporte a chamadas de ferramentas com respostas de streaming.
- façanhaNovo endpoint /v2/numbers/port para envios programáticos de LNP.
2026-04-22
v2026.04
- consertarO cache de idempotência agora respeita corretamente o TTL 24h em POST/chamadas.
- tarefaEndpoints v1 obsoletos removidos (anunciados em 2025-11).
2026-03-31
v2026.03
- façanhaWebSocket media-streams beta já está disponível para todos.
- façanhaMensagens de modelo do WhatsApp adicionadas em /v2/messages.

Assine o feed do changelog da API →