Cuentas de una entidad
curl --request GET \
--url http://api.gu1.ai/entities/{id}/accounts \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/accounts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/{id}/accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/{id}/accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/accounts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/accounts")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyReferencia API
Cuentas de una entidad
Registrá y administrá cuentas financieras pertenecientes a una entidad persona o empresa.
GET
/
entities
/
{id}
/
accounts
Cuentas de una entidad
curl --request GET \
--url http://api.gu1.ai/entities/{id}/accounts \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/accounts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/{id}/accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/{id}/accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/accounts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/accounts")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyDescripción general
Las cuentas son recursos hijos de entidades persona y empresa. Permiten registrar varias cuentas por cliente, incluso en distintas monedas. Cada cuenta tiene unexternalId definido por el cliente, una currency ISO 4217 y al menos un identificador de pago. Los datos quedan aislados dentro de la organización actual.
Endpoints
El mismo CRUD existe para tres búsquedas de entidad, igual que actualizar por external ID yPATCH /entities/by-tax-id/{taxId}:
| Método | Ruta | Búsqueda de entidad |
|---|---|---|
GET POST | /entities/{id}/accounts | UUID de Gu1 |
PATCH DELETE | /entities/{id}/accounts/{accountId} | UUID de Gu1 |
GET POST | /entities/by-external-id/{externalId}/accounts | Tu externalId (match exacto) |
PATCH DELETE | /entities/by-external-id/{externalId}/accounts/{accountId} | Tu externalId |
GET POST | /entities/by-tax-id/{taxId}/accounts | Tax ID, denormalizado |
PATCH DELETE | /entities/by-tax-id/{taxId}/accounts/{accountId} | Tax ID, denormalizado |
{accountId} es siempre el UUID de Gu1 de la cuenta (el de create/list).
Búsqueda por tax ID ignora puntuación y mayúsculas (CUIT 20-12345678-9 matchea 20123456789). Usa la misma clave alfanumérica que la unicidad de tax ID a nivel organización (idx_entities_org_norm_tax_id). Codificá el segmento de path si el valor tiene caracteres reservados.
La lectura requiere entities:read. Las mutaciones requieren entities:edit, con fallback legacy entities:write.
Campos de la cuenta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
externalId | string | Sí | ID de cuenta en tu sistema; único dentro de la organización |
currency | string | Sí | Código ISO 4217, como USD, ARS o BRL |
accountType | enum | No | Tipo canónico de cuenta; consultá los valores admitidos debajo |
status | string | No | active, inactive, frozen o closed; default active |
countryCode | string | No | País ISO 3166-1 alpha-2 |
accountNumber | string | Condicional | Número de cuenta genérico |
cbu | string | Condicional | CBU de 22 dígitos |
cvu | string | Condicional | CVU de 22 dígitos |
iban | string | Condicional | IBAN de hasta 34 caracteres |
alias | string | Condicional | Alias de la cuenta |
bankName | string | No | Banco o institución financiera |
bankCode | string | No | Código de banco definido por el cliente |
isPrimary | boolean | No | Cuenta principal de la entidad para esa moneda |
metadata | object | No | Datos adicionales propios del cliente |
openedAt | string | No | Fecha de apertura ISO 8601 |
closedAt | string | No | Fecha de cierre ISO 8601 |
Tipos de cuenta admitidos
accountType acepta exclusivamente uno de estos valores:
- Genéricos:
bank_account,personal,business,other - Depósitos bancarios:
checking,savings,business_checking,business_savings,payroll,pension,money_market,fixed_deposit - Inversión y custodia:
investment,brokerage,custody,escrow - Pagos y fondos digitales:
payment,wallet,virtual_account,prepaid,merchant - Crédito:
credit,loan - Operación institucional:
correspondent,settlement,clearing,cash_management
bank_account cuando sabés que es una cuenta bancaria pero no conocés el producto, y other solo cuando ninguna categoría represente la cuenta. checking corresponde a cuenta corriente y savings a caja de ahorro. Un valor fuera del enum devuelve 400 VALIDATION_ERROR.
Al crear una cuenta se requiere al menos uno de estos campos: accountNumber, cbu, cvu, iban o alias.
Ejemplo de creación
curl -X POST "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "account-usd-001",
"currency": "USD",
"accountType": "savings",
"accountNumber": "ACC-001",
"countryCode": "AR",
"isPrimary": true
}'
{
"success": true,
"account": {
"id": "77c2ca62-4528-4d2e-a424-ff7c0ee7ab18",
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "account-usd-001",
"currency": "USD",
"accountType": "savings",
"status": "active",
"accountNumber": "ACC-001",
"isPrimary": true
}
}
externalId en vez del UUID de Gu1:
curl -X POST "https://api.gu1.ai/entities/by-external-id/merchant-99/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "account-usd-001",
"currency": "USD",
"accountType": "savings",
"accountNumber": "ACC-001",
"isPrimary": true
}'
curl -X POST "https://api.gu1.ai/entities/by-tax-id/20-12345678-9/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "account-ars-001",
"currency": "ARS",
"cbu": "0000003100000000000001"
}'
isPrimary: true, la API quita la marca principal de las otras cuentas de la misma entidad y moneda.
Errores
| HTTP | Código | Cuándo |
|---|---|---|
400 | VALIDATION_ERROR | El input es inválido, accountType no pertenece al enum o no queda ningún identificador de pago |
404 | NOT_FOUND | La entidad o cuenta no existe en la organización actual |
409 | CONFLICT | El externalId ya existe en la organización actual |
Was this page helpful?