Billing — Catalogs

Lookup endpoints for billing reference data. Use these to discover valid values for status_code, concept_id, tariff_id, and currency_id before creating or filtering invoices.

Prerequisites

All endpoints on this page require a valid JWT token, API key, and tenant header. See Authentication for details.

Pending Implementation

These endpoints are documented but not yet implemented in the public API (/apidev/v1/billing/*). The internal billing services exist in geotareas/facturacion/ but have not been wired to the API developers module. This documentation reflects the planned contract — DTOs, controller routes, permissions, and tests are still pending.

---

Billing Statuses

List all invoice status codes configured for the tenant.

GET/apidev/v1/billing/statuses

PermissionAPICLI_BILLING_READ

Rate Limit60 req/min

Cache300s

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 company hostname (e.g., yourcompany.geotareas.com)
Content-Type	Conditional	application/json — required for POST and PUT requests

Response Fields

Field	Type	Description
id	string	Status ID
code	string	Status code used in API filters and mutations
name	string	Display name
behavior	integer	System behavior code (1=Pending, 2=Reconciled, 3=Closed, 9=Cancelled)
behavior_name	string	Human-readable behavior label
is_estimated	boolean	Whether this is an estimated/provisional status

Code Examples

cURL

curl -s -X GET "https://api.example.com/apidev/v1/billing/statuses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  'https://api.example.com/apidev/v1/billing/statuses',
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);

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

Response Example

{
  "success": true,
  "data": [
    { "id": "1", "code": "PENDIENTE", "name": "Pendiente", "behavior": 1, "behavior_name": "Pendiente", "is_estimated": false },
    { "id": "2", "code": "CONCILIADO", "name": "Conciliado", "behavior": 2, "behavior_name": "Conciliado", "is_estimated": false },
    { "id": "3", "code": "CERRADA", "name": "Cerrada", "behavior": 3, "behavior_name": "Cerrada", "is_estimated": false },
    { "id": "9", "code": "ANULADA", "name": "Anulada", "behavior": 9, "behavior_name": "Anulada", "is_estimated": false }
  ]
}

---

Billing Concepts

List all billable concept types configured for the tenant (e.g., "Movida", "Kilometros recorridos").

GET/apidev/v1/billing/concepts

PermissionAPICLI_BILLING_READ

Rate Limit60 req/min

Cache300s

Response Fields

Field	Type	Description
id	string	Concept ID used in invoice creation
name	string	Concept display name
unit.id	string	Unit ID
unit.name	string	Unit name (e.g., "Unidades", "Kilometros")
description	string	Optional description

Response Example

{
  "success": true,
  "data": [
    {
      "id": "3",
      "name": "Movida",
      "unit": { "id": "1", "name": "Unidades" },
      "description": "Servicio de grua / traslado basico"
    },
    {
      "id": "5",
      "name": "Kilometros recorridos",
      "unit": { "id": "2", "name": "Kilometros" },
      "description": ""
    }
  ]
}

---

Currencies

List currencies available for the tenant.

GET/apidev/v1/billing/currencies

PermissionAPICLI_BILLING_READ

Rate Limit60 req/min

Cache600s

Response Fields

Field	Type	Description
id	string	Currency ID used in invoice creation
name	string	Currency name
symbol	string	Currency symbol (e.g., "$U", "US$")

Response Example

{
  "success": true,
  "data": [
    { "id": "1", "name": "Pesos Uy", "symbol": "$U" },
    { "id": "2", "name": "Dolar Americano", "symbol": "US$" }
  ]
}

---

Tariffs

List active tariffs available for invoice creation.

GET/apidev/v1/billing/tariffs

PermissionAPICLI_BILLING_READ

Rate Limit60 req/min

Cache120s

Query Parameters

Parameter	Type	Description
provider_id	string	Filter by provider
currency_id	string	Filter by currency
type	string	Filter by type: PAGAR or COBRAR

Response Fields

Field	Type	Description
id	string	Tariff ID
name	string	Tariff name
type	string	PAGAR or COBRAR
status	string	ACTIVA or INACTIVA
currency.id	string	Currency ID
currency.name	string	Currency name
currency.symbol	string	Currency symbol
provider	object | null	Specific provider, or null if applies to all
applies_to_all_providers	boolean	Whether the tariff is global
prestations_count	integer	Number of applicable prestations
origins_count	integer	Number of applicable origins
concepts_count	integer	Number of concepts in the tariff

Response Example

{
  "success": true,
  "data": [
    {
      "id": "1",
      "name": "Tarifa General - Prestador",
      "type": "PAGAR",
      "status": "ACTIVA",
      "currency": { "id": "1", "name": "Pesos Uy", "symbol": "$U" },
      "provider": null,
      "applies_to_all_providers": true,
      "prestations_count": 3,
      "origins_count": 2,
      "concepts_count": 2
    }
  ]
}

---

Tariff Detail

Get the full detail of a tariff including its concepts, unit prices, prestations, and origins.

GET/apidev/v1/billing/tariffs/{id}

PermissionAPICLI_BILLING_READ

Rate Limit60 req/min

Cache120s

Response Example

{
  "success": true,
  "data": {
    "id": "1",
    "name": "Tarifa General - Prestador",
    "type": "PAGAR",
    "status": "ACTIVA",
    "currency": { "id": "1", "name": "Pesos Uy", "symbol": "$U" },
    "provider": null,
    "provider_type": null,
    "vehicle_type": null,
    "shift": null,
    "prestations": [
      { "id": "10", "name": "Asistencia Vial" },
      { "id": "11", "name": "Grua" }
    ],
    "origins": [
      { "id": "99", "name": "Servicios Sura" }
    ],
    "concepts": [
      {
        "concept_id": "3",
        "concept_name": "Movida",
        "type": 1,
        "unit_price": 900.00,
        "negotiable": false,
        "includes_tax": false,
        "tax_percent": 22.00,
        "total": 1098.00
      },
      {
        "concept_id": "5",
        "concept_name": "Kilometros recorridos",
        "type": 1,
        "unit_price": 50.00,
        "negotiable": true,
        "includes_tax": false,
        "tax_percent": 22.00,
        "total": 61.00
      }
    ]
  }
}

Errors

Code	HTTP	Description
BILLING_TARIFF_NOT_FOUND	404	Tariff not found

Code	HTTP Status	Description	Resolution
VALIDATION_ERROR	400	Request body or query parameters failed validation	Check the error.details field for specific validation failures
UNAUTHORIZED	401	Missing, expired, or invalid JWT token or API key	Re-authenticate via Login to get a fresh token
RATE_LIMITED	429	Too many requests — rate limit exceeded	Wait until the Retry-After header time elapses. See Rate Limits
INTERNAL_ERROR	500	Unexpected server error	Retry after a brief delay. If persistent, contact support

---

Related

• Invoices — Read
• Invoices — Write — uses concept_id, tariff_id, currency_id from these catalogs
• Automation Rules