Referencia de la API

URL base

https://api.bitelio.com

Todas las solicitudes van a esta URL base.

Autenticación

Pasa tu clave de API como token bearer en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

• Clave secreta (sk_*) — necesaria en todos los endpoints excepto /v1/track
• Clave pública (pk_*) — solo se acepta en /v1/track, para que puedas registrar eventos desde código del lado del cliente

Cómo hacer solicitudes

Enviar un correo transaccional

curl -X POST https://api.bitelio.com/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "body": "<p>Your message here</p>"
  }'

Registrar un evento

curl -X POST https://api.bitelio.com/v1/track \
  -H "Authorization: Bearer pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "signed_up"
  }'

Crear un contacto

curl -X POST https://api.bitelio.com/contacts \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "subscribed": true,
    "data": {
      "firstName": "John",
      "plan": "pro"
    }
  }'

Formato de respuesta

Respuestas de éxito

Los endpoints públicos (/v1/send, /v1/track, /v1/verify) envuelven su payload en un sobre:

{
  "success": true,
  "data": {
    "contact": "cnt_abc123",
    "event": "evt_xyz789",
    "timestamp": "2025-11-30T10:30:00.000Z"
  }
}

Los endpoints tipo panel (contactos, plantillas, campañas, segmentos, workflows, etc.) omiten el sobre success/data y devuelven directamente el recurso:

{
  "id": "cnt_abc123",
  "email": "user@example.com",
  "createdAt": "2025-11-30T10:30:00.000Z"
}

Los endpoints de listado con paginación por cursor responden con:

{
  "data": [ /* items */ ],
  "cursor": "def456",
  "hasMore": true,
  "total": 10000
}

Respuesta de error

Cada error trae suficiente detalle como para depurarlo directamente:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 422,
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "errors": [
      {
        "field": "email",
        "message": "Invalid email",
        "code": "invalid_string"
      }
    ],
    "suggestion": "One or more fields have incorrect types. Check that strings are quoted, numbers are unquoted, and booleans are true/false."
  },
  "timestamp": "2025-11-30T10:30:00.000Z"
}

Campos del error:

• code — identificador estable y legible por máquina sobre el que puedes ramificar tu código
• message — explicación del fallo en lenguaje llano
• statusCode — el estado HTTP
• requestId — único por solicitud; cítalo cuando escribas a soporte
• errors — desglose de validación por campo, presente cuando aplica
• suggestion — una pista sobre cómo resolver el problema

La documentación de códigos de error cubre todos los códigos con ejemplos resueltos.

Paginación

La paginación basada en cursor es la norma en los endpoints de listado:

GET /contacts?limit=100&cursor=abc123

Parámetros:

• limit — tamaño de página (por defecto: 20, máximo: 100)
• cursor — el valor cursor devuelto por la página anterior

Respuesta:

{
  "data": [ /* items */ ],
  "cursor": "def456",
  "hasMore": true,
  "total": 10000
}

Pasa el cursor de cada respuesta al parámetro de consulta cursor de la siguiente solicitud, y detente cuando hasMore venga false. Solo la primera página (la que se pide sin cursor) calcula total; las páginas siguientes reportan total: 0 para que el listado siga siendo rápido.

Un puñado de endpoints (p. ej. GET /segments/:id/contacts) pagina por número de página en su lugar, tomando page y pageSize y devolviendo total, page y pageSize en la respuesta.

Límites de tasa

Para mantener el servicio saludable para todos, Bitelio aplica límites razonables:

• Envío de correos — regulado por proyecto para proteger la entregabilidad.
• Solicitudes de API — 1000 solicitudes/minuto por proyecto.
• Operaciones masivas — se encolan automáticamente para procesamiento asíncrono.

Superar un límite te devuelve una respuesta 429 Too Many Requests.

Códigos de error

Los errores combinan códigos de estado HTTP estándar con identificadores de código legibles por máquina:

400 Bad Request — Los parámetros son inválidos o el cuerpo de la solicitud está mal formado

401 Unauthorized — Falta la clave de API o no es válida

403 Forbidden — No tienes acceso al recurso, o el proyecto está deshabilitado

404 Not Found — No existe ese recurso

422 Unprocessable Entity — La validación rechazó la solicitud (el array errors explica por qué)

429 Too Many Requests — Alcanzaste un límite de tasa

500 Internal Server Error — Algo falló de nuestro lado (envía a soporte el ID de la solicitud)

El catálogo completo, con pasos de resolución de problemas, está en la documentación de códigos de error.

Endpoints de la API

Todos los endpoints que expone la API de Bitelio, agrupados por recurso.

API pública

Las rutas /v1/* existen para el código de tu aplicación y toman payloads planos y desnormalizados. De todos los endpoints, solo POST /v1/track acepta una clave pública (pk_*).

Contactos

Plantillas

Campañas

Segmentos

Workflows

Un workflow se guarda como un registro de workflow más un grafo de pasos, las transiciones que los conectan, y una ejecución por cada contacto que pasa por él. Los endpoints siguen esa misma estructura.

Eventos

Dominios

Actividad y analíticas

Subidas

Autenticación y gestión de usuarios

Estas rutas dan soporte al panel, que inicia sesión con cookies JWT. Rara vez importan para el trabajo servidor a servidor, pero se incluye la lista para que nada quede sin documentar.

Claves de API

Claves secretas con alcance, por proyecto. Consulta la guía de claves de API para ver el catálogo de permisos y las reglas de creación. Las tres requieren una sesión de panel con inicio de sesión y el permiso apikeys:manage — ninguna puede llamarse con una clave de API.

Configuración

Endpoints internos de webhook

La infraestructura de correo y facturación entrega aquí sus eventos. Tus aplicaciones nunca llaman a estos — aparecen solo para que la lista esté completa.

Bibliotecas cliente

Node.js

const BITELIO_SECRET_KEY = process.env.BITELIO_SECRET_KEY;

async function sendEmail(to, subject, body) {
  const response = await fetch('https://api.bitelio.com/v1/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${BITELIO_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ to, subject, body })
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error(`[${data.error.code}] ${data.error.message}`);
  }

  return data.data;
}

Python

import os
import requests

BITELIO_SECRET_KEY = os.environ['BITELIO_SECRET_KEY']

def send_email(to, subject, body):
    response = requests.post(
        'https://api.bitelio.com/v1/send',
        headers={
            'Authorization': f'Bearer {BITELIO_SECRET_KEY}',
            'Content-Type': 'application/json'
        },
        json={'to': to, 'subject': subject, 'body': body}
    )

    data = response.json()

    if not data.get('success'):
        error = data['error']
        raise Exception(f"[{error['code']}] {error['message']}")

    return data['data']

cURL

curl -X POST https://api.bitelio.com/v1/send \
  -H "Authorization: Bearer $BITELIO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "body": "Message"}'

Qué sigue

• Enviar un correo transaccional
• Registrar un evento
• Referencia de códigos de error