Identificarse
Identificarse

Crear códigos de reclamación

Crear códigos de reclamación

Asegúrese de configurar su cuenta de la API de Amazon Incentives antes de iniciar la integración. Crear una cuenta de la API de Incentives.

La API de Incentives le permite crear y distribuir códigos de reclamación de Cheques regalo de Amazon rápidamente a través de Internet.

Puede comprar códigos de reclamación de Cheques regalo de Amazon mediante un servicio web y distribuirlos a sus clientes. En este documento se describe cómo los desarrolladores pueden utilizar la API de AGCOD para crear códigos de reclamación de Cheques regalo de Amazon. Puede utilizar estos códigos de muchas maneras, por ejemplo:

  • Inserción de códigos de reclamación en Cheques regalo electrónicos
  • Regalos de grupo
  • Canje en tiempo real de códigos de reclamación en programas de fidelidad (es decir, programas de puntos).

Operaciones

Su código realiza solicitudes HTTP POST firmadas a nuestros puntos de enlace para crear o cancelar códigos de reclamación. (No se aceptan solicitudes SOAP). El cuerpo de sus solicitudes HTTP contendrá JSON o XML.

Nota: Todas las solicitudes a un punto de enlace de operación de la API de Incentives deben estar firmadas digitalmente mediante sus credenciales de seguridad de la API de Incentives y el algoritmo de firma Signature Version 4.

Operación Descripción
CreateGiftCard Si hay fondos suficientes en la cuenta de prepago, se deduce el importe y se responde con un código de reclamación del cheque regalo, junto con otros detalles de la transacción.
CancelGiftCard Cancela un código de reclamación de un cheque regalo si un cliente de Amazon no lo ha reclamado y este no ha caducado.
GetAvailableFunds Devuelve el saldo de la cuenta de prepago.

En la siguiente tabla se describen los conceptos y elementos que se utilizarán al llamar a estos puntos de enlace:

Producto Descripción
partnerId Un identificador único (DISTINGUE ENTRE MAYÚSCULAS Y MINÚSCULAS, la primera letra está en mayúscula y las cuatro siguientes en minúsculas) proporcionado por el equipo de Amazon. Este valor aparece en la carga de cada solicitud de AGCOD Gateway.
creationRequestId Identificador único para cada solicitud de CreateGiftCard. Debe generar un nuevo valor para cada solicitud de creación (excepto para reintentos). (Ver las notas más abajo.)
RespuestaCreateGiftCard y CancelGiftCard Cada solicitud a estos puntos de enlace devuelve una respuesta que su código debe examinar, y es posible que deba guardarlo.
Transaction Una transacción es cualquier solicitud de respuesta que dé lugar a la creación o cancelación de un cheque regalo dentro de los sistemas de Amazon.

Para mantener el creationRequestId globalmente, siga estos requisitos:

  • Genere un valor alfanumérico único dentro del sistema. Este ID puede tener hasta 40 caracteres alfanuméricos.
  • Comience el valor creationRequestId con su partnerID.

Ejemplo: Si su partnerID es Amzn1, su creationRequestId debe comenzar con Amzn1 y cualquier carácter adicional que desee en su ID (ejemplo: Amzn154321). Como la API es idempotente, si se envía una solicitud con un creationRequestId que se utilizó anteriormente, la API Incentives devolverá el estado original que se creó la primera vez que se utilizó creationRequestId.

CreateGiftCard

La operación CreateGiftCard crea un código de reclamación del cheque regalo y deduce el importe de la cuenta de prepago. La respuesta contiene detalles que debe almacenar.

El valor creationRequestId identifica de forma única cada solicitud de creación, junto con otros detalles como la cantidad, la moneda, etc. (además de los metadatos sobre esa solicitud, información de autenticación, etc.)

Para realizar esta operación, se deben realizar los siguientes pasos:

  1. El cliente envía una solicitud de CreateGiftCard a la API de Incentives.
  2. Amazon confirma fondos suficientes para la solicitud mediante la comprobación de la cuenta de pago por adelantado.
  3. Amazon descuenta el importe del pedido y responde con un mensaje de respuesta simultáneo CreateGiftCard que contiene gcClaimCode (el código de reclamación del cheque regalo) y gcExpirationDate (fecha de caducidad, no se aplica a los cheques regalo creados en Estados Unidos, Canadá y Australia).
  4. El código debe almacenar los valores creationRequestId, amount, y currencyCode y debe gestionar el gcClaimCode de forma segura. Consulte las Pautas de almacenamiento de datos para obtener más información.

Ejemplo de solicitud

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

Ejemplo de respuesta

<CreateGiftCardResponse>
    <gcClaimCode>W3GU-YD4NGH-88C8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>EUR</currencyCode>
            <amount>1.00</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A3B6AC387ESRIX</gcId>
    <creationRequestId> AwssbTSpecTest001</creationRequestId>
    <gcExpirationDate>Mon Jun 09 21:59:59 UTC 2025</gcExpirationDate>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

Esta operación es idempotente, por lo que si la API de Incentives recibe más de una solicitud con el mismo creationRequestId, solo la primera solicitud dará como resultado la creación de un nuevo cheque regalo y todas las respuestas posteriores devolverán el mismo cheque regalo original. No se tratarán como transacciones diferentes.

Una invocación de la llamada CreateGiftCard da como resultado la creación de un solo código de reclamación de cheque regalo (la creación masiva no se admite en este momento).

Necesario para los revendedores: ProgramID

Puede utilizar el campo programID para ayudar a realizar el seguimiento a los clientes y usar transacciones. programID es un identificador aprobado proporcionado por Amazon a través de un proceso de envío. Primero debe enviar la información del cliente y el ejemplo de uso a través de nuestro proceso de solicitud de socio. Los envíos aprobados reciben un número de referencia llamado programID que su código incluirá en cada llamada de transacción a la API. El programID es alfanumérico y puede tener hasta 100 caracteres de longitud.

El siguiente mensaje de ejemplo resalta las modificaciones necesarias para acomodar el campo programID.

<CreateGiftCardRequest>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <partnerId>Awssb</partnerId>
  <value>
    <currencyCode>EUR</currencyCode>
    <amount>1.00</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</CreateGiftCardRequest>

Necesario para cupones de producto: productType

El campo productType es obligatorio para crear un código de reclamación de cupón de producto de Amazon. Debe recibir autorización para usar este campo. Este campo será diferente y único para cada tipo de vale de producto. Si no se aprueba este campo opcional, el código de reclamación devuelto será para un Cheque regalo de Amazon. Este atributo es alfanumérico con una longitud máxima de 50 caracteres.

Nota: Solo los socios autorizados pueden crear cupones de producto. Para obtener más información, póngase en contacto con su administrador de cuentas.

Los tipos de producto disponibles se pueden encontrar en esta hoja de cálculo.

<CreateGiftCardRequest>
  <creationRequestId>Humana_2018072650</creationRequestId>
  <partnerId>Humana</partnerId>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>25</amount>
  </value>
  <productType>bookPV</productType>
</CreateGiftCardRequest>

Requisitos adicionales en emplazamientos físicos

Cada llamada a CreateGiftCard que se produzca en una ubicación física debe incluir detalles de la ubicación en la que se produjo la transacción. Las solicitudes a estos puntos de enlace pueden incluir un objeto transactionSource que describe la ubicación física del evento.

Campo en transactionSource Descripción
sourceId Identificador de la entidad de origen de una transacción (Ejemplo: número de tienda o ID de tienda).
institutionId Identificador de una entidad matriz de origen de una transacción (Ejemplo: ID del vendedor). Si la entidad matriz no existe, copie sourceId.
sourceDetails cadena para proporcionar más información sobre el origen de la transacción. Debe contener la clave institutionName con valor como nombre de la fuente (por ejemplo, nombre del comerciante). Debe incluirse otra información, como la ubicación de la fuente, el número de teléfono, etc.
institutionParentCompany Nombre de la empresa matriz para instituitionName. Si no hay una empresa matriz, se debe repetir institutionName.

Existen dos opciones para enviar datos de ubicación de tienda a Amazon:

  1. Formulario largo: el socio proporciona datos específicos de ubicación del almacén para cada transacción (debe incluir sourceId, institutionId y sourceDetails)
  2. Formulario corto: el socio proporciona solo el sourceId y el institutionId en la solicitud de la API. Debe enviarse un archivo de mapeo de ubicación independiente que asigne estos identificadores a ubicaciones físicas. Consulte las instrucciones del archivo de mapeo de ubicaciones en esta hoja de cálculo.

A continuación se muestra un ejemplo de carga de "formulario largo" para el origen de la transacción en formato XML y JSON. Tenga en cuenta que sourceDetails debe formatearse como un blob de JSON. En el ejemplo JSON, el blob de JSON utiliza la barra invertida para evitar las comillas.

Ejemplo de formulario largo del cuerpo XML (tenga en cuenta que el valor sourceDetails debe formatearse como un blob de JSON):

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

Ejemplo de formulario corto del cuerpo XML:

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

Ejemplo de formulario corto del cuerpo JSON:

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceId": "59990492",
    "institutionId": "99990492"
  }
}

Ejemplo de formulario largo del cuerpo JSON:

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}",
    "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"
  }
}

Opcional: atributo de referencia externa

Puede utilizar el campo externalReference para pasar su propio identificador de referencia como una cadena al realizar solicitudes de código de reclamación (hasta 100 caracteres Unicode). El campo externalReference se puede utilizar para almacenar una asignación conveniente que le ayude con el seguimiento. Por ejemplo, puede especificar reclamaciones de seguros, quioscos, casos de clientes, ID de pedido, cuentas de clientes de revendedor o almacenar información en el campo externalReference.

Nota: En este campo solo se permiten referencias opacas de orden sin contenido en lenguaje natural.

El identificador en el campo externalReference aparece con la transacción en el portal de la API de Incentives, en la descarga Actividad detallada.

El siguiente ejemplo incluye un campo externalReference.

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
    <externalReference>889jj14797</externalReference>
</CreateGiftCardRequest>

Campos de respuesta

Estos elementos pueden aparecer en el cuerpo de respuesta de una llamada positiva a la operación CreateGiftCard.

Producto Descripción
gcClaimCode Código que un cliente puede canjear de forma manual más adelante. Almacénelo de forma segura y bórrelo después de distribuirlo. Disponible en Amazon más adelante a través de una llamada idéntica a CreateGiftCard (ver más abajo).
amount Cantidad en tarjeta, en moneda de la tarjeta.
currencyCode Un código de moneda ISO-4217 que especifica la moneda de la tarjeta.
cardStatus Estado de la tarjeta después de esta operación. Valor positivo: Fulfilled
gcId Identificador único del cheque regalo que indica que una llamada a CreateGiftCard dio lugar a un gcClaimCode.
creationRequestId Identificador único para esta solicitud. Comienza con el ID de socio.
gcExpirationDate Fecha de caducidad. El cliente no puede reclamar el cheque después de esta fecha. (Nunca presente para cheques emitidos en Estados Unidos, Canadá o Australia.)
status Resultado de esta operación. Valor positivo: SUCCESS

Puede volver a solicitar un gcClaimCode existente más tarde llamando de nuevo a CreateGiftCard con los mismos valores creationRequestId, currencyCode y amount.

El punto de enlace CreateGiftCard devuelve el cardStatus actual de un código de reclamación.

Gestionado: el código de reclamación se ha creado correctamente.

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

RefundedToPurchaser: el código de reclamación se ha cancelado correctamente y se ha reembolsado en la llamada previa a CancelGiftCard.

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>RefundedToPurchaser</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

Caducado: el código de reclamación no se reclamó antes de la fecha de caducidad.

<CreateGiftCardResponse>
    <gcClaimCode>G22G-WACQNJ-27S8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>JPY</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Expired</cardStatus>
    </cardInfo>
    <gcId>A2BWWZ1SGEZF2F</gcId>
    <creationRequestId>Awssb-ABR-10</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

CancelGiftCard

Puedes cancelar un cheque regalo siempre y cuando no lo solicite un cliente de Amazon. El creationRequestId original utilizado para crear el cheque regalo será necesario para cancelarlo.

Nota: Esta operación solo se puede ejecutar en los 15 minutos siguientes al momento de creación de la solicitud. Una vez transcurrido el período de tiempo, el código de reclamación no se puede cancelar y los cargos se deducirán de su saldo de prepago.

Para realizar esta operación, envíe una solicitud CancelGiftCard y la API de Incentives responderá con una CancelGiftCardResponse simultánea.

Tanto la operación CreateGiftCard como la CancelGiftCard son idempotentes, por lo que si la API de Incentives recibe más de una de esas solicitudes con el mismo creationRequestId, la primera solicitud dará como resultado la creación/cancelación de la solicitud de cheque regalo, mientras que todas las respuestas posteriores no harán nada y no serán tratadas como una transacción única.

Ejemplo de solicitud

POST /CancelGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
</CancelGiftCardRequest>

Ejemplo de respuesta

<CancelGiftCardResponse>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <status>SUCCESS</status>
</CancelGiftCardResponse>

GetAvailableFunds

Esta operación devuelve la cantidad de fondos disponibles actualmente en su cuenta de Amazon Incentives. Proporciona una alternativa a iniciar sesión en el portal de la API de Incentives para ver los fondos disponibles. Puede utilizar esta operación para supervisar su saldo y emitir alertas.

Notas:

  • Esta operación se limita a una transacción por segundo. Los intentos de enviar solicitudes a una velocidad mayor serán ignorados.
  • Dado que no hay saldo de cuenta real en un Sandbox, la operación GetAvailableFunds siempre devolverá un saldo cero.
Parámetro de solicitud Descripción
partnerId Un identificador único que distingue entre mayúsculas y minúsculas asignado a su cuenta por Amazon
Parámetro de respuesta Descripción
amount El valor de los fondos disponibles actualmente en su cuenta de prepago/pospago. Nota: el entorno Sandbox siempre devolverá un valor cero.
currencyCode El código de moneda ISO-4217
status El estado de la solicitud. En funcionamiento normal, este valor es success.
timestamp Fecha en UTC yyyy-MM-dd HH:mm:ss

Solicitud de muestra

POST 
/GetAvailableFunds HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.GetAvailableFunds
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657

{"partnerId": "Aptuk"}

  Respuesta de muestra

{
"availableFunds":{
"amount":10.0,
"currencyCode":"USD"
},
"status":"SUCCESS",
"timestamp":20170915T200959Z
}

Ejemplo de solicitudes de operación con detalles de firma

En esta sección se muestran llamadas de ejemplo a CreateGiftCard y CancelGiftCard, incluidos valores de firma de ejemplo.

Parámetros requeridos

Nota: El valor de moneda (USD, GBP, EUR, JPY, AUD, TRY, AED) puede variar según la configuración regional.

Encabezado Valor
Método de solicitud HTTP POST
URI canónico /CreateGiftCard
Cadena de consulta canónica " (cadena vacía)
Encabezados canónicos (Ver más abajo)
SignedHeaders content-type;host;x-amz-date;x-amz-target
Algoritmo AWS4-HMAC-SHA256
Fecha de solicitud 20130910T221949Z
CredentialScope 20130910/us-east-1/AGCODService/aws4_request
Nombre del servicio AGCODService
ID de solicitud de creación AwssbTSpecTest001
Servidor agcod-v2-gamma.amazon.com (use applicable endpoint)
Nombre de la región us-east-1 (use applicable endpoint)
ID de socio Awssb (use your own Partner ID)
Cantidad 1
Código de moneda USD

Los encabezados canónicos pueden ser así:

    accept:application/json
    content-type:application/json
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T222620Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

o así:

    content-type:application/x-www-form-urlencoded; charset=UTF-8
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T221949Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

CreateGiftCard

Nota: Los siguientes ejemplos se crearon con una cuenta de prueba de Amazon. Debe usar sus propios identificadores de acceso (accessKeyID, partnerID, requestID).

Muestra de solicitud POST HTTP CreateGiftCard con carga JSON

PAYLOAD

{"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "value": {"currencyCode": "USD", "amount": 1.00}}

HASHED PAYLOAD

6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

CANONICAL REQUEST

POST
/CreateGiftCard

accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

HASHED CANONICAL REQUEST

447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222620Z
20130910/us-east-1/AGCODService/aws4_request
447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71
{"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "value": {"currencyCode": "USD", "amount": 1.00}}

Muestra de solicitud POST HTTP CreateGiftCard con carga XML

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

CANONICAL REQUEST

POST
/CreateGiftCard

accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

HASHED CANONICAL REQUEST

4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T221949Z
20130910/us-east-1/AGCODService/aws4_request
4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

Muestra de respuesta CreateGiftCard

Cuerpo de respuesta JSON

{
  "cardInfo": {
    "cardNumber": null,
    "cardStatus": "RefundedToPurchaser",
    "expirationDate": null,
    "value": {
      "amount": 1,
      "currencyCode": "USD"
    }
  },
  "creationRequestId": "AwssbTSpecTest001",
  "gcClaimCode": "Z7NV-LBBG39-75MU",
  "gcExpirationDate": null,
  "gcId": "A2GCN9BRX5QS76",
  "status": "SUCCESS"
}

Cuerpo de respuesta XML

<CreateGiftCardResponse>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <cardInfo>
    <value>
      <amount>1.0</amount>
      <currencyCode>USD</currencyCode>
    </value>
    <cardStatus>Fulfilled</cardStatus>
  </cardInfo>
  <status>SUCCESS</status>
  <gcId>A2GCN9BRX5QS76</gcId>
  <gcClaimCode>Z7NV-LBBG39-75MU</gcClaimCode>
</CreateGiftCardResponse>

CancelGiftCard

Muestra de solicitud POST HTTP de CancelGiftCard con carga JSON

PAYLOAD

 {"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "gcId": "A2GCN9BRX5QS76"}

HASHED PAYLOAD

 7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

CANONICAL REQUEST

POST
/CancelGiftCard

accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

HASHED CANONICAL REQUEST

0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222545Z
20130910/us-east-1/AGCODService/aws4_request
0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CancelGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949
{
  "creationRequestId": "AwssbTSpecTest001",
  "partnerId": "Awssb",
  "gcId": "A2GCN9BRX5QS76"
}

Muestra de solicitud POST HTTP CancelGiftCard con carga XML

PAYLOAD

<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

HASHED PAYLOAD

bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

CANONICAL REQUEST

POST
/CancelGiftCard

accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

HASHED CANONICAL REQUEST

8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222449Z
20130910/us-east-1/AGCODService/aws4_request
8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CancelGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

Muestra de respuesta de CancelGiftCard

Cuerpo de respuesta JSON

{"creationRequestId":"AwssbTSpecTest001","gcId":"A2GCN9BRX5QS76","status":"SUCCESS"}

Cuerpo de respuesta XML

<CancelGiftCardResponse>
<creationRequestId>AwssbTSpecTest001</creationRequestId>
<status>SUCCESS</status>
<gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardResponse>

Parámetros requeridos

Nota: El valor de moneda (USD, GBP, EUR, JPY, AUD, TRY, AED) puede variar según la configuración regional.

  • HTTP Request Method=POST
  • Canonical URI=/CancelGiftCard
  • Canonical Query String=" (cadena vacía)

  • Canonical Headers=

      accept:application/json
  content-type:application/json
  host:agcod-v2-gamma.amazon.com
  x-amz-date:20130910T222545Z
  x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

    o

       accept:application/x-www-form-urlencoded; charset=UTF-8
   content-type:application/x-www-form-urlencoded; charset=UTF-8
   host:agcod-v2-gamma.amazon.com
   x-amz-date:20130910T222449Z
   x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
  • SignedHeaders=tipo de contenido; host; x-amz-date; x-amz-target
  • Algorithm=AWS4-HMAC-SHA256
  • Request Date=20130910T222449Z
  • CredentialScope=20130910/us-east-1/AGCODService/aws4_request
  • Service Name=AGCODService
  • Creation Request ID=AwssbTSpecTest001
  • Host=agcod-v2-gamma.amazon.com (use el punto de enlace aplicable)
  • Region Name=us-east-1 (use el punto de enlace aplicable)
  • Partner Id=Awssb (use su propio ID de socio)

Ejemplo de firma de Signature V4

Para ayudarle en el desarrollo, hemos incluido un ejemplo de prueba con clave de acceso/claves secretas ficticias para generar una prueba de respuesta conocida para diferentes etapas de la firma a continuación. Los detalles sobre cómo ejecutar cada etapa de la firma se pueden encontrar aquí. Vea también este diagrama del proceso.

Parámetros utilizados

Partner ID: Test
creationRequestId: Test001
AGCODAccess Key: fake-access-key
AGCOD Secret Key: fake-secret-key
Timestamp: 20140205T171524Z

kSecret: su-credencial-de-seguridad
kDate: 41b8dd5e0d1716ba90401d46b58b12d500accdd2ea9c2b22a2d275946c9d978e
kRegion: 7b47360ce7afbe1b839e0b0e55834df99979a5414bc7f846b17c9374d230d45d
kService: 68136b0a64b2d01c8934370288b46500243645e468f521503e0d1fa73526d409
kSigning: 27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>Test001</creationRequestId>
    <partnerId>Test</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

CANONICAL REQUEST

POST
/CreateGiftCard
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

HASHED CANONICAL REQUEST

7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

STRING TO SIGN

AWS4-HMAC-SHA256
20140205T171524Z
20140205/us-east-1/AGCODService/aws4_request
7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

DERIVED SIGNING KEY

27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

SIGNATURE

 e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=fake-aws-key/20140205/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1
<CreateGiftCardRequest>
    <creationRequestId>Test001</creationRequestId>
    <partnerId>Test</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</CreateGiftCardRequest>

Gestión de errores

Cada respuesta enviada desde la API de Incentives tiene un elemento de estado que describe el estado de ejecución de la operación en particular; hay tres valores de statusCode : SUCCESS, FAILURE y RESEND. Consulte Gestión de errores para obtener más información.

Códigos de error

Utilizamos una convención de códigos F2XX para denotar errores cuando la solicitud no es válida. Utilizamos una convención de F1XX cuando los errores los causa Amazon.

Hemos proporcionado ID de solicitud de error simulado para simular ciertas respuestas de error con las llamadas Crear/Cancelar. Al simular una respuesta de error, el ID de solicitud de error simulado tendrá que pasar al campo creationRequestId similar a un ID de solicitud normal. Los valores pasados para el resto de los campos simplemente se repetirán en la respuesta. Para simular una respuesta positiva, el valor de F1000 se puede pasar por el identificador de solicitud de error simulado. Consulte Ejemplos de pruebas de simulación y Gestión de errores para obtener más detalles.

Gestión de los códigos de reclamación de los cheques regalo

Los códigos de reclamación de cheques regalo tienen un valor monetario y deben tratarse de forma muy segura. Recomendamos que disponga de controles para garantizar la gestión con total seguridad de los datos confidenciales (códigos de reclamación de cheques regalo, credenciales de acceso de seguridad, etc.). Esto incluye definir controles de auditoría adecuados en los sistemas de archivos/bases de datos donde se almacena información confidencial. Debe cambiar periódicamente la contraseña de sus cuentas del portal de la API de Incentives que tengan acceso a claves secretas. Recomendamos cambiar las claves de acceso al menos una vez cada 180 días (6 meses). El portal de la API de Incentives le permite generar una nueva clave de acceso en cualquier momento. Sin embargo, AGCOD no admite el cambio automático de claves.

  • Los códigos de reclamación deben ser confidenciales mientras están en tránsito entre Amazon y sus sistemas.
  • Los códigos de reclamación no deben almacenarse.
  • Debe establecer prácticas de gestión de datos seguras en las instalaciones en las que se pueda acceder a los códigos de reclamación (ya sea en tránsito o en reposo).

Para obtener más información, consulte Pautas para el almacenamiento de datos de la API de Incentives.

Nota: Usted será responsable de los códigos de reclamación en cuanto la API de Incentives responda correctamente a su solicitud de CreateGiftCard.

Límites de la cantidad de la transacción

Las llamadas a CreateGiftCard deben especificar un código de moneda autorizado por su cuenta, dentro del rango permitido para el país de emisión.

País Código de moneda Rango
Australia AUD $ 1 - $ 2 000
Canadá CAD $ 0,01 - $ 5 000
Francia EUR € 0,01 - € 5 000
Alemania EUR € 0,01 - € 5 000
Italia EUR € 0,01 - € 5 000
Japón JPY ¥ 1 - ¥ 500 000
México MXN $5 - $ 5 000
España EUR € 0,01 - € 5 000
Turquía TRY ₺ 1 - ₺ 5 000
Emiratos Árabes Unidos AED 1 AED - 6 000 AED
Reino Unido GBP £ 0.01 - £ 5 000
Estados Unidos de América USD $ 0.01 - $ 2 000

Script de prueba de creación de códigos digitales

Para verificar su integración con la API, ejecute las siguientes pruebas.

Descripción de la prueba Detalle de prueba Resultado esperado
1. Creación de un código de reclamación Inicie una solicitud de CreateGiftCard por una cantidad válida, como 100 unidades de su moneda, y gestione la respuesta recibida. Debería recibir una respuesta SUCCESS. Su sistema debe manejar correctamente la respuesta SUCCESS, en función de los requisitos.
2. Cancelación de un código de reclamación Inicie una solicitud CancelGiftCard para el creationRequestId creado en la prueba (1). Debería recibir una respuesta SUCCESS. Su sistema debe manejar correctamente la respuesta SUCCESS, en función de los requisitos.
3. Idempotencia Inicie una solicitud de CreateGiftCard por 1000 unidades de su moneda y gestione la respuesta recibida. Envíe otra solicitud CreateGiftCard con el mismo creationRequestId. Debe recibir una respuesta SUCCESS y los mismos gcId y claimCode.