Un movimiento

Un movimiento de tu empresa. El id va sellado por empresa: el de otra da 404.

Dato	Valor
Método y ruta	`GET /v1/movements/{id}`
Servidor	`https://widget.fital.xyz`
`operationId`	`getMovement`
Acceso	Llave con el scope `movements:read`
Firma de petición	No aplica
Idempotencia	No aplica

Encabezados de la petición

Encabezado	Obligatorio	Descripción
`Authorization`	Sí	`Bearer` y tu llave.
`X-Fital-Scenario`	No	Sólo simuladores: elige la respuesta que quieres practicar.

Parámetros

Parámetro	En	Tipo	Obligatorio	Descripción
`id`	ruta	texto	Sí	Identificador del recurso. Hasta 250 caracteres.

Respuestas correctas

200 Correcto

Campo	Tipo	Obligatorio	Descripción
`amount`	texto o `null`	Sí	Monto del movimiento.
`completed_at`	texto o `null`	Sí	Fecha en que terminó. ISO 8601 en UTC.
`created_at`	texto o `null`	Sí	Fecha de creación. ISO 8601 en UTC.
`currency`	texto o `null`	Sí	Moneda del monto.
`destination_currency`	texto o `null`	Sí	Moneda de destino.
`external_ref`	texto o `null`	Sí	Tu `external_ref` del pago o cobro del que sale este movimiento. null si no tiene.
`final_amount`	texto o `null`	Sí	Monto final, cuando se conoce.
`final_currency`	texto o `null`	Sí	Moneda del monto final.
`id`	texto	Sí	Identificador del movimiento, con prefijo `mov_`.
`payment_id`	texto o `null`	Sí	Pago de esta API del que sale este movimiento, con prefijo `pay_`. null si no salió de un pago creado por esta API.
`read_status`	texto	Sí	Cuánto se pudo leer. `complete`: Se leyó el detalle completo. `partial`: No se pudo leer el detalle completo. El estado no avanza con una lectura parcial.
`status`	texto	Sí	Estado público. Sólo `completed`, `failed`, `returned` y `canceled` son terminales. `processing`: Aceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal. `in_review`: En revisión. No lo repitas: el pago ya existe. `completed`: Se pagó. Aún puede pasar a `returned`. `failed`: No se hizo y no queda dinero en tránsito. `returned`: Se devolvió y el saldo ya volvió. `canceled`: Se canceló antes de ejecutarse.
`type`	texto	Sí	Categoría del movimiento. `payment`: Salida por un riel de pago. `deposit`: Entrada de dinero. `crypto`: Envío o recepción de un token. `internal`: Movimiento interno de la cuenta. `card`: Operación con tarjeta. `other`: Cualquier otro movimiento.
`updated_at`	texto o `null`	Sí	Última actualización. ISO 8601 en UTC.

Valores de `read_status`

Valor	Significado
`complete`	Se leyó el detalle completo.
`partial`	No se pudo leer el detalle completo. El estado no avanza con una lectura parcial.

Valores de `status`

Valor	Significado
`processing`	Aceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal.
`in_review`	En revisión. No lo repitas: el pago ya existe.
`completed`	Se pagó. Aún puede pasar a `returned`.
`failed`	No se hizo y no queda dinero en tránsito.
`returned`	Se devolvió y el saldo ya volvió.
`canceled`	Se canceló antes de ejecutarse.

Valores de `type`

Valor	Significado
`payment`	Salida por un riel de pago.
`deposit`	Entrada de dinero.
`crypto`	Envío o recepción de un token.
`internal`	Movimiento interno de la cuenta.
`card`	Operación con tarjeta.
`other`	Cualquier otro movimiento.

{
  "amount": "1500.00",
  "completed_at": "2026-11-04T18:01:30.000Z",
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "destination_currency": "MXN",
  "external_ref": "pedido-7731",
  "final_amount": "1500.00",
  "final_currency": "MXN",
  "id": "mov_2hKsV9tBq4XzM7nD1cYpL6rF",
  "payment_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "read_status": "complete",
  "status": "completed",
  "type": "payment",
  "updated_at": "2026-11-04T18:01:30.000Z"
}

Lectura parcial: el estado no avanza:

{
  "amount": "1500.00",
  "completed_at": null,
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "destination_currency": "MXN",
  "external_ref": "pedido-7731",
  "final_amount": null,
  "final_currency": null,
  "id": "mov_2hKsV9tBq4XzM7nD1cYpL6rF",
  "payment_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "read_status": "partial",
  "status": "processing",
  "type": "payment",
  "updated_at": "2026-11-04T18:01:30.000Z"
}

Encabezados de la respuesta

Encabezado	Contenido
`X-Request-Id`	Identificador de la petición. Cítalo con soporte.
`Retry-After`	Segundos a esperar, con `429` y a veces con `503`.

Errores

Todos usan la forma de Errores: error.code, message, request_id, details, retryable y docs_url. Decide por code.

HTTP	Código	Cuándo sale	`retryable`
400	`invalid_request`	Algún parámetro o campo no cumple el esquema. Mira `details.fields`.	`false`
401	`invalid_api_key`	La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida.	`false`
401	`wrong_environment`	La llave es de otro ambiente.	`false`
403	`forbidden_scope`	La llave no tiene el scope de esta operación. `details.required_scope` lo nombra.	`false`
403	`ip_not_allowed`	La IP de origen no está activa en la lista de esa llave.	`false`
403	`kyb_required`	La empresa no tiene KYB aprobado o aún no está inscrita.	`false`
403	`account_not_active`	La cuenta no está activa.	`false`
404	`not_found`	El movimiento no existe o es de otra empresa.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
500	`internal_error`	Fallo nuestro. El resultado de la petición no se conoce.	`true`
503	`service_unavailable`	El servicio no está disponible por ahora. El resultado de la petición no se conoce.	`true`

Ejemplos de error

400 invalid_request:

{
  "error": {
    "code": "invalid_request",
    "message": "Petición inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "fields": {
        "limit": "Entre 1 y 100"
      }
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
  }
}

401 invalid_api_key:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Credencial inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key"
  }
}

403 forbidden_scope:

{
  "error": {
    "code": "forbidden_scope",
    "message": "La llave no tiene permiso para esta operación",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "required_scope": "movements:read"
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
  }
}

404 not_found:

{
  "error": {
    "code": "not_found",
    "message": "No encontrado",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found"
  }
}

429 rate_limited:

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiadas peticiones",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited"
  }
}

500 internal_error:

{
  "error": {
    "code": "internal_error",
    "message": "Error interno",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error"
  }
}

503 service_unavailable:

{
  "error": {
    "code": "service_unavailable",
    "message": "Servicio no disponible",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable"
  }
}

Reintentos

Es una lectura: repetirla no tiene efecto.

429 rate_limited: Espera lo que indique Retry-After y repite.
500 internal_error: Repite con espera exponencial.
503 service_unavailable: Repite con espera exponencial. Respeta Retry-After si viene.

Ver Reintentos y Límites.

Muestras

Variables de estas muestras: simulador público, sin cuenta

Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público:

export FITAL_API="https://widget.fital.xyz/explorar/v1"
export FITAL_KEY="sk_test_sandbox_publica"

En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los id de ejemplo por los tuyos. Ver Ambientes.

op-consultar-movimiento.sh

curl -sS "$FITAL_API/movements/mov_2hKsV9tBq4XzM7nD1cYpL6rF" \
  -H "Authorization: Bearer $FITAL_KEY"

Guías

Ver esta página en Markdown

Encabezados de la peticiónCopiar enlace

ParámetrosCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar enlace

Valores de read_statusCopiar enlace

Valores de statusCopiar enlace

Valores de typeCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página