Desembolsar fondos para acreditar cuentas de clientes

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.

El servicio web de Inicio de sesión y recepción proporciona una API para desembolsar fondos a un cliente de Amazon nuevo o existente. Un desembolso añade un valor monetario al saldo de Cheques regalo de la cuenta de un cliente de Amazon en tiempo real. Este servicio web basado en REST forma parte de la API de Incentives, que es un conjunto de servicios que admiten operaciones de Cheques regalo de Amazon.

Póngase en contacto con Inicio de sesión y recepción en los siguientes casos prácticos:

• Si necesita desembolsar dinero de manera inmediata y garantizada a sus clientes a través de una aplicación web existente.
• Tiene que asegurar que el valor monetario no sea transferible para cumplir con las obligaciones legales o comerciales.
• Quiere enviar un correo electrónico a los clientes para notificar un caso de desembolso.

Esta página describe cómo llamar a la API de Inicio de sesión y recepción desde la aplicación, y documenta las tareas que puede realizar con ella.

• Conceptos clave y flujo básico
• Requisitos previos
• API de Inicio de sesión y recepción
  • Operaciones
    • LoadAmazonBalance
    • VoidAmazonBalanceLoad
    • GetAvailableFunds
• Solicitudes de prueba
• Script de prueba de Inicio de sesión y recepción
• Rendimiento
• Códigos de error

Conceptos clave y flujo básico

La API de Inicio de sesión y recepción utiliza el servicio web Inicio de sesión con Amazon que permite a los usuarios autenticar su cuenta de Amazon utilizando sus credenciales de cuenta de Amazon dentro de su aplicación móvil o en el navegador. Una vez completada la autenticación, el servicio Inicio de sesión con Amazon proporciona a su aplicación un identificador de usuario que podrá utilizar como parámetro de entrada para la API de Inicio de sesión y recepción. Juntos, estos servicios ofrecen una experiencia perfecta a los usuarios finales.

Inicio de sesión con Amazon ofrece personalizaciones que se adaptan a su experiencia de usuario preferida, incluyendo SDK. Visite Inicio de sesión con Amazon en el Portal para desarrolladores para obtener más información.

A continuación se muestra una descripción del proceso de la aplicación para Inicio de sesión y recepción:

1. Un usuario de la aplicación solicita abonar el saldo de Cheques regalo de su cuenta de Amazon.
2. La aplicación muestra una página en el módulo Inicio de sesión con Amazon que solicita al usuario sus credenciales de Amazon.
3. Los nuevos clientes de Amazon pueden registrar una nueva cuenta en el proceso de inicio de sesión con Amazon.
4. Si su código solicita el nombre, la dirección de correo electrónico o el código postal del cliente de Amazon, el proceso de Inicio de sesión con Amazon solicitará el consentimiento del cliente para compartir esta información con el servicio.
5. El módulo inicia una solicitud de autorización mediante la API de Inicio de sesión con Amazon.
6. Un valor de id que identifica de forma exclusiva la cuenta de usuario se devuelve como objeto JSON en la respuesta.
7. La aplicación llama al método LoadAmazonBalance con el valor de id en el cuerpo de la solicitud.
8. La operación LoadAmazonBalance actualiza el saldo de Cheques regalo de la cuenta.
9. Amazon envía una confirmación por correo electrónico a la dirección de correo electrónico asociada a la cuenta de cliente de Amazon cuando los fondos se han aplicado correctamente o se ha anulado el saldo de Cheques regalo de la cuenta del cliente. Este correo electrónico contendrá el texto especificado en el parámetro notificationMessage de la solicitud LoadAmazonBalance.

Notas:

• El usuario puede cancelar el proceso de Inicio de sesión con Amazon en cualquier momento seleccionando Cancelar o cerrando la ventana emergente (si se utiliza este método de UX).
• El almacenamiento de información de identificación personal, incluido el nombre, la dirección de correo electrónico y el código postal, requerirá disposiciones de seguridad adicionales para cumplir con el RGPD, la CCPA y otras leyes de privacidad.

Requisitos previos

Complete estos pasos de configuración para usar Inicio de sesión y recepción:

• Siga las instrucciones de la guía de configuración de la integración de la API de Incentives para establecer una cuenta y aceptar un contrato con Amazon Incentives.
• Integre su aplicación web o móvil en el servicio web Inicio de sesión con Amazon para proporcionar autenticación y acceso (opcional) a los datos del perfil de usuario. Para obtener más información sobre cómo integrar su aplicación con Inicio de sesión con Amazon, siga los pasos del Centro de desarrolladores de Inicio de sesión con Amazon. Nota: Para usar Inicio de sesión con Amazon en su aplicación móvil, debe usar el SDK de Inicio de sesión con Amazon. Aunque una interacción basada en navegador es técnicamente posible desde una aplicación móvil, lo prohibimos por razones de seguridad.
• El Sandbox es un entorno de pruebas que utilizará al desarrollar y probar su aplicación. Póngase en contacto con su administrador de cuentas de Amazon para obtener las credenciales de acceso a Sandbox. Una vez que se le haya concedido el acceso a Sandbox, puede comenzar el desarrollo y las pruebas utilizando el valor de ID de socio que le hayan proporcionado. Las direcciones URL de punto de enlace para acceder a Sandbox se proporcionan en la sección Regiones y puntos de enlace. Con el acceso a Sandbox, puede desarrollar y probar su código siguiendo las instrucciones de la guía de configuración de la API de Integración de Amazon Incentives.

API de Inicio de sesión y recepción

Su aplicación interactúa con Inicio de sesión y recepción realizando solicitudes sincrónicas al servicio web. En esta sección se describe la estructura de una solicitud y las operaciones disponibles. Invocar una operación consiste en enviar una solicitud HTTP a un punto de enlace de la API de Incentives y esperar la respuesta. Una solicitud HTTP REST contiene un método de solicitud, URI, encabezados y un cuerpo presentado en XML o JSON. La respuesta contiene un código de estado HTTP, encabezados de respuesta y un cuerpo de respuesta. Cada llamada a la API deberá firmarse utilizando sus credenciales de seguridad y el proceso de firma de AWS Signature Version 4.

A continuación se muestra una descripción de cada operación de API, encabezados de solicitud y parámetros asociados.

Operaciones

Se admiten las siguientes operaciones:

• LoadAmazonBalance
• VoidAmazonBalanceLoad
• GetAvailableFunds

LoadAmazonBalance

La operación LoadAmazonBalance aplica fondos al saldo de Cheques regalo de un cliente de Amazon. A continuación se muestra una descripción de los parámetros del cuerpo de la solicitud.

Solicitud de muestra

POST 
/LoadAmazonBalance HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{   "loadBalanceRequestId":"Amazon123456",
    "partnerId":"Amazon",
    "amount":{
        "currencyCode":"USD",
        "value": 1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "transactionSource":{
        "sourceId":"Customer Service"
    },
    "externalReference":"serviceId:123",
    "notificationDetails":{
        "notificationMessage":"Thank you for your purchase!"
    }
}

Respuesta de muestra

{
    "status": "Success",
    "amount": {
        "currencyCode": "USD",
        "value": 9000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    },
    "loadBalanceRequestId": "Amazon123456"
}

VoidAmazonBalanceLoad

Esta operación anula una solicitud LoadAmazonBalance que ya se ha realizado correctamente si el cliente receptor de Amazon aún no ha utilizado los fondos del código promocional emitido. Esta operación se puede ejecutar hasta 15 minutos desde la llamada original a LoadAmazonBalance. Después de eso, una llamada a VoidAmazonBalanceLoad no hará nada.

Su aplicación debe llamar a esta operación cuando no pueda confirmar que una solicitud anterior de AmazonBalanceLoad se haya realizado correctamente. Por ejemplo, si su llamada a LoadAmazonBalance no devuelve ningún resultado, llame a VoidAmazonBalanceLoad para asegurar que no se añaden fondos al saldo de Cheques regalo del cliente de Amazon.

A continuación se muestra una descripción de los parámetros del cuerpo de la solicitud.

Nota: Todos los siguientes parámetros deben coincidir con los utilizados en una solicitud anterior de LoadAmazonBalance.

Solicitud de muestra

POST 
/VoidAmazonBalanceLoad HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{
    "loadBalanceRequestId": "Amazon123456",
    "partnerId": "Amazon",
    "amount": {
        "currencyCode": "USD",
        "value": 1000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    }
}

Respuesta de muestra

{
    "status":"Success",
    "amount":{
        "currencyCode":"USD",
        "value":1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "loadBalanceRequestId":"Amazon123456"
}

GetAvailableFunds

Consulte GetAvailableFunds.

Solicitudes de prueba

Para probar su integración, puede simular una respuesta desde la API creando una solicitud simulada. La respuesta de la solicitud simulada está controlada por el parámetro ID. Por ejemplo, pasar en ID F0000 simulará una respuesta positiva mientras que pasar en ID F1000 simulará un error general. Consulte los Códigos de error para obtener una lista completa de las respuestas disponibles. Los siguientes son los parámetros necesarios (mínimos) para invocar una solicitud simulada:

{
  "loadBalanceRequestId": "Amazon123456",
  "account": {
    "id": "F2044",
    "type": "0"
  }
}

Nota: Cualquier valor que se pase a otros campos se repetirá en la respuesta y no es obligatorio.

Muestra de solicitud simulada

POST /LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{   "loadBalanceRequestId":"Amazon123456",
    "partnerId":"",
    "amount":{
        "currencyCode":"",
        "value":""
    },
    "account":{
        "id":"F2044",
        "type":"0"
    },
    "transactionSource":{
        "sourceId":""
    },
    "externalReference":"",
    "notificationDetails":{
        "notificationMessage":""
    }
}

Muestra de respuesta simulada

{
    "errorCode": "F2044",
    "errorMessage": "Source Id is too long. Received 41 characters. Maximum   
number of characters is 40",
    "errorType": "SourceIdTooLong",
    "status": "FAILURE"
}

Script de prueba de Inicio de sesión y recepción

Puede verificar algunos componentes de la integración usando el entorno Sandbox. Sin embargo, las pruebas completas de la experiencia de usuario de las aplicaciones solo se pueden realizar utilizando la cuenta de API de producción.

Sandbox: Simular una respuesta desde la API LoadAmazonBalance creando una solicitud "simulada".

Producción:

• Utilice el componente Inicio de sesión con Amazon para recibir un valor de customer.id válido para una cuenta de cliente de Amazon.
• Llame a los puntos de enlace LoadAmazonBalance y VoidAmazonBalanceLoad.
• Pruebas completas de su aplicación y experiencia de usuario.

Rendimiento

La API está diseñada para procesar transacciones a una velocidad máxima de 10 transacciones por segundo (TPS).

Nota: El entorno de Sandbox no se rige por un SLA y las tasas de transacción pueden parecer erráticas.

Códigos de error

Utilizamos una convención de códigos para indicar errores. Por ejemplo, cuando la causa está del lado del cliente, la API responde con un error F2xx y F1XX si el problema se debe a un problema del sistema de Amazon. En general, los códigos de error se traducen como se muestra en la tabla siguiente.