Listar tarjetas de regalo

GET

https://app.recurrente.com/api/gift_cards

GET

/api/gift_cards

curl https://app.recurrente.com/api/gift_cards \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json"

[
  {
    "id": "gc_9f8e7d6c",
    "account_id": "ac_987654",
    "code": "GC-2BCD-FG3H",
    "status": "active",
    "currency": "GTQ",
    "initial_amount_in_cents": 25000,
    "balance_in_cents": 15000,
    "expires_on": "2024-12-31",
    "recipient": {
      "name": "María López",
      "email": "maria.lopez@example.com",
      "phone": "+502 5555 1234"
    },
    "message": "Feliz cumpleaños, disfruta tu regalo!",
    "deliver_on": "2024-01-10",
    "delivered_at": "2024-01-10T14:45:00Z",
    "purchaser": {
      "name": "Carlos Méndez",
      "email": "carlos.mendez@empresa.com"
    },
    "checkout_id": "chk_4567abcd",
    "public_url": "https://recurrente.com/gift_cards/gc_9f8e7d6c",
    "transactions": [
      {
        "id": "gct_1a2b3c4d",
        "kind": "issue",
        "amount_in_cents": 25000,
        "balance_after_in_cents": 25000,
        "currency": "GTQ",
        "account_id": "ac_987654",
        "checkout_id": "chk_4567abcd",
        "note": "Emisión inicial de la tarjeta",
        "created_at": "2024-01-10T14:45:00Z"
      },
      {
        "id": "gct_5e6f7g8h",
        "kind": "redeem",
        "amount_in_cents": -10000,
        "balance_after_in_cents": 15000,
        "currency": "GTQ",
        "account_id": "ac_987654",
        "checkout_id": "chk_7890efgh",
        "note": "Canje en tienda física",
        "created_at": "2024-02-05T11:20:00Z"
      }
    ],
    "created_at": "2024-01-10T14:45:00Z"
  }
]

Las tarjetas que la cuenta puede tomar (las suyas y las de su organización), de la más nueva a la más vieja, cada una con su saldo y sus movimientos. q busca por código (en cualquier forma: “gc 2bcd-fg3h” o “2BCDFG3H”) o, desde 3 caracteres, por nombre o correo de quien la recibió.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Query parameters

statusenumOptional

Allowed values:

qstringOptional

Código, o parte del nombre o correo de quien la recibió.

pageintegerOptionalDefaults to 1

Response

Las tarjetas

idstringOptional

account_idstringOptional

La cuenta que la vendió.

codestringOptional

El código que se canjea. Es un secreto al portador.

statusenumOptional

Allowed values:

currencystringOptional

initial_amount_in_centsintegerOptional

balance_in_centsintegerOptional

expires_ondate or nullOptional

recipientobjectOptional

messagestring or nullOptional

deliver_ondate or nullOptional

delivered_atdatetime or nullOptional

purchaserobjectOptional

checkout_idstring or nullOptional

El checkout que la vendió.

public_urlstringOptional

La página de saldo de la tarjeta, la que abre su QR.

transactionslist of objectsOptional

Sus movimientos, del más viejo al más nuevo.

created_atdatetimeOptional

Errors

403

Forbidden Error