API de Incentives

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 proporciona puntos de enlace programáticos que puede utilizar para realizar estas tareas en tiempo real:

• Cree códigos promocionales que se puedan utilizar en el sitio web de Amazon como moneda para comprar productos.
• Active cheques regalo físicos.
• Abone el saldo del Cheque regalo de una cuenta de cliente a través de su aplicación o sitio web.
• Abone el saldo del Cheque regalo de una cuenta de cliente a un sitio físico.

Su software puede realizar solicitudes simultáneas a los puntos de enlace de la API de Incentives. Si su solicitud resulta en un código promocional, puede entregar este código a un cliente de una manera que haya sido aprobada por Amazon.

• Puntos de enlace
  • Puntos de enlace de Sandbox
  • Puntos de enlace de producción
• Creación de solicitudes de la API de Incentives
  • Scratchpad de la API de Incentives
  • Código de muestra de AWS Signature Version 4
  • Muestras de la API de Incentives
  • Encabezados de solicitud comunes
  • Implementación de Signature Version 4
    • Tarea 1: Crear una solicitud canónica
    • Tarea 2: Crear una cadena para firmar
    • Tarea 3: Crear una firma
• Ejemplo de solicitud firmada
• Gestión de errores
• Solución de problemas del código de firma
• Transmisión segura de datos
• Cambios en la respuesta de la API
• Portal de la API de Incentives
• Controlar claves
  • Seguridad para credenciales
  • Rotar claves
• Pautas de almacenamiento de datos
• Porcentaje de aceleración
• Gestión de errores
  • Códigos de error
• Contactar con Amazon para recibir servicio técnico (requiere contrato/acuerdo activo)
• Legal

Puntos de enlace

Las solicitudes de su código a cualquier API de Incentives incluyen una URL de base que forma parte de una dirección de punto de enlace completa. Su código enviará solicitudes a una única URL de base determinada por su país de operación. También proporcionamos un Sandbox con el que puede llamar a cualquier punto de enlace de la API de Incentives sin consecuencias. Las siguientes tablas muestran valores de URL de base de producción y Sandbox para los países en los que está disponible la API de Incentives.

Nota: Las direcciones IP subyacentes de estos puntos de enlace cambian con frecuencia en función de la geografía y la carga. No codifique las direcciones IP en su código o en su lista blanca de firewall. Utilice únicamente las direcciones DNS completas que se muestran aquí para llegar a nuestros puntos de enlace.

Puntos de enlace de Sandbox

Puntos de enlace de producción

Creación de solicitudes de la API de Incentives

Todas las solicitudes a un punto de enlace 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. Firmar correctamente con Signature Version 4 puede ser el obstáculo más difícil de superar al llamar a los puntos de enlace de la API de Incentives. En esta sección se describen los recursos que se utilizan para crear el código de firma.

Scratchpad de la API de Incentives

Puede llamar a algunas operaciones de la API de Incentives en un Sandbox mediante el Scratchpad de la API de Incentives. Al revelar los detalles de la solicitud y la respuesta, esta herramienta puede mostrar cómo debe verse una llamada a una operación de API de Incentives.

Nota: Al pasar una solicitud con un cuerpo JSON, el bloc de notas no muestra el encabezado content_type que se establece en application/json.

Código de muestra de AWS Signature Version 4

Signature Version 4 es un estándar de AWS. La documentación de AWS incluye fragmentos de código que pueden llamar a una operación con esta firma. La siguiente tabla muestra los parámetros que puede modificar en el ejemplo POST de Python que se encuentra en Ejemplos del proceso completo de firma de Signature Version 4. Con estas modificaciones, el código Python llama a la operación CreateGiftCard en el Sandbox de América del Norte usando un cuerpo JSON:

También encontrará fragmentos adicionales en Java, C#, Python, Ruby y JavaScript: Ejemplos de cómo derivar una clave de firma para Signature Version 4

Muestras de la API de Incentives

También proporcionamos código de muestra de Java, C#, Python, Ruby, PHP y HTML (JavaScript). Estas muestras se personalizan para llamar a la mayoría de las operaciones de la API de Incentives.

• Muestra de Java
  • Puede seleccionar el formato del cuerpo de la solicitud comentando en la línea del formato no preferido.

  • 

• Muestra de C#
  • En el constructor AWSAuthenticator, establezca el parámetro espacio de nombre en com.amazonaws.agcod
• Muestra de Python
• Muestra de Ruby
• Muestra de PHP
• Muestra de HTML

Notas:

• El código de muestra no tiene una buena gestión de errores, por lo que no está "Listo para producción" y solo debe usarse como guía.
• La clave secreta, la clave de acceso y el PartnerId aparecen en este código fuente en texto sin cifrar.
• Este código fuente y sus secretos podrían revelarse en algunos escenarios, incluyendo escenarios donde un error no controlado conduce a un comportamiento no determinista en el programa.

Proporcione los siguientes parámetros utilizando sus propios valores específicos antes de la prueba:

• partnerId: Acme1
• currencyCode: USD para US, EUR para EU, JPY para JP, CAD para CA, AUD para AU, TRY para TR, AED para EAU
• agcodAccessKey: su-credencial-de-seguridad
• agcodSecretKey: su-credencial-de-seguridad
• región: us-east-1 (variará según la ubicación y el entorno, consulte regiones y puntos de enlace)
• punto de enlace: (variará según la ubicación y el entorno, consulte regiones y puntos de enlace)

Encabezados de solicitud comunes

La API de Incentives requiere los siguientes encabezados en cada solicitud HTTP.

Para x-amz-date/date, los siguientes formatos de fecha y hora son valores válidos de x-amz-date: 20120325T120000Z. El encabezado x-amz-date es opcional para todas las solicitudes. Si el encabezado de fecha se especifica en el formato básico ISO 8601, no se necesitax-amz-date. Para obtener más información, consulte Gestión de fechas en Signature Version 4 en la Referencia general de Amazon Web Services. Cuando se recibe la solicitud, la hora tiene que estar a menos de 15 minutos de la hora del sistema de Amazon. Si no lo está, la solicitud fallará con el código de error RequestExpired para evitar que otra persona reproduzca sus solicitudes.

Implementación de Signature Version 4

Es posible que las muestras enumeradas anteriormente no cubran su escenario. Para implementar Signature Version 4 desde cero, comience por estudiar estos temas:

• Firma de solicitudes de AWS con Signature Version 4
• Ejemplo: Solicitud GET sencilla con parámetros
• Solución de problemas de Signature Version 4 de AWS

Cada solicitud de operación REST que envía su código debe incluir una firma. Para firmar una solicitud, cree una cadena que incluya el texto de su solicitud junto con su clave de acceso secreta. Pase esta cadena a una función hash criptográfica, que devuelve un valor hash. Debe incluir este valor hash en el campo Firma del encabezado Autorización de la solicitud de operación REST. Antes de gestionar su solicitud, nuestros servicios vuelven a calcular la firma usando las mismas entradas y confirman que su valor hash de autorización coincide con nuestro cálculo.

El portal de la API admite la autenticación mediante Signature Version 4 de AWS. El proceso para calcular una firma se puede dividir en tres tareas:

Tarea 1: Crear una solicitud canónica

Cree su solicitud HTTP con el formato canónico descrito en la Tarea 1: Cree una solicitud canónica para Signature Version 4 en la referencia general de Amazon Web Services.

Tarea 2: Crear una cadena para firmar

Cree una cadena que utilizará como uno de los valores de entrada para su función hash criptográfica. La cadena, llamada cadena para firmar, es una concatenación del nombre del algoritmo hash, la fecha de solicitud, una cadena de ámbito de credenciales y la solicitud canónica de la tarea anterior. La cadena de ámbito de credenciales es una concatenación de la información de fecha, región y servicio.

Para el parámetro x-amz-credential, especifique el código del punto de enlace al que enviará la solicitud, por ejemplo, us-east-1. Busque su región en las tablas Puntos de enlace. Ejemplo:

x-amz-credential=AKIAIGHKAVYIDBOH3O3A/20170118/us-east-1/AGCODService/aws4_request

Importante: Debe utilizar caracteres en minúsculas para la región, el nombre del servicio y la cadena de terminación especial. El encabezado x-amz-credential se utiliza cuando se añaden parámetros de autenticación a la cadena de consulta. Se pueden añadir fácilmente al encabezado de autorización único, y en ese caso, no aparece x-amz-credential. Por lo tanto, es un poco confuso mencionar x-amz-credential, una palabra clave que solo se usa en una instancia particular, y no es necesaria. Su valor es obligatorio, pero x-amz-credential es solo necesario cuando los parámetros de cadena de consulta se utilizan para llevar a cabo la autenticación.

Tarea 3: Crear una firma

Cree una firma para su solicitud mediante una función hash criptográfica que acepta dos cadenas de entrada: su cadena para firmar y una clave derivada. La clave derivada se calcula comenzando con la clave de acceso secreta y utilizando la cadena de ámbito de credenciales para crear una serie de códigos de autenticación de mensajes (HMAC) basados en hash. El siguiente diagrama ilustra el proceso general de cálculo de una firma:

Ejemplo de solicitud firmada

Carga para firmar

{"loadBalanceRequestId":"Amazon123456","partnerId":"Amazon","amount":{"currencyCode":"USD","value":"1000"},"transactionSource":{"sourceId":"Customer Service"},"account":{"id":"amz1.account.123512341234","type":"2"}}

Carga hash

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1 

Solicitud canónica (incluir líneas vacías)

POST /LoadAmazonBalance

accept: application/json
content-type: application/json
host: agcod-v2-gamma.amazon.com
x-amz-date: 20160708T073147Z
x-amz-target: com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target 24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Solicitud canónica hash

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14 

Cadena para firmar

AWS4-HMAC-SHA256 
20160708T073147Z 
20160708/us-east-1/AGCODService/aws4_request 
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14 

Clave de firma derivada

780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453 

Firma

Su firma será diferente, ya que tiene credenciales de clave de acceso de seguridad diferentes, pero seguirá este formato:

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a

Carga firmada

POST /LoadAmazonBalance HTTP/1.1 
accept:application/json 
content-type:application/json 
host:agcod-v2-gamma.amazon.com 
x-amz-date:20160708T073147Z 
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance 
Authorization:AWS4-HMAC-SHA256 Credential=<AWS Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a 
{"loadBalanceRequestId":"Amazon123456","partnerId":"Amazon","amount":{"currencyCode":"USD","value":"1000"},"transactionSource":{"sourceId":"Customer Service"},"account":{"id":"amz1.account.123512341234","type":"2"}}

Gestión de errores

Cada respuesta enviada desde el portal de servicio web tiene un elemento de estado asociado que describe el estado de ejecución de la operación en particular. Hay tres valores de estado SUCCESS, FAILURE y RESEND. Consulte Gestión de errores para obtener instrucciones, especialmente para manejar el resultado de RESEND con la lógica de reintento.

Solución de problemas del código de firma

Compruebe aquí los siguientes errores comunes de codificación: http://docs.aws.amazon.com/general/latest/gr/signature-v4-examples.html

Los errores de codificación comunes incluyen:

• Intercambiar inadvertidamente la clave y los datos al calcular claves intermediarias. El resultado del cálculo del paso anterior es la clave, no los datos. Compruebe cuidadosamente la documentación de sus primitivas criptográficas para asegurarse de colocar los parámetros en el orden correcto.
• Ha olvidado anteponer la cadena "AWS" delante de la clave para el primer paso. Es posible implementar la derivación de claves usando un "bucle" o iterador. Cuando lo haga, no olvide usar mayúsculas y minúsculas en la primera iteración para que incluya la cadena "AWS".
• Ha olvidado usar la opción asBytes para la función JavaScript HMAC.Crypto. Si no utiliza la opción asBytes, la implementación HMAC realizará una codificación hexadecimal adicional de forma predeterminada.
• Asegúrese de que la cadena de consulta en su solicitud esté ordenada y codificada correctamente, que los nombres de encabezado estén en minúscula y que los encabezados se hayan ordenado por código de caracteres. Consulte Creación de una solicitud canónica para Signature Version 4.
• Las solicitudes de cuerpo JSON solo serán correctas si content_type se establece en application/json.

Transmisión segura de datos

Los puntos de enlace de la API de Incentives están abiertos SOLO a través de un puerto seguro (HTTPS) y todo el tráfico a través de este canal está protegido mediante SSL/TLS 1.2. Este protocolo estándar de la industria cifra los datos de los cheques regalo mientras están en tránsito. Es necesario que proporcione sus propios mecanismos seguros dentro de sus sistemas para evitar el acceso no autorizado a las claves de cifrado utilizadas por SSL/TLS 1.2.

Importante: Las solicitudes de API deben utilizar TLS 1.2 o superior.

Cambios en la respuesta de la API

Las respuestas de los puntos de enlace de la API de Incentives suelen incluir información en formato de intercambio de datos XML o JSON. En el futuro, es posible que se añadan nuevos atributos a estas respuestas y que los elementos aparezcan en un orden diferente. Su código debe ser capaz de manejar cambios futuros en el XML o JSON de un cuerpo de respuesta mediante el uso de un analizador XML o JSON. Por ejemplo, XPath analiza los valores del contenido XML utilizando una sintaxis de expresión. Una biblioteca de analizador es más confiable cuando el esquema de un cuerpo de respuesta XML o JSON cambia o crece.

Portal de la API de Incentives

En el portal de la API de Incentives, puede:

• ver el saldo de la cuenta, el gasto medio diario (en los últimos 14 días), los días restantes (en función del gasto medio) y las alertas;
• ver la actividad de transacción detallada, en el navegador o descargándola;
• establecer alertas de saldo bajo;
• notificar a Amazon de que ha realizado un pago;
• (Solo administradores) crear nuevas claves de acceso y controlar las claves existentes.

Control de claves

Las claves de acceso son credenciales que se utilizan para firmar sus solicitudes programáticas a la API de Incentives. Como si se tratara de un nombre de usuario y una contraseña, debe usar el ID de clave de acceso y la clave de acceso secreta juntos para autenticar todas sus solicitudes.

Una cuenta de socio con permisos de administrador puede crear nuevas claves de acceso y controlar las claves existentes desde el portal de la API de Incentives, en la página de credenciales de seguridad de la API. (Una cuenta de socio que no tiene permisos de administrador no puede ver esta página. Escriba a incentives-api@amazon.com para pedirnos que demos acceso de administrador a una cuenta concreta).

Seguridad para credenciales

Las claves de acceso y las claves secretas proporcionadas en la página de credenciales de seguridad de la API deben estar protegidas contra el acceso no autorizado y la liberación accidental. Esto se aplica tanto a las credenciales de producción como a las de Sandbox. La seguridad de su sistema y de sus fondos depende del trato seguro de estos secretos. No comparta sus claves.

Rotación de claves

Cambiar las claves de forma regular es una práctica recomendada de seguridad y reduce el impacto en la empresa en caso de que dicha clave se pusiera en riesgo. Como práctica recomendada de seguridad, le sugerimos que haga rotar (cambie) con regularidad sus claves de acceso. Además, tener un proceso definido que se ejecute con regularidad garantiza que se verifiquen los pasos operativos ligados a la rotación de claves, de modo que cambiar una clave deje de ser una tarea angustiosa en su organización.

Debe cambiar sus claves de acceso al menos una vez cada 180 días (6 meses). Recibirá un correo electrónico 30 días antes de que deba rotar las claves como recordatorio para iniciar el proceso. Si tiene alguna pregunta, póngase en contacto con su administrador de cuenta o escríbanos a incentives-api@amazon.com.

Para cambiar las claves de acceso, siga estos pasos:

1. En el portal de la API de Incentives, haga clic en credenciales de seguridad de la API.
2. Haga clic en crear nueva clave de acceso.
3. Actualice todas sus aplicaciones para usar la nueva clave de acceso.
4. Confirme que todas las solicitudes a las operaciones de la API de Incentives se ejecutan correctamente con los nuevos valores de clave.
5. Para la clave original, haga clic en Desactivar.
6. Confirme de nuevo que todas las solicitudes a las operaciones de la API de Incentives se están ejecutando correctamente con los nuevos valores de clave. ¡Tenga seguridad! Una vez que se elimina una clave de acceso, no se puede recuperar.
7. Para la clave original, haga clic en Eliminar.

Ahora se está utilizando la nueva clave; la clave original está inactiva y no se puede volver a utilizar.

Pautas de almacenamiento de datos

En esta sección se describen algunas prácticas recomendadas para tratar los resultados de CreateGiftCard, especialmente los valores de gcClaimCode.

También puede revisar los requisitos de seguridad en las Condiciones de compra y distribución de Cheques regalo de Amazon para empresas, incluidas las prácticas recomendadas de seguridad de las políticas de Cheques regalo para empresas

en las Condiciones de servicio la API de Amazon Incentives que se encuentran en https://www.amazon.com/gp/help/customer/display.html?nodeId=202120960.

Pautas para solicitar y almacenar códigos de reclamación de cheques regalo devueltos por una llamada positiva a CreateGiftCard:

• El código de cliente genera un valor creationRequestId único para cada nueva llamada a la operación CreateGiftCard.
• El código de cliente debe almacenar los valores creationRequestId, amount, y currencyCode utilizados en cada solicitud.
• Amazon almacena cada gcClaimCode. Después de generar un código de reclamación de un cheque regalo, su código puede recuperarlo de nuevo al enviar una nueva solicitud a CreateGiftCard utilizando los mismos valores de códigocreationRequestId, amount y currency. Esta puede ser una alternativa más segura para almacenar los códigos de reclamación de cheques regalo en su base de datos.
• No debe almacenar códigos de reclamación. Si su código conserva los códigos de reclamación de cheques regalo de forma temporal, estos valores deben eliminarse después de haberse entregado al cliente. (Consulte Seguridad.)
• Si necesita cancelar un código de reclamación de un cheque regalo, su código debe llamar a CancelGiftCard dentro de los 15 minutos posteriores a la creación del código.

Porcentaje de aceleración

AGCOD acelerará o rechazará las solicitudes entrantes para evitar el mal uso del sistema. La tasa de solicitudes no puede superar las 10 por segundo, incluidos todos los tipos de transacción.

Cuando las solicitudes de su código superan una velocidad de aceleración, su solicitud falla y se devuelve una ThrottlingException:

<ThrottlingException>
  <Message>Rate exceeded</Message>
</ThrottlingException>

Gestión de errores

Cada respuesta enviada desde el portal de AGCOD tiene asociado un elemento "Status" que describe el estado de ejecución de la operación en particular; hay tres valores statusCode: SUCCESS, FAILURE y RESEND.

SUCCESS

Una respuesta de operación incluye el valor de StatusCode de SUCCESS cuando la operación se realiza correctamente.

FAILURE

Una respuesta de operación incluye un statusCode de FAILURE cuando la API de Incentives no puede aceptar la solicitud. Esta respuesta de estado puede incluir datos de solicitud que no sean válidos o algún error de lógica empresarial que el socio debe revisar. El campo errorCode se rellenará en tales casos proporcionando detalles adicionales relacionados con el error.

RESEND

Una respuesta de operación incluye un statusCode de RESEND y un error F400 cuando hay un error temporal del sistema que probablemente se puede resolver reintentando la solicitud. Es importante que su código proporcione lógica de reintento, porque un error F400 es un "estado desconocido" que puede dar lugar a cargos en su cuenta. El error RESEND no debe interpretarse como un fallo.

Nota: En los siguientes pasos se muestra la estrategia de retroceso para una llamada a ActivateGiftCard/DeactivateGiftCard. Su código también debe utilizar esta estrategia de retroceso para las llamadas a CreateGiftCard/CancelGiftCard y a LoadAmazonBalance/VoidAmazonBalanceLoad.

1. Cuando su solicitud devuelve un mensaje de error F400, intente de nuevo la operación ActivateGiftCard, si es posible. Si no puede volver a intentarlo, continúe con el paso 2.
2. Envíe una operación de DeactivateGiftCard utilizando el mismo valor *requestId.
3. Si la llamada a DeactivateGiftCard devuelve SUCCESS, vuelva a llamar a ActivateGiftCard utilizando un nuevo valor *requestId.
4. Si falla la llamada a DeactivateGiftCard espere un segundo y envíe de nuevo la misma solicitud DeactivateGiftCard.
5. Si transcurren diez segundos sin una solicitud DeactivateGiftCard positiva, aumente el retraso utilizando un esquema de retroceso exponencial.
6. Tras 24 horas, deje de intentarlo y envíe un correo electrónico a Amazon con detalles de las operaciones fallidas.

Códigos de error

Utilizamos una convención de códigos F2XX para denotar errores que provienen de su solicitud, y F1XX si la causa proviene de 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 identificador de solicitud de error simulado tendrá que pasarse al campo creationRequestId, similar a una 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 la sección de ejemplos de simulación para obtener más detalles.

Contactar con Amazon para recibir servicio técnico (requiere contrato/acuerdo activo)

Durante todo el proceso de desarrollo e integración, puede enviar preguntas técnicas a Amazon.

Si no tiene un acuerdo activo y no se le ha dado acceso a Sandbox, es probable que los desarrolladores que supervisan este alias no lo reconozcan. Es importante que trabaje con su administrador de cuenta para seguir los pasos necesarios para obtener acceso a Sandbox.

Es importante que incluya su ID de socio en las comunicaciones con nuestros desarrolladores para asegurarse de que puedan identificar fácilmente su cuenta. En su comunicación, proporcione la mayor cantidad posible de la siguiente información (según corresponda):

• par de solicitud/respuesta completo de su llamada a la API de Incentives;
• la URL completa del punto de enlace utilizado para realizar la solicitud (incluida la URL del servidor);
• el valor StringToSign utilizado en la solicitud, si no se encuentra en la solicitud/respuesta anterior;
• la firma correspondiente del valor StringToSign utilizado, si no se encuentra en la solicitud/respuesta anterior;
• la hora aproximada de su solicitud (con el huso horario, que está configurado en la máquina que emitió la solicitud anterior);
• el lenguaje de programación utilizado;
• cualquier cambio reciente en su lado (tanto de programación como de infraestructura);
• captura de pantalla del error.

Legal

Al integrar y usar la API de Incentives, usted (en nombre propio o de la empresa que representa) acepta cumplir las Condiciones de compra y distribución de Cheques regalo para empresas de Amazon, que se encuentran en https://www.amazon.com/gp/help/customer/display.html?nodeId=202120960.