Autenticación API

La API utiliza autenticación JWT combinada con API Key para todas las peticiones.

⚙

Este contenido es técnico y está pensado para el equipo que integra tu sistema con Frande ECF. Como cliente emisor no necesitas hacer nada aquí: tu proveedor o desarrollador se encarga. Si integras por tu cuenta, cámbiate a la vista Desarrollador arriba.

Flujo de autenticación

Envía tus credenciales al endpoint de autenticación
Recibe un accessToken, idToken y refreshToken
Usa el accessToken en el header Authorization de tus peticiones
Cuando expire, usa el refreshToken para obtener nuevos tokens

Endpoint de autenticación

POST /{env}/customer/authentication

Headers requeridos

Header	Valor	Descripción
`Content-Type`	`application/json`	Tipo de contenido
`Authorization`	`Basic base64(email:password)`	Credenciales en Base64
`X-API-KEY`	`ecf_sk_...`	Tu API Key

Ejemplos

curl -X POST https://ecf.frandeone.com/TesteCF/customer/authentication \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n '[email protected]:MiPassword123' | base64)" \
  -H "X-API-KEY: ecf_sk_a1b2c3d4e5f6..."

const credentials = btoa('[email protected]:MiPassword123');

const response = await fetch('https://ecf.frandeone.com/TesteCF/customer/authentication', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${credentials}`,
    'X-API-KEY': 'ecf_sk_a1b2c3d4e5f6...'
  }
});

const data = await response.json();
console.log(data.data.accessToken);
// Guardar tokens para futuras peticiones

$credentials = base64_encode('[email protected]:MiPassword123');

$ch = curl_init('https://ecf.frandeone.com/TesteCF/customer/authentication');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "Authorization: Basic {$credentials}",
        'X-API-KEY: ecf_sk_a1b2c3d4e5f6...'
    ]
]);

$response = json_decode(curl_exec($ch), true);
$accessToken = $response['data']['accessToken'];
curl_close($ch);

using var client = new HttpClient();
var credentials = Convert.ToBase64String(
    Encoding.UTF8.GetBytes("[email protected]:MiPassword123"));

client.DefaultRequestHeaders.Add("Authorization", $"Basic {credentials}");
client.DefaultRequestHeaders.Add("X-API-KEY", "ecf_sk_a1b2c3d4e5f6...");

var response = await client.PostAsync(
    "https://ecf.frandeone.com/TesteCF/customer/authentication",
    new StringContent("", Encoding.UTF8, "application/json"));

var json = await response.Content.ReadAsStringAsync();
// Parsear el accessToken del JSON

Respuesta exitosa

200 OK

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "idToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

Usar el token en peticiones

Incluye el accessToken en el header Authorization de todas las peticiones:

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-API-KEY: ecf_sk_a1b2c3d4e5f6...

Refresh token

Cuando el accessToken expire (por defecto 1 hora), usa el refreshToken para obtener nuevos tokens sin re-autenticarte:

POST /{env}/customer/refresh

cURL

curl -X POST https://ecf.frandeone.com/TesteCF/customer/refresh \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ecf_sk_a1b2c3d4e5f6..." \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiIs..."}'

💡

Implementa la lógica de refresh automáticamente en tu cliente HTTP. Si recibes un 401 Unauthorized, intenta refrescar el token antes de reintentar la petición.

Errores comunes

Código	Error	Solución
`401`	Credenciales inválidas	Verifica email, password y que el Base64 esté correcto
`401`	Token expirado	Usa el refresh token para obtener nuevos tokens
`403`	API Key inválida	Verifica tu API Key en el header X-API-KEY
`429`	Rate limit excedido	Espera el tiempo indicado en el header Retry-After