Obtené el token, hacé tu primera consulta y conocé el formato de las respuestas.
Dos peticiones separan una cuenta de Fidel del primer dato consumido por código: una para obtener el token, otra para consultar un endpoint.
Requisitos previos 📋
| Dato | Descripción | Origen |
|---|---|---|
username | Usuario de tu cuenta de Fidel. | Administración de usuarios del sistema. |
password | Contraseña de ese usuario. | Ídem. |
account | Identificador de la cuenta (empresa) en Fidel. Valor fijo. | Solicitar a Soporte. |
Usá un usuario dedicado a la integraciónNo utilices las credenciales de un usuario nominal. Un cambio de contraseña o una baja de personal interrumpe la integración sin aviso.
Las tres credenciales dan acceso a los datos de la empresa: almacenalas en la configuración del servidor, nunca en código de frontend, repositorios ni capturas de pantalla.
Paso 1: obtener el token 🔑
Petición
curl -X POST "{{URL_BASE}}/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "username=TU_USUARIO" \
-d "password=TU_CONTRASEÑA" \
-d "account=TU_ACCOUNT"Parámetros (application/x-www-form-urlencoded)
| Parámetro | Requerido | Valor |
|---|---|---|
grant_type | Sí | Constante password. |
username | Sí | Usuario de Fidel. |
password | Sí | Contraseña del usuario. |
account | Sí | Identificador de la cuenta. |
Respuesta 200 OK
{
"access_token": "AbC1dEf2GhI3...",
"token_type": "bearer",
"expires_in": 86399
}expires_in se expresa en segundos: 86399 ≈ 24 horas.
Cacheá el tokenSolicitar un token por cada consulta es el error más frecuente en integraciones nuevas: agrega latencia, duplica el tráfico y consume cuota de peticiones sin necesidad.
Obtené un token, reutilizalo durante su vigencia y renovalo únicamente cuando esté por vencer o cuando la API responda
401.
Paso 2: consumir un endpoint 📡
curl -X GET "{{URL_BASE}}/api/products?page=1&pageSize=50" \
-H "Authorization: Bearer AbC1dEf2GhI3..." \
-H "account: TU_ACCOUNT"Headers requeridos en todas las peticiones
| Header | Valor |
|---|---|
Authorization | Bearer + espacio + access_token. |
account | Identificador de la cuenta, el mismo utilizado para obtener el token. |
El resto de los endpoints sigue exactamente el mismo patrón: cambia la ruta y los parámetros, no la autenticación.
Quickstart completo ⚡
Script ejecutable que obtiene el token, consulta la primera página de productos y recorre el catálogo completo respetando la paginación. Reemplazá las cuatro variables iniciales.
#!/bin/bash
# Quickstart API de Fidel — token, consulta y paginación
BASE_URL="{{URL_BASE}}"
USUARIO="TU_USUARIO"
PASSWORD="TU_CONTRASEÑA"
ACCOUNT="TU_ACCOUNT"
# 1. Token (una sola vez: es válido por 24 hs)
TOKEN=$(curl -s -X POST "$BASE_URL/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "username=$USUARIO" \
-d "password=$PASSWORD" \
-d "account=$ACCOUNT" | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
if [ -z "$TOKEN" ]; then
echo "Error: no se obtuvo el token. Verificar username, password y account."
exit 1
fi
# 2. Primera página. Se capturan los headers de respuesta con -D
PAGE_SIZE=200
curl -s -D headers.txt -X GET \
"$BASE_URL/api/products?page=1&pageSize=$PAGE_SIZE" \
-H "Authorization: Bearer $TOKEN" \
-H "account: $ACCOUNT" > pagina-1.json
# 3. El header total-records indica el total de registros del listado
TOTAL=$(grep -i "^total-records:" headers.txt | tr -d '\r' | cut -d' ' -f2)
PAGINAS=$(( ($TOTAL + $PAGE_SIZE - 1) / $PAGE_SIZE ))
echo "$TOTAL registros en $PAGINAS páginas."
# 4. Páginas restantes, con pausa entre peticiones
for (( PAGINA=2; PAGINA<=$PAGINAS; PAGINA++ )); do
echo "Página $PAGINA/$PAGINAS"
curl -s -X GET \
"$BASE_URL/api/products?page=$PAGINA&pageSize=$PAGE_SIZE" \
-H "Authorization: Bearer $TOKEN" \
-H "account: $ACCOUNT" > "pagina-$PAGINA.json"
sleep 1
doneDos decisiones del script son deliberadas: el token se solicita una sola vez y hay un sleep entre página y página. El motivo está explicado en Rate Limit.
Formato de las respuestas 📐
Todas las respuestas son JSON con las propiedades en camelCase y codificación UTF-8.
Paginación 📄
Los listados se devuelven paginados y se controlan por query string:
| Parámetro | Default | Descripción |
|---|---|---|
page | 1 | Número de página. |
pageSize | 50 | Registros por página. Una petición de 200 registros consume un cuarto de la cuota que cuatro peticiones de 50. |
orderBy | +ID | Campo de ordenamiento. Prefijo + ascendente, - descendente (ej.: -ID). |
La respuesta incluye además estos headers:
| Header | Contenido |
|---|---|
total-records | Total de registros que cumplen el filtro. Permite calcular la cantidad de páginas sin iterar a ciegas. |
link | Enlaces a la página anterior (rel="prev") y a la última (rel="last"). |
Entornos 💻
Ambos entornos exponen los mismos endpoints. Difieren únicamente en la URL base y las credenciales.
| Entorno | URL base | Uso |
|---|---|---|
| Pruebas | https://dev.integraciones.fidel.com.ar/api | Desarrollo e integración, con datos ficticios. |
| Producción | https://integraciones.fidel.com.ar/api | Operación real. |
Desarrollá contra el entorno de pruebasLos endpoints de escritura impactan datos reales. Un
POST /api/ordersmal construido contra producción genera pedidos que después hay que anular manualmente.
Probá desde esta documentaciónCada endpoint incluye un panel donde cargás el token y el
accounty ejecutás la petición en el momento, útil para inspeccionar el esquema de respuesta antes de programar contra él.
Errores comunes 🛠️
| Código | Causa típica | Resolución |
|---|---|---|
400 + "error": "invalid_grant" | Credenciales incorrectas al solicitar el token. | Verificar username, password y account. El account es el parámetro que más se omite: sin él la API no puede resolver a qué cuenta pertenece el usuario. |
400 Bad Request | Parámetro obligatorio ausente o con formato inválido. | El cuerpo de la respuesta indica el campo. Prestar atención al formato de fechas y decimales. |
401 Unauthorized | Token ausente, mal formado o vencido. | Verificar que el header incluya el prefijo Bearer con el espacio. Si el formato es correcto, solicitar un token nuevo: probablemente superó las 24 horas. |
404 Not Found | Recurso inexistente o ruta mal escrita. | Antes de asumir que el registro no existe, validar la URL: /api/product en singular devuelve 404 igual que un id inexistente. |
429 Too Many Requests | Se superó el límite de peticiones. | Reintentar con espera creciente. Ver Rate Limit. |
500 Internal Server Error | Error del lado del servidor. | Reintentar en bucle no lo resuelve. Si persiste, reportar a soporte con la URL, el horario y el cuerpo de la petición. |
Próximamente: X-API-KEY ⚠️
X-API-KEY ⚠️Se está incorporando un header adicional, X-API-KEY, que identifica a la integración además del token de acceso.
Todavía no es obligatorio y su activación se comunicará con anticipación. Recomendación aplicable desde hoy: definí los headers como parámetros de configuración y no como valores fijos en el código, de modo que activarlo no requiera un nuevo despliegue. El detalle está en Rate Limit.
