Introducción
Para actualizar las llaves usamos el modelo de actualización de objeto [signer] (../about/about-signers).
Transfiya funciona como un directorio federado que puede almacenar copias de llaves que no se sincronizan automáticamente con DICE.
Información sobre cómo sincronizar con DICE.
Flujos de actualización
El nuevo modelo regulado simplifica el proceso de actualización, porque no utiliza wallets.
En el flujo actual para actualizar una llave con el que está vinculada la cuenta implica eliminar un singer y crear nuevo vínculo.
Nuevo flujo
Flujo anterior
El modelo actual de billeteras permanecerá activo para garantizar compatibilidad con los sistemas existentes.
Ejemplos de API
Para modificar la información de la cuenta de una llave se realiza actualizando las etiquetas de un signer.
| Parameter | Type | Description |
|---|
| handle | string | 26-35 characters Alphanumeric characters allowed base58 structure |
| labels | object | Metadata describing the address. Use them to describe the details of the signer. |
curl -X PUT \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"labels": {
"bankAccountType": "DBMO",
"bankAccountNumber": "302058294920"
}
}' "URL/v1/signer/wRFmYXS2sP9ho9VCZ3j4FuP1j55ABeFvsF"
Códigos de Error
| Error Code | Description |
|---|
| 99 | Unexpected server error |
| 100 | You don’t have permissions to access this method |
| 102 | Invalid labels |
| 118 | Resource schema validation error |
| 121 | Signer not found in database |
Cambio de llave de un signer
La modificación de los alias de signer es una de las operaciones de llave contempladas dentro del marco regulatorio del SPI. Esta operación debe entenderse internamente como una cancelación del valor de la llave actual y la creación de una nueva.
Para este caso de uso, se habilitó el campo “allowImmediateReuse", el cual debe enviarse con el valor:
true: si la operación corresponde a una modificación del alias.false: si se trata de una cancelación definitiva.
| Parameter | Type | Description |
|---|
| handle | string | 26-35 characters Alphanumeric characters allowed base58 structure |
| labels | object | Metadata describing the address. Use them to describe the details of the signer. |
curl -X PUT \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"labels": {
"status": "INACTIVE",
"allowImmediateReuse":true
}
}' "URL/v1/signer/wRFmYXS2sP9ho9VCZ3j4FuP1j55ABeFvsF"
Crear Nuevo Alias
Crear un nuevo signer con un alias diferente y asociar los mismos datos de usuario:
POST /v1/signer/
curl -X POST \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"labels": {
"aliasType": "EMAIL",
"aliasValue": "jorge2@company.io",
"type": "PERSON",
"firstName": "Jorge",
"secondName": "Alejandro",
"lastName": "Fernandez",
"secondLastName": "Garcia",
"proprietary": "CC",
"identification": "1010101010",
"bankAccountType": "SVGS",
"bankAccountNumber": "12345654321",
"countryOfResidence": "CO",
"bankBicfi": "7095",
"bankName": "Banco Rojo",
"routerReference": "$bancorojo",
"targetSpbviCode": "TFY",
"consented": "2024-10-11T11:59:23.241-05:00"
},
"keeper": [
{
"scheme": "ecdsa-ed25519",
"public": "0463e75c8b975f069813ca8e6c36c0b6fd246eac708affb7ed2c6480fa201defe8725322d6380ec66e94f6dcb49f635c0ca51296e48da4a12b3ec66582a1297adf"
}
]
} "URL/v1/signer"
| Error Code | Description |
|---|
| 99 | Unexpected server error |
| 100 | You don’t have permissions to access this method |
| 102 | Invalid labels |
| 118 | Resource schema validation error |
| 121 | Signer not found in database |
Para modificar la información personal de un signer, se realiza por medio de la actualización de las etiquetas del signer.
| Parameter | Type | Description |
|---|
| handle | string | 26-35 characters Alphanumeric characters allowed base58 structure |
| labels | object | Metadata describing the address. Use them to describe the details of the signer. |
curl -X PUT \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"labels": {
"lastName": "Garcia",
"identification": "54812184282"
}
}' "URL/v1/signer/wRFmYXS2sP9ho9VCZ3j4FuP1j55ABeFvsF"
Códigos de Error
| Error Code | Description |
|---|
| 99 | Unexpected server error |
| 100 | You don’t have permissions to access this method |
| 102 | Invalid labels |
| 118 | Resource schema validation error |
| 121 | Signer not found in database |
🔐 Actualización de datos y gestión de llaves en el sistema Bre-B
La correcta administración de las llaves en los Sistemas de Pago de Bajo Valor Inmediatos (SPBVI) es fundamental para garantizar la seguridad, trazabilidad e interoperabilidad de las transacciones. Cuando un usuario solicita la actualización de sus datos como el tipo de cuenta asociada a una llave es responsabilidad directa de la entidad participante ejecutar dicha modificación de forma inmediata y conforme a los lineamientos establecidos por el Banco de la República.
Cualquier demora en el proceso puede generar acreditaciones erróneas de recursos económicos, afectando la integridad del sistema y la confianza del usuario. Según la normativa Bre-B, en especial la Circular Reglamentaria Externa DSP-465, los participantes deben reportar en tiempo real las novedades a la Entidad Administradora del SPBVI (EASPBVI), asegurando que los cambios se reflejen oportunamente en el Directorio Federado y el Directorio Centralizado.
📌 Importante: Si la entidad participante no actualiza oportunamente la llave tras una solicitud válida del usuario, y se generan errores en la acreditación de fondos, será responsable por las consecuencias derivadas de dicha omisión.
