Developers
Ingresar a la plataforma

Listar transacciones

GET/api/public/v1/purchases

Devuelve una página de transacciones de la empresa, paginada por número de página (page, size). Admite filtros (fechas, montos, estados, presupuesto y comercio). La respuesta usa el formato HAL.

dateFrom/dateTo filtran por fecha de pago. Los filtros de lista se envían repitiendo el parámetro por cada valor.

Orden: por defecto se aplica el sort enviado, salvo en estos casos, en los que el filtro de fecha determina el orden y el sort enviado se reemplaza:

  • con lastModifiedDateFrom o lastModifiedDateTo: lastModifiedDate descendente;
  • con approvalWorkflowLastModifiedDateFrom o approvalWorkflowLastModifiedDateTo: approvalWorkflow.lastModifiedDate ascendente. No lo combines con los filtros de lastModifiedDate: la búsqueda responde 400;
  • con confirmationDateFrom o confirmationDateTo (y sin filtrar y ordenar por fecha de pago): confirmationDate descendente.

Los filtros por lastModifiedDate sólo están disponibles para api-keys asociadas a un grupo económico; en otro caso responden 400. Con pendingTasksFilter y sin dateFrom, la búsqueda se limita a los últimos 6 meses.

Autorización

apiKeyScheme
X-API-KEY<token>

En: header

Parámetros de consulta

text?string

Texto libre a buscar en la transacción (descripción, comercio y otros datos de texto). Si el valor tiene forma de identificador corto de transacción (shortId), busca las transacciones cuyo uniqueCode empieza con ese valor.

include?array<string>

uniqueCode de las transacciones a las que se limita el resultado: sólo se devuelven transacciones de esta lista (que además cumplan el resto de los filtros).

exclude?array<string>

uniqueCode de las transacciones a excluir del resultado.

dateFrom?string

Fecha de pago desde la cual filtrar las transacciones, inclusive.

Formatodate-time
dateTo?string

Fecha de pago hasta la cual filtrar las transacciones, inclusive.

Formatodate-time
lastModifiedDateFrom?string

Fecha de última modificación de la transacción desde la cual filtrar, inclusive. Al usarlo, el orden pasa a ser lastModifiedDate descendente y el sort enviado se ignora. Sólo disponible para api-keys asociadas a un grupo económico.

Formatodate-time
lastModifiedDateTo?string

Fecha de última modificación de la transacción hasta la cual filtrar, inclusive. Mismo reemplazo de orden y misma restricción que lastModifiedDateFrom.

Formatodate-time
amountFrom?number

Monto mínimo (amount) de la transacción, inclusive.

amountTo?number

Monto máximo (amount) de la transacción, inclusive.

budgetCode?string

Código único (uniqueCode) del presupuesto por el cual filtrar.

payerPersonCode?array<string>

Códigos únicos (uniqueCode) de las personas pagadoras por las cuales filtrar.

types?array<>

Tipos de transacción por los cuales filtrar: PURCHASE (transacción), REFUND (devolución), REVERSAL (reverso), CASH_WITHDRAWAL (retiro de efectivo), ADJUSTMENT (ajuste) o MILEAGE (gasto de kilometraje).

Valor en

  • "PURCHASE"
  • "REFUND"
  • "REVERSAL"
  • "CASH_WITHDRAWAL"
  • "ADJUSTMENT"
  • "MILEAGE"
summaryStatus?array<>

Estados resumidos de la transacción por los cuales filtrar: PENDING (pendiente de confirmación), AUTHORIZED_PAYMENT (pago autorizado), AUTHORIZED_WITHDRAWAL (retiro de efectivo autorizado), DECLINED_PAYMENT (pago rechazado), DECLINED_WITHDRAWAL (retiro rechazado), REFUNDED (devolución o reverso de una transacción autorizada), CANCELLED (transacción autorizada que luego se devolvió o revirtió por completo), EXPIRED (venció sin confirmarse) o ADJUSTMENT (ajuste sobre una transacción existente).

Valor en

  • "PENDING"
  • "AUTHORIZED_PAYMENT"
  • "AUTHORIZED_WITHDRAWAL"
  • "DECLINED_PAYMENT"
  • "DECLINED_WITHDRAWAL"
  • "REFUNDED"
  • "CANCELLED"
  • "EXPIRED"
  • "ADJUSTMENT"
paymentStatus?array<>

Estados de pago por los cuales filtrar: PENDING (aceptado, pendiente de confirmación), PROCESSED (aceptado y confirmado), DECLINED (rechazado por las restricciones del medio de pago) o EXPIRED (aceptado pero no confirmado dentro del plazo).

Valor en

  • "PENDING"
  • "DECLINED"
  • "PROCESSED"
  • "EXPIRED"
transactionStatus?array<>

Estados de transacción por los cuales filtrar: PENDING (aceptada, todavía sin confirmar), CONFIRMED (aceptada y confirmada), DECLINED (rechazada) o EXPIRED (venció sin confirmarse).

Valor en

  • "PENDING"
  • "CONFIRMED"
  • "DECLINED"
  • "EXPIRED"
paymentLegalStatus?array<>

Estados del pago ante la autoridad fiscal por los cuales filtrar: ACTIVE (verificado y vigente), CANCELED (verificado y cancelado), NOT_FOUND (la autoridad fiscal no lo encontró) o FOREIGN (pago realizado en el exterior: la autoridad fiscal no tiene información sobre él y no requiere verificación).

Valor en

  • "ACTIVE"
  • "CANCELED"
  • "NOT_FOUND"
  • "FOREIGN"
paymentMode?array<>

Modos de pago por los cuales filtrar: PHYSICAL_CARD, VIRTUAL_CARD, EXTERNAL_CARD, CASH, WIRE, EXTERNAL_WIRE, OTHER, EXTERNAL_CASH, AMEX_CORPORATE, VISA_CORPORATE, MASTERCARD_CORPORATE o IN_ADVANCE_CASH. Los modos disponibles dependen de la configuración de cada empresa.

Valores válidos: el conjunto válido depende del cluster. Consulta con tu contacto de onboarding los valores habilitados para tu cluster.

Valor en

  • "PHYSICAL_CARD"
  • "VIRTUAL_CARD"
  • "EXTERNAL_CARD"
  • "CASH"
  • "WIRE"
  • "EXTERNAL_WIRE"
  • "OTHER"
  • "EXTERNAL_CASH"
  • "AMEX_CORPORATE"
  • "VISA_CORPORATE"
  • "MASTERCARD_CORPORATE"
  • "IN_ADVANCE_CASH"
  • "TRAVEL_CARD"
  • "TRAVEL_ACCOUNT"
legalUniqueCode?string

Código único legal (folio fiscal) del comprobante por el cual filtrar.

archived?boolean

Sin efecto: este filtro no se aplica y el resultado no depende de su valor.

fileCodes?array<string>

uniqueCode de archivos: devuelve las transacciones que tienen alguno de ellos como factura o comprobante fiscal digital.

companyCode?array<string>

uniqueCode de las empresas por las cuales filtrar, dentro de las que la api-key tiene acceso.

traceId?array<string>

Identificadores de traza (traceId) de las transacciones por los cuales filtrar.

transactionId?array<string>

Identificadores de transacción por los cuales filtrar.

merchantCode?array<string>

uniqueCode de los comercios (merchant) por los cuales filtrar.

sellerTransactionName?string

Nombre del comercio informado en la transacción por el cual filtrar.

approvalWorkflowStatus?array<>

Estados del flujo de aprobación por los cuales filtrar: PENDING_SUBMISSION (pendiente de envío: faltan campos obligatorios), SUBMITTED (enviada, esperando la primera aprobación), PARTIAL_AUTHORIZED (aprobada en al menos un nivel, esperando el siguiente), AUTHORIZED (aprobada en todos los niveles), UNAUTHORIZED (rechazada), INFORMATION_REQUIRED (un aprobador pidió información al responsable), EXEMPTED (eximida del flujo por una regla de exención), ERROR (error al procesar el flujo) o PENDING (valor histórico: sólo en transacciones anteriores a la introducción de PENDING_SUBMISSION).

Valor en

  • "PENDING"
  • "SUBMITTED"
  • "AUTHORIZED"
  • "UNAUTHORIZED"
  • "PARTIAL_AUTHORIZED"
  • "ERROR"
  • "PENDING_SUBMISSION"
  • "EXEMPTED"
  • "INFORMATION_REQUIRED"
purchaseBillingStatus?array<>

Sin efecto: este filtro no se aplica y el resultado no depende de su valor.

Valor en

  • "ACTIVE"
  • "BLOCKED"
  • "CLOSED"
automaticProcessStatus?array<>

Sin efecto: este filtro no se aplica y el resultado no depende de su valor.

Valor en

  • "AUTOMATIC_IN_PROGRESS"
  • "AUTOMATIC_CLOSED"
  • "AUTOMATIC_NO_PROCESSABLE"
  • "AUTOMATIC_FAIL"
  • "NONE"
paymentLocationType?array<>

Ubicación del pago respecto del país de la empresa por la cual filtrar: LOCAL o INTERNATIONAL.

Valor en

  • "LOCAL"
  • "INTERNATIONAL"
processorIdentificationCode?string

Código de identificación de la transacción asignado por el procesador.

cancelled?boolean

true devuelve sólo transacciones canceladas (devueltas o revertidas por completo); false, sólo las no canceladas. Sin valor, no filtra.

pendingTasksFilter?boolean

true devuelve sólo las transacciones que su responsable todavía tiene que revisar o completar; false, las que no. Sin dateFrom, la búsqueda se limita a los últimos 6 meses.

confirmationDateFrom?string

Fecha de confirmación de la transacción desde la cual filtrar, inclusive. Salvo que se filtre y ordene por fecha de pago, el orden pasa a ser confirmationDate descendente.

Formatodate-time
confirmationDateTo?string

Fecha de confirmación de la transacción hasta la cual filtrar, inclusive. Mismo reemplazo de orden que confirmationDateFrom.

Formatodate-time
approvalWorkflowLastModifiedDateFrom?string

Fecha de última modificación del flujo de aprobación desde la cual filtrar, inclusive. Al usarlo, el orden pasa a ser approvalWorkflow.lastModifiedDate ascendente y el sort enviado se ignora. No lo combines con lastModifiedDateFrom/lastModifiedDateTo: responde 400.

Formatodate-time
approvalWorkflowLastModifiedDateTo?string

Fecha de última modificación del flujo de aprobación hasta la cual filtrar, inclusive. Mismo reemplazo de orden que approvalWorkflowLastModifiedDateFrom.

Formatodate-time
fieldsNull?array<string>

Campos que deben estar vacíos: devuelve sólo las transacciones sin valor en todos ellos. Valores permitidos: budgetCode (sin presupuesto), purchaseBilling (sin información de facturación), approvalWorkflow.status (sin flujo de aprobación). Otro valor responde 400.

page?integer

Número de página a devolver, comenzando en 0.

Formatoint32
Rango0 <= value
size?integer

Cantidad de elementos por página. Por defecto 20; un valor mayor al máximo de la operación (500 salvo que se indique otro) se recorta a ese máximo.

Formatoint32
sort?array<>

Criterios de ordenamiento, en orden de prioridad. Cada criterio se envía con índice: sort[0].property=<campo>&sort[0].direction=ASC|DESC.

Criterios de ordenamiento, enviados como sort[0].property y sort[0].direction (ASC o DESC). Sin ordenamiento explícito, el orden de los resultados no está garantizado.

property?string
direction?string

Valor en

  • "ASC"
  • "DESC"
excludeCount?boolean

Si es true, omite el cálculo del total de resultados para responder más rápido.

Cuerpo de la respuesta

application/vnd.hal+json

application/json

application/json

curl -X GET "https://example.com/api/public/v1/purchases?dateFrom=2024-11-13T16%3A51%3A00.000Z&dateTo=2024-11-13T16%3A51%3A00.000Z&lastModifiedDateFrom=2024-11-13T16%3A51%3A00.000Z&lastModifiedDateTo=2024-11-13T16%3A51%3A00.000Z&amountFrom=100&amountTo=5000&confirmationDateFrom=2024-11-13T16%3A51%3A00.000Z&confirmationDateTo=2024-11-13T16%3A51%3A00.000Z&approvalWorkflowLastModifiedDateFrom=2024-11-13T16%3A51%3A00.000Z&approvalWorkflowLastModifiedDateTo=2024-11-13T16%3A51%3A00.000Z"
{  "_embedded": {    "purchases": [      {        "deleted": true,        "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",        "companyCode": "string",        "lastModifiedDate": "2024-11-13T16:51:00.000Z",        "createdDate": "2024-11-13T16:51:00.000Z",        "createdBy": "string",        "externalId": "string",        "description": "string",        "version": 0,        "seller": {          "legalId": "string",          "name": "string",          "legalName": "string",          "merchantCode": "string",          "category": "string",          "categoryDescription": "string",          "categoryCode": "string"        },        "invoiceNumber": "string",        "payment": {          "transactionId": "string",          "traceId": "string",          "cancellationCode": "string",          "status": "PENDING",          "legalStatus": "ACTIVE",          "mode": "PHYSICAL_CARD",          "rejectionReason": "CARD_NOT_FOUND",          "rejectionReasonDescription": "string",          "paymentBank": "string",          "paymentCardCode": "string",          "paymentCardLast4Digits": "4321",          "date": "2024-11-13T16:51:00.000Z",          "legalUniqueCode": "string",          "legalSignature": "string",          "invoiceFile": {            "filename": "string",            "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82"          },          "digitalInvoiceFile": {            "filename": "string",            "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82"          },          "errorType": "PAYER_MISMATCH",          "errorTypeDescription": "string",          "channel": "ONLINE",          "locationType": "LOCAL",          "ticketAttached": true        },        "issuerBank": "string",        "budgetCode": "string",        "budgetName": "Marketing Q4",        "ruleUniqueCode": "string",        "ruleName": "string",        "legalAmount": 2358,        "amount": 2358,        "confirmedAmount": 2358,        "legalAmountDiff": 0,        "taxAmount": 358,        "sign": -1,        "surchargeFee": 0,        "currency": {          "code": "string",          "minDecimalPlaces": 0,          "maxDecimalPlaces": 0        },        "notes": "string",        "foreignAmount": 125,        "settlementAmount": 2358,        "confirmedForeignAmount": 125,        "effectiveConfirmedForeignAmount": 125,        "foreignCurrencyCode": "USD",        "settlementCurrencyCode": "USD",        "cancelled": true,        "parentUniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",        "type": "PURCHASE",        "accountType": {          "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",          "companyCode": "string",          "number": "string",          "name": "Viáticos",          "selectable": true        },        "expenseCategory": {          "code": "string",          "description": "string"        },        "countryCode": "MX",        "city": "string",        "costCenterCode": "string",        "costCenterName": "Marketing",        "budget": {          "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",          "companyCode": "string",          "lastModifiedDate": "2024-11-13T16:51:00.000Z",          "createdDate": "2024-11-13T16:51:00.000Z",          "createdBy": "string",          "externalId": "string",          "name": "Marketing Q4",          "status": "EXPIRED",          "goal": 50000,          "cycleType": "ONE_TIME",          "expirationDate": "2024-11-13T16:51:00.000Z",          "active": true,          "spent": 12500,          "availableToSpend": 37500,          "membersCount": 0,          "currency": {            "code": "string",            "minDecimalPlaces": 0,            "maxDecimalPlaces": 0          },          "spendLimitedForAllMembers": true,          "expired": true,          "availableForUse": true,          "spentPercentage": 25,          "spentAvailablePercentage": 75,          "exceeded": true        },        "archived": true,        "reference": "string",        "processorIdentificationCode": "string",        "logoFileName": "string",        "invoiceIssueDate": "2024-11-13T16:51:00.000Z",        "withdrawalFee": 0,        "purchaseSplits": [          {            "accountType": {              "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",              "companyCode": "string",              "number": "string",              "name": "Viáticos",              "selectable": true            },            "costCenter": {              "uniqueCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",              "name": "Marketing",              "externalId": "string"            },            "amount": 2358,            "splitSignedAmount": -2358          }        ],        "editable": true,        "shortId": "string",        "signedAmount": -2358,        "signedForeignAmount": -125,        "companyExternalId": "string",        "personal": true,        "involvesPoliticallyExposed": true,        "politicallyExposedPersonName": "string",        "confirmationDate": "2024-11-13T16:51:00.000Z",        "transactionStatus": "PENDING",        "purchasePayer": {          "companyLegalId": "string",          "companyName": "string",          "personCode": "0590843e-1d92-4d51-82c6-4a22a6b8be82",          "fullName": "string",          "legalId": "string",          "email": "string"        },        "payerSupervisor": {          "email": "string",          "code": "0590843e-1d92-4d51-82c6-4a22a6b8be82"        },        "approvalWorkflow": {          "status": "string",          "auditPolicyStatus": "string",          "payerSupervisorCode": "string",          "lastEventComment": "string",          "lastEventAuditorUniqueCode": "string",          "lastEventType": "string",          "lastModifiedDate": "2024-11-13T16:51:00.000Z"        },        "missingFilesReason": "string",        "mileageDistance": 125.5,        "unusualPurchase": {          "indicator": "string",          "flaggingDate": "2024-11-13T16:51:00.000Z"        },        "merchantCategoryFields": [          {            "merchantCategoryCode": "string",            "name": "string",            "value": "string"          }        ]      }    ]  },  "_links": {    "property1": {      "href": "string",      "hreflang": "string",      "title": "string",      "type": "string",      "deprecation": "string",      "profile": "string",      "name": "string",      "templated": true    },    "property2": {      "href": "string",      "hreflang": "string",      "title": "string",      "type": "string",      "deprecation": "string",      "profile": "string",      "name": "string",      "templated": true    }  },  "page": {    "size": 0,    "totalElements": 0,    "totalPages": 0,    "number": 0  }}