Bienvenidos desarrolladores
Introducción
Las APIs CPG de Rappi están diseñadas sobre REST (Representational State Transfer). Nuestras APIs tienen URLs predecibles orientadas a recursos; aceptan solicitudes y devuelven respuestas como objetos en formato JSON; asimismo, usan códigos de respuesta, autenticación y verbos HTTP.
El control de versiones de nuestra API es manejado por nuestro gateway a través de un parámetro de ruta.
La documentación para versiones anteriores estará disponible en nuestro portal para desarrolladores y, en este punto, las versiones principales solo quedarán obsoletas una vez que todos los clientes hayan migrado a versiones más recientes.
Primeros pasos
- Recomendamos leer las guías de integración de cada producto que estarás integrando antes de comenzar con las especificaciones de la API. Estos documentos te darán descripciones generales de cada implementación y sus prácticas idóneas.
Rappi Inventory.
Rappi Promotions (documentación disponible próximamente).
Rappi Connect.
Rappi Payless.
Revisa las especificaciones de la API para los endpoints con los que tu aplicación estará interactuando.
Envía un correo electrónico a cpg-open-apis@rappi.com solicitando nuevas credenciales de aplicación o contacta a tu gerente técnico de cuenta (en inglés technical account manager o TAM).
Desarrolla y prueba tu integración con Rappi usando nuestro ambiente de pruebas (sandbox).
Agenda una reunión con tu TAM para verificar que la integración está lista para producción.
Convenciones aplicadas
La sintaxis y protocolos usados por REST (JSON y el protocolo de direccionamiento URI) son ampliamente conocidos y se basan en cómo se usa la web. El sistema subyacente ya ha sido construido e instalado y está disponible para usarse por cualquiera. Esto minimiza la cantidad de trabajo que los usuarios y desarrolladores tienen que realizar para poner sus aplicaciones en funcionamiento. En teoría, todas las APIs RESTful tienen el mismo formato de interfaz, fácil de aprender.
La arquitectura REST enfatiza el mejoramiento de las interacciones entre clientes y servicios teniendo un número limitado de operaciones con las que actúa. Específicamente, existen cuatro métodos HTTP comunes que te otorgan capacidades completas “CRUD”: Create, Retrieve, Update y Delete. Cada uno de los métodos HTTP principales (GET, POST, PUT y DELETE) tiene un significado particular en la arquitectura REST, de esta manera REST evita ambigüedades. Puedes considerar los métodos HTTP como los verbos de una operación REST.
Una solicitud REST está compuesta por tres partes principales: la operación REST, el encabezado de solicitudes HTTP y el cuerpo de la solicitud.
La operación REST
Las operaciones REST son la combinación de un método HTTP y un URI asociado. Esta construcción es la parte más identificable de una interfaz REST y es comúnmente llamada method name (y a veces llamado endpoint).
Los métodos HTTP están definidos por W3C in RFC 2616, Section 9. Mientras que la especificación define cerca de 10 métodos HTTP, nuestras APIs REST hacen uso de los siguientes métodos HTTP:
| HTTP method | Description |
|---|---|
POST | Los métodos POST solicitan que el servidor acepte la entidad incluida en la solicitud como un nuevo subordinado del recurso web identificado por el URI. Por ejemplo, los datos publicados podrían ser una anotación para recursos ya existentes; un mensaje para un tablero de anuncios, un grupo de noticias, una lista de correos o un hilo de comentarios; un bloque de datos que es el resultado de enviar un formulario web a un proceso de manejo de datos; o un elemento para agregar a una base de datos. |
PUT | Los métodos PUT solicitan que la entidad adjunta (pasada en el cuerpo de la solicitud) se almacene bajo el URI proporcionado. Si el URI remite a un recurso ya existente, el recurso es modificado. Si el URI no señala un recurso existente, el servidor puede crear el recurso con ese URI. |
GET | Los métodos GET solicitan una representación de un recurso específico. Por ejemplo, un método que recupera una dirección obtiene una representación de un recurso de dirección específico (o un conjunto de recursos de dirección). Las solicitudes que usan GET únicamente deberían recuperar información, no deberían tener otro efecto o efectos secundarios. |
La parte URI de una operación REST señala al recurso sobre el cual la operación actúa. Por ejemplo, el siguiente es un URI que es usado en una operación de una API de transacciones payless que usa un método HTTP POST::
https://microservices.dev.rappi.com/api/cpg/v3/barcodes/{barcode}/authorize
Los URIs son creados combinando varias piezas de información:
| URI part | Description |
|---|---|
https://microservices.dev.rappi.com/api | La base URI de nuestro ambiente de producción actualmente es específica para cada país. Para el ambiente de desarrollo únicamente tenemos un URI base que sirve a todos los mercados. |
/cpg | El dominio en Rappi que tiene la propiedad de una operación. |
/v3 | La versión de nuestra API pública que estás consumiendo. |
/payments | La colección de recursos sobre los cuales la operación actúa -una colección de recursos es un conjunto de recursos similares-. |
/{payment_code} | Conocido como parámetro de ruta, estos son frecuentemente usados para determinar un recurso específico dentro de un grupo de recursos. |
/authorize | PODRÁS encontrar controladores en operaciones POST, o subcolecciones de recursos en operaciones GET. Los controladores son parte de modelos de recursos y actúan como funciones ejecutables, con parámetros y valores de retorno; entradas y salidas. Las subcolecciones son propiedades de modelos de datos de colecciones de recursos suficientemente relevantes para ser expuestos a través de sus propias rutas. |
Los parámetros de consulta son extensiones de un URI que ayudan a definir contenido o acción específica con base en los datos entregados. Son comúnmente encontrados en operaciones GET para filtrar y paginar resultados. Todos los caracteres no ASCII DEBEN de estar codificados en URL. Por ejemplo: ?created=2020-07-12&limit=100
Encabezados de solicitudes HTTP
Las APIs de Rappi combinan tanto encabezados HTTP como encabezados personalizados de Rappi. Todos los encabezados personalizados de Rappi comienzan con “X-RAPPI”. La siguiente tabla presenta los encabezados de solicitud principales implementados por nuestras APIs.
| HTTP header | Description |
|---|---|
Accept optional | Accept indica los formatos que el cliente acepta por respuesta. Este encabezado se empareja con el encabezado Content-Type, el cual especifica el formato requerido por Rappi para la solicitud. Actualmente, todas las interfaces REST requieren que los cuerpos de las solicitudes tengan formato JSON. JSON es el formato predeterminado y el único formato devuelto en los cuerpos de respuesta. Ejemplo: Accept: application/json |
Authorization required | Authorization especifica el token y el tipo de token usado para autorizar la solicitud. Debes proporcionar este encabezado en cada solicitud que hagas a las APIs de Rappi. Para más detalles, consulta genera tus tokens de acceso JTW. Ejemplo: Authorization: Bearer <accessToken> |
Content-type required | Content-Type indica el formato del cuerpo de la solicitud proveída por el cliente. Este encabezado es requerido por todas las operaciones POST y PUT; application/json es actualmente el único valor apoyado. Ejemplo: Content-Type: application/json |
X-RAPPI-CHANNEL conditional | X-RAPPI-CHANNEL es un encabezado específico de nuestra API de pagos. Identifica al cliente que interactúa con el cajero en tienda; actualmente, B2B es el único valor admitido. Ejemplo: X-RAPPI-CHANNEL: B2B |
El cuerpo de la solicitud
Un cuerpo de solicitud, usualmente llamado "payload", se proporciona con una solicitud cuando quieres crear o actualizar un recurso. En las APIs REST de Rappi, los payloads de solicitud y respuesta siempre tienen formato como objetos JSON. Cada documento de especificación de la API describe las propiedades admitidas en el cuerpo de cada operación.
Fechas y marcas de tiempo
Todas las propiedades de fecha y hora utilizarán el formato ISO 8601 YYYY-MM-DDTHH:mm:ss.sssZ. Las marcas de tiempo NUNCA se referirán a zonas horarias locales o específicas de un país. Las marcas de tiempo SIEMPRE usarán UTC como estándar.
Las fechas simples tienen el formato YYYY-MM-DD.
Autenticación de usuario
Las APIs de Rappi utilizan autenticación basada en JWT. Para obtener información sobre cómo obtener tus tokens de acceso y autenticar tus solicitudes, consulte la sección Servidores y Autenticación.