Guía de inicio

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 📋

DatoDescripciónOrigen
usernameUsuario de tu cuenta de Fidel.Administración de usuarios del sistema.
passwordContraseña de ese usuario.Ídem.
accountIdentificador de la cuenta (empresa) en Fidel. Valor fijo.Solicitar a Soporte.
🚧

Usá un usuario dedicado a la integración

No 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ámetroRequeridoValor
grant_typeSíConstante password.
usernameSíUsuario de Fidel.
passwordSíContraseña del usuario.
accountSí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 token

Solicitar 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

HeaderValor
AuthorizationBearer + espacio + access_token.
accountIdentificador 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
done

Dos 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ámetroDefaultDescripción
page1Número de página.
pageSize50Registros por página. Una petición de 200 registros consume un cuarto de la cuota que cuatro peticiones de 50.
orderBy+IDCampo de ordenamiento. Prefijo + ascendente, - descendente (ej.: -ID).

La respuesta incluye además estos headers:

HeaderContenido
total-recordsTotal de registros que cumplen el filtro. Permite calcular la cantidad de páginas sin iterar a ciegas.
linkEnlaces 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.

EntornoURL baseUso
Pruebashttps://dev.integraciones.fidel.com.ar/apiDesarrollo e integración, con datos ficticios.
Producciónhttps://integraciones.fidel.com.ar/apiOperación real.
⚠️

Desarrollá contra el entorno de pruebas

Los endpoints de escritura impactan datos reales. Un POST /api/orders mal construido contra producción genera pedidos que después hay que anular manualmente.

📘

Probá desde esta documentación

Cada endpoint incluye un panel donde cargás el token y el account y ejecutás la petición en el momento, útil para inspeccionar el esquema de respuesta antes de programar contra él.

Errores comunes 🛠️

CódigoCausa típicaResolució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 RequestPará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 UnauthorizedToken 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 FoundRecurso 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 RequestsSe superó el límite de peticiones.Reintentar con espera creciente. Ver Rate Limit.
500 Internal Server ErrorError 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 ⚠️

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.