Da de baja una tarjeta guardada

DELETE

/v1/pagos/clientes/{clienteId}/tarjetas/{id}

Producción
Homologación / pruebas

Baja la tarjeta primero en la red de pagos y después localmente.

Es baja lógica: la fila se apaga, no se borra, porque hay cobros y suscripciones que la referencian y el historial tiene que sobrevivir.

meta.yaNoExistiaEnProveedor: true significa que del otro lado ya no estaba — sigue siendo una baja efectiva, no un error. Cualquier otro fallo aborta la baja: una tarjeta viva allá y muerta acá es la otra mitad de la desincronización.

Emite tarjeta.baja.

Alcance requerido: pagos:tarjetas. 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

clienteId

required

string format: uuid

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

Tarjeta dada de baja

object

Ejemplos

{
  "data": {
    "id": "3a2f1e0d-9c8b-4a7f-8e6d-5c4b3a2f1e0d",
    "clienteId": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
    "mascara": "589656******2345",
    "brandCode": "CABAL",
    "activo": false
  },
  "meta": {
    "yaNoExistiaEnProveedor": false,
    "auditNumber": "000789"
  }
}

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