Autenticación

Para acceder a los recursos de la API, es necesario autenticar todas las solicitudes HTTP. En esta guía, explicamos cómo funciona la autenticación en fiscalapi. La API ofrece dos esquemas de autenticación: JWT bearer tokens y api-key.

Encabezados http requeridos

Para autenticar sus solicitudes HTTP, debe incluir los siguientes encabezados en todas las solicitudes después del inicio de sesión o la obtención de la api-key:

X-TENANT-KEY: Requerido en todas las solicitudes. Representa el identificador único de su cuenta en FiscalAPI. Consulte Obtener tus credenciales para generar su tenant-key.
X-API-KEY: Requerido en todas las solicitudes cuando se utiliza el esquema de autenticación api-key. Representa la clave de la API utilizada para autenticar la solicitud. Consulte Obtener tus credenciales para generar su api-key.
Authorization: Bearer: Requerido en todas las solicitudes cuando se utiliza el esquema de autenticación JWT bearer. Representa el token JWT obtenido al iniciar sesión. Siga leyendo para aprender cómo obtener un JWT Token.

Nota: Los encabezados X-API-KEY y Authorization: Bearer son mutuamente excluyentes, ya que cada uno corresponde a un esquema de autenticación diferente. Asegúrese de incluir únicamente uno de estos encabezados en sus solicitudes HTTP.

JSON Web Tokens (JWT)

La autenticación con JWT Bearer permite utilizar su correo electrónico y contraseña para obtener un token JWT, el cual se emplea para autenticar todas las solicitudes HTTP subsiguientes. A continuación, se muestra un ejemplo de cómo realizar la autenticación utilizando cURL:

Solicitud de inicio de sesión

Login request

POST

/api/v4/account/login

curl --location 'https://test.fiscalapi.com/api/v4/account/login' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "someone@somewhere.com",
  "password": "yourStrongPassword"
}'

Respuesta de inicio de sesión

El servidor responderá con un token JWT que debe incluir en el encabezado de todas las solicitudes futuras. La propiedad accessToken contiene el JWT Bearer token, mientras que refreshToken proporciona un token de actualización. A continuación, se muestra un ejemplo de la respuesta para la solicitud anterior. ver el módelo de respuestas fiscalapi .

Login response

{
  "data": {
    "tokenType": "JWT Bearer",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6Ijk2ZWFhNmU1LTZlNjctNGNmMS1hOTYyLTA3Y2YxNWFmM2YwZSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcyI6Im1yc29wb3J0ZWNlbEBnbWFpbC5jb20iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiT1NDQVIgS0FMQSBIQUFLIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvY3VzdG9tZXIiOiJjdXNfUkM2V2xQNEdQaVVBREMiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3JvbGUiOlsiRGV2IiwiVXNlciJdLCJleHAiOjE3MzEzMzkyMzIsImlzcyI6IkZpc2NhbEFQSSIsImF1ZCI6IkZpc2NhbEFQSSJ9.9fS4tPWquAZrYoKJR_MrMBYpNNcAzTTVJVR_aFXvKoE",
    "expiresIn": 3600,
    "refreshToken": "287e52cc-b2bc-4cca-a8e6-b6cd002890e2",
    "tenantId": "494a5958-0993-4a53-972e-f3b51e16358d",
    "userId": "96eaa6e5-6e67-4cf1-a962-07cf15af3f0e"
  },
  "succeeded": true,
  "message": "",
  "details": "",
  "httpStatusCode": 200
}

Accediendo a un recurso protegido con JWT Bearer Token

Para acceder a un recurso protegido utilizando un JWT Bearer Token, incluya su token en el encabezado de la solicitud HTTP. A continuación, se muestra un ejemplo de cómo obtener una factura (invoice) con el id=b240558b-6e97-4e35-bc51-68f4ca3be324. En este caso, también se incluye el parámetro details=true para recuperar los objetos relacionados con la factura.

Cuando utiliza el query param details=true, la respuesta incluirá los siguientes objetos adicionales:

invoiceIssuer: Detalles del emisor de la factura.
invoiceRecipient: Detalles del receptor de la factura.
invoiceResponses: Contiene toda la información fiscal relacionada con el timbrado en el SAT.

Obtener factura por id

GET

/api/v4/invoices/{id}?details=true

curl --location 'https://test.fiscalapi.com/api/v4/invoices/b240558b-6e97-4e35-bc51-68f4ca3be324?details=true' \
--header 'X-TENANT-KEY: your_tenant_key_value' \
--header 'Authorization: Bearer your_jwt_token_value' \
--data ''

API Key

La autenticación mediante API Key es la forma automatizada de autenticar sus solicitudes HTTP en FiscalAPI. Este esquema de autenticación es especialmente recomendado para integraciones entre sistemas (automatizaciones), ya que una api-key no requiere renovación y no expira, a diferencia de los tokens JWT.

Características clave:

Uso continuo: Ideal para procesos automáticos que necesitan acceso constante a la API.
Seguridad: Asegúrese de mantener su api-key segura, ya que permite acceso directo a los recursos protegidos.
Simplificación: No requiere la gestión de sesiones ni la renovación de tokens.

Lea la documentación de inicio rápido para saber como generar una apikey

Importante: Todas las API Keys estarán activas hasta que usted las revoque explícitamente desde el dashboard. Es fundamental almacenar sus API Keys en un lugar seguro y tratarlas como secretos de aplicación. Si sospecha que alguna de sus API Keys ha sido comprometida, revoquela de inmediato para proteger el acceso a sus recursos.

Accediendo a un recurso protegido con API Key

Para acceder a un recurso protegido utilizando una api-key, incluya su API Key en el encabezado de la solicitud HTTP. A continuación, se muestra un ejemplo de cómo obtener una factura (invoice) con el id=b240558b-6e97-4e35-bc51-68f4ca3be324. También se incluye el parámetro details=true para recuperar los objetos relacionados con la factura.

Cuando utiliza el query param details=true, la respuesta incluirá los siguientes objetos adicionales:

invoiceIssuer: Detalles del emisor de la factura.
invoiceRecipient: Detalles del receptor de la factura.
invoiceResponses: Contiene toda la información fiscal relacionada con el timbrado en el SAT.

Obtener factura por id

GET

/api/v4/invoices/{id}?details=true

curl --location 'https://test.fiscalapi.com/api/v4/invoices/b240558b-6e97-4e35-bc51-68f4ca3be324?details=true' \
--header 'X-TENANT-KEY: your_tenant_key_value' \
--header 'X-API-KEY: sk_test_221c25d5...' \
--data ''

Usando un SDK

Si utiliza uno de nuestros SDKs oficiales, no tendrá que preocuparse por manejar directamente la autenticación o los encabezados requeridos. La biblioteca se encarga automáticamente de estas tareas detrás de cámaras, simplificando la integración con fiscalapi.

Ventajas de usar un SDK:

Gestión automatizada: La autenticación, renovación de tokens y manejo de encabezados se realizan de forma transparente.
Facilidad de uso: Métodos predefinidos que simplifican las solicitudes a la API.
Mejor mantenimiento: Los SDKs se actualizan regularmente para garantizar compatibilidad y seguridad.

Consulte nuestra lista de SDKs oficiales para obtener más información