Autenticación
La API de Sendveo autentica cada solicitud con una clave de API. Las claves se crean y revocan en el panel, en Claves de API.
Claves de API
Una clave se muestra completa exactamente una vez, cuando la creas. Guárdala de forma segura. Sendveo conserva solo un prefijo para que puedas reconocerla más tarde. Trata las claves como contraseñas: nunca las incluyas en el control de versiones ni las expongas en un navegador.
Enviar la clave
Pasa la clave en la cabecera X-API-KEY:
curl https://api.sendveo.com/v1/numbers \
-H "X-API-KEY: sv_live_your_key_here"También se acepta un token bearer, si eso encaja mejor con tu cliente HTTP:
curl https://api.sendveo.com/v1/numbers \
-H "Authorization: Bearer sv_live_your_key_here"Ámbitos
Cada clave lleva un conjunto de ámbitos que limitan lo que puede hacer. Concede solo lo que necesita una integración determinada.
| Ámbito | Concede |
|---|---|
| numbers:read | Listar y leer números. |
| numbers:write | Crear, verificar, reconectar y desconectar números. |
| messages:read | Leer los mensajes almacenados. |
| messages:send | Enviar mensajes. |
| messages:manage | Reaccionar, reenviar, eliminar para todos y marcar una conversación como leída. |
| chats:read | Listar y leer conversaciones. |
| chats:manage | Archivar, silenciar y traer el historial anterior. |
| contacts:read | Perfiles de contactos, fotos de contactos y la comprobación de presencia en WhatsApp. |
| groups:read | Listar y leer grupos, y las fotos de grupo. |
| groups:manage | Crear un grupo, añadir y eliminar miembros, salir. |
| webhooks:manage | Leer y configurar tu webhook de retransmisión. |
| *:read | Todos los ámbitos de lectura a la vez (una clave de solo lectura). |
La lectura y la escritura están separadas por área, y contacts:read no tiene gemelo de escritura a propósito: Sendveo nunca escribe un contacto en ninguna parte. Una clave emitida antes de que existiera un ámbito no lo lleva y responde 403 en las rutas que lo necesitan; el ámbito no se le puede añadir, así que emite una clave nueva.
No autorizado
Una clave que falta, está revocada o fuera de ámbito devuelve 401 o 403 con el envoltorio de error estándar:
{
"error": {
"code": "UNAUTHORIZED",
"message": "The request was not authenticated."
}
}Cuenta en espera
Un rechazo no siempre es un problema de la clave: un 402 con el código ACCOUNT_SUSPENDED describe el estado de la cuenta. La clave es válida, sus ámbitos son correctos, y rotarla o repetir un flujo de consentimiento no cambia nada. Mientras la cuenta esté en espera, todas las rutas responden igual salvo el inicio de sesión y la facturación. Contacta con nosotros para restablecer el acceso.
{
"error": {
"code": "ACCOUNT_SUSPENDED",
"message": "Your account is on hold. Contact us to restore access."
}
}