Subir Documento
curl --request POST \
--url http://api.gu1.ai/documents/upload \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": "<string>",
"categoryId": "<string>"
}
'import requests
url = "http://api.gu1.ai/documents/upload"
payload = {
"entityId": "<string>",
"categoryId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({entityId: '<string>', categoryId: '<string>'})
};
fetch('http://api.gu1.ai/documents/upload', 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/documents/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => '<string>',
'categoryId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/documents/upload"
payload := strings.NewReader("{\n \"entityId\": \"<string>\",\n \"categoryId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/documents/upload")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": \"<string>\",\n \"categoryId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/documents/upload")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": \"<string>\",\n \"categoryId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"400": {},
"401": {},
"500": {},
"id": "<string>",
"name": "<string>",
"originalFileName": "<string>",
"fileSize": 123,
"mimeType": "<string>",
"storagePath": "<string>",
"storageProvider": "<string>",
"categoryId": "<string>",
"organizationId": "<string>",
"createdAt": {}
}Referencia API
Subir Documento
Sube un documento y opcionalmente asócialo con una entidad y categoría — en la plataforma gu1 para KYC, KYB y evidencia de compliance.
POST
/
documents
/
upload
Subir Documento
curl --request POST \
--url http://api.gu1.ai/documents/upload \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": "<string>",
"categoryId": "<string>"
}
'import requests
url = "http://api.gu1.ai/documents/upload"
payload = {
"entityId": "<string>",
"categoryId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({entityId: '<string>', categoryId: '<string>'})
};
fetch('http://api.gu1.ai/documents/upload', 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/documents/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => '<string>',
'categoryId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/documents/upload"
payload := strings.NewReader("{\n \"entityId\": \"<string>\",\n \"categoryId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/documents/upload")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": \"<string>\",\n \"categoryId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/documents/upload")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": \"<string>\",\n \"categoryId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"400": {},
"401": {},
"500": {},
"id": "<string>",
"name": "<string>",
"originalFileName": "<string>",
"fileSize": 123,
"mimeType": "<string>",
"storagePath": "<string>",
"storageProvider": "<string>",
"categoryId": "<string>",
"organizationId": "<string>",
"createdAt": {}
}Sube archivos asociados a entidades usando multipart/form-data.
Categorías comunes incluyen:
Autenticación
Este endpoint requiere autenticación mediante token Bearer y contexto de organización. Headers Requeridos:Authorization: Bearer <jwt-token>X-Organization-ID: <organization-id>
Parámetros del Form Data
File
required
El archivo a subir (cualquier tipo soportado)
UUID
ID de la entidad a la que asociar el documento
UUID
ID de la categoría del documento (UBO, Representante Legal, Corporativo, etc.)
Ejemplo de Request
curl -X POST https://api.gu1.ai/documents/upload \
-H "Authorization: Bearer TU_JWT_TOKEN" \
-H "X-Organization-ID: TU_ORG_ID" \
-F "file=@/ruta/al/documento.pdf" \
-F "entityId=bb0c2d24-b519-40ec-b765-86de831ca0af" \
-F "categoryId=c5e9a3f2-1234-5678-9abc-def012345678"
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('entityId', 'bb0c2d24-b519-40ec-b765-86de831ca0af');
formData.append('categoryId', 'c5e9a3f2-1234-5678-9abc-def012345678');
const response = await fetch('https://api.gu1.ai/documents/upload', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'X-Organization-ID': organizationId
},
body: formData
});
const document = await response.json();
import requests
files = {'file': open('/ruta/al/documento.pdf', 'rb')}
data = {
'entityId': 'bb0c2d24-b519-40ec-b765-86de831ca0af',
'categoryId': 'c5e9a3f2-1234-5678-9abc-def012345678'
}
response = requests.post(
'https://api.gu1.ai/documents/upload',
headers={
'Authorization': f'Bearer {token}',
'X-Organization-ID': org_id
},
files=files,
data=data
)
document = response.json()
Respuesta
UUID
Identificador único del documento
string
Nombre del documento
string
Nombre original del archivo subido
number
Tamaño del archivo en bytes
string
Tipo MIME del archivo
string
Ruta donde se almacena el archivo (clave S3 o ruta local)
string
Proveedor de almacenamiento usado (‘s3’ o ‘local’)
UUID
ID de la categoría del documento (si se asignó)
UUID
ID de la organización propietaria del documento
timestamp
Fecha de creación del documento
Ejemplo de Respuesta
{
"id": "d7f8e9c0-1234-5678-9abc-def012345678",
"name": "document.pdf",
"description": "Documento subido: document.pdf",
"type": "other",
"fileName": "1730649606123_document.pdf",
"originalFileName": "document.pdf",
"fileSize": 245678,
"mimeType": "application/pdf",
"fileExtension": "pdf",
"storagePath": "/uploads/1730649606123_document.pdf",
"storageProvider": "local",
"securityLevel": "internal",
"categoryId": "c5e9a3f2-1234-5678-9abc-def012345678",
"organizationId": "24236b0a-e34d-4218-b3d2-76b101ce8aa9",
"createdBy": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"createdAt": "2025-11-03T15:30:45.123Z",
"updatedAt": "2025-11-03T15:30:45.123Z"
}
Qué Sucede Después de la Subida
- Almacenamiento: El archivo se sube a S3 (si está habilitado) o almacenamiento local
- Registro en Base de Datos: Se crea el registro del documento en la base de datos
- Versionamiento: Se crea automáticamente la versión inicial (v1)
- Relación con Entidad: Si se proporciona
entityId, se crea la relación automáticamente - Análisis de Riesgo: Se activa el análisis automático de riesgo si hay reglas configuradas
Tipos de Archivo Soportados
- Documentos: PDF, DOC, DOCX, TXT
- Imágenes: PNG, JPG, JPEG, GIF
- Hojas de Cálculo: XLS, XLSX, CSV
- Otros: Cualquier tipo de archivo
Categorías de Documentos
Para obtener las categorías disponibles, usa:GET /documents/categories
- UBO (Beneficiario Final)
- Representante Legal
- Documentos Corporativos
- Debida Diligencia Reforzada
Respuestas de Error
error
Bad Request - Falta archivo o autenticación
{
"error": "No file provided"
}
error
No Autorizado - Token inválido
{
"error": "Unauthorized - No token provided"
}
error
Error Interno del Servidor
{
"error": "Error interno del servidor",
"details": "Mensaje de error aquí"
}
Notas
El sistema detecta automáticamente si el almacenamiento S3 está configurado y lo usa, de lo contrario usa almacenamiento local.
El tamaño máximo del archivo depende de la configuración del servidor (típicamente 50MB).
Incluso si
entityId o categoryId no existen, el documento se creará de todos modos. La relación o asignación de categoría simplemente se omitirá.Was this page helpful?