Documentación API

Primeros Pasos

La API de FineSpeak está organizada en torno a REST. Nuestra API tiene URLs orientadas a recursos predecibles, acepta cuerpos de solicitud codificados en JSON, devuelve respuestas codificadas en JSON y utiliza códigos de respuesta HTTP y autenticación estándar.

URL Base

https://api.finespeak.net/v1

SDK Libraries

PHP

composer require finespeak/sdk

Node.js

npm install finespeak

Python

pip install finespeak

Autenticación

La API de FineSpeak utiliza claves API para autenticar solicitudes. Puedes ver y administrar tus claves API en el Panel de Control.

Autenticación con Clave API

Incluye tu clave API en el encabezado de autorización:

curl https://api.finespeak.net/v1/numbers \
  -H "Authorization: Bearer TU_CLAVE_API"
                    

¡Mantén tus claves API seguras! No compartas tus claves API secretas en áreas públicamente accesibles como GitHub, código del lado del cliente, etc.

Números de Teléfono

Listar Números Disponibles

Busca números de teléfono disponibles para comprar.

GET /numbers/available

curl https://api.finespeak.net/v1/numbers/available?country=US&area_code=415 \
  -H "Authorization: Bearer TU_CLAVE_API"
                    

Comprar un Número

Compra un número de teléfono para tu cuenta.

POST /numbers/purchase

curl -X POST https://api.finespeak.net/v1/numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Support Line"
  }'
                    

Listar Tus Números

Recupera una lista de números de teléfono que pertenecen a tu cuenta.

GET /numbers

curl https://api.finespeak.net/v1/numbers \
  -H "Authorization: Bearer TU_CLAVE_API"
                    

Llamadas

Realizar una Llamada

Inicia una llamada saliente.

POST /calls

curl -X POST https://api.finespeak.net/v1/calls \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155555678",
    "callback_url": "https://tudominio.com/call-status"
  }'
                    

Recuperar Detalles de Llamada

Obtiene información sobre una llamada específica.

GET /calls/{call_id}

curl https://api.finespeak.net/v1/calls/CA123456789 \
  -H "Authorization: Bearer TU_CLAVE_API"
                    

Finalizar una Llamada

Termina una llamada activa.

DELETE /calls/{call_id}

curl -X DELETE https://api.finespeak.net/v1/calls/CA123456789 \
  -H "Authorization: Bearer TU_CLAVE_API"
                    

Mensajería

Enviar SMS

Envía un mensaje SMS.

POST /messages

curl -X POST https://api.finespeak.net/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155555678",
    "body": "Hello from FineSpeak!"
  }'
                    

Listar Mensajes

Recupera el historial de mensajes.

GET /messages

curl https://api.finespeak.net/v1/messages?limit=50 \
  -H "Authorization: Bearer TU_CLAVE_API"
                    

Webhooks

FineSpeak utiliza webhooks para notificar a tu aplicación cuando ocurren eventos en tu cuenta. Los webhooks son particularmente útiles para eventos asíncronos como llamadas y mensajes entrantes.

Eventos de Webhook

call.initiated - Se ha iniciado una llamada
call.answered - Se ha contestado una llamada
call.completed - Se ha finalizado una llamada
message.received - Se ha recibido un mensaje SMS
message.delivered - Se ha entregado un mensaje SMS

Ejemplo de Carga de Webhook

{
  "event": "message.received",
  "timestamp": "2025-12-04T10:30:00Z",
  "data": {
    "message_id": "SM123456789",
    "from": "+14155555678",
    "to": "+14155551234",
    "body": "Hello!",
    "status": "received"
  }
}
                    

Códigos de Error

FineSpeak utiliza códigos de respuesta HTTP convencionales para indicar el éxito o el fracaso de una solicitud de API.

Código	Descripción
`200`	OK - La solicitud tuvo éxito
`201`	Creado - Recurso creado exitosamente
`400`	Solicitud Incorrecta - Parámetros de solicitud inválidos
`401`	No Autorizado - Clave API inválida
`403`	Prohibido - Permisos insuficientes
`404`	No Encontrado - El recurso no existe
`429`	Demasiadas Solicitudes - Límite de tasa excedido
`500`	Error Interno del Servidor - Algo salió mal de nuestro lado

Formato de Respuesta de Error

{
  "error": {
    "code": "invalid_request",
    "message": "The 'to' parameter is required",
    "param": "to"
  }
}
                    

Navegación Rápida