DESCANSO · WebSocket · gRPC

API
referencia.

312 puntos finales, especificaciones OpenAPI completas, idempotencia en cada mutación y un contrato público de tiempo de actividad. Sin cajas negras.

URL básica
api.rozper.com
Versión
v2026.05
Límite de tarifa
1000 rps
CORREO/v2/llamadas
"color:#22D3EE">curl "color:#22D3EE">-X "color:#34D399;peso de fuente:600"> PUBLICAR https://api.rozper.com/v2/calls\
  "color:#22D3EE">-H "Autorización: Portador $ROZPER_API_KEY" \
  "color:#22D3EE">-H "Tipo de contenido: aplicación/json" \
  "color:#22D3EE">-d '{
    "a":   "+14155551234",
    "de": "+12025550100",
    "URL":  "https://tu.aplicación/voice/answer"
  }'
201Respuesta · 84 ms
{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "status": "queued",
  "to":     "+14155551234",
  "from":   "+12025550100",
  "created_at": "2026-05-12T14:23:01Z"
}
§01 · Autenticación

Fichas al portador.
Alcance. Giratorio.

Cada solicitud lleva una clave de proyecto como token de portador. Las claves tienen alcance (lectura, escritura, facturación), se pueden rotar sin tiempo de inactividad y se pueden fijar mediante IP desde el panel.

  • Claves por entorno (prueba/en vivo)
  • Se admiten credenciales de cliente OAuth 2.0
  • TLS mutuo disponible en Enterprise
encabezado de autorización
rizoNodoPitónIr
# .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 · Referencia

Explore cada punto final.

llamadascrear una llamada

crear una llamada

Originar una llamada PSTN saliente. Regresa inmediatamente con un objeto de llamada en cola: escuche en webhooks para detectar cambios de estado.

CORREO/v2/llamadas
Parámetros
tocadenarequerido

Número de destino E.164.

fromcadenarequerido

Número de Rozper verificado o alquilado.

urlcadena

Punto final HTTPS que devuelve instrucciones de voz cuando se conecta la llamada.

recordbooleano

Graba ambas piernas en tu almacenamiento. Por defecto es falso.

timeoutentero

Tiempo de espera del timbre en segundos. Por defecto 60.

Pedido · nodo● vivir
const call = await rozper.calls.create({
  to:   "+14155551234",
  from: "+12025550100",
  url:  "https://your.app/voice/answer",
})
Respuesta · 201 creados84 ms
{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "object": "call",
  "created_at": "2026-05-12T14:23:01Z"
}
§03 · Errores

Errores predecibles y legibles por máquina.

Cada 4xx y 5xx devuelve la misma forma: un establo code, un mensaje legible por humanos y una identificación de solicitud que puede pegar en el soporte.

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

Cuerpo de solicitud mal formado o falta un campo obligatorio.

401
unauthorized

Clave API faltante, caducada o revocada.

403
forbidden

Key carece del alcance necesario para este recurso.

404
not_found

La identificación del recurso no existe para esta cuenta.

409
conflict

La clave de idempotencia choca con una carga útil diferente.

422
invalid_param

Un parámetro falló en la validación. Inspeccione param_errors[].

429
rate_limited

Retroceda usando el encabezado Retry-After.

500
server_error

Nos avisaron. Vuelva a intentar llamadas idempotentes.

§04 · Webhooks

Firmado, reintentado y protegido contra reproducción.

Cada evento se entrega con una firma HMAC, una identificación de evento única y una marca de tiempo UTC. Volvemos a intentarlo con un retroceso exponencial de hasta 24 horas.

Firma HMAC-SHA256 en Rozper-Signature
Hasta 8 reintentos · Ventana de 24 horas
Enviar a múltiples puntos finales simultáneamente
Verificar un webhook · Nodo✓ comparación en tiempo 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 en total
call.initiated

Llamada saliente aceptada por el operador.

call.ringing

El otro extremo está sonando.

call.answered

Respondió el extremo lejano (o AMD detectó a un humano).

call.completed

La llamada finalizó. Incluye duración, facturación y metadatos del tramo.

recording.ready

Activo de grabación cargado y URL firmada disponible.

message.delivered

Recibo de entrega del transportista (donde sea compatible).

agent.handoff

El agente de IA pasó a una cola humana.

number.purchased

Adquisición de números completada.

§05 · Registro de cambios

Cada cambio, en un lenguaje sencillo.

  1. 2026-05-10
    v2026.05
    • logroLos agentes de voz ahora admiten llamadas mediante herramientas con respuestas en tiempo real.
    • logroNuevo punto final /v2/numbers/port para envíos LNP programáticos.
  2. 2026-04-22
    v2026.04
    • arreglarLa caché de idempotencia ahora respeta correctamente el TTL de 24 horas en POST/llamadas.
    • faenaSe eliminaron los puntos finales v1 obsoletos (anunciados en 2025-11).
  3. 2026-03-31
    v2026.03
    • logroLa versión beta de WebSocket Media-streams ya está disponible de forma generalizada.
    • logroMensajes de plantilla de WhatsApp agregados en /v2/messages.
Suscríbase al feed del registro de cambios de API →
Referencia de API · Rozper REST y WebSocket Docs | Rozper hoy