Consulta un pago

GET

/v1/pagos/{id}

Producción
Homologación / pruebas

Detalle de un cobro, con su solicitud de origen y sus imputaciones a facturas.

El comprobante fiscal no se expande acá: el campo reciboCfeId es el UUID del CFE y se consulta con GET /v1/cfe/info/{id}, que devuelve el estado real en DGI. Importa la diferencia: un comprobante puede estar emitido y rechazado a la vez, y esa distinción vive en el módulo de CFE, no acá.

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 path

required

string format: uuid

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

Detalle del pago

object

Ejemplos

{
  "data": {
    "id": "9b1c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "estado": "facturado",
    "canal": "link",
    "monto": "1234.56",
    "moneda": "UYU",
    "reciboCfeId": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "anulable": false,
    "solicitud": {
      "id": "8f14e45f-ceea-467a-9f5a-2b1c3d4e5f60",
      "referenciaIntegrador": "orden-12345",
      "estado": "pagada"
    },
    "imputaciones": [
      {
        "id": "6c7d8e9f-0a1b-4c2d-3e4f-5a6b7c8d9e0f",
        "pagoId": "9b1c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
        "cfeEmitidoId": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
        "monto": "1234.56",
        "moneda": "UYU",
        "origen": "automatica"
      }
    ],
    "comprobante": {
      "cfeEmitidoId": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "tipo": 101,
      "serie": "A",
      "numero": 1042,
      "estadoDGI": "AC",
      "aceptadoPorDGI": true,
      "motivoDGI": null,
      "anulado": false
    }
  }
}

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"
}

404

No existe un pago con ese id en tu cuenta

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 encontrado

{
  "error": {
    "code": "PAGOS_PAGO_NO_ENCONTRADO",
    "message": "Pago no encontrado"
  },
  "requestId": "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e"
}

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"
}