Portal de Proveedores — Facturas

Estos endpoints permiten a un proveedor (prestador) gestionar sus propias facturas directamente desde la API: listarlas, abrir una para ver el detalle, declarar el monto que está facturando, declarar varias a la vez y verificar un monto contra la tolerancia de la compañía antes de enviarlo. Cada endpoint está acotado a la cuenta de proveedor detrás del token — solo ves y operás sobre tus propias facturas.

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.

Listar facturas

Obtiene una lista paginada de las facturas del proveedor para un rango de fechas, con estado opcional y búsqueda de texto libre. Cada fila incluye el monto del sistema, el monto declarado y la diferencia entre ambos. La respuesta también incluye la tolerancia que aplica al proveedor para que puedas interpretar las diferencias.

GET/apidev/v1/supplier-portal/invoices

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

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`startdate`	string (ISO 8601)	Sí	Inicio del rango de fechas
`enddate`	string (ISO 8601)	Sí	Fin del rango de fechas (el rango no puede exceder los 93 días)
`status`	string	No	Filtrar por código de estado de factura: `PEN`, `ENV`, `APR`, `REV`, `REC`, `AJU`, `LIQ`
`search`	string	No	Coincidencia de texto libre en número de servicio, cuenta o número de factura (máx. 120 caracteres)
`limit`	integer	No	Registros por página. Mín.: `1`, Máx.: `100`, Predeterminado: `25`
`offset`	integer	No	Registros a omitir. Predeterminado: `0`

Campos de la respuesta — `data.rows[]`

Campo	Tipo	Descripción
`invoice_id`	string	Identificador único de la factura
`invoice_date`	string \| null	Fecha de la factura
`service_id`	string	ID del servicio/tarea relacionado
`service_number`	string \| null	Número visible del servicio
`service_call_date`	string \| null	Cuándo se solicitó el servicio
`account_name`	string \| null	Cuenta a la que pertenece el servicio
`city`	string \| null	Ciudad del servicio
`system_amount`	number	Monto calculado por el sistema
`declaration_id`	string \| null	ID de la declaración, si el proveedor ya declaró un monto
`declared_amount`	number \| null	Monto declarado por el proveedor
`declared_notes`	string \| null	Notas que el proveedor agregó en la declaración
`provider_invoice_number`	string \| null	Número de factura propio del proveedor
`provider_invoice_date`	string \| null	Fecha de factura propia del proveedor
`state_code`	string	Código de estado de la factura (`PEN`, `ENV`, …)
`state_name`	string	Nombre del estado de la factura
`difference`	number \| null	Monto declarado menos monto del sistema
`difference_pct`	number \| null	Diferencia como porcentaje del monto del sistema
`attachment_url`	string \| null	URL al archivo de factura adjunto
`attachment_filename`	string \| null	Nombre original del archivo del adjunto

Campos de la respuesta — `data.tolerance`

Campo	Tipo	Descripción
`mode`	string \| null	Modo de tolerancia: `PCT`, `ABS`, `AMB`, 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
JavaScript

curl -s "https://$TENANT/apidev/v1/supplier-portal/invoices?startdate=2026-05-01&enddate=2026-05-31&status=PEN&limit=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const params = new URLSearchParams({
  startdate: '2026-05-01',
  enddate: '2026-05-31',
  status: 'PEN',
  limit: '10',
});

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

const { data, meta } = await response.json();
console.log(`${data.rows.length} of ${meta.total} invoices, tolerance source: ${data.tolerance.source}`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "rows": [
      {
        "invoice_id": "7234567890123456789",
        "invoice_date": "2026-05-03T15:02:00",
        "service_id": "103878",
        "service_number": "SRV-2026-0042",
        "service_call_date": "2026-05-02T09:10:00",
        "account_name": "Supermercado Centro",
        "city": "Montevideo",
        "system_amount": 1098.00,
        "declaration_id": "8100000000045",
        "declared_amount": 1100.00,
        "declared_notes": "Incluye traslado.",
        "provider_invoice_number": "A-0001-0000123",
        "provider_invoice_date": "2026-05-03",
        "state_code": "ENV",
        "state_name": "Enviada",
        "difference": 2.00,
        "difference_pct": 0.18,
        "attachment_url": "https://files.example.com/inv/123.pdf",
        "attachment_filename": "factura-123.pdf"
      }
    ],
    "tolerance": {
      "mode": "PCT",
      "tolerance_pct": 5.0,
      "tolerance_abs": null,
      "auto_approve": true,
      "source": "proveedor"
    }
  },
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Detalle de factura

Obtiene una factura individual con su desglose completo: los mismos campos de fila que el listado, más los conceptos de las líneas de detalle y la tolerancia que aplica. Devuelve 404 si la factura no existe o no pertenece al proveedor.

GET/apidev/v1/supplier-portal/invoices/{id}

PermisoAPICLI_PORTALPROVEEDOR_READ

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

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	Identificador único de la factura

Campos de la respuesta — `data.concepts[]`

Campo	Tipo	Descripción
`concept_id`	string	ID del catálogo de conceptos
`description`	string	Descripción del concepto
`unit_amount`	number	Monto por unidad
`quantity`	number	Cantidad
`tax_pct`	number	Porcentaje de impuesto aplicado
`total`	number	Total de la línea

El objeto data también incluye todos los campos listados para una fila del listado y un objeto tolerance (ver Listar facturas).

Ejemplo de código

cURL
JavaScript

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

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

const { data } = await response.json();
console.log(`${data.service_number}: ${data.concepts.length} concepts`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "invoice_id": "7234567890123456789",
    "invoice_date": "2026-05-03T15:02:00",
    "service_id": "103878",
    "service_number": "SRV-2026-0042",
    "account_name": "Supermercado Centro",
    "city": "Montevideo",
    "system_amount": 1098.00,
    "declaration_id": "8100000000045",
    "declared_amount": 1100.00,
    "declared_notes": "Incluye traslado.",
    "provider_invoice_number": "A-0001-0000123",
    "provider_invoice_date": "2026-05-03",
    "state_code": "ENV",
    "state_name": "Enviada",
    "difference": 2.00,
    "difference_pct": 0.18,
    "attachment_url": "https://files.example.com/inv/123.pdf",
    "attachment_filename": "factura-123.pdf",
    "concepts": [
      {
        "concept_id": "100",
        "description": "Mano de obra",
        "unit_amount": 900.00,
        "quantity": 1,
        "tax_pct": 22.0,
        "total": 1098.00
      }
    ],
    "tolerance": {
      "mode": "PCT",
      "tolerance_pct": 5.0,
      "tolerance_abs": null,
      "auto_approve": true,
      "source": "proveedor"
    }
  },
  "meta": {}
}

Declarar monto de factura

Declara el monto que el proveedor está facturando para una factura. Es un upsert: si todavía no existe una declaración se crea, de lo contrario se actualiza la existente. La respuesta informa el estado resultante y cómo se compara el monto declarado con la tolerancia de la compañía.

POST/apidev/v1/supplier-portal/invoices/declare

PermisoAPICLI_PORTALPROVEEDOR_WRITE

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

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`invoice_id`	string	Sí	Factura a declarar (cadena numérica)
`amount`	number	Sí	Monto declarado. Debe ser `>= 0`
`notes`	string	No	Notas de texto libre para la declaración
`invoice_number`	string	No	Número de factura propio del proveedor (máx. 60 caracteres)
`invoice_date`	string (ISO 8601)	No	Fecha de factura propia del proveedor
`tax_pct`	number	No	Porcentaje de impuesto (0–100)

Campos de la respuesta — `data.tolerance`

Campo	Tipo	Descripción
`within_tolerance`	boolean	Si el monto declarado está dentro de la tolerancia
`difference`	number	Monto declarado menos monto del sistema
`difference_pct`	number	Diferencia como porcentaje del monto del sistema
`difference_abs`	number	Diferencia absoluta
`action`	string	Acción resultante (por ejemplo, aprobación automática o envío a revisión)
`config_source`	string	De dónde proviene la tolerancia aplicada

Ejemplo de código

cURL
JavaScript

curl -s -X POST "https://$TENANT/apidev/v1/supplier-portal/invoices/declare" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "7234567890123456789",
    "amount": 1100.00,
    "notes": "Incluye traslado.",
    "invoice_number": "A-0001-0000123",
    "invoice_date": "2026-05-03",
    "tax_pct": 22
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/invoices/declare`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      invoice_id: '7234567890123456789',
      amount: 1100.0,
      notes: 'Incluye traslado.',
      invoice_number: 'A-0001-0000123',
      invoice_date: '2026-05-03',
      tax_pct: 22,
    }),
  }
);

const { data } = await response.json();
console.log(`Declared. Within tolerance: ${data.tolerance.within_tolerance}`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "declaration_id": "8100000000045",
    "declared_amount": 1100.00,
    "state_id": 101,
    "tolerance": {
      "within_tolerance": true,
      "difference": 2.00,
      "difference_pct": 0.18,
      "difference_abs": 2.00,
      "action": "AUTO_APPROVE",
      "config_source": "proveedor"
    }
  },
  "meta": {}
}

Declarar en lote

Declara montos para muchas facturas en una sola solicitud. Cada ítem se procesa de forma independiente, por lo que la solicitud siempre devuelve 200 con un éxito o fallo por ítem. Usalo para enviar todas las declaraciones de un período de una sola vez.

POST/apidev/v1/supplier-portal/invoices/declare-batch

PermisoAPICLI_PORTALPROVEEDOR_WRITE

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

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`declarations`	array	Sí	Lista de declaraciones (1–100 ítems)

Cada ítem en declarations[] acepta los mismos campos que Declarar monto de factura:

Campo	Tipo	Requerido	Descripción
`invoice_id`	string	Sí	Factura a declarar
`amount`	number	Sí	Monto declarado (`>= 0`)
`notes`	string	No	Notas de texto libre
`invoice_number`	string	No	Número de factura propio del proveedor
`invoice_date`	string (ISO 8601)	No	Fecha de factura propia del proveedor
`tax_pct`	number	No	Porcentaje de impuesto (0–100)

Campos de la respuesta — `data`

Campo	Tipo	Descripción
`results`	array	Una entrada por cada ítem enviado, en orden
`accepted`	number	Cuántos ítems se declararon correctamente
`rejected`	number	Cuántos ítems fallaron

Cada entrada de results[] incluye invoice_id y success. En caso de éxito incluye los mismos campos que una declaración individual; en caso de fallo incluye un error que describe el motivo.

Ejemplo de código

cURL
JavaScript

curl -s -X POST "https://$TENANT/apidev/v1/supplier-portal/invoices/declare-batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "declarations": [
      { "invoice_id": "7234567890123456789", "amount": 1100.00, "invoice_number": "A-0001-0000123" },
      { "invoice_id": "7234567890123456790", "amount": 540.00 }
    ]
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/invoices/declare-batch`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      declarations: [
        { invoice_id: '7234567890123456789', amount: 1100.0, invoice_number: 'A-0001-0000123' },
        { invoice_id: '7234567890123456790', amount: 540.0 },
      ],
    }),
  }
);

const { data } = await response.json();
console.log(`${data.accepted} accepted, ${data.rejected} rejected`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "results": [
      {
        "invoice_id": "7234567890123456789",
        "success": true,
        "declaration_id": "8100000000045",
        "declared_amount": 1100.00,
        "state_id": 101,
        "tolerance": {
          "within_tolerance": true,
          "difference": 2.00,
          "difference_pct": 0.18,
          "difference_abs": 2.00,
          "action": "AUTO_APPROVE",
          "config_source": "proveedor"
        }
      },
      {
        "invoice_id": "7234567890123456790",
        "success": false,
        "error": {
          "code": "NOT_FOUND",
          "message": "Invoice not found or not owned by this supplier."
        }
      }
    ],
    "accepted": 1,
    "rejected": 1
  },
  "meta": {}
}

Validar monto (verificación previa)

Verifica un monto contra la tolerancia de la compañía antes de declararlo. Este endpoint no escribe nada — solo te dice cómo se trataría el monto. Devuelve 404 si la factura no pertenece al proveedor.

POST/apidev/v1/supplier-portal/invoices/validate

PermisoAPICLI_PORTALPROVEEDOR_READ

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

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`invoice_id`	string	Sí	Factura a verificar
`amount`	number	Sí	Monto a probar. Debe ser `>= 0`

Campos de la respuesta — `data`

Campo	Tipo	Descripción
`invoice_id`	string	Factura que se verificó
`system_amount`	number	Monto calculado por el sistema
`declared_amount`	number	Monto que enviaste para la verificación
`within_tolerance`	boolean	Si el monto está dentro de la tolerancia
`difference`	number	Monto enviado menos monto del sistema
`difference_pct`	number	Diferencia como porcentaje del monto del sistema
`difference_abs`	number	Diferencia absoluta
`action`	string	Acción que resultaría (por ejemplo, aprobación automática o envío a revisión)
`config_source`	string	De dónde proviene la tolerancia aplicada

Ejemplo de código

cURL
JavaScript

curl -s -X POST "https://$TENANT/apidev/v1/supplier-portal/invoices/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "7234567890123456789",
    "amount": 1500.00
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/invoices/validate`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      invoice_id: '7234567890123456789',
      amount: 1500.0,
    }),
  }
);

const { data } = await response.json();
if (!data.within_tolerance) {
  console.log(`Out of tolerance by ${data.difference_pct}% — would go to review`);
}

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "invoice_id": "7234567890123456789",
    "system_amount": 1098.00,
    "declared_amount": 1500.00,
    "within_tolerance": false,
    "difference": 402.00,
    "difference_pct": 36.61,
    "difference_abs": 402.00,
    "action": "REVIEW",
    "config_source": "proveedor"
  },
  "meta": {}
}

Errores

Código	HTTP	Aplica a	Descripción
`VALIDATION_ERROR`	400	Todos	Parámetros o cuerpo inválidos (por ejemplo, falta `startdate`, `amount` menor a 0, más de 100 declaraciones)
`INVALID_DATE_RANGE`	400	Listado	El rango de fechas excede los 93 días, o las fechas son inválidas
`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 del permiso requerido
`NOT_FOUND`	404	Detalle, Declarar, Validar	La factura no existe o no pertenece a tu cuenta de proveedor
`RATE_LIMITED`	429	Todos	Se excedió el límite de solicitudes del endpoint

Catálogos y Tolerancia — estados de factura, conceptos y la tolerancia efectiva
Liquidaciones — agrupar facturas aprobadas en liquidaciones

Listar facturas​

Encabezados de la solicitud​

Parámetros de consulta​

Campos de la respuesta — data.rows[]​

Campos de la respuesta — data.tolerance​

Ejemplo de código​

Ejemplo de respuesta​

Detalle de factura​

Parámetros de ruta​

Campos de la respuesta — data.concepts[]​

Ejemplo de código​

Ejemplo de respuesta​

Declarar monto de factura​

Cuerpo de la solicitud​

Campos de la respuesta — data.tolerance​

Ejemplo de código​

Ejemplo de respuesta​

Declarar en lote​

Cuerpo de la solicitud​

Campos de la respuesta — data​

Ejemplo de código​

Ejemplo de respuesta​

Validar monto (verificación previa)​

Cuerpo de la solicitud​

Campos de la respuesta — data​

Ejemplo de código​

Ejemplo de respuesta​

Errores​

Relacionado​

Listar facturas

Encabezados de la solicitud

Parámetros de consulta

Campos de la respuesta — `data.rows[]`

Campos de la respuesta — `data.tolerance`

Ejemplo de código

Ejemplo de respuesta

Detalle de factura

Parámetros de ruta

Campos de la respuesta — `data.concepts[]`

Ejemplo de código

Ejemplo de respuesta

Declarar monto de factura

Cuerpo de la solicitud

Campos de la respuesta — `data.tolerance`

Ejemplo de código

Ejemplo de respuesta

Declarar en lote

Cuerpo de la solicitud

Campos de la respuesta — `data`

Ejemplo de código

Ejemplo de respuesta

Validar monto (verificación previa)

Cuerpo de la solicitud

Campos de la respuesta — `data`

Ejemplo de código

Ejemplo de respuesta

Errores

Relacionado