Bienvenido a la API Transaction Enrichment, esta documentación te ayudará a conocer los conceptos básicos como la autenticación, peticiones, respuestas, etc. para que puedas utilizar de mejor maneja los productos de Xerpa.
\nServicio que agrega propiedades sobre las transacciones de cuentas y tarjetas para enriquecerlas y ofrecer un mejor contexto al usuario y al banco sobre el tipo de transacción y el comercio asociado a ella.
\nPredicción de categorías para ingresos y gastos
\n80% tasa de categorización efectiva
\nMás de 15,000 comercios identificados con su nombre y logo.
\nOperación en línea y en batch.
\nActualmente la solución se encuentra disponible con comercios de los siguientes países:
\n🇨🇱 Chile
\n🇵🇪 Perú
\n🇲🇽 México
Próximamente en:
🇨🇴 Colombia
\n🇪🇨 Ecuador
\n🇦🇷 Argentina
\nNuestras APIs están disponibles en tres ambientes:
\nEl ambiente de Sandbox está expuesto a internet y es de uso público con previo registro. El ambiente de producción es de exclusivo uso de clientes Xerpa.
\nLos comercios que se logran identificar por cada transacción y que tienen un logo se disponibiliza bajo la propiedad merchant_logo_url que viene en la respuesta de la API.
Se disponibilizan directamente desde el CDN de Xerpa para su uso.
\n![\"ec9ac56d-985d-4dcd-99b9-bcf92b96acdf.png\"](\"../assets/images/ec9ac56d-985d-4dcd-99b9-bcf92b96acdf.png\")
\n\n![\"0b506dba-d58e-4967-842a-10c677407901.png\"](\"../assets/images/0b506dba-d58e-4967-842a-10c677407901.png\")
\n\n![\"0eb1eee1-f64d-48e6-9f41-3f4e12983c4b.png\"](\"../assets/images/0eb1eee1-f64d-48e6-9f41-3f4e12983c4b.png\")
\n\nLos logos son imágenes en formato PNG de dimensiones de 128x128 pixeles.
Todas las APIs están versionadas para identificar qué funcionalidades están disponibles en cada una de ellas.
\nLas funcionalidades que se vayan agregando o deprecando entre versiones se comunicarán en el documento de change log de cada versión.
\nEn cada petición se debe indicar de forma explícita la versión a la cual se hace referencia:
\nhttps://pro.getxerpa.com/data-enrichment/
A menos de que se especifique lo contrario, todos los campos de las peticiones son obligatorios. Solo bajo ciertas circunstancias y donde quede explícitamente documentado se manejarán campos opcionales para las peticiones. Estos campos opcionales se indicarán en cada endpoint que lo permita.
\nSe utilizan códigos de error internos para problemas relacionados al uso de la API, estos códigos se retornarán dentro del cuerpo de la respuesta.
\nEl case-id es un identificador único de la petición para trazar el error en los logs internos y atender actividades de soporte.
\nEl error-code es un código que se puede buscar en el diccionario de errores y donde se puede encontrar más información del problema.
\n{ \n case-id: UUID\n error-code: XX-XXX\n}\n\nLas peticiones a la API pueden fallar por múltiples razones, desde problemas de red, límite de peticiones, timeouts o errores de servicios. Como recomendación, sugerimos desarrollar un sistema de reintento de peticiones cuando se obtengas las siguientes respuestas HTTP:
\n5xx (Server errors)
\n429 (Rate Limits)
\n408 (Timeouts)
\nEl límite por defecto de las peticiones desde una misma IP son de 1,000 peticiones por minuto. El límite aplica para cada ambiente (sandbox y producción) independientemente.
\nSi se alcanza el límite, las peticiones responderán con un error HTTP 429.
En caso de ser necesario el límite se puede aumentar para ambientes productivos con previo análisis con el equipo responsable de las APIs en Xerpa.
\nTodas nuestras APIs tienen timeouts para identificar que ha ocurrido un error lo antes posible y con eso puedas reintentar la petición. Es recomendable manejar los mismos tiempos de timeouts para los clientes.
\nTiempo por Defecto - La mayoría de las APIs arrojará un timeout a los 29 segundos.
\nPara los registros que hacen uso de fechas, estas se manejan bajo el estándar ISO 8601 con UTC.
\nPara solo fechas, la estructura debe ser: YYYY-MM-DD
Para fechas que incluyen hora, el formato debe ser: YYYY-MM-DDTHH:MM:SS. Ej: 2007-11-03T24:12:03
La API es capaz de procesar transacciones de distintos países. En cada transacción se debe especificar su país de origen y/o el tipo de moneda con el que realizó.
\nPara los códigos del país de origen de las transacciones se utiliza el formato ISO 3166 Alfa 2
\nPara los códigos de la moneda de origen de las transacciones se utiliza el formato ISO 4217
\n\n\nIncorporar estos datos dentro de la transacción aumentará la precisión de los datos enriquecidos
\n
La API de enriquecimiento de transacciones utiliza los servicios de Amazon Web Services para montar su infraestructura.
\n![\"data-enrichment-architecture.drawio.png\"](\"../assets/images/data-enrichment-architecture.drawio.png\")
\n\nNuestras APIs usan un API Key el que debe ser incluído en la cabecera de todas las llamadas. Una API Key inválida o ausente retornará una respuesta HTTP 403 Forbidden.
Los clusters de K8s están protegidos externamente por security groups (para nodos y pods) y IAM roles (para autenticación al cluster), además, los componentes internos usan RBAC.
\nS3 no públicos y protegidos por políticas IAM.
\nLas transacciones que se reciben son 100% anónimas.
\nTodas las APIS utilizan TLS V 1.2
\nBases de datos con encryption in transit con TLS y storage encrypted con KMS.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Logos de comercio","slug":"logos-de-comercio"},{"content":"Versionamiento","slug":"versionamiento"},{"content":"Arquitectura","slug":"arquitectura"}],"owner":"1972870","collectionId":"0e67c617-416e-4d5b-8c15-a27b81c8b601","publishedId":"2sBXijKXLX","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-03-23T18:13:58.000Z"},"item":[{"name":"Resources","item":[{"name":"Health-check","event":[{"listen":"test","script":{"id":"b3a530c3-4d57-41a8-bd33-ca48d4ef6eab","exec":[""],"type":"text/javascript","packages":{}}}],"id":"ee2e2de3-bad0-46af-8681-e7fdbb9994e7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{host}}/data-enrichment/health-check","description":"Gets information about a collection. For a complete list of this endpoint's possible values, use the collection.json schema file.
\n","urlObject":{"path":["data-enrichment","health-check"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[{"id":"251bfb3a-451c-4edf-8fa2-ea45dc398e36","name":"Successful Response","originalRequest":{"method":"GET","header":[{"warning":"This is a duplicate header and will be overridden by the X-API-Key header generated by Postman.","key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{host}}data-enrichment/health-check"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 23 Jul 2024 16:23:13 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"29"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"075426ab-4f5e-4878-86bd-c41c629d7960"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"bX7VwFtUIAMEo1A="},{"key":"X-Amzn-Trace-Id","value":"Root=1-669fd8f1-5a018ad948c3dbb22b7de8fb;Parent=63e83e31950f8b77;Sampled=0;lineage=26e7f5e2:0"},{"key":"Access-Control-Allow-Credentials","value":"true"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"message\": \"OK\"\n}"},{"id":"723119c3-ec55-4cd0-86e9-5272fea59755","name":"Not Found","originalRequest":{"method":"GET","header":[{"warning":"This is a duplicate header and will be overridden by the X-API-Key header generated by Postman.","key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{host}}data-enrichment/health-chec"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 23 Jul 2024 16:24:05 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"179"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"f268110e-006e-46ae-a686-c9b3e1cfc882"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"bX7d1F_HoAMEcBw="},{"key":"X-Amzn-Trace-Id","value":"Root=1-669fd925-4a5f493b1815ed3b1fd68737;Parent=3ec2a491294c4841;Sampled=0;lineage=26e7f5e2:0"},{"key":"Access-Control-Allow-Credentials","value":"true"}],"cookie":[],"responseTime":null,"body":"\n\n\n\nThe requested resource was not found on this server.
\n\n\n"}],"_postman_id":"ee2e2de3-bad0-46af-8681-e7fdbb9994e7"},{"name":"Enriquecimiento en línea","event":[{"listen":"test","script":{"id":"b3a530c3-4d57-41a8-bd33-ca48d4ef6eab","exec":[""],"type":"text/javascript","packages":{}}}],"id":"8d0f52cb-148e-41d5-8b89-5e0d7b0b44ee","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"country\": \"CL\",\n \"transactions\": [\n {\n \"id\": \"1d92e05c-e45d-4183-a4cc-6e3fae10b688\",\n \"description\": \"UBER TRIP\",\n \"amount\": -2510.00,\n \"currency\": \"CLP\",\n \"country\": \"CL\",\n \"date\": \"2023-07-05\"\n },\n {\n \"id\": \"1d92e05c-e45d-4183-a4cc-6e3fae10b689\",\n \"description\": \"TOTTUS BIO BIO \",\n \"amount\": -22000.00,\n \"currency\": \"CLP\",\n \"country\": \"CL\",\n \"date\": \"2023-07-05\"\n },\n {\n \"id\": \"1d92e05c-e45d-4183-a4cc-6e3fae10b699\",\n \"description\": \"COPEC COLLIN 1101\",\n \"amount\": -41000.00,\n \"currency\": \"CLP\",\n \"country\": \"CL\",\n \"date\": \"2023-07-05\"\n },\n {\n \"id\": \"1d92e05c-e45d-4183-a4cc-6e3fae10b688\",\n \"description\": \"UBER TRIP\",\n \"amount\": -2510.00,\n \"currency\": \"CLP\",\n \"country\": \"CL\",\n \"date\": \"2023-07-05\",\n \"mcc\":\"1234\",\n \"transaction_type\":\"test\",\n \"product_id\":\"id_invalido\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{host}}data-enrichment/","description":"Este endpoint permite enriquecer una lista de transacciones utilizando el enriquecimiento de datos de Xerpa. Este envia una solicitud POST a {{host}}data-enrichment/ con un cuerpo en formato JSON que incluye el código del país y una lista de transacciones, el servidor procesa esta información y devuelve detalles enriquecidos sobre las transacciones, como identificadores, montos, descripciones y categorías asociadas. La respuesta incluye un estado 200 si la solicitud es exitosa, junto con un objeto JSON que contiene la información enriquecida de las transacciones.
Método: POST
\nURL: {{host}}data-enrichment/
El cuerpo de la solicitud debe contener los siguientes parámetros:
\ncountry (string): Código del país en formato ISO (ejemplo: \"CL\").
transactions (array of object): Lista de transacciones, donde cada transacción debe incluir:
\nid (string): Identificador único de la transacción.
description (string): Descripción de la transacción.
amount (number): Monto de la transacción (puede ser negativo).
currency (string): Código de la moneda (ejemplo: \"CLP\").
date (string): Fecha de la transacción en formato ISO (ejemplo: \"2023-07-05\").
mcc (string) (Opcional): Código de categoría de comerciante.
transaction_type (string) (Opcional): Tipo de transacción.
product_id (string): ID del producto asociado con la transacción.
La respuesta será un objeto JSON que contiene una lista de transacciones procesadas. Cada transacción incluirá los siguientes campos:
\nid (string): ID de la transacción.
amount (number): Monto de la transacción.
date (string): Fecha de la transacción.
description (string): Descripción de la transacción.
country (string): Código del país.
user_id (string|null): ID del usuario asociado (puede ser nulo).
mcc (string): Código de categoría de comerciante.
transaction_type (string): Tipo de transacción.
category_id (string): ID de la categoría.
category_name (string): Nombre de la categoría.
is_fixed_expense (boolean): Indica si es un gasto fijo.
is_subscription (boolean): Indica si es una suscripción.
subcategory_id (string): ID de la subcategoría.
subcategory_name (string): Nombre de la subcategoría.
merchant_id (string): ID del comerciante.
merchant_name (string): Nombre del comerciante.
merchant_logo_url (string): URL del logo del comerciante.
intermediary_id (string|null): ID del intermediario (puede ser nulo).
intermediary_name (string|null): Nombre del intermediario (puede ser nulo).
intermediary_logo (string|null): Logo del intermediario (puede ser nulo).
tags (array): Lista de etiquetas asociadas, donde cada etiqueta incluye:
id (string): ID de la etiqueta.
type (string): Tipo de etiqueta.
value (string): Valor de la etiqueta.
created_at (string): Fecha de creación de la transacción.
{\n \"type\": \"object\",\n \"properties\": {\n \"id\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"amount\": { \"type\": \"number\" },\n \"date\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"description\": { \"type\": \"string\" },\n \"country\": { \"type\": \"string\", \"maxLength\": 2 },\n \"user_id\": {\n \"type\": [\"string\", \"null\"],\n \"format\": \"uuid\"\n },\n \"category_id\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"category_name\": { \"type\": \"string\" },\n \"is_fixed_expense\": { \"type\": \"boolean\" },\n \"is_subscription\": { \"type\": \"boolean\" },\n \"subcategory_id\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"subcategory_name\": { \"type\": \"string\" },\n \"merchant_id\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"merchant_name\": { \"type\": \"string\" },\n \"merchant_logo_url\": { \"type\": \"string\", \"format\": \"uri\" },\n \"intermediary_id\": {\n \"type\": [\"string\", \"null\"],\n \"format\": \"uuid\"\n },\n \"intermediary_name\": { \"type\": [\"string\", \"null\"] },\n \"intermediary_logo\": { \"type\": [\"string\", \"null\"], \"format\": \"uri\" },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"type\": { \"type\": \"string\" },\n \"value\": { \"type\": \"string\" }\n }\n }\n },\n \"created_at\": { \"type\": \"string\", \"format\": \"date-time\" }\n }\n}\n\nServicio para procesar en línea hasta 1,000 transacciones por petición. Ideal para integrar en casos donde se busca ofrecer una mejor experiencia al usuario a través de los canales digitales y donde la instantaneidad entre que el usuario realiza la transacción y su enriquecimiento es una prioridad
\n![\"te-online-flow-2.png\"](\"../assets/images/te-online-flow-2.png\")
\n\nEl banco genera una petición con las transacciones que quiere enriquecer bajo la estructura de la API.
\nXerpa a través de sus motores procesa las transacciones y complementa cada uno con los datos que pudo enriquecer: categoría de comercio, nombre de comercio, logo de comercio, etc.
\nXera genera una respuesta con los nuevos campos por cada transacción.
\nLa API requiere como input de un listado de transactions que serán retornadas con la información que nuestros modelos puedan enriquecer. Por cada petición la API es capaz de procesar hasta 1,000 transacciones.
Adicionalmente, cada petición debe incluir una propiedad de country con el código de país para utilizar por defecto en caso de que no exista en alguna transacción.
theme: warning
\n\n\n<h4 >Categorización</h4><p >El monto de la transacción indicará si va a categorizar como un gasto o in ingreso. Este parámetro se utiliza para determinar a qué conjunto de categorías se puede asociar la transacción.</p>
\n
En caso de no venir incluido el country en la transacción se tomará por defecto el valor country que viene en la petición.
{\n \"country\":\"CL\",\n \"transactions\":[\n {\n \"id\":\"id1\",\n \"description\":\"Claro\",\n \"amount\":-10000.00,\n \"country\":\"CL\",\n \"date\":\"2023-07-05\"\n },\n {\n \"id\":\"id2\",\n \"description\":\"Entel\",\n \"amount\":-12000.00,\n \"country\":\"CL\",\n \"date\":\"2023-07-05\"\n },\n {\n \"id\":\"id3\",\n \"description\":\"PayPal * SKYAIRLINES MTHCUF\",\n \"amount\":-23000.00,\n \"country\":\"CL\",\n \"date\":\"2023-07-05\"\n }\n ]\n}\n\nLa API retornará el mismo arreglo de transacciones agregando en cada una de ellas propiedades
dependiendo de qué información se pudo enriquecer.
\n\nEstos campos en caso de no enriquecerse, se retornarán con valor NULL.
\n
{\n \"transactions\": [\n {\n \"id\": \"0ab1a829-8ec5-455b-908e-74365a85bef8\",\n \"amount\": -10000.0,\n \"date\": \"2023-07-05T00:00:00-06:00\",\n \"description\": \"Claro\",\n \"country\": \"CL\",\n \"user_id\": null,\n \"category_id\": \"8442c4fa-64e6-4470-af7c-8d007d5f572f\",\n \"category_name\": \"Cuentas & Servicios\",\n \"is_fixed_expense\": true,\n \"is_subscription\": false,\n \"subcategory_id\": \"5e80ae8f-a042-4696-8fc0-472bd30cd1c4\",\n \"subcategory_name\": \"Servicios de Fax, Servicios de Telecomunicaciones\",\n \"merchant_id\": \"57e748af-65ba-4e27-84db-13992056a1e2\",\n \"merchant_name\": \"Claro\",\n \"merchant_logo_url\": \"https://data-enrichment-xerpa.s3.amazonaws.com/logos/57e748af-65ba-4e27-84db-13992056a1e2.png\",\n \"intermediary_id\": null,\n \"intermediary_name\": null,\n \"intermediary_logo\": null,\n \"created_at\": \"2024-12-23T09:51:25.602141\"\n },\n {\n \"id\": \"c4b48bd7-5553-433d-9f9e-d598542c1dab\",\n \"amount\": -12000.0,\n \"date\": \"2023-07-05T00:00:00-06:00\",\n \"description\": \"Entel\",\n \"country\": \"CL\",\n \"user_id\": null,\n \"category_id\": \"8442c4fa-64e6-4470-af7c-8d007d5f572f\",\n \"category_name\": \"Cuentas & Servicios\",\n \"is_fixed_expense\": true,\n \"is_subscription\": false,\n \"subcategory_id\": \"5e80ae8f-a042-4696-8fc0-472bd30cd1c4\",\n \"subcategory_name\": \"Servicios de Fax, Servicios de Telecomunicaciones\",\n \"merchant_id\": \"e3bbb543-ecc6-4c51-9698-018157047651\",\n \"merchant_name\": \"Entel\",\n \"merchant_logo_url\": \"https://data-enrichment-xerpa.s3.amazonaws.com/logos/e3bbb543-ecc6-4c51-9698-018157047651.png\",\n \"intermediary_id\": null,\n \"intermediary_name\": null,\n \"intermediary_logo\": null,\n \"created_at\": \"2024-12-23T09:51:25.602141\"\n },\n {\n \"id\": \"96a11433-d493-4fb9-9540-c7fe89096b9a\",\n \"amount\": -23000.0,\n \"date\": \"2023-07-05T00:00:00-06:00\",\n \"description\": \"PayPal * SKYAIRLINES MTHCUF\",\n \"country\": \"CL\",\n \"user_id\": null,\n \"category_id\": \"84e6fa2f-8790-4d94-8f65-6944c7bcba10\",\n \"category_name\": \"Vacaciones & Viajes\",\n \"is_fixed_expense\": false,\n \"is_subscription\": false,\n \"subcategory_id\": \"2a2ca212-89ce-4740-9e63-3adc562a46ae\",\n \"subcategory_name\": \"Aerolíneas\",\n \"merchant_id\": \"16b254b3-f417-484c-86c7-277c888c7a0b\",\n \"merchant_name\": \"Sky Airlines\",\n \"merchant_logo_url\": \"https://data-enrichment-xerpa.s3.amazonaws.com/logos/16b254b3-f417-484c-86c7-277c888c7a0b.png\",\n \"intermediary_id\": \"2267dbe5-cca9-47b3-987a-1b0f57026d1e\",\n \"intermediary_name\": \"Paypal\",\n \"intermediary_logo\": \"https://data-enrichment-xerpa.s3.amazonaws.com/logos/2267dbe5-cca9-47b3-987a-1b0f57026d1e.png\",\n \"created_at\": \"2024-12-23T09:51:25.602141\"\n }\n ]\n}\n\n\n\nSi dos o más transacciones tengan el mismo id, serán procesadas como una única transacción y los valores se sobreescribirán por la última transacción
\n
La API está diseñada para responder en el menor tiempo posible.
\n","_postman_id":"0bd3e4c9-be81-4c08-b29f-ed04c9911322","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-API-Key"},{"key":"value","value":"{{x-api-key}}"}]},"isInherited":true,"source":{"_postman_id":"0e67c617-416e-4d5b-8c15-a27b81c8b601","id":"0e67c617-416e-4d5b-8c15-a27b81c8b601","name":"API Xerpa Transaction Enrichment","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-API-Key"},{"key":"value","value":"{{x-api-key}}"}]}},"event":[{"listen":"prerequest","script":{"id":"a9087468-5b6d-43e7-9df0-66ebd1694dde","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"cb9ccf06-bfce-467f-a48e-89a0e0500384","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://farming-simulator.pstmn.io"}]}