Portal de Proveedores — Catálogos y Tolerancia

Estos endpoints le dan a un proveedor (prestador) los datos de referencia necesarios para trabajar con sus propias facturas: la lista de estados de factura, el catálogo de conceptos de facturación y la tolerancia resuelta actualmente para su cuenta. Son de solo lectura y están acotados al proveedor detrás del token.

Cuenta de proveedor requerida

El usuario autenticado debe estar vinculado a un proveedor (prestador). Las solicitudes desde una cuenta que no sea de proveedor se rechazan con 403 FORBIDDEN. Todos los endpoints requieren un token JWT válido, una clave de API y el encabezado tenant. Ver Autenticación.

---

Catálogo de estados de factura

Obtiene el catálogo de estados de factura. Usa estos códigos al filtrar facturas por status.

GET/apidev/v1/supplier-portal/catalogs/states

PermisoAPICLI_PORTALPROVEEDOR_READ

Límite de solicitudes30 req/min (ventana deslizante)

Encabezados de la solicitud

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Campos de la respuesta — data[]

Campo	Tipo	Descripción
id	number	Identificador del estado (rango 100–106)
code	string	Código de estado: PEN, ENV, APR, REV, REC, AJU, LIQ
name	string	Nombre visible del estado

Ejemplo de código

cURL

curl -s "https://$TENANT/apidev/v1/supplier-portal/catalogs/states" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/catalogs/states`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
    },
  }
);

const { data } = await response.json();
data.forEach((s) => console.log(`${s.code} → ${s.name}`));

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": 100, "code": "PEN", "name": "Pendiente" },
    { "id": 101, "code": "ENV", "name": "Enviada" },
    { "id": 102, "code": "APR", "name": "Aprobada" },
    { "id": 103, "code": "REV", "name": "En revisión" },
    { "id": 104, "code": "REC", "name": "Rechazada" },
    { "id": 105, "code": "AJU", "name": "Ajustada" },
    { "id": 106, "code": "LIQ", "name": "Liquidada" }
  ],
  "meta": {}
}

---

Catálogo de conceptos

Obtiene el catálogo de conceptos de facturación disponibles para el proveedor. Los conceptos describen las líneas de detalle de una factura y se tipifican como cargo, recargo o descuento.

GET/apidev/v1/supplier-portal/catalogs/concepts

PermisoAPICLI_PORTALPROVEEDOR_READ

Límite de solicitudes30 req/min (ventana deslizante)

Campos de la respuesta — data[]

Campo	Tipo	Descripción
id	string	Identificador del concepto
code	string	Código del concepto
name	string	Nombre visible del concepto
type	string	G (cargo), R (recargo), o D (descuento)
order	number	Orden de visualización

Ejemplo de código

cURL

curl -s "https://$TENANT/apidev/v1/supplier-portal/catalogs/concepts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/catalogs/concepts`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
    },
  }
);

const { data } = await response.json();
const charges = data.filter((c) => c.type === 'G');
console.log(`${charges.length} charge concepts available`);

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "100", "code": "MO", "name": "Mano de obra", "type": "G", "order": 1 },
    { "id": "101", "code": "REP", "name": "Repuestos", "type": "G", "order": 2 },
    { "id": "102", "code": "URG", "name": "Recargo por urgencia", "type": "R", "order": 3 },
    { "id": "103", "code": "DESC", "name": "Descuento por volumen", "type": "D", "order": 4 }
  ],
  "meta": {}
}

---

Tolerancia efectiva

Obtiene la tolerancia resuelta actualmente para el proveedor autenticado. Una configuración por proveedor tiene prioridad; cuando no hay ninguna definida, aplica la tolerancia global de la compañía; cuando no hay ninguna de las dos, el origen se informa como ninguna.

GET/apidev/v1/supplier-portal/tolerance/effective

PermisoAPICLI_PORTALPROVEEDOR_READ

Límite de solicitudes30 req/min (ventana deslizante)

Campos de la respuesta — data

Campo	Tipo	Descripción
mode	string | null	Modo de tolerancia: PCT (porcentaje), ABS (absoluta), AMB (ambas), o null cuando no aplica ninguna
tolerance_pct	number | null	Diferencia porcentual permitida
tolerance_abs	number | null	Diferencia absoluta permitida
auto_approve	boolean	Si los montos dentro de la tolerancia se aprueban automáticamente
source	string	De dónde proviene la tolerancia: proveedor, global o ninguna

Ejemplo de código

cURL

curl -s "https://$TENANT/apidev/v1/supplier-portal/tolerance/effective" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/tolerance/effective`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
    },
  }
);

const { data } = await response.json();
console.log(`Mode: ${data.mode ?? 'none'}, source: ${data.source}`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "mode": "PCT",
    "tolerance_pct": 5.0,
    "tolerance_abs": null,
    "auto_approve": true,
    "source": "proveedor"
  },
  "meta": {}
}

---

Errores

Código	HTTP	Aplica a	Descripción
UNAUTHORIZED	401	Todos	Token JWT / clave de API faltante o inválido
TOKEN_EXPIRED	401	Todos	El JWT era válido pero ha expirado (vigencia de 1 hora)
FORBIDDEN	403	Todos	La cuenta no es de proveedor — "This endpoint requires a supplier account." — o carece de APICLI_PORTALPROVEEDOR_READ
RATE_LIMITED	429	Todos	Se excedió el límite de solicitudes del endpoint

---

Relacionado

• Facturas — listar, declarar y validar facturas
• Liquidaciones — agrupar facturas aprobadas en liquidaciones