La API de tarjetas de regalo para personas y agentes
Una sola API REST para cotizar, pedir y entregar tarjetas de regalo de más de 4700 marcas en más de 150 países. El acceso anticipado ya está abierto.
# 1. Quote a gift card
curl -X POST "$BIDALI_API_URL/v1/quotes" \
-H "Authorization: Bearer $BIDALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"brand": "starbucks-us", "amount": 25, "currency": "USD"}'
# 2. Order it and email it to the recipient
curl -X POST "$BIDALI_API_URL/v1/orders" \
-H "Authorization: Bearer $BIDALI_API_KEY" \
-H "Idempotency-Key: 6f1c2b7e-9d3a-4e58-b1a0-2c5d7e8f9a10" \
-H "Content-Type: application/json" \
-d '{"quote_id": "qt_123", "delivery": {"method": "email", "to": "sam@example.com"}}'Borrador, sujeto a cambios
Resumen de la API
Nueve endpoints, un solo flujo
Encuentra una marca, cotiza el precio, haz el pedido y deja que el webhook te avise cuando esté listo.
- Autenticación
- Clave de API tipo Bearer en el encabezado Authorization
- Idempotencia
- Encabezado Idempotency-Key en POST /v1/orders
- Entrega
- email, sms, link o inline en la respuesta del pedido
- Host del sandbox
- Se anuncia con el acceso anticipado
| Método | Endpoint | Qué hace |
|---|---|---|
GET | /v1/countries | Lista los países donde se venden tarjetas de regalo.Devuelve los códigos de país ISO y sus nombres. |
GET | /v1/currencies | Lista las monedas admitidas.Devuelve los códigos de moneda y la precisión en unidades menores. |
GET | /v1/brands | Busca en el catálogo.Consulta: country, category. Resultados paginados. |
GET | /v1/brands/{slug} | Obtén una marca.Denominaciones, términos e instrucciones de canje. |
POST | /v1/quotes | Cotiza una tarjeta de regalo antes de comprarla.Cuerpo: brand, amount, currency. Devuelve una cotización que vence. |
POST | /v1/orders | Pide una tarjeta de regalo a partir de una cotización.Cuerpo: quote_id, delivery (email, sms, link o inline). Envía un encabezado Idempotency-Key. |
GET | /v1/orders/{id} | Obtén un pedido y su estado.Devuelve la tarjeta de regalo cuando el pedido se completa. |
GET | /v1/balance | Obtén tu saldo prepagado.Devuelve el saldo disponible y los movimientos recientes. |
POST | /v1/webhooks | Registra un webhook.Cuerpo: url, events (order.fulfilled, order.failed, balance.low). |
En código
Del catálogo a la tarjeta de regalo entregada
HTTPS y JSON, sin más. Si sabes llamar a curl o fetch, sabes vender una tarjeta de regalo.
Explorar y registrar un webhook
# Groceries available in Canada
curl "$BIDALI_API_URL/v1/brands?country=CA&category=groceries" \
-H "Authorization: Bearer $BIDALI_API_KEY"
# Get told when an order is done or your balance runs low
curl -X POST "$BIDALI_API_URL/v1/webhooks" \
-H "Authorization: Bearer $BIDALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/bidali", "events": ["order.fulfilled", "order.failed", "balance.low"]}'Cotizar y pedir
// uuid() is any UUID generator; store the key with your own order record.
const base = process.env.BIDALI_API_URL!;
const headers = {
Authorization: `Bearer ${process.env.BIDALI_API_KEY}`,
'Content-Type': 'application/json',
};
const quote = await fetch(`${base}/v1/quotes`, {
method: 'POST',
headers,
body: JSON.stringify({ brand: 'starbucks-us', amount: 25, currency: 'USD' }),
}).then((res) => res.json());
const order = await fetch(`${base}/v1/orders`, {
method: 'POST',
headers: { ...headers, 'Idempotency-Key': uuid() },
body: JSON.stringify({
quote_id: quote.id,
delivery: { method: 'email', to: 'sam@example.com' },
}),
}).then((res) => res.json());
console.log(order.id, order.status);Lista para producción
Lo que necesitas para lanzarla
Sandbox
Prueba cada llamada con pedidos de mentira antes de tocar producción, con las mismas respuestas y los mismos errores.
Webhooks
Entérate cuando un pedido se cumple o falla, y cuando tu saldo está bajo.
Pedidos idempotentes
Envía un Idempotency-Key y reintenta sin riesgo. Un error de red nunca compra dos veces la misma tarjeta de regalo.
Saldo y estados de cuenta
Consulta tu saldo en una sola llamada y concilia cada pedido con tu estado de cuenta.
Documentación legible por máquinas
Una especificación OpenAPI 3.1 para generadores de SDK y agentes de IA: llamar a la herramienta está a un solo import de distancia.
Casos de uso
Lo que los equipos construyen con ella
Las mismas llamadas impulsan recompensas, beneficios de nómina y agentes de IA.
Incentivos para clientes
Bonos de registro, referidos y pagos por encuestas.
Recompensas para empleados
Recompensas útiles para tu equipo, en cualquier país.
Comercio agéntico
Dale a tu agente de IA un presupuesto, no una tarjeta.
Acceso anticipado
Obtén acceso al sandbox
Cuéntanos qué estás construyendo. Estamos incorporando a un grupo pequeño de equipos y te responderemos con los detalles del sandbox.
Cuéntanos sobre tu proyecto
Comparte algunos detalles y nuestro equipo te responderá.
Contactar a ventasPreguntas frecuentes
Empieza con el sandbox
Solicita acceso anticipado y haz tu primer pedido hoy mismo.