Supplier Portal — Catalogs & Tolerance

These endpoints give a supplier (prestador) the reference data needed to work with their own invoices: the list of invoice states, the catalog of billing concepts, and the tolerance currently resolved for their account. They are read-only and scoped to the supplier behind the token.

Supplier account required

The authenticated user must be linked to a supplier (prestador). Requests from a non-supplier account are rejected with 403 FORBIDDEN. All endpoints require a valid JWT token, API key, and tenant header. See Authentication.

---

Invoice States Catalog

Retrieve the catalog of invoice states. Use these codes when filtering invoices by status.

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

PermissionAPICLI_PORTALPROVEEDOR_READ

Rate Limit30 req/min (sliding window)

Request Headers

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

Response Fields — data[]

Field	Type	Description
id	number	State identifier (range 100–106)
code	string	State code: PEN, ENV, APR, REV, REC, AJU, LIQ
name	string	State display name

Code Example

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}`));

Example Response

{
  "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": {}
}

---

Concepts Catalog

Retrieve the catalog of billing concepts available to the supplier. Concepts describe the line items on an invoice and are typed as a charge, a surcharge, or a discount.

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

PermissionAPICLI_PORTALPROVEEDOR_READ

Rate Limit30 req/min (sliding window)

Response Fields — data[]

Field	Type	Description
id	string	Concept identifier
code	string	Concept code
name	string	Concept display name
type	string	G (charge), R (surcharge), or D (discount)
order	number	Display order

Code Example

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`);

Example Response

{
  "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": {}
}

---

Effective Tolerance

Retrieve the tolerance currently resolved for the authenticated supplier. A per-supplier setting takes priority; when none is set, the company global tolerance applies; when neither is set, the source is reported as ninguna.

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

PermissionAPICLI_PORTALPROVEEDOR_READ

Rate Limit30 req/min (sliding window)

Response Fields — data

Field	Type	Description
mode	string | null	Tolerance mode: PCT (percentage), ABS (absolute), AMB (both), or null when none applies
tolerance_pct	number | null	Allowed percentage difference
tolerance_abs	number | null	Allowed absolute difference
auto_approve	boolean	Whether amounts within tolerance are approved automatically
source	string	Where the tolerance comes from: proveedor, global, or ninguna

Code Example

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}`);

Example Response

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

---

Errors

Code	HTTP	Applies to	Description
UNAUTHORIZED	401	All	Missing or invalid JWT token / API key
TOKEN_EXPIRED	401	All	The JWT was valid but has expired (1 hour lifetime)
FORBIDDEN	403	All	The account is not a supplier — "This endpoint requires a supplier account." — or lacks APICLI_PORTALPROVEEDOR_READ
RATE_LIMITED	429	All	Exceeded the endpoint rate limit

---

Related

• Invoices — list, declare, and validate invoices
• Settlements — group approved invoices into settlements