Portal de Proveedores — Liquidaciones

Estos endpoints permiten a un proveedor (prestador) gestionar sus propias liquidaciones: listarlas, abrir una para ver el detalle, armar un borrador a partir de facturas aprobadas y enviarlo para su pago. Una liquidación agrupa varias facturas en un único lote de pago. Cada endpoint está acotado al proveedor detrás del token — solo ves y operás sobre tus propias liquidaciones.

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 liquidaciones

Obtiene una lista paginada de las liquidaciones del proveedor, con filtros opcionales de rango de fechas y estado.

GET/apidev/v1/supplier-portal/settlements

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)	No	Inicio del rango de fechas
`enddate`	string (ISO 8601)	No	Fin del rango de fechas
`status`	string	No	Filtrar por código de estado de liquidación: `BOR`, `LENV`, `LAPR`, `LREC`, `CER`
`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
`settlement_id`	string	Identificador único de la liquidación
`date`	string	Fecha de creación de la liquidación
`close_date`	string \| null	Cuándo se cerró la liquidación
`state_id`	number	ID del estado de la liquidación
`state_code`	string	Código de estado de la liquidación (`BOR`, `LENV`, …)
`state_name`	string	Nombre del estado de la liquidación
`total`	number	Monto total de la liquidación
`invoice_count`	number	Número de facturas incluidas
`receipts_total`	number	Total de los recibos adjuntos
`adjustments_total`	number	Total de los ajustes
`difference`	number	Diferencia entre el total y los recibos
`notes`	string \| null	Notas de texto libre
`payment_date`	string \| null	Fecha de pago
`payment_reference`	string \| null	Referencia de pago

Ejemplo de código

cURL
JavaScript

curl -s "https://$TENANT/apidev/v1/supplier-portal/settlements?startdate=2026-05-01&enddate=2026-05-31&status=BOR" \
  -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: 'BOR',
});

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/settlements?${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} settlements`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "rows": [
      {
        "settlement_id": "9100000000001",
        "date": "2026-05-31T10:00:00",
        "close_date": null,
        "state_id": 1,
        "state_code": "BOR",
        "state_name": "Borrador",
        "total": 3294.00,
        "invoice_count": 3,
        "receipts_total": 0.00,
        "adjustments_total": 0.00,
        "difference": 3294.00,
        "notes": "Liquidación mayo.",
        "payment_date": null,
        "payment_reference": null
      }
    ]
  },
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Detalle de liquidación

Obtiene una liquidación individual con su desglose completo: los mismos campos de fila que el listado, más las facturas que agrupa y los recibos adjuntos a ella. Devuelve 404 si la liquidación no pertenece al proveedor.

GET/apidev/v1/supplier-portal/settlements/{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 liquidación

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

Campo	Tipo	Descripción
`invoice_id`	string	Identificador único de la factura
`service_number`	string \| null	Número visible del servicio
`account_name`	string \| null	Cuenta a la que pertenece el servicio
`system_amount`	number	Monto calculado por el sistema
`declared_amount`	number \| null	Monto declarado por el proveedor
`provider_invoice_number`	string \| null	Número de factura propio del proveedor
`state_code`	string	Código de estado de la factura
`state_name`	string	Nombre del estado de la factura
`is_manual`	boolean	Si la línea se agregó manualmente
`description`	string \| null	Descripción de la línea

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

Campo	Tipo	Descripción
`receipt_id`	string	Identificador único del recibo
`number`	string \| null	Número del recibo
`date`	string \| null	Fecha del recibo
`type`	string	Tipo de recibo
`amount`	number	Monto del recibo
`notes`	string \| null	Notas de texto libre
`attachment_url`	string \| null	URL al archivo del recibo adjunto

El objeto data también incluye todos los campos listados para una fila del listado.

Ejemplo de código

cURL
JavaScript

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

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

const { data } = await response.json();
console.log(`${data.invoices.length} invoices, ${data.receipts.length} receipts`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "settlement_id": "9100000000001",
    "date": "2026-05-31T10:00:00",
    "close_date": null,
    "state_id": 1,
    "state_code": "BOR",
    "state_name": "Borrador",
    "total": 3294.00,
    "invoice_count": 3,
    "receipts_total": 3300.00,
    "adjustments_total": 0.00,
    "difference": 6.00,
    "notes": "Liquidación mayo.",
    "payment_date": null,
    "payment_reference": null,
    "invoices": [
      {
        "invoice_id": "7234567890123456789",
        "service_number": "SRV-2026-0042",
        "account_name": "Supermercado Centro",
        "system_amount": 1098.00,
        "declared_amount": 1100.00,
        "provider_invoice_number": "A-0001-0000123",
        "state_code": "APR",
        "state_name": "Aprobada",
        "is_manual": false,
        "description": null
      }
    ],
    "receipts": [
      {
        "receipt_id": "9200000000010",
        "number": "REC-0001",
        "date": "2026-05-31",
        "type": "TRANSFER",
        "amount": 3300.00,
        "notes": "Transferencia bancaria.",
        "attachment_url": "https://files.example.com/rec/10.pdf"
      }
    ]
  },
  "meta": {}
}

Crear liquidación

Crea una liquidación en borrador a partir de las facturas aprobadas del proveedor. Cada factura se valida: debe pertenecer al proveedor, estar en estado APR (aprobada) y no formar parte ya de una liquidación activa. Devuelve 201 con el detalle de la nueva liquidación.

POST/apidev/v1/supplier-portal/settlements

PermisoAPICLI_PORTALPROVEEDOR_WRITE

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

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`invoice_ids`	array	Sí	Facturas a agrupar (cadenas numéricas, 1–500 ítems)
`note`	string	No	Nota de texto libre para la liquidación

Ejemplo de código

cURL
JavaScript

curl -s -X POST "https://$TENANT/apidev/v1/supplier-portal/settlements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_ids": ["7234567890123456789", "7234567890123456790"],
    "note": "Liquidación mayo."
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/settlements`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      invoice_ids: ['7234567890123456789', '7234567890123456790'],
      note: 'Liquidación mayo.',
    }),
  }
);

const { data } = await response.json();
console.log(`Draft settlement created: ${data.settlement_id}`);

Ejemplo de respuesta — `201 Created`

{
  "success": true,
  "data": {
    "settlement_id": "9100000000001",
    "date": "2026-05-31T10:00:00",
    "close_date": null,
    "state_id": 1,
    "state_code": "BOR",
    "state_name": "Borrador",
    "total": 1640.00,
    "invoice_count": 2,
    "receipts_total": 0.00,
    "adjustments_total": 0.00,
    "difference": 1640.00,
    "notes": "Liquidación mayo.",
    "payment_date": null,
    "payment_reference": null,
    "invoices": [
      {
        "invoice_id": "7234567890123456789",
        "service_number": "SRV-2026-0042",
        "account_name": "Supermercado Centro",
        "system_amount": 1100.00,
        "declared_amount": 1100.00,
        "provider_invoice_number": "A-0001-0000123",
        "state_code": "APR",
        "state_name": "Aprobada",
        "is_manual": false,
        "description": null
      }
    ],
    "receipts": []
  },
  "meta": {}
}

Enviar liquidación

Envía una liquidación en borrador para su pago. Mueve la liquidación de BOR (borrador) a LENV (enviada) y requiere que al menos un recibo esté adjunto. Devuelve la fila de liquidación actualizada, o 404 si la liquidación no pertenece al proveedor.

PUT/apidev/v1/supplier-portal/settlements/{id}/submit

PermisoAPICLI_PORTALPROVEEDOR_WRITE

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

Parámetros de ruta

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

Ejemplo de código

cURL
JavaScript

curl -s -X PUT "https://$TENANT/apidev/v1/supplier-portal/settlements/9100000000001/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

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

const { data } = await response.json();
console.log(`Settlement now in state: ${data.state_code}`);

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "settlement_id": "9100000000001",
    "date": "2026-05-31T10:00:00",
    "close_date": null,
    "state_id": 2,
    "state_code": "LENV",
    "state_name": "Enviada",
    "total": 3294.00,
    "invoice_count": 3,
    "receipts_total": 3300.00,
    "adjustments_total": 0.00,
    "difference": 6.00,
    "notes": "Liquidación mayo.",
    "payment_date": null,
    "payment_reference": null
  },
  "meta": {}
}

Errores

Código	HTTP	Aplica a	Descripción
`VALIDATION_ERROR`	400	Listado, Crear, Enviar	Parámetros o cuerpo inválidos (por ejemplo, `invoice_ids` vacío, más de 500 ítems, una factura que no está aprobada, o enviar sin un recibo)
`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, Enviar	La liquidación (o una factura referenciada) no existe o no pertenece a tu cuenta de proveedor
`RATE_LIMITED`	429	Todos	Se excedió el límite de solicitudes del endpoint

Facturas — listar, declarar y validar facturas
Catálogos y Tolerancia — estados de factura, conceptos y la tolerancia efectiva

Listar liquidaciones​

Encabezados de la solicitud​

Parámetros de consulta​

Campos de la respuesta — data.rows[]​

Ejemplo de código​

Ejemplo de respuesta​

Detalle de liquidación​

Parámetros de ruta​

Campos de la respuesta — data.invoices[]​

Campos de la respuesta — data.receipts[]​

Ejemplo de código​

Ejemplo de respuesta​

Crear liquidación​

Cuerpo de la solicitud​

Ejemplo de código​

Ejemplo de respuesta — 201 Created​

Enviar liquidación​

Parámetros de ruta​

Ejemplo de código​

Ejemplo de respuesta​

Errores​

Relacionado​

Listar liquidaciones

Encabezados de la solicitud

Parámetros de consulta

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

Ejemplo de código

Ejemplo de respuesta

Detalle de liquidación

Parámetros de ruta

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

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

Ejemplo de código

Ejemplo de respuesta

Crear liquidación

Cuerpo de la solicitud

Ejemplo de código

Ejemplo de respuesta — `201 Created`

Enviar liquidación

Parámetros de ruta

Ejemplo de código

Ejemplo de respuesta

Errores

Relacionado