> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fegora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción al API

> URL base, autenticación, formato de contenido y convenciones generales del API de Fegora.

El API de Fegora es **un único API** que sirve a cuentas emisoras de Guatemala, El Salvador y República Dominicana. No hay una URL ni un API distinto por país: el país lo determina la configuración fiscal de la cuenta emisora que autentica la solicitud, no la ruta ni ningún header.

## URL base

```
https://api.fegora.com
```

Todos los endpoints descritos en esta referencia son relativos a esta URL base.

## Autenticación

El API usa OAuth 2.0 (password grant) para emitir un token JWT que se envía como `Bearer` en cada llamada. Vea el detalle completo, incluida la renovación del token y el manejo de cuentas múltiples, en [Autenticación](/primeros-pasos/autenticacion).

```bash theme={null}
curl https://api.fegora.com/dte/{id} \
  -H "Authorization: Bearer {access_token}"
```

Un pequeño grupo de endpoints (por ejemplo `GET /dte/{id}`, `GET /dte/{id}/pdf`) es de acceso anónimo, ya que corresponden a enlaces públicos (el PDF de un documento, la consulta por su identificador) que se comparten con terceros.

## Formato de contenido

* Todas las solicitudes y respuestas usan `application/json`, **excepto** `POST /token`, que usa `application/x-www-form-urlencoded` (vea [Autenticación](/primeros-pasos/autenticacion)).
* Los endpoints que generan archivos (`GET /dte/{id}/pdf`, exportaciones a Excel) responden con el `Content-Type` binario correspondiente (`application/pdf`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`).
* Los nombres de campo en JSON usan `camelCase` (`idCuenta`, `fechaEmision`, `precioUnitario`, etc.).
* Los campos con valor `null` se omiten de las respuestas — si un campo no aparece, equivale a que su valor es `null`/no aplica.

## Encabezados comunes

| Header          | Uso                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer {access_token}`. Requerido en la mayoría de endpoints.                                                                             |
| `Content-Type`  | `application/json` para el cuerpo de la solicitud (excepto `POST /token`).                                                                 |
| `Accept`        | `application/json` (recomendado, aunque el API responde JSON por defecto).                                                                 |
| `X-API-Version` | Opcional. Selecciona la versión del API. Actualmente sólo existe la versión `1.0`, que es la que se usa por defecto si el header se omite. |

## Paginación

Los endpoints de listado (por ejemplo `GET /dte`, `GET /cuenta`) aceptan parámetros de consulta `pageNumber` (por defecto `1`) y `pageSize` para paginar los resultados, además de los filtros propios de cada listado (rango de fechas, tipo de documento, ambiente, etc.).

La respuesta envuelve los resultados en un sobre común:

```json theme={null}
{
  "data": [ /* elementos de la página actual */ ],
  "meta": {
    "totalItems": 134,
    "totalPages": 14,
    "pageNumber": 1,
    "pageSize": 10
  },
  "links": {
    "self": "https://api.fegora.com/dte?pageNumber=1",
    "first": "https://api.fegora.com/dte?pageNumber=1",
    "next": "https://api.fegora.com/dte?pageNumber=2",
    "prev": null,
    "last": "https://api.fegora.com/dte?pageNumber=14"
  }
}
```

## Límites de tasa

El API aplica límites de solicitudes por dirección IP: **60 solicitudes por minuto** y **1000 solicitudes por hora**. Al excederlos, el API responde `429 Too Many Requests`.

## Multi-país

El mismo API atiende cuentas de 🇬🇹 Guatemala, 🇸🇻 El Salvador y 🇩🇴 República Dominicana. El país de una cuenta emisora determina, entre otras cosas, qué campos son relevantes en el DTE, qué catálogos de impuestos y de documentos aplican, y contra qué autoridad fiscal se certifica cada documento. Vea el detalle específico de cada país en [Guatemala](/paises/guatemala), [El Salvador](/paises/el-salvador) y [República Dominicana](/paises/republica-dominicana).