Documentacion API
Acceda a los datos de su aplicacion Inventory de forma programatica a traves de nuestra API externa.
Vision general
Que es la API?
La API externa proporciona una interfaz para acceder a los datos de la aplicacion Inventory desde programas externos.
Casos de uso
- Automatizacion: Procesamiento por lotes de documentos mediante scripts
- Integracion de terceros: Sincronizacion de datos con otros servicios
- Operaciones masivas: Creacion y comparticion masiva de plantillas
Primeros pasos
Obtener una clave API
Para usar la API, primero necesita una clave API.
- Abra la pantalla de Perfil en la aplicacion Inventory
- Busque la seccion Clave API
- Toque el boton Generar clave
- Su clave API se mostrara en pantalla
Importante: La clave API se muestra solo una vez cuando se genera. Asegurese de copiarla y guardarla en un lugar seguro. Si la pierde, necesitara regenerarla.
Formato de la clave API
Las claves API siguen este formato:
inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- Comienza con el prefijo
inv_ - Cadena codificada en Base64URL de aproximadamente 50 caracteres
Gestion de claves API
- Regenerar: Revoca la clave existente y emite una nueva
- Eliminar: Elimina completamente la clave API (acceso API deshabilitado)
Autenticacion
Todas las solicitudes API requieren un encabezado Authorization.
Token Bearer
Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Ejemplo de solicitud
curl -H "Authorization: Bearer inv_your_api_key" \
"https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items"
Limitacion de velocidad
El uso de la API esta sujeto a limites.
| Tipo de limite | Umbral | Descripcion |
|---|---|---|
| Por minuto | 60 solicitudes | Previene solicitudes excesivas |
| Mensual | Varia segun cuenta | Determinado por contrato |
Cuando se excede el limite
- Se devuelve el codigo de estado HTTP
429 Too Many Requests - Por favor espere e intente de nuevo mas tarde
Endpoints API
URL base
https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1
APIs de lectura (GET)
| Endpoint | Descripcion |
|---|---|
GET /items |
Listar sus articulos |
GET /items/{token} |
Obtener detalles del articulo |
GET /templates |
Listar sus plantillas |
GET /templates/{token} |
Obtener detalles de plantilla |
GET /templates/shared |
Listar plantillas compartidas |
GET /user/stats |
Obtener estadisticas de usuario |
APIs de escritura (POST)
| Endpoint | Descripcion |
|---|---|
POST /templates |
Crear nueva plantilla |
POST /templates/{token}/share |
Compartir plantilla |
POST /templates/revoke |
Revocar comparticion |
POST /templates/{token}/send |
Enviar plantilla |
Referencia API detallada
GET /items - Listar articulos
Recupera una lista de articulos (documentos) que posee.
Solicitud
curl -H "Authorization: Bearer inv_xxx" \
"https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items?page=1&pageSize=20"
Parametros de consulta
| Parametro | Tipo | Predeterminado | Descripcion |
|---|---|---|---|
| page | number | 1 | Numero de pagina |
| pageSize | number | 20 | Articulos por pagina (max 100) |
| status | string | “active” | Filtro de estado (active, pending) |
| type | string | - | Filtro de tipo (paper, stamp) |
Respuesta
{
"success": true,
"data": {
"items": [
{
"token": "id_articulo_cifrado",
"title": "Titulo del articulo",
"content": "Contenido del articulo",
"type": "paper",
"status": "active",
"imageUrl": "https://...",
"createdAt": "2025-01-01T00:00:00Z",
"updatedAt": "2025-01-01T00:00:00Z"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"totalItems": 50,
"totalPages": 3
}
}
}
POST /templates - Crear plantilla
Crea una nueva plantilla (sello).
Solicitud
curl -X POST \
-H "Authorization: Bearer inv_xxx" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/image.png",
"title": "Titulo de plantilla",
"content": "Contenido de plantilla",
"commentMode": "independent",
"keywords": ["producto:laptop", "precio:$1500EUR$"]
}' \
"https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates"
Cuerpo de solicitud
| Campo | Tipo | Requerido | Descripcion |
|---|---|---|---|
| imageUrl | string | Si | URL de imagen (HTTPS recomendado) |
| title | string | Si | Titulo (max 32 caracteres) |
| content | string | Si | Contenido (max 1024 caracteres) |
| commentMode | string | No | Modo comentario: “independent” o “shared” |
| keywords | string[] | No | Array de palabras clave (max 128) |
Formato de palabras clave
Las palabras clave deben seguir el formato clave:valor.
| Tipo | Formato | Ejemplo |
|---|---|---|
| General | clave:valor |
producto:boligrafo |
| Fecha | clave:@AAAA-MM-DD@ |
inicio:@2025-01-15@ |
| Telefono | clave:#telefono# |
contacto:#+34 612 345 678# |
| Ubicacion | clave:%direccion% |
lugar:%Madrid, Centro% |
| Monto | clave:$montoMoneda$ |
precio:$50000EUR$ |
Respuesta
{
"success": true,
"data": {
"token": "id_plantilla_cifrado",
"title": "Titulo de plantilla",
"createdAt": "2025-01-01T00:00:00Z"
}
}
POST /templates/{token}/share - Compartir plantilla
Comparte una plantilla para que otros usuarios puedan descubrirla.
Solicitud
curl -X POST \
-H "Authorization: Bearer inv_xxx" \
-H "Content-Type: application/json" \
-d '{
"durationMinutes": 1440,
"tags": ["TAG1", "TAG2"]
}' \
"https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/share"
Cuerpo de solicitud
| Campo | Tipo | Requerido | Descripcion |
|---|---|---|---|
| durationMinutes | number | Si | Duracion del compartido (minutos). 60-43200 o 0 (ilimitado) |
| tags | string[] | Si | Etiquetas de busqueda (1-16, mayusculas auto) |
Respuesta
{
"success": true,
"data": {
"shareToken": "id_compartido_cifrado",
"expiresAt": "2025-01-02T00:00:00Z",
"tags": ["TAG1", "TAG2"]
}
}
Codigos de error
Cuando una solicitud API falla, los errores se devuelven en este formato:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descripcion del error"
}
}
Lista de codigos de error
| Codigo | Estado HTTP | Descripcion |
|---|---|---|
| INVALID_API_KEY | 401 | Clave API invalida |
| API_KEY_EXPIRED | 401 | Clave API expirada |
| API_DISABLED | 403 | API deshabilitada |
| RATE_LIMIT_EXCEEDED | 429 | Limite de solicitudes excedido |
| VALIDATION_ERROR | 400 | Entrada invalida |
| INVALID_TOKEN | 400 | Token invalido |
| NOT_FOUND | 404 | Recurso no encontrado |
| FORBIDDEN | 403 | Acceso denegado |
| RECIPIENT_NOT_FOUND | 404 | Destinatario no encontrado |
Recomendaciones de seguridad
- Proteger claves API: Nunca exponer claves API en repositorios publicos o codigo cliente
- Usar HTTPS: Todas las solicitudes se transmiten via HTTPS
- Rotacion de claves: Regenerar claves API periodicamente
- Privilegio minimo: Solo realizar operaciones necesarias
Contacto
Si tiene problemas usando la API, contactenos a traves de la pagina Sugerencias.