Ir al contenido
API de tarjetas de regaloAcceso anticipado

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.

curl
# 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
Borrador — sujeto a cambios
Endpoints del borrador de la API de tarjetas de regalo. Borrador — sujeto a cambios.
MétodoEndpointQué hace
GET/v1/countriesLista los países donde se venden tarjetas de regalo.Devuelve los códigos de país ISO y sus nombres.
GET/v1/currenciesLista las monedas admitidas.Devuelve los códigos de moneda y la precisión en unidades menores.
GET/v1/brandsBusca 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/quotesCotiza una tarjeta de regalo antes de comprarla.Cuerpo: brand, amount, currency. Devuelve una cotización que vence.
POST/v1/ordersPide 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/balanceObtén tu saldo prepagado.Devuelve el saldo disponible y los movimientos recientes.
POST/v1/webhooksRegistra 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

curl
# 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

TypeScript (fetch)
// 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 ventas

Preguntas frecuentes

El acceso anticipado ya está abierto. Compartiremos una fecha de disponibilidad general con los equipos de acceso anticipado en cuanto esté definida.

Los límites se publicarán junto con el sandbox. Los equipos de acceso anticipado nos ayudan a definirlos, así que cuéntanos el volumen que esperas.

El acceso a producción requiere una revisión de verificación de negocio, como parte de nuestro programa de cumplimiento completo. Puedes desarrollar en el sandbox antes de que termine.

No hay comisión por la plataforma. Pagas las tarjetas de regalo que pides, y ves el precio en una cotización antes de comprometerte.

El catálogo cubre más de 4700 marcas en más de 150 países. Llama a GET /v1/countries y GET /v1/brands para ver qué hay disponible en cada lugar.

Sí. La API es HTTPS y JSON sin más, y el borrador de la especificación OpenAPI 3.1 permite que un agente la llame como herramienta. Hay un servidor MCP en planes.

Empieza con el sandbox

Solicita acceso anticipado y haz tu primer pedido hoy mismo.