Está en la página 1de 22

2019

API Itaú Cvu – Guía


de Uso v 1.0

BANCO ITAU ARGENTINA | Dirección de Sistemas y Tecnología


Tabla de contenido
Objetivo ................................................................................................................................................................... 2
Introducción........................................................................................................................................................... 2
Recursos .................................................................................................................................................................. 3
Cvu ........................................................................................................................................................................ 3
POST /transaction/cvu .............................................................................................................................. 5
CvuTransaction ............................................................................................................................................... 5
PUT /transaction/cvu/{cvu} ..................................................................................................................... 7
DELETE /transaction/cvu/{cvu}............................................................................................................... 9
GET /cvu/{cvu}............................................................................................................................................ 10
UniqueKey........................................................................................................................................................ 12
GET /uniquekey/{keynumber}/validation ........................................................................................ 12
Transfer ............................................................................................................................................................. 14
POST /transfer............................................................................................................................................ 14
GET /transfer/{transferId} – No implementado ............................................................................. 18
Ambientes y Seguridad ................................................................................................................................... 20
Anexo ..................................................................................................................................................................... 21

P á g i n a 1 | 21
Objetivo

El objeto del presente documento es el de detallar la API expuesta por Banco Itaú
Argentina S.A., para la administración (alta, baja, modificación, eliminación y consulta) de la
nueva entidad CVU (Clave Virtual Uniforme), de acuerdo a lo dispuesto en la Comunicación
“A” 6510 del Banco Central de la República Argentina, con fecha 15 de Mayo de 2018.

Introducción

El servicio de administración de Cvu se expone mediante una API REST, publicada por el
Banco Itau Argentina.

La API cuenta con cuatro recursos, a saber:

P á g i n a 2 | 21
Recursos

Cvu

El recurso Cvu cuenta con cuatro endpoints para el CRUD de entidades. En particular los
métodos POST, PUT y DELETE tiene un modo de procesamiento asincrónico, de acuerdo a
la siguiente secuencia:

Este diagrama referencia, a modo ilustrativo, al endpoint POST /cvu, pero es igualmente
trasladable en concepto a los métodos PUT y DELETE. La API responderá con un código
HTTP 200 y un objeto Json del tipo Transaction, de acuerdo al siguiente esquema:

P á g i n a 3 | 21
El campo transactionId contendrá un string con un identificador único de transacción, que
servirá para consolidar la información sobre la finalización y resultado de la transacción. El
backend enviará un objeto del tipo TransactionResult al endpoint POST
/transacction/notification, definido en el archivo ITAU-cvu-psp.json. Este endpoint deberá
ser implementado por quien desee consumir los servicios de la API Cvu:

P á g i n a 4 | 21
POST /transaction/cvu

La invocación a éste endpoint permite la creación y registro de una Cvu asociado a un Psp
(Proveedor de Servicios de Pago), mediante el envío de datos del usuario y el cuit del Psp.

El objeto cvuTransaction tiene la siguiente definición:

CvuTransaction
{

clientId* ClientId number


minimum: 0
maximum: 99999999999

cuit* string

holderName* string

personType* PersonType string

Kind of person owner of the CVU - Fisica/Juridica

Enum:
[ Fisica, Juridica ]

P á g i n a 5 | 21
currency* Currency string

currently, ARS
only https://es.wikipedia.org/wiki/ISO_4217

Enum:
[ ARS, USD ]

La respuesta del servicio tendrá la siguiente estructura:

HTTP 200 - Ok

Transaction
{
transactionId String
transactionType String
Enum:
[ createCvuTransaction, modifyCvuTransaction, deleteCvuTransaction ]
date String
}

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}

P á g i n a 6 | 21
PUT /transaction/cvu/{cvu}

La invocación a éste endpoint permite la modificación total de un registro de una Cvu


asociado a un Psp (Proveedor de Servicios de Pago), mediante el envío de datos del
usuario, el número de cvu y el cuit del Psp.

El objeto cvuTransaction tiene la siguiente definición:

CvuTransaction
{

clientId* ClientId number


minimum: 0
maximum: 99999999999

cuit* string

holderName* string

P á g i n a 7 | 21
personType* PersonType string

Kind of person owner of the CVU - Fisica/Juridica

Enum:
[ Fisica, Juridica ]

currency* Currency string

currently, ARS
only https://es.wikipedia.org/wiki/ISO_4217

Enum:
[ ARS, USD ]

La respuesta del servicio tendrá la siguiente estructura:

HTTP 200 - Ok

Transaction
{
transactionId String
transactionType String
Enum:
[ createCvuTransaction, modifyCvuTransaction, deleteCvuTransaction ]
date String
}

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}

P á g i n a 8 | 21
DELETE /transaction/cvu/{cvu}

La invocación a éste endpoint permite la eliminación total de un registro de una Cvu


asociado a un Psp (Proveedor de Servicios de Pago), mediante el envío de datos del
número de cvu y el cuit del Psp.

La respuesta del servicio tendrá la siguiente estructura:

HTTP 200 - Ok

Transaction
{
transactionId String
transactionType String
Enum:
[ createCvuTransaction, modifyCvuTransaction, deleteCvuTransaction ]
date String
}

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}
P á g i n a 9 | 21
GET /cvu/{cvu}

La invocación a éste endpoint permite la consulta de un registro de una Cvu asociado a un


Psp (Proveedor de Servicios de Pago), mediante el envío del número de cvu y el cuit del
Psp.

La respuesta del servicio tendrá la siguiente estructura:

HTTP 200 – Ok

Cvu
{

clientId* ClientId number


minimum: 0
maximum: 99999999999

cvu KeyNumber number


minimum: 0
maximum: 1e+22

cuit* string

holderName* string

personType* PersonType string

Kind of person owner of the CVU - Fisica/Juridica

Enum:
Array [ 2 ]

currency* Currency string

P á g i n a 10 | 21
currently, ARS
only https://es.wikipedia.org/wiki/ISO_4217

Enum:
Array [ 2 ]

alias string

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}

P á g i n a 11 | 21
UniqueKey

El recurso UniqueKey cuenta con un endpoint de consulta para validación de clave única,
aceptando tanto Cvu como Cbu.

Además de los detalles de la clave, éste endpoint devuelve, en caso de éxito, un token de
validación JWT. Dicho token puede enviarse opcionalmente como entrada al endpoint
POST /transfer, permitiendo acelerar los tiempos de respuesta a través de la omisión de
pasos de validación.

GET /uniquekey/{keynumber}/validation

La invocación a éste endpoint permite la validación de una clave única, sea Cvu o Cbu,
mediante el envío de la misma, y el cuit del PSP.

La respuesta del servicio constará de un objeto UniqueKey, que responde a la siguiente


definición:

P á g i n a 12 | 21
HTTP 200 – Ok

UniqueKey
{

keyNumber* KeyNumbernumber
minimum: 0
maximum: 1e+22

cuit* string

holderName* string

personType PersonTypestring

Kind of person owner of the CVU - Fisica/Juridica

Enum:
Array [ 2 ]

accountCurrency* Currencystring

currently, ARS
only https://es.wikipedia.org/wiki/ISO_4217

Enum:
Array [ 2 ]

alias string

Además, dentro del header HTTP, será enviado el campo keyValidationToken.

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}

P á g i n a 13 | 21
Transfer

El recurso Transfer cuenta con dos endpoints para alta y consulta de entidades, definidos
por los métodos GET y POST.

El modo de procesamiento para ambos endpoints es sincrónico.

El método GET aún se encuentra sin implementar al momento de emisión de este manual,
pero queda documentado para futuro uso.

POST /transfer

La invocación a este endpoint permite la creación de una transferencia de dinero desde un


Cvu a otro Cvu o Cbu, mediante la información del número de cuit del Psp y el objeto
transfer.

P á g i n a 14 | 21
Dicho objeto responde a la siguiente definición:

Transfer {
debitAccount*

DebitAccount {
uniqueKey string

Unique Virtual or Banking Key.

Accepts Cvu or Cbu

accountAlias string

Alias assigned to account

accountNumber string

P á g i n a 15 | 21
Account number

creditAccount*

CreditAccount {
creditCuit string

creditUniqueKey string

Credit Unique Virtual or Banking Key.

Accepts Cvu or Cbu

creditAccountType stringEnum:
Array [ 2 ]

ownerName string

amount* number($double)

currency* Currencystring

currently, ARS only https://es.wikipedia.org/wiki/ISO_4217

Enum:
[ ARS, USD ]

transferConcept* string

En particular, respecto de los objetos DebitAccount, existe una obligatoriedad implícita


sobre los campos que componen el objeto, y que no se encuentra reflejada en el contrato
Swagger por limitaciones de la especificación, a saber:

DebitAccount
{
uniqueKey string
Unique Virtual or
Banking Key.
Accepts Cvu or Debe informarse sólo uno de
Cbu (uniqueKey, accountAlias,
accountAlias string  accountNumber). Son mutuamente
Alias assigned to excluyentes.
account
accountNumber string
Account number
}

P á g i n a 16 | 21
La información de dos o más campos resultará en un error HTTP 400 – Bad Request.

La respuesta del servicio será un objeto del tipo TransferResult, con la siguiente
estructura:

HTTP 200 – Ok

TransferResult
{
transferId* string
message* Message{
messageCode string
messageDescription string
}
uri* string
}

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}

P á g i n a 17 | 21
GET /transfer/{transferId} – No implementado

La invocación a este endpoint permite la consulta de un objeto Transfer, mediante la


información del número de cuit del Psp y el parámetro transferId devuelto por POST
/transfer.

La respuesta consiste a un objeto del tipo Transfer, de acuerdo a lo antes definido:

HTTP 200 – Ok

Transfer {
debitAccount*

DebitAccount {
uniqueKey string

Unique Virtual or Banking Key.

Accepts Cvu or Cbu

accountAlias string

Alias assigned to account

accountNumber string

Account number

P á g i n a 18 | 21
creditAccount*

CreditAccount {
creditCuit string

creditUniqueKey string

Credit Unique Virtual or Banking Key.

Accepts Cvu or Cbu

creditAccountType stringEnum:
Array [ 2 ]

ownerName string

amount* number($double)

currency* Currencystring

currently, ARS only https://es.wikipedia.org/wiki/ISO_4217

Enum:
[ ARS, USD ]

transferConcept* string

En caso de error:

HTTP 500 – Internal Server Error

Error
{
code* string
messageCode integer($int32)
message* string
}

P á g i n a 19 | 21
Ambientes y Seguridad

El Banco cuenta con dos ambientes disponibles: Homologación y Producción. Las URL son,
respectivamente:

Homologación: https://wsechomo.itau.com.ar/apiCvu/v1

Producción: https://wsec.itau.com.ar/apiCvu/v1

Ambos ambientes se encuentran expuestos en Internet, siendo necesario para la conexión


y consumo de la API en cada uno de ellos, la presentación de un certificado cliente,
provisto por el Banco Itaú Argentina. El mismo puede requerirse a los funcionarios de
Middle Office, a la siguiente casilla de contacto: Impleproductos@itau.com.ar.

De idéntica forma, para la operación con endpoints asíncronos del recurso Cvu, es
necesaria, tanto la implementación de una API conforme al contrato ITAU-cvu-psp.json,
como de la provisión de un certificado cliente que los servidores del banco deberán
presentar ante un call-back, para establecer conexión segura con los servidores del PSP.

P á g i n a 20 | 21
Anexo

P á g i n a 21 | 21