Proveedores

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.

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.

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.

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.

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

{
  "cantidadDocumentos": 148,
  "montosPorMoneda": {
    "GTQ": 84210.500000,
    "USD": 1920.000000
  },
  "monedaUltimoDocumento": "GTQ",
  "montoUltimoDocumento": 1250.000000
}

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.

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

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.

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

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.

Introducción

Documentos DTE

Guías por país

Cómo se llena

Identificación fiscal opcional

Los montos van por moneda

Sucursales del proveedor

Endpoints

Buscar

Editar

Retirar

Fusionar duplicados

Errores

​Cómo se llena

​Identificación fiscal opcional

​Los montos van por moneda

​Sucursales del proveedor

​Endpoints

​Buscar

​Editar

​Retirar

​Fusionar duplicados

​Errores

Cómo se llena

Identificación fiscal opcional

Los montos van por moneda

Sucursales del proveedor

Endpoints

Buscar

Editar

Retirar

Fusionar duplicados

Errores