> For the complete documentation index, see [llms.txt](https://yutax.gitbook.io/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yutax.gitbook.io/developer/api-reference/accounts.md).
# Accounts
Alta / bulk de cuentas
## Crear/actualizar cuenta (upsert single)
> Upsert por UNIQUE (recomendado): (business\_id, account\_id). Requiere email o phone (al menos uno).
```json
{"openapi":"3.0.3","info":{"title":"Yutax API","version":"1.0.0"},"tags":[{"name":"Accounts","description":"Alta / bulk de cuentas"}],"servers":[{"url":"https://business.yutax.net","description":"Host placeholder (cambia por tu dominio)"}],"security":[{"HmacHeaders":[]}],"components":{"securitySchemes":{"HmacHeaders":{"type":"apiKey","in":"header","name":"X-SIGNATURE","description":"Auth por headers.\nHeaders: - X-PUBLIC-KEY: public key del business (test o live) - X-TIMESTAMP: unix timestamp (string numérico) - X-NONCE: opcional - X-SIGNATURE: Base64(HMAC-SHA256(stringToSign, privateKey))\nstringToSign:\n POST\\n{path}\\n{timestamp}\\n{nonce}\\n{sha256(body)}\\n\n\nNota: en NDJSON bulk, el server usa sha256 del body gzip real.\n"}},"parameters":{"XPublicKey":{"name":"X-PUBLIC-KEY","in":"header","required":true,"schema":{"type":"string"},"description":"Public key (ej- yk_live_pk_...)"},"XTimestamp":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Unix timestamp (string numérico)"},"XNonce":{"name":"X-NONCE","in":"header","required":false,"schema":{"type":"string"},"description":"Nonce opcional"},"XSignature":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Firma HMAC base64"}},"schemas":{"AccountsCreateRequest":{"type":"object","additionalProperties":false,"required":["account_id","fullname","account_name","account_type_id","responsibility_id","open_date","status_id"],"anyOf":[{"required":["email"]},{"required":["phone"]}],"properties":{"account_id":{"type":"string","maxLength":80},"fullname":{"type":"string","maxLength":150},"account_name":{"type":"string","maxLength":160},"ci":{"type":"string","maxLength":50},"email":{"type":"string","maxLength":190,"description":"Requerido si phone vacío (regla- email o phone)"},"phone":{"type":"string","maxLength":40,"description":"Requerido si email vacío (regla- email o phone)"},"account_type_id":{"type":"integer","enum":[1,2,3,4,5,6,7],"description":"Tipo de cuenta.\n1=debit, 2=credit, 3=wallet, 4=saving, 5=loan, 6=store, 7=subscription\n"},"responsibility_id":{"type":"integer","enum":[1,2,3],"description":"responsibility_id (catálogo):\n1=Individual, 2=Authorized User, 3=Business\n"},"open_date":{"type":"string","description":"YYYY-MM-DD"},"status_id":{"type":"integer","enum":[1,2,3,4,5,6],"description":"status_id (catálogo):\n1=open, 2=closed, 3=pending, 4=inactive, 5=suspended, 6=blocked\n"},"address":{"type":"string","maxLength":255},"account_amount":{"type":"string","nullable":true,"description":"Decimal como string (para MySQL)"},"notes":{"type":"string","maxLength":2000}}},"AccountsCreateResponse":{"type":"object","additionalProperties":false,"required":["ok","mode","business_id","updated_at"],"properties":{"ok":{"type":"boolean"},"mode":{"type":"string","enum":["single"]},"business_id":{"type":"integer"},"report_id":{"type":"integer","nullable":true,"description":"ID autoincrement (report_id) asignado/actualizado"},"updated_at":{"type":"string"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Código de error"},"message":{"type":"string","description":"Mensaje legible (cuando aplique)"}}}},"responses":{"AuthError":{"description":"Auth inválida / headers faltantes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Método no permitido (solo POST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/accounts/create":{"post":{"tags":["Accounts"],"summary":"Crear/actualizar cuenta (upsert single)","description":"Upsert por UNIQUE (recomendado): (business_id, account_id). Requiere email o phone (al menos uno).\n","parameters":[{"$ref":"#/components/parameters/XPublicKey"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsCreateRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsCreateResponse"}}}},"400":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/AuthError"},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}}}}
```
## Bulk upsert (JSON) — requiere gzip
> Bulk JSON con \`columns\` + \`rows\`. Debe enviarse con header \`Content-Encoding: gzip\`. Devuelve \`results\` como tabla: \[account\_id, report\_id] (primer row es header).
```json
{"openapi":"3.0.3","info":{"title":"Yutax API","version":"1.0.0"},"tags":[{"name":"Accounts","description":"Alta / bulk de cuentas"}],"servers":[{"url":"https://business.yutax.net","description":"Host placeholder (cambia por tu dominio)"}],"security":[{"HmacHeaders":[]}],"components":{"securitySchemes":{"HmacHeaders":{"type":"apiKey","in":"header","name":"X-SIGNATURE","description":"Auth por headers.\nHeaders: - X-PUBLIC-KEY: public key del business (test o live) - X-TIMESTAMP: unix timestamp (string numérico) - X-NONCE: opcional - X-SIGNATURE: Base64(HMAC-SHA256(stringToSign, privateKey))\nstringToSign:\n POST\\n{path}\\n{timestamp}\\n{nonce}\\n{sha256(body)}\\n\n\nNota: en NDJSON bulk, el server usa sha256 del body gzip real.\n"}},"parameters":{"XPublicKey":{"name":"X-PUBLIC-KEY","in":"header","required":true,"schema":{"type":"string"},"description":"Public key (ej- yk_live_pk_...)"},"XTimestamp":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Unix timestamp (string numérico)"},"XNonce":{"name":"X-NONCE","in":"header","required":false,"schema":{"type":"string"},"description":"Nonce opcional"},"XSignature":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Firma HMAC base64"}},"schemas":{"AccountsBulkRequest":{"type":"object","additionalProperties":false,"required":["mode","columns","rows"],"properties":{"mode":{"type":"string","enum":["upsert"]},"columns":{"type":"array","items":{"type":"string"},"description":"Columnas permitidas: account_id, fullname, ci, email, phone, address, account_name, account_type_id, account_amount, responsibility_id, open_date, status_id, notes\n"},"rows":{"type":"array","items":{"type":"array","items":{}},"description":"Array de filas, cada fila debe tener el mismo largo que columns"}}},"AccountsBulkResponse":{"type":"object","additionalProperties":false,"required":["ok","mode","gzip_required","business_id","received_rows","processed_rows","failed_rows","chunk_size","max_rows","updated_at","results","errors"],"properties":{"ok":{"type":"boolean"},"mode":{"type":"string","enum":["bulk"]},"gzip_required":{"type":"boolean"},"business_id":{"type":"integer"},"received_rows":{"type":"integer"},"processed_rows":{"type":"integer"},"failed_rows":{"type":"integer"},"chunk_size":{"type":"integer"},"max_rows":{"type":"integer"},"updated_at":{"type":"string"},"results":{"type":"array","description":"Tabla [account_id, report_id] con header como primer row","items":{"type":"array","items":{}}},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Código de error"},"message":{"type":"string","description":"Mensaje legible (cuando aplique)"}}}},"responses":{"AuthError":{"description":"Auth inválida / headers faltantes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Método no permitido (solo POST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/accounts/bulk":{"post":{"tags":["Accounts"],"summary":"Bulk upsert (JSON) — requiere gzip","description":"Bulk JSON con `columns` + `rows`. Debe enviarse con header `Content-Encoding: gzip`. Devuelve `results` como tabla: [account_id, report_id] (primer row es header).\n","parameters":[{"$ref":"#/components/parameters/XPublicKey"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSignature"},{"name":"Content-Encoding","in":"header","required":true,"schema":{"type":"string","enum":["gzip"]},"description":"Debe ser gzip"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsBulkRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsBulkResponse"}}}},"400":{"description":"Error de validación (columns/rows)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/AuthError"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"413":{"description":"Demasiadas filas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"gzip requerido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Bulk upsert (NDJSON streaming) — requiere gzip
> Stream NDJSON comprimido en gzip.\
> \- Header HTTP obligatorio: \`Content-Encoding: gzip\` - El body, al inflarse, contiene líneas NDJSON. - La PRIMERA línea debe ser \`{ "type":"header", "columns":\[...] }\` - Luego múltiples \`{ "type":"row", "data": ... }\` - \`data\` puede ser array (en el orden de columns) o object.\
> Auth: la firma se calcula con el SHA-256 del body gzip (bytes reales).
````json
{"openapi":"3.0.3","info":{"title":"Yutax API","version":"1.0.0"},"tags":[{"name":"Accounts","description":"Alta / bulk de cuentas"}],"servers":[{"url":"https://business.yutax.net","description":"Host placeholder (cambia por tu dominio)"}],"security":[{"HmacHeaders":[]}],"components":{"securitySchemes":{"HmacHeaders":{"type":"apiKey","in":"header","name":"X-SIGNATURE","description":"Auth por headers.\nHeaders: - X-PUBLIC-KEY: public key del business (test o live) - X-TIMESTAMP: unix timestamp (string numérico) - X-NONCE: opcional - X-SIGNATURE: Base64(HMAC-SHA256(stringToSign, privateKey))\nstringToSign:\n POST\\n{path}\\n{timestamp}\\n{nonce}\\n{sha256(body)}\\n\n\nNota: en NDJSON bulk, el server usa sha256 del body gzip real.\n"}},"parameters":{"XPublicKey":{"name":"X-PUBLIC-KEY","in":"header","required":true,"schema":{"type":"string"},"description":"Public key (ej- yk_live_pk_...)"},"XTimestamp":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Unix timestamp (string numérico)"},"XNonce":{"name":"X-NONCE","in":"header","required":false,"schema":{"type":"string"},"description":"Nonce opcional"},"XSignature":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Firma HMAC base64"}},"schemas":{"AccountsBulkNdjsonResponse":{"type":"object","additionalProperties":false,"required":["ok","time","mode","gzip_required","business_id","received_rows","processed_rows","failed_rows","chunk_size","max_rows","updated_at","results","errors"],"properties":{"ok":{"type":"boolean"},"mode":{"type":"string","enum":["bulk_ndjson"]},"gzip_required":{"type":"boolean"},"business_id":{"type":"integer"},"received_rows":{"type":"integer"},"processed_rows":{"type":"integer"},"failed_rows":{"type":"integer"},"chunk_size":{"type":"integer"},"max_rows":{"type":"integer"},"updated_at":{"type":"string"},"results":{"type":"array","items":{"type":"array","items":{}}},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Código de error"},"message":{"type":"string","description":"Mensaje legible (cuando aplique)"}}}},"responses":{"AuthError":{"description":"Auth inválida / headers faltantes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Método no permitido (solo POST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/accounts/bulk_ndjson":{"post":{"tags":["Accounts"],"summary":"Bulk upsert (NDJSON streaming) — requiere gzip","description":"Stream NDJSON comprimido en gzip.\n- Header HTTP obligatorio: `Content-Encoding: gzip` - El body, al inflarse, contiene líneas NDJSON. - La PRIMERA línea debe ser `{ \"type\":\"header\", \"columns\":[...] }` - Luego múltiples `{ \"type\":\"row\", \"data\": ... }` - `data` puede ser array (en el orden de columns) o object.\nAuth: la firma se calcula con el SHA-256 del body gzip (bytes reales).\n","parameters":[{"$ref":"#/components/parameters/XPublicKey"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSignature"},{"name":"Content-Encoding","in":"header","required":true,"schema":{"type":"string","enum":["gzip"]},"description":"Debe ser gzip"}],"requestBody":{"required":true,"content":{"application/x-ndjson":{"schema":{"type":"string","description":"NDJSON (stream). \nLa primera línea debe ser `{\"type\":\"header\"...}` y luego `{\"type\":\"row\"...}`.\n\n```text\n{\"type\":\"header\",\"columns\":[\"account_id\",\"fullname\",\"ci\",\"email\",\"phone\",\"account_name\",\"account_type_id\",\"responsibility_id\",\"open_date\",\"status_id\",\"notes\"]}\n{\"type\":\"row\",\"data\":[\"ACC-001\",\"Juan Perez\",\"123\",\"juan@example.com\",\"+1555\",\"Primary\",\"1\",\"1\",\"2024-01-10\",\"1\",\"note\"]}\n{\"type\":\"row\",\"data\":{\"account_id\":\"ACC-002\",\"fullname\":\"Ana Diaz\",\"ci\":\"987\",\"phone\":\"+1666\",\"account_name\":\"Savings\",\"account_type_id\":\"4\",\"responsibility_id\":\"1\",\"open_date\":\"2023-02-01\",\"status_id\":\"1\",\"notes\":\"\"}}\n```\n"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsBulkNdjsonResponse"}}}},"400":{"description":"Stream inválido / JSON line inválida / header faltante","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/AuthError"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"413":{"description":"Demasiadas filas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"gzip requerido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
````