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
- Gestión de errores
- Gestión de códigos de reclamación de Cheques regalo
- Límites de la cantidad de la transacción
- Script de prueba de creación de códigos digitales
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:
- El cliente envía una solicitud de
CreateGiftCard
a la API de Incentives. - Amazon confirma fondos suficientes para la solicitud mediante la comprobación de la cuenta de pago por adelantado.
- Amazon descuenta el importe del pedido y responde con un mensaje de respuesta simultáneo
CreateGiftCard
que contienegcClaimCode
(el código de reclamación del cheque regalo) ygcExpirationDate
(fecha de caducidad, no se aplica a los cheques regalo creados en Estados Unidos, Canadá y Australia). - El código debe almacenar los valores
creationRequestId
,amount
, ycurrencyCode
y debe gestionar elgcClaimCode
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:
- Formulario largo: el socio proporciona datos específicos de ubicación del almacén para cada transacción (debe incluir
sourceId
,institutionId
ysourceDetails
) - Formulario corto: el socio proporciona solo el
sourceId
y elinstitutionId
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 . |