Movimientos

La API de Movimientos te permite recuperar el historial de transacciones y los detalles de movimientos de las cuentas de usuario. Incluye filtrado, paginación y capacidades avanzadas de consulta usando GraphQL.

El objeto Movement

{
  "id": 789012,
  "amount": 10000,
  "currency": "USD",
  "state": "completed",
  "reference": "REF-123",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z",
  "balanceBefore": 140000,
  "balanceAfter": 150000
}

Atributos

Atributo	Tipo	Descripción
`id`	integer	Identificador único del movimiento
`amount`	integer	Monto del movimiento en céntimos
`currency`	string	Código de moneda (USD, EUR, etc.)
`state`	string	Estado del movimiento (`pending`, `completed`, `failed`, `cancelled`)
`reference`	string	Referencia externa o ID de transacción
`createdAt`	string	Marca temporal ISO 8601 de cuándo se creó el movimiento
`completedAt`	string	Marca temporal ISO 8601 de cuándo se completó el movimiento
`balanceBefore`	integer	Saldo de la cuenta antes del movimiento en céntimos
`balanceAfter`	integer	Saldo de la cuenta después del movimiento en céntimos

Listar movimientos

Devuelve una lista de movimientos para el usuario autenticado con filtrado y paginación opcionales.

GET/movements/

curl -X GET "https://sandbox.tropipay.me/api/v3/movements/?limit=20&offset=0" \
  -H "Authorization: Bearer sk_test_..."

Parámetros

Parámetro	Tipo	Requerido	Descripción
`limit`	integer	No	Número de resultados a devolver (máx: 50, por defecto: 20)
`offset`	integer	No	Número de registros a omitir (por defecto: 0)
`query`	string	No	Objeto de filtro codificado en JSON

Objeto de filtro de consulta

El parámetro query acepta un objeto codificado en JSON con los siguientes campos opcionales:

{
  "state": ["completed", "pending"],
  "currency": "USD",
  "amountGte": 1000,
  "amountLte": 100000,
  "createdAtFrom": "2024-01-01T00:00:00Z",
  "createdAtTo": "2024-12-31T23:59:59Z",
  "reference": "REF-123"
}

Filtro	Tipo	Descripción
`state`	array	Filtrar por estados de movimiento
`currency`	string	Filtrar por moneda
`amountGte`	integer	Monto mínimo en céntimos
`amountLte`	integer	Monto máximo en céntimos
`createdAtFrom`	string	Fecha de inicio (ISO 8601)
`createdAtTo`	string	Fecha de fin (ISO 8601)
`reference`	string	Filtrar por referencia

Respuesta

{
  "items": [
    {
      "id": 789012,
      "amount": 10000,
      "currency": "USD",
      "state": "completed",
      "reference": "REF-123",
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:31:00Z",
      "balanceBefore": 140000,
      "balanceAfter": 150000
    }
  ],
  "totalCount": 1,
  "hasMore": false
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`items`	array	Array de objetos de movimiento
`totalCount`	integer	Número total de movimientos que coinciden con la consulta
`hasMore`	boolean	Indica si hay más resultados disponibles

Listar movimientos de una cuenta

Devuelve los movimientos de una cuenta específica.

GET/accounts/{accountId}/movements

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/acc_123/movements \
  -H "Authorization: Bearer sk_test_..."

Parámetros

Los mismos parámetros que el endpoint general de movimientos, pero filtrados a la cuenta especificada.

Consulta avanzada de movimientos (GraphQL)

Para consultas complejas y filtrado avanzado, usa el endpoint GraphQL.

POST/movements/business

curl -X POST https://sandbox.tropipay.me/api/v3/movements/business \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetMovements($filter: MovementFilter, $pagination: Pagination) { movements(filter: $filter, pagination: $pagination) { items { id amount state currency createdAt recipient { name email } sender { name email } } totalCount } }",
    "variables": {
      "filter": {
        "state": ["completed", "pending"],
        "amountGte": 100,
        "amountLte": 100000,
        "createdAtFrom": "2024-01-01T00:00:00Z",
        "createdAtTo": "2024-12-31T23:59:59Z"
      },
      "pagination": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

Esquema GraphQL

MovementFilter

input MovementFilter {
  state: [MovementState!]
  currency: String
  amountGte: Int
  amountLte: Int
  createdAtFrom: DateTime
  createdAtTo: DateTime
  reference: String
  accountId: String
}

Pagination

input Pagination {
  limit: Int
  offset: Int
}

Movement Type

type Movement {
  id: ID!
  amount: Int!
  currency: String!
  state: MovementState!
  reference: String
  createdAt: DateTime!
  completedAt: DateTime
  balanceBefore: Int!
  balanceAfter: Int!
  recipient: User
  sender: User
  account: Account!
}

MovementState Enum

enum MovementState {
  PENDING
  COMPLETED
  FAILED
  CANCELLED
}

Respuesta GraphQL

{
  "data": {
    "movements": {
      "items": [
        {
          "id": "789012",
          "amount": 10000,
          "state": "COMPLETED",
          "currency": "USD",
          "createdAt": "2024-01-15T10:30:00Z",
          "recipient": {
            "name": "John",
            "email": "john@example.com"
          },
          "sender": {
            "name": "Jane",
            "email": "jane@example.com"
          }
        }
      ],
      "totalCount": 1
    }
  }
}

Reembolsar una transacción

Permite a un usuario reembolsar una transacción previamente completada.

POST/movements/in/refund

Autenticación:

Requiere autenticación de usuario (token JWT)
Requiere autenticación de dos factores (2FA) habilitada
Requiere permiso ALLOW_REFUND

curl -X POST https://sandbox.tropipay.me/api/v3/movements/in/refund \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderCode": "ORD-123456",
    "amount": 5000
  }'

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
`orderCode`	string	Sí	Código del pedido/transacción a reembolsar
`amount`	number	Sí	Monto a reembolsar en céntimos
`securityCode`	string	Sí	2fa para la cuenta. En sandbox siempre "123456" o autenticador.

Respuesta

Código de estado: 200 OK

Devuelve un objeto de reserva con los detalles del reembolso generado.

{
  "id": 123456,
  "orderCode": "ORD-123456",
  "amount": 5000,
  "currency": "USD",
  "state": "completed",
  "type": "refund",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z"
}

Respuestas de error

Código de estado	Descripción
`400`	Bad Request - Faltan parámetros requeridos o los valores son inválidos
`401`	Unauthorized - Usuario no autenticado
`403`	Forbidden - El usuario no tiene permiso `ALLOW_REFUND` o el 2FA no está habilitado
`404`	Not Found - El código de orden no existe
`500`	Internal Server Error - Error durante el procesamiento del reembolso

Ejemplo de respuesta de error

{
  "error": {
    "type": "permission_error",
    "code": "missing_permission",
    "message": "User does not have ALLOW_REFUND permission"
  }
}

Notas

El reembolso se procesa como una solicitud iniciada por el cliente
Tanto el código de orden como el monto deben ser válidos
La transacción debe estar en un estado reembolsable
El 2FA debe estar habilitado en la cuenta de usuario

Estados de movimiento

Estado	Descripción
`pending`	El movimiento está siendo procesado
`completed`	El movimiento se completó exitosamente
`failed`	El movimiento falló debido a un error
`cancelled`	El movimiento fue cancelado por el usuario o el sistema

Paginación

Todos los endpoints de movimientos soportan paginación usando los parámetros limit y offset:

limit: Número máximo de resultados a devolver (1-50, por defecto: 20)
offset: Número de registros a omitir (por defecto: 0)

Ejemplo de paginación

# Obtener los primeros 20 movimientos
curl -X GET "https://sandbox.tropipay.me/api/v3/movements/?limit=20&offset=0"

# Obtener los siguientes 20 movimientos
curl -X GET "https://sandbox.tropipay.me/api/v3/movements/?limit=20&offset=20"

Manejo de errores

La API de Movimientos utiliza códigos de respuesta HTTP convencionales para indicar el éxito o fracaso de una solicitud a la API.

Códigos de error comunes

Código	Descripción
`400`	Bad Request - Parámetros de consulta inválidos
`401`	Unauthorized - Autenticación inválida
`403`	Forbidden - Permisos insuficientes
`404`	Not Found - La cuenta o el movimiento no existen
`422`	Unprocessable Entity - Parámetros de filtro inválidos
`429`	Too Many Requests - Límite de tasa excedido
`500`	Internal Server Error

Ejemplo de respuesta de error

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_filter",
    "message": "Invalid date format in createdAtFrom parameter",
    "param": "query.createdAtFrom"
  }
}

Mejores prácticas

Usa paginación para conjuntos grandes de resultados y mejorar el rendimiento
Filtra por rango de fechas para limitar el alcance de tus consultas
Usa estados específicos para obtener solo los movimientos que necesitas
Cachea resultados cuando sea apropiado para reducir llamadas a la API
Usa GraphQL para consultas complejas que requieren datos relacionados

El objeto Movement​

Atributos​

Listar movimientos​

Parámetros​

Objeto de filtro de consulta​

Respuesta​

Parámetros de la respuesta​

Listar movimientos de una cuenta​

Parámetros​

Consulta avanzada de movimientos (GraphQL)​

Esquema GraphQL​

MovementFilter​

Pagination​

Movement Type​

MovementState Enum​

Respuesta GraphQL​

Reembolsar una transacción​

Parámetros del cuerpo de la solicitud​

Respuesta​

Respuestas de error​

Ejemplo de respuesta de error​

Notas​

Estados de movimiento​

Paginación​

Ejemplo de paginación​

Manejo de errores​

Códigos de error comunes​

Ejemplo de respuesta de error​

Mejores prácticas​

El objeto Movement

Atributos

Listar movimientos

Parámetros

Objeto de filtro de consulta

Respuesta

Parámetros de la respuesta

Listar movimientos de una cuenta

Parámetros

Consulta avanzada de movimientos (GraphQL)

Esquema GraphQL

MovementFilter

Pagination

Movement Type

MovementState Enum

Respuesta GraphQL

Reembolsar una transacción

Parámetros del cuerpo de la solicitud

Respuesta

Respuestas de error

Ejemplo de respuesta de error

Notas

Estados de movimiento

Paginación

Ejemplo de paginación

Manejo de errores

Códigos de error comunes

Ejemplo de respuesta de error

Mejores prácticas