Lista pagos

GET

/v1/pagos

Producción
Homologación / pruebas

Listado paginado de los cobros de la cuenta, con el vínculo a su comprobante fiscal.

Los filtros están documentados uno por uno en los parámetros de query. referenciaIntegrador filtra por igualdad exacta y es el camino para responder “¿cuál es el cobro de mi orden 12345?”: el controller la resuelve a su link y devuelve los cobros de ese link. Si la referencia no existe, el listado sale vacío.

Estado	Qué significa
`aprobado`	Cobrado; no correspondía emitir comprobante
`pendiente_facturacion`	Cobrado y sin comprobante todavía. La plata está; la emisión falló o está en cola
`facturado`	Cobrado y con comprobante emitido (`reciboCfeId`)
`anulado` / `fallido`	Reversado / no prosperó

Canales: link, tarjeta_registrada, suscripcion, manual, qr_pos.

Para los pendiente_facturacion, el DTO trae intentosFacturacion y ultimoErrorFacturacion: un reintento automático los levanta mientras el fallo sea transitorio; un fallo definitivo necesita que alguien corrija el dato desde el panel.

Los montos son el bruto cobrado, nunca neteados por la comisión del adquirente. La comisión no viaja en el aviso de cobro y es un gasto de la empresa, no un menor ingreso.

Alcance requerido: pagos:leer. Si la credencial no lo tiene, la respuesta es 403 API_ALCANCE_INSUFICIENTE con la lista en error.requerido. Las credenciales creadas antes del modelo de alcances (alcances: null) conservan acceso total.

La empresa sale de la credencial. No hay ningún parámetro ni campo de cuerpo que la elija: cada API_KEY opera sobre su propia EFacturaCuenta. La ÚNICA excepción es la cabecera x-cuenta-id de una credencial de revendedor, que apunta a una subcuenta de su cartera. Si integrás empresas que no son de tu cartera, usá una API_KEY por empresa.

Autorizaciones

BearerAuth

Parámetros

Parámetros de query

pagina

Página, desde 1

integer

>= 1

Ejemplo

Página, desde 1

porPagina

Filas por página (máx. 200)

integer

>= 1 <= 200

Ejemplo

Filas por página (máx. 200)

ordenarPor

Campo por el que ordenar

string

<= 64 characters

Campo por el que ordenar

orden

string

Allowed values: asc desc

busqueda

Búsqueda parcial libre

string

<= 255 characters

Búsqueda parcial libre

desde

Fecha desde, YYYY-MM-DD

string

Ejemplo

2026-09-01

Fecha desde, YYYY-MM-DD

hasta

Fecha hasta, YYYY-MM-DD

string

Ejemplo

2026-09-30

Fecha hasta, YYYY-MM-DD

estado

pendiente_facturacion es LA consulta para detectar plata cobrada cuyo comprobante todavía no salió.

string

Allowed values: aprobado pendiente_facturacion facturado anulado fallido

pendiente_facturacion es LA consulta para detectar plata cobrada cuyo comprobante todavía no salió.

canal

string

Allowed values: link tarjeta_registrada suscripcion manual qr_pos

clienteId

string format: uuid

moneda

Moneda del cobro (ISO-4217). Se procesan únicamente UYU y USD: cualquier otra devuelve 422 PAGOS_MONEDA_NO_SOPORTADA.

string

Allowed values: UYU USD

Ejemplo

UYU

Moneda del cobro (ISO-4217). Se procesan únicamente UYU y USD: cualquier otra devuelve 422 PAGOS_MONEDA_NO_SOPORTADA.

referenciaIntegrador

Referencia del cobro en TU sistema (orden, carrito, socio). Filtra por igualdad exacta, no parcial: es el camino para responder “¿cuál es el cobro de mi orden 12345?”. Para búsqueda parcial está busqueda, que también la mira.

string

<= 128 characters

Ejemplo

orden-12345

Parámetros de header

x-cuenta-id

string format: uuid

Ejemplo

0199d1b0-0000-7000-8000-000000000000

Sólo para credenciales de cuenta proveedora (revendedor). UUID de la subcuenta de la cartera sobre la que se quiere operar: la cuenta efectiva del request pasa a ser esa.

Una credencial que no es de proveedor, o una subcuenta que no está en su cartera, recibe 403 API_CUENTA_FUERA_DE_CARTERA. Sin la cabecera, la cuenta es siempre la de la credencial.

x-branch-id

string format: uuid

Sucursal contra la que operar, cuando la credencial es global. Si la credencial está fijada a una sucursal y esta cabecera indica otra, la respuesta es 403 API_ACCESS_BRANCH_MISMATCH. Sin la cabecera se asume la casa central.

x-point-id

string format: uuid

Punto de emisión dentro de la sucursal resuelta. Obligatorio cuando la sucursal tiene 2 o más puntos activos (400 PUNTO_EMISION_REQUERIDO si falta); con uno solo se selecciona automáticamente.

Respuestas

200

Pagos de la cuenta

object

Ejemplos

{
  "data": [
    {
      "id": "9b1c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "solicitudId": "8f14e45f-ceea-467a-9f5a-2b1c3d4e5f60",
      "clienteId": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
      "estado": "facturado",
      "canal": "link",
      "monto": "1234.56",
      "moneda": "UYU",
      "fechaPago": "2026-09-12T10:31:00.000-03:00",
      "authorizationCode": "123456",
      "marca": "VISA",
      "mascara": "450995******3345",
      "reciboCfeId": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "suscripcionId": null,
      "intentosFacturacion": 1,
      "ultimoErrorFacturacion": null,
      "anulable": false
    }
  ],
  "meta": {
    "paginacion": {
      "pagina": 1,
      "porPagina": 20,
      "totalFilas": 1,
      "totalPaginas": 1
    }
  }
}

401

No autenticado. La API_KEY no fue enviada, no es válida o la credencial está desactivada.

Códigos posibles: API_AUTH_HEADER_MISSING, API_AUTH_HEADER_INVALID, API_ACCESS_INVALID.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Falta header Authorization

{
  "error": {
    "code": "API_AUTH_HEADER_MISSING",
    "message": "Se esperaba la cabecera Authorization con esquema Bearer"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Secret key inválida o revocada

{
  "error": {
    "code": "API_ACCESS_INVALID",
    "message": "Acceso no autorizado"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

403

El módulo de cobros no está habilitado para esta cuenta, o la credencial no tiene el alcance que la operación exige. Son dos cosas distintas y se corrigen distinto:

Code	Qué pasó	Cómo se corrige
`PAGOS_NO_HABILITADO`	La cuenta no tiene el módulo de cobros	Es una habilitación comercial: la hace administración, no se activa desde la API
`API_ALCANCE_INSUFICIENTE`	La credencial no tiene el alcance (va en `error.requerido`)	Editar la credencial en Integraciones → API
`API_CUENTA_FUERA_DE_CARTERA`	`x-cuenta-id` apunta a una cuenta ajena a la cartera	Revisar el UUID de la subcuenta

Ninguno se arregla reintentando.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

La cuenta no tiene el módulo de cobros

{
  "error": {
    "code": "PAGOS_NO_HABILITADO",
    "message": "El módulo de pagos no está habilitado para esta cuenta. Es una habilitación comercial: la hace administración, no se activa desde la API."
  },
  "requestId": "4c5d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f"
}

Falta el alcance

{
  "error": {
    "code": "API_ALCANCE_INSUFICIENTE",
    "message": "La credencial de API no tiene ninguno de los alcances necesarios para esta operación (pagos:cobrar)",
    "requerido": [
      "pagos:cobrar"
    ]
  },
  "requestId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

429

Rate limit excedido. Esperá los segundos del header Retry-After. La cuota va por credencial: 60 req/min en cuentas estándar, 600 en cuentas proveedor.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Excediste el rate limit

{
  "error": {
    "code": "API_RATE_LIMITED",
    "message": "Se superó el límite de requests para esta API key"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Headers

Retry-After

integer

Ejemplo

Segundos hasta que se libera la ventana de rate limit

503

No se pudo verificar la habilitación del módulo (PAGOS_ESTADO_INDETERMINADO), o falta la clave maestra de cifrado de secretos (PAGOS_CLAVE_MAESTRA_AUSENTE). Nada que corregir del lado del integrador: reintentar.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español. No parsearlo: puede cambiar

string

details

Any of:

object

requerido

Sólo en 403 API_ALCANCE_INSUFICIENTE: alcances que habilitan la operación

Array<string>

Allowed values: cfe:emitir cfe:leer recibidos:leer consultas clientes:leer clientes:escribir pagos:leer pagos:cobrar pagos:tarjetas pagos:suscripciones pagos:configurar webhooks:gestionar

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

No se pudo leer el flag de pagos

{
  "error": {
    "code": "PAGOS_ESTADO_INDETERMINADO",
    "message": "No se pudo verificar si el módulo de pagos está habilitado para esta cuenta. Reintentá."
  },
  "requestId": "0f4a1c2e-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
}

Clave maestra ausente

{
  "error": {
    "code": "PAGOS_CLAVE_MAESTRA_AUSENTE",
    "message": "No está configurada la clave maestra de secretos de pagos"
  },
  "requestId": "0f4a1c2e-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
}