Guía para Integradores
Escríbele esto a tu IA para que comience a trabajar
Lee https://docs.cachicamo.app/guia-integradores.md y con eso comienza a integrar Cachicamo App en mi proyecto.
Con ese único mensaje tu asistente de IA obtiene todo el contexto que necesita —autenticación, identificador de tienda, límites de uso y endpoints— y ya puedes comenzar a integrarlo en tu proyecto.
Descarga nuestra skill
Si trabajas con un asistente de IA en tu editor o entorno de desarrollo, puedes descargar la skill lista para usar y descomprimirla en la raíz de tu proyecto. Cada skill le indica a tu IA que es especialista en la API de Cachicamo y que consulte automáticamente la guía oficial y actualizada.
Estructura de Agent Skills (.agent/skills/) compatible con Google Antigravity y Gemini CLI / Code Assist.
Reglas de proyecto (.cursor/rules/ y .cursorrules) para el agente y asistente de Cursor.
Skill nativa en .claude/skills/ para el CLI de Claude Code y asistentes de Anthropic.
Reglas de contexto en .windsurfrules para Windsurf (Cascade).
Instrucciones de repositorio en .github/copilot-instructions.md para GitHub Copilot.
Incluye todas las estructuras anteriores en un solo archivo, ideal para equipos que combinan múltiples herramientas.
API Token
Índice
- API Token
Obtener el API Token
Para interactuar con la API de CACHICAMO, primero necesitas obtener tu API Token. Para ello:
- Inicia sesión con el usuario que va a usar la API.
- Ve a Configuración → Perfil, pestaña Seguridad (el dueño también lo encuentra en Configuración → Integraciones).
- Copia el Access Token. Con Revocar lo invalidas y se genera uno nuevo.
Cada usuario tiene su propio token y actúa con sus permisos: el del dueño puede hacer todo; el de un empleado, sólo lo que permite su rol. Todo lo que se haga con un token queda registrado a nombre de su usuario. Si vas a conectar una IA, crea un empleado para ella con un rol limitado y usa su token: así sus cambios se distinguen de los de tu personal.
Para consultar todos los enpoint disponibles puede verlo en nuestra API Reference
Autenticación con Bearer Token
Las solicitudes a la API de CACHICAMO deben incluir un API Token para la autenticación. Este token se puede enviar de dos formas:
-
En el header de la solicitud: Usando la autenticación Bearer.
Ejemplo de header:
Authorization: Bearer API_TOKEN -
En la URL: En lugar de enviarlo en el header, también se puede enviar el token en la URL del cuerpo de la solicitud.
Ejemplo de URL:
https://api.cachicamo.app/invoices?access_token=API_TOKEN
Ambas formas son válidas, pero se recomienda utilizar el header Bearer por motivos de seguridad.
Identificador de la tienda (S-ID)
Algunos endpoints de la API requieren un identificador único de la tienda, conocido como S-ID. Este identificador debe incluirse en el header de la solicitud como X-Store-Uuid.
Cómo obtener el S-ID
- Dirígete a CACHICAMO Dashboard.
- En el menú "Mis Tiendas y Almacenes", verás una lista de las tiendas asociadas a tu cuenta.
- Encuentra la tienda que deseas utilizar y haz clic en el ícono de portapapeles al lado del S-ID para copiar el identificador completo.
- El S-ID tiene el siguiente formato: 00000000-0000-0000-0000-000000000000 (un UUID).
Consultar tiendas por API (sin requerir S-ID)
También puedes consultar todas las tiendas y almacenes a los que tienes acceso mediante el endpoint GET /stores, enviando únicamente tu token de autenticación (no requiere X-Store-Uuid):
curl -H "Authorization: Bearer API_TOKEN" https://api.cachicamo.app/stores
Respuesta:
{
"owner": [
{
"uuid": "00000000-0000-0000-0000-000000000000",
"name": "Tienda Principal",
"is_depot": false
}
],
"employee": []
}
El campo uuid de cada tienda o almacén devuelto es el identificador que debes enviar como S-ID (X-Store-Uuid).
- En el header de la solicitud: Este S-ID debe ser enviado en el header de la solicitud como sigue:
X-Store-Uuid: 00000000-0000-0000-0000-000000000000
- En la URL: En lugar de enviarlo en el header, también se puede enviar el S-ID en la URL del cuerpo de la solicitud.
Ejemplo de URL:
https://api.cachicamo.app/invoices?access_token=API_TOKEN&store_uuid=00000000-0000-0000-0000-000000000000
Ambas formas son válidas, pero se recomienda utilizar el header por motivos de seguridad.
Asegúrate de utilizar el S-ID correcto al realizar las solicitudes a la API que requieren este identificador.
Consultas a la API
La API de CACHICAMO utiliza tecnología API REST, que es un conjunto de convenciones y principios para la comunicación entre sistemas mediante HTTP. Esta tecnología es ampliamente utilizada por su simplicidad y flexibilidad. En REST, los recursos se identifican mediante URLs y las operaciones se realizan utilizando los métodos HTTP estándar.
Métodos CRUD
- GET: Obtener datos del servidor.
- POST: Crear nuevos recursos.
- PUT: Actualizar recursos existentes.
- DELETE: Eliminar recursos.
Ejemplos con cURL
- GET (Obtener datos)
curl -X GET "https://api.cachicamo.app/ENDPOINT" -H "Authorization: Bearer <API_TOKEN>"
- POST (Crear un recurso)
curl -X POST "https://api.cachicamo.app/ENDPOINT" -H "Authorization: Bearer <API_TOKEN>" -d '{ ... }'
- PUT (Actualizar un recurso)
curl -X PUT "https://api.cachicamo.app/ENDPOINT/123" -H "Authorization: Bearer <API_TOKEN>" -d '{ ... }'
- DELETE (Eliminar un recurso)
curl -X DELETE "https://api.cachicamo.app/ENDPOINT/123" -H "Authorization: Bearer <API_TOKEN>"
Limiter en la API
La API de CACHICAMO aplica un sistema de límites para gestionar la cantidad de solicitudes permitidas por token en un período de tiempo determinado. Este mecanismo asegura un uso justo y eficiente de los recursos del sistema.
Límites por tipo de solicitud
- GET: Máximo de 120 solicitudes por minuto.
- POST: Máximo de 80 solicitudes por minuto.
- Otros métodos (PUT, DELETE): Máximo de 20 solicitudes por minuto.
Los límites se cuentan por token, o por dirección IP cuando la solicitud no lleva token. Existe además un techo general de 100 solicitudes por segundo por dirección IP.
Al agotar el cupo la API responde 429 Too Many Requests con el cuerpo {"error": "Rate limit exceeded"}.
Headers de respuesta
Cada respuesta de la API incluye información en los headers para indicar cuántas solicitudes puedes realizar antes de alcanzar el límite:
X-RateLimit-Post-Remaining: Número de solicitudes POST restantes en el período actual.X-RateLimit-Get-Remaining: Número de solicitudes GET restantes en el período actual.X-RateLimit-Other-Remaining: Número de solicitudes de otros métodos restantes en el período actual.
Ejemplo de headers
HTTP/1.1 200 OK
X-RateLimit-Post-Remaining: 77
X-RateLimit-Get-Remaining: 115
X-RateLimit-Other-Remaining: 15
Ejemplos de uso de la API
PHP
<?php
$api_token = 'tu_api_token_aqui';
$s_id = '00000000-0000-0000-0000-000000000000';
$api_url = 'https://api.cachicamo.app/invoices';
// Inicializar cURL
$ch = curl_init($api_url);
// Configurar los parámetros de la solicitud
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $api_token",
"X-Store-Uuid: Bearer $s_id"
]);
// Ejecutar la solicitud y obtener la respuesta
$response = curl_exec($ch);
// Verificar errores
if(curl_errno($ch)) {
echo 'Error:' . curl_error($ch);
}
curl_close($ch);
// Procesar la respuesta
echo $response;
JavaScript
const apiToken = 'tu_api_token_aqui';
const storeId = '00000000-0000-0000-0000-000000000000';
const apiUrl = 'https://api.cachicamo.app/invoices';
fetch(apiUrl, {
method: 'GET',
headers: {
'Authorization': `Bearer ${apiToken}`,
'X-Store-Uuid': storeId
}
})
.then(response => response.json())
.then(data => {
console.log(data);
})
.catch(error => {
console.error('Error:', error);
});
Java
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.BufferedReader;
public class CACHICAMOAPI {
public static void main(String[] args) {
try {
String apiToken = "tu_api_token_aqui";
String storeId = "00000000-0000-0000-0000-000000000000";
String apiUrl = "https://api.cachicamo.app/invoices";
URL url = new URL(apiUrl);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", "Bearer " + apiToken);
connection.setRequestProperty("X-Store-Uuid", storeId);
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
} catch (Exception e) {
e.printStackTrace();
}
}
}
Go
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiToken := "tu_api_token_aqui"
storeId := "00000000-0000-0000-0000-000000000000"
apiUrl := "https://api.cachicamo.app/invoices"
// Crear una solicitud GET
req, err := http.NewRequest("GET", apiUrl, nil)
if err != nil {
fmt.Println(err)
return
}
// Agregar el encabezado de autorización
req.Header.Add("Authorization", "Bearer "+apiToken)
req.Header.Add("X-Store-Uuid", storeId)
// Hacer la solicitud
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
// Leer la respuesta
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
CSharp
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
// URL de la API
string url = "https://api.cachicamo.app/invoices";
// API Token
string apiToken = "TU_API_TOKEN_AQUÍ"; // Reemplaza con tu API Token
// S-ID (Identificador de la tienda)
string storeId = "00000000-0000-0000-0000-000000000000"; // Reemplaza con tu S-ID
// Crea un cliente HTTP
using (HttpClient client = new HttpClient())
{
// Agrega el header Authorization con Bearer Token
client.DefaultRequestHeaders.Add("Authorization", "Bearer " + apiToken);
// Agrega el header X-Store-Uuid con el S-ID
client.DefaultRequestHeaders.Add("X-Store-Uuid", storeId);
// Realiza la solicitud GET
HttpResponseMessage response = await client.GetAsync(url);
// Verifica si la solicitud fue exitosa
if (response.IsSuccessStatusCode)
{
string responseData = await response.Content.ReadAsStringAsync();
Console.WriteLine("Respuesta exitosa: ");
Console.WriteLine(responseData);
}
else
{
Console.WriteLine("Error: " + response.StatusCode);
}
}
}
}
Conclusión
La API de CACHICAMO permite interactuar con el sistema de forma sencilla y segura. Asegúrate de obtener tu API Token desde el menú de Integraciones y utilizarlo para autenticar tus peticiones. Los ejemplos anteriores te permitirán hacer consultas a la API utilizando diferentes lenguajes de programación.
Si tienes dudas o necesitas más información sobre cómo utilizar la API, no dudes en contactarnos.