Emitir una gift card

POST/giftcardsProbar

ServidorURL base

API key x-api-keyRecordar la clave en este navegador (localStorage, no sale de aquí)

CabecerasIdempotency-KeyÚnico por operación. El alcance es tu cuenta **y el modo** de la key: una `sk_test_` y una `sk_live_` no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera `Idempotent-Replayed: true`; con otro payload da `409 idempotency_key_reused`. Los campos secretos (el `url` de una gift card, una `apiKey` nueva, un `webhookSecret`) sólo llegan en la primera respuesta: al repetir llegan en `null`.

Cuerpo de la petición (JSON)

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST

/giftcards

const url = 'http://localhost:3000/v1/giftcards';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: '{"externalId":"cacao-order-88213","brandId":"farmatodo","amount":2000,"expiresInDays":90,"beneficiaryName":"example","giftSender":"example","giftMessage":"example","sticker":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:3000/v1/giftcards \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "externalId": "cacao-order-88213", "brandId": "farmatodo", "amount": 2000, "expiresInDays": 90, "beneficiaryName": "example", "giftSender": "example", "giftMessage": "example", "sticker": "example" }'

Scope giftcards:write. Se paga con tu saldo en USD al emitirla: valor más tu margen. Con una key sk_test_ es de pruebas: no se canjea ni se cobra. externalId es tu id de la orden y es la idempotencia real: la misma orden nunca se emite ni se cobra dos veces.

El url lleva, después de #k=, la clave para gastar la tarjeta: quien tiene el enlace tiene el saldo. Sólo sale en el 201; no lo guardamos. Si lo pierdes, pídelo con GET /giftcards/{id}?includeLink=1.

Authorizations

ApiKeyAuth

Parameters

Header Parameters

Idempotency-Key

string

Único por operación. El alcance es tu cuenta y el modo de la key: una sk_test_ y una sk_live_ no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera Idempotent-Replayed: true; con otro payload da 409 idempotency_key_reused. Los campos secretos (el url de una gift card, una apiKey nueva, un webhookSecret) sólo llegan en la primera respuesta: al repetir llegan en null.

Request Body^required

application/json

object

externalId

required

Tu id de la orden

string

/^[A-Za-z0-9_.:-]{1,64}$/

Example

cacao-order-88213

brandId

required

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

Example

farmatodo

amount

required

Centavos de USD (2000 = $20,00), dentro del mínimo y máximo de la tienda

integer

>= 100 <= 50000

Example

expiresInDays

integer

default: 90 >= 1 <= 365

beneficiaryName

string

<= 60 characters

giftSender

string

<= 60 characters

giftMessage

string

<= 240 characters

sticker

string

<= 16 characters

Responses

200

Ese externalId ya se había emitido: es la misma tarjeta (replay: true), no se cobra otra vez y url viene en null.

application/json

object

giftcard

object

string format: uuid

externalId

string

mode

string

Allowed values: test live

brandId

string

amount

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

fee

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

balance

Lo que queda por gastar

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

status

pendiente → activa → usada (saldo en cero) o expirada. fallida es una emisión que no salió: su dinero ya volvió a tu saldo.

string

Allowed values: pendiente activa usada expirada fallida

opened

Si quien la recibió ya abrió el regalo

boolean

expiresAt

string format: date-time

nullable

createdAt

string format: date-time

error

Sólo si está fallida

object

code

string

message

string

url

Sólo en la primera respuesta 201. Lleva la clave de gasto después de #k=: trátalo como dinero. En una repetición con la misma Idempotency-Key llega null: pídelo con GET /v1/giftcards/{id}?includeLink=1.

string

nullable

replay

Sólo en el 200: ese externalId ya se había emitido

boolean

Example

{
  "giftcard": {
    "externalId": "cacao-order-88213",
    "mode": "test",
    "brandId": "farmatodo",
    "amount": {
      "asset": "USD",
      "amount": "2000"
    },
    "fee": {
      "asset": "USD",
      "amount": "2000"
    },
    "balance": {
      "asset": "USD",
      "amount": "2000"
    },
    "status": "pendiente",
    "error": {
      "code": "giftcards_unavailable"
    }
  }
}

Headers

Idempotent-Replayed

string

Allowed values: true

true cuando la respuesta es la repetición guardada de una petición anterior con la misma Idempotency-Key. No viene en la primera.

201

Emitida, con el url

application/json

object

giftcard

object

string format: uuid

externalId

string

mode

string

Allowed values: test live

brandId

string

amount

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

fee

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

balance

Lo que queda por gastar

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

status

pendiente → activa → usada (saldo en cero) o expirada. fallida es una emisión que no salió: su dinero ya volvió a tu saldo.

string

Allowed values: pendiente activa usada expirada fallida

opened

Si quien la recibió ya abrió el regalo

boolean

expiresAt

string format: date-time

nullable

createdAt

string format: date-time

error

Sólo si está fallida

object

code

string

message

string

url

string

nullable

replay

Sólo en el 200: ese externalId ya se había emitido

boolean

Example

{
  "giftcard": {
    "externalId": "cacao-order-88213",
    "mode": "test",
    "brandId": "farmatodo",
    "amount": {
      "asset": "USD",
      "amount": "2000"
    },
    "fee": {
      "asset": "USD",
      "amount": "2000"
    },
    "balance": {
      "asset": "USD",
      "amount": "2000"
    },
    "status": "pendiente",
    "error": {
      "code": "giftcards_unavailable"
    }
  }
}

Headers

Idempotent-Replayed

string

Allowed values: true

true cuando la respuesta es la repetición guardada de una petición anterior con la misma Idempotency-Key. No viene en la primera.

202

No hubo respuesta a tiempo: queda pendiente con el dinero retenido y se resuelve sola (llega giftcard.issued o giftcard.failed). No la repitas con otro externalId.

application/json

object

giftcard

object

string format: uuid

externalId

string

mode

string

Allowed values: test live

brandId

string

amount

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

fee

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

balance

Lo que queda por gastar

object

asset

string

Allowed values: USD

amount

Centavos de USD

string

status

pendiente → activa → usada (saldo en cero) o expirada. fallida es una emisión que no salió: su dinero ya volvió a tu saldo.

string

Allowed values: pendiente activa usada expirada fallida

opened

Si quien la recibió ya abrió el regalo

boolean

expiresAt

string format: date-time

nullable

createdAt

string format: date-time

error

Sólo si está fallida

object

code

string

message

string

url

string

nullable

replay

Sólo en el 200: ese externalId ya se había emitido

boolean

Example

{
  "giftcard": {
    "externalId": "cacao-order-88213",
    "mode": "test",
    "brandId": "farmatodo",
    "amount": {
      "asset": "USD",
      "amount": "2000"
    },
    "fee": {
      "asset": "USD",
      "amount": "2000"
    },
    "balance": {
      "asset": "USD",
      "amount": "2000"
    },
    "status": "pendiente",
    "error": {
      "code": "giftcards_unavailable"
    }
  }
}

Headers

Idempotent-Replayed

string

Allowed values: true

true cuando la respuesta es la repetición guardada de una petición anterior con la misma Idempotency-Key. No viene en la primera.

400

invalid_amount (fuera de 100 a 50000) o validation_failed

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

403

giftcards_program_suspended

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

409

giftcard_external_id_reused: ese externalId ya se usó con otra tienda u otro monto

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

422

insufficient_tenant_funds (no te alcanza el saldo en USD; no se cobró nada) o giftcard_brand_not_allowed (meta.allowedBrands)

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

503

giftcards_unavailable: no se cobró nada; reintenta con el MISMO externalId

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

Emitir una gift card

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Example

Example

Responses

200

Example

Headers

201

Example

Headers

202

Example

Headers

400

Example

403

Example

409

Example

422

Example

503

Example

Request Body^required