> ## 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.

# Proveedores

> El catálogo de proveedores de su Cuenta, que Fegora construye automáticamente a partir de los documentos que usted recibe, y cómo consultarlo desde el API.

Cada documento tributario que su Cuenta **recibe** lo emite alguien: un proveedor. Fegora registra a ese emisor automáticamente en un catálogo por Cuenta, de modo que pueda listar a sus proveedores, ver el último documento de cada uno y cuánto le ha comprado, sin tener que recorrer documento por documento.

<Note>
  El catálogo de proveedores se alimenta de documentos **recibidos** (`/recibidos/dte`). Es el espejo del catálogo de clientes, que se alimenta de los documentos que su Cuenta **emite**.
</Note>

## Cómo se llena

No hay que dar de alta nada a mano: cuando entra un documento recibido, Fegora busca al emisor en el catálogo y lo crea si no existía, actualiza sus datos de contacto y dirección, y suma el documento a sus contadores.

También puede registrar un proveedor explícitamente con `POST /proveedor` — útil para un proveedor al que le registra gastos antes de recibir su primer documento.

<Note>
  El registro automático es **best-effort**: nunca afecta al documento. Si el catálogo falla por cualquier razón, el documento recibido se almacena igual.
</Note>

## Identificación fiscal opcional

A diferencia de otros catálogos, un proveedor **no necesita identificación fiscal**. Es deliberado: un gasto en el extranjero — un boleto de avión, un alojamiento, un servicio en la nube — no corresponde a un documento fiscal de ningún fisco de la región y no trae NIT, RNC ni DUI.

| Campo          | Descripción                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------- |
| `idFiscal`     | La identificación tal como venía en el documento, con separadores. Puede ser nula.            |
| `tipoIdFiscal` | Tipo de identificación: `NIT`, `RNC`, `DUI`, `VAT`, `EIN`, `NINGUNO`… El conjunto es abierto. |
| `sinIdFiscal`  | `true` cuando el proveedor no tiene identificación fiscal utilizable.                         |

Como el nombre no es una identidad, **pueden aparecer duplicados** en ese caso (por ejemplo el mismo servicio escrito de dos maneras). Eso se resuelve con [fusión](#fusionar-duplicados), no rechazando el segundo registro.

## Los montos van por moneda

Un proveedor no acumula un total único: acumula **un total por cada moneda** en la que le ha facturado.

```json theme={null}
{
  "cantidadDocumentos": 148,
  "montosPorMoneda": {
    "GTQ": 84210.500000,
    "USD": 1920.000000
  },
  "monedaUltimoDocumento": "GTQ",
  "montoUltimoDocumento": 1250.000000
}
```

<Warning>
  No sume los valores de `montosPorMoneda` entre sí — son monedas distintas y el resultado no significa nada. Si necesita una cifra única, elija una moneda o convierta usted con el tipo de cambio que corresponda a cada fecha.
</Warning>

Los contadores son una **caché de conveniencia, no contabilidad**: incluyen notas de crédito sin signo y no se descuentan cuando un documento se anula después. Para cualquier cifra fiscal o financiera, consulte los documentos.

## Sucursales del proveedor

Un proveedor puede facturarle desde varios establecimientos, cada uno con su propia dirección y su propio nombre comercial. Fegora los deriva del documento, así que también aparecen sin configuración alguna.

```
GET /proveedor/{id}/sucursal
```

La respuesta es paginada. Conviene que lo sea: un proveedor grande puede tener cientos de establecimientos.

| Campo                                                            | Descripción                                                                       |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `codigoEstablecimiento`                                          | El código que el emisor estampa en sus documentos. Es único dentro del proveedor. |
| `nombre`                                                         | Nombre del establecimiento (normalmente el nombre comercial de esa sucursal).     |
| `direccion`, `municipio`, `departamento`, `codigoPostal`, `pais` | Dirección de ese establecimiento en particular.                                   |

`GET /proveedor/{id}` incluye además las sucursales embebidas, y el listado trae `cantidadSucursales` para no cargar payload de más.

## Endpoints

| Método   | Ruta                       | Qué hace                                  |
| -------- | -------------------------- | ----------------------------------------- |
| `GET`    | `/proveedor`               | Busca proveedores de la Cuenta. Paginado. |
| `GET`    | `/proveedor/{id}`          | Un proveedor, con sus sucursales.         |
| `GET`    | `/proveedor/{id}/sucursal` | Sucursales del proveedor, paginadas.      |
| `POST`   | `/proveedor`               | Registra un proveedor.                    |
| `PATCH`  | `/proveedor/{id}`          | Edita un proveedor.                       |
| `DELETE` | `/proveedor/{id}`          | Retira un proveedor (no lo borra).        |
| `POST`   | `/proveedor/{id}/activar`  | Reactiva un proveedor retirado.           |
| `POST`   | `/proveedor/fusionar`      | Fusiona duplicados.                       |

### Buscar

```bash theme={null}
curl "https://api.fegora.com/proveedor?termino=super%20fresh&pageSize=25" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

`termino` es insensible a acentos, mayúsculas y puntuación, y busca por **subcadena** sobre nombre, nombre comercial, identificación fiscal, correo y teléfono — "super fresh" encuentra "MI SUPER FRESH PASAJE NARANJO".

| Parámetro                | Descripción                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| `termino`                | Texto libre.                                                                                |
| `idFiscal`               | Filtro exacto por identificación (los separadores no importan).                             |
| `sinIdFiscal`            | `true` devuelve sólo proveedores sin identificación fiscal; `false` sólo los que la tienen. |
| `pais`                   | Filtra por país — la separación práctica entre proveedor local y extranjero.                |
| `incluirInactivos`       | Incluye los retirados. Por omisión no aparecen.                                             |
| `pageNumber`, `pageSize` | Paginación. `pageSize` máximo 200.                                                          |

Los resultados vienen ordenados por documento más reciente primero.

### Editar

`PATCH` sólo escribe las propiedades presentes en el cuerpo, así que corregir un teléfono no borra la dirección. Un `null` explícito **sí** limpia el campo.

```bash theme={null}
curl -X PATCH "https://api.fegora.com/proveedor/482" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"telefono": "2222-3333", "noSincronizar": true}'
```

`noSincronizar: true` **fija** el registro: los documentos que lleguen después seguirán sumando a los contadores, pero ya no sobrescribirán el nombre, el contacto ni la dirección que usted depuró. Es especialmente útil aquí, porque el nombre comercial varía por sucursal y sin ese candado lo reescribiría la sucursal que facturó más recientemente.

### Retirar

`DELETE /proveedor/{id}` es un **retiro lógico**, no un borrado: el proveedor desaparece de las búsquedas pero conserva su historial. No existe borrado físico.

Si después llega un documento de ese proveedor, Fegora lo reactiva automáticamente — recibir un documento demuestra que sigue siendo su proveedor.

### Fusionar duplicados

```bash theme={null}
curl -X POST "https://api.fegora.com/proveedor/fusionar" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idPrincipal": 482, "idsDuplicados": [911, 1204]}'
```

El proveedor principal absorbe los contadores, los montos por moneda y las sucursales de los duplicados, y se queda con los datos que a él le faltaban — los suyos siempre ganan. Los duplicados se retiran (no se borran) y quedan con una nota que indica dónde fueron fusionados.

## Errores

| Código              | Cuándo                                                                      |
| ------------------- | --------------------------------------------------------------------------- |
| `FEG_PRV_OBTE_INEX` | El proveedor no existe o no pertenece a su Cuenta.                          |
| `FEG_PRV_CREA_001`  | Ya existe un proveedor con esa identificación fiscal en la Cuenta.          |
| `FEG_PRV_CREA_002`  | No se especificó la Cuenta y no se pudo deducir.                            |
| `FEG_PRV_ACTU_001`  | La identificación fiscal que intenta asignar ya la tiene otro proveedor.    |
| `FEG_PRV_FUSI_001`  | Fusión inválida (sin duplicados distintos del principal, o de otra Cuenta). |

Los proveedores de una Cuenta sólo son visibles para esa Cuenta. Un id de otra Cuenta responde como inexistente.