Ir al contenido
Sursa Developers

POST/v1/finance/report

Obtener un informe financiero resumido

finance_report

Devuelve los totales de las facturas o los pagos de la organización, agrupados por hasta tres dimensiones (categoría, grupo, tipo de actividad del proveedor, proveedor, comprador, contraparte, sentido, moneda, mes, trimestre, año), con las medidas invoiced, paid, unpaid y tax. Los totales solo incluyen los documentos visibles para el usuario (las colecciones y las categorías de su perfil de datos, y la opción «responder solo a partir de tarjetas verificadas»); los filtros de la solicitud reducen este alcance, pero nunca lo amplían.

En el modo reporting (predeterminado), los importes se convierten a la moneda de los informes de la organización al tipo de la fecha del documento, y los importes sin tipo se enumeran en conversion.unconverted. En el modo original, los importes en monedas distintas no se suman, y la moneda pasa a ser una dimensión de la fila. Si hay más filas que limit, truncated es true, y totals sigue abarcando todas las filas. Requiere un perfil de datos con acceso a los datos financieros (finance.forbidden).

El informe, las listas de facturas y de pagos y sus exportaciones son operaciones de lectura aunque usen POST: están disponibles en modo «View as» y para las claves de API con el ámbito read (y, como antes, para las claves con el ámbito write).

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de encabezado

  • X-View-Asstring

    Solo para claves de API con el rol admin. Ejecuta la solicitud como el perfil de datos <profile>[:viewer|verifier|editor], por ejemplo employee:viewer. La clave de instalación no puede usar este encabezado (403).

Parámetros de cookie

  • kb_view_asstring

    Cookie del modo «View as» para una sesión. POST /auth/view-as la establece y DELETE /auth/view-as la elimina.

Cuerpo de la solicitud

application/json

Objeto: FinanceReportRequest

  • basisstring

    invoices: facturas, notas de crédito y recibos. payments: el registro de pagos (flujo de caja). Con payments, la única medida es paid, y la dimensión direction y el total muestran el movimiento de dinero, in u out, mientras que una transferencia entre sus propias entidades jurídicas es internal.

    Valores permitidos: invoicespayments

    Predeterminado: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Valor predeterminado: invoiced (paid con payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Qué fecha determina el período y el filtro from/to: la fecha del documento o la fecha del pago.

    Valores permitidos: documentpayment

    Predeterminado: "document"

  • filtersFinanceFilter
  • order_bystring

    Medida o dimensión por la que se ordena. De forma predeterminada, la primera medida en orden descendente.

  • order_descboolean

    Predeterminado: true

  • limitinteger

    Predeterminado: 1000≥ 1, ≤ 10000

  • languagestring

    Idioma de las etiquetas de categorías y grupos, en|ru. Valor predeterminado: en.

Respuestas

200El informe

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: FinanceReport

  • currency_modeFinanceCurrencyModeobligatorio
  • currencystring

    Moneda de los informes (modo reporting).

  • rowsarray of FinanceReportRowobligatorio
  • totalsarray of FinanceReportTotalobligatorio

    Totales de todas las filas antes del recorte, un elemento por moneda (en un informe dividido por dirección, por moneda y dirección, FinanceReportTotal.direction).

  • truncatedbooleanobligatorio
  • limitintegerobligatorio
  • total_rowsintegerobligatorio

    Número de filas agrupadas antes del recorte.

  • conversionFinanceConversion
  • warningsarray of string

    Códigos de advertencia: profile_missing, los datos de la empresa de la organización no están configurados, por lo que la dirección de las facturas es in de forma predeterminada; catalog_missing, el directorio de empresas no está cargado; fx_rate_missing, algunos importes no tienen tipo de cambio (conversion.unconverted); fx_rate_stale, algunos tipos están desactualizados; enrichment_pending, algunos documentos todavía se están procesando y no se incluyen en los totales. Muestre un código desconocido con un mensaje genérico.

400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

  • Retry-After

    Número de segundos que hay que esperar antes de reintentar la solicitud.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

503Un servicio del que depende esta solicitud no está disponible temporalmente. Vuelva a intentarlo más tarde.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← finance · Referencia de la API