Sign inGet Started

Conceptos de SDK

Los SDKs de TypeScript, Go, Python y PHP siguen un mismo diseño. Cada uno tiene una base generada con tipos y un cliente de bajo nivel producido a partir de la especificación OpenAPI de Bird. Una capa escrita a mano gestiona el ciclo de vida de las solicitudes y expone la superficie curada. Esta página cubre su comportamiento compartido. Las páginas por lenguaje cubren los detalles idiomáticos.

Idempotencia automática

Cada mutación (POST, PUT, PATCH, DELETE) recibe un encabezado Idempotency-Key generado automáticamente. La clave se genera una vez por llamada lógica y se reutiliza en cada intento de reintento. Esto evita que una escritura reintentada se aplique dos veces. Si un envío expira después de que el servidor lo procesa, el reintento recibe la respuesta almacenada. Pasa tu propia clave (idempotencyKey / option.WithIdempotencyKey / idempotency_key por llamada) cuando la operación lógica abarca más de una llamada a SDK, como un bucle de reintento de la aplicación alrededor del SDK. Consulta Idempotencia para el protocolo del lado del servidor.

Reintentos seguros

Los reintentos están activados por defecto (maxRetries: 2 en cada SDK). El cliente reintenta fallos transitorios, incluyendo errores de red, tiempos de espera por intento, respuestas 429 y respuestas 5xx reintentables. Usa backoff exponencial con jitter y respeta el encabezado Retry-After del servidor. Los fallos deterministas (401, 404, 422 y otras respuestas 4xx) nunca se reintentan. Reutilizar la clave de idempotencia hace que los reintentos de mutaciones sean seguros. El tiempo de espera se aplica a cada intento (60 segundos por defecto), así que una llamada con reintentos puede tardar más. PHP usa el tiempo de espera impuesto por el cliente HTTP inyectado porque PSR-18 no tiene un tiempo de espera portable por solicitud.

Paginación

Los endpoints de listado usan paginación por cursor. Cada SDK admite iteración nativa, que obtiene páginas sucesivas automáticamente. Para control manual del cursor, usa el accessor de página individual. Cada página incluye data y next_cursor; pasa el cursor de vuelta como starting_after para avanzar.
for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
Consulta la referencia de paginación para cursores, limit y include_total.

Inferencia de región

Las claves Bird API codifican su región: bk_{region}_{token}. El SDK lee el prefijo y enruta a https://{region}.platform.bird.com automáticamente. Una opción region sobreescribe la región inferida. Un baseUrl explícito (option.WithBaseURL / base_url) tiene precedencia sobre ambos y permite desarrollo local o despliegues autoalojados. La construcción falla cuando la clave no coincide con el formato bk_{region}_ y no se ha definido una sobreescritura.

Opciones por llamada vs configuración solo en construcción

La configuración tiene dos niveles. Los ajustes de identidad y transporte son solo de construcción: la clave API, la URL base o región, y el cliente HTTP o la implementación fetch. Los ajustes de ciclo de vida se pueden definir como valores por defecto en construcción y sobreescribir por llamada: timeout, maxRetries, la clave de idempotencia y encabezados adicionales. TypeScript, Python y PHP usan un objeto de opciones al final; Go usa opciones variádicas option.With…. Los encabezados propiedad de SDK (Authorization, User-Agent, Idempotency-Key) tienen precedencia sobre los encabezados proporcionados por quien llama. Los valores por defecto de canal, como un from de email por defecto, siguen el mismo patrón.

Verificación de webhooks

Cada SDK proporciona un punto de entrada de verificación: webhooks.unwrap(rawBody, headers). Implementa Standard Webhooks con HMAC-SHA256 sobre el payload crudo y el secreto de firma de tu endpoint. Acepta entradas de firma etiquetadas con v1, rechaza timestamps fuera de una ventana de tolerancia de 5 minutos y compara firmas en tiempo constante. Pasa los bytes crudos del cuerpo de la solicitud exactamente como se recibieron. Parsear y re-serializar el JSON cambia los bytes e invalida la firma.
Si la verificación es exitosa, unwrap devuelve un evento tipado discriminado por type, como email.delivered o email.bounced. Los tipos de evento desconocidos aún se verifican y decodifican, así que gestiónalos en tu rama default. Un fallo de verificación es un error distinto (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); responde con 400. Consulta Webhooks para la configuración de endpoints y el catálogo de eventos.

Próximos pasos