POST/v1/finance/report

Obtenir un informe financer resumit

finance_report

Retorna els totals de les factures o dels pagaments de l’organització, agrupats per un màxim de tres dimensions (categoria, grup, tipus d’activitat del proveïdor, proveïdor, comprador, contrapart, direcció, moneda, mes, trimestre, any), amb les mesures invoiced, paid, unpaid i tax. Els totals només inclouen els documents visibles per a l’usuari (les col·leccions i les categories del seu perfil de dades, i la configuració «respondre només a partir d’entrades verificades»); els filtres de la sol·licitud restringeixen aquest abast, però mai no l’amplien.

En el mode reporting (per defecte), els imports es converteixen a la moneda dels informes de l’organització amb el tipus de canvi de la data del document, i els imports sense tipus de canvi es llisten a conversion.unconverted. En el mode original, els imports en monedes diferents no se sumen, i la moneda passa a ser una dimensió de la fila. Si hi ha més files que limit, truncated és true, i totals continua cobrint totes les files. Requereix un perfil de dades amb accés a les dades financeres (finance.forbidden).

L’informe, les llistes de factures i de pagaments i les seves exportacions són operacions de lectura tot i que fan servir POST: estan disponibles en mode «View as» i per a les claus d’API amb l’àmbit read (i, com abans, per a les claus amb l’àmbit write).

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de capçalera

X-View-Asstring
Només per a claus d’API amb el rol admin. Fa la sol·licitud com el perfil de dades <profile>[:viewer|verifier|editor], per exemple employee:viewer. La clau d’instal·lació no pot fer servir aquesta capçalera (403).

Paràmetres de galeta

kb_view_asstring
Galeta del mode «View as» per a una sessió. POST /auth/view-as l’estableix i DELETE /auth/view-as l’esborra.

Cos de la sol·licitud

application/json

Objecte: FinanceReportRequest

basisstring
invoices: factures, notes d’abonament i rebuts. payments: el registre de pagaments (flux de caixa). Amb payments, l’única mesura és paid, i la dimensió direction i el total mostren el moviment de diners, in o out, mentre que una transferència entre les vostres pròpies persones jurídiques és internal.
Valors permesos: invoicespayments
Per defecte: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
Per defecte, invoiced (paid per a payments).
currency_modeFinanceCurrencyMode
date_basisstring
Data que defineix el període i el filtre from/to: la data del document o la data del pagament.
Valors permesos: documentpayment
Per defecte: "document"
filtersFinanceFilter
order_bystring
Mesura o dimensió per ordenar. Per defecte, la primera mesura en ordre descendent.
order_descboolean
Per defecte: true
limitinteger
Per defecte: 1000≥ 1, ≤ 10000
languagestring
Llengua de les etiquetes de categories i grups, en|ru. Per defecte, en.

Respostes

200L’informe

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: FinanceReport

currency_modeFinanceCurrencyModeobligatori
currencystring
Moneda dels informes (mode reporting).
rowsarray of FinanceReportRowobligatori
totalsarray of FinanceReportTotalobligatori
Totals de totes les files abans del truncament, un element per moneda (en un informe desglossat per direcció, per moneda i direcció, FinanceReportTotal.direction).
truncatedbooleanobligatori
limitintegerobligatori
total_rowsintegerobligatori
Nombre de files agrupades abans del truncament.
conversionFinanceConversion
warningsarray of string
Codis d’avís: profile_missing, les dades de l’empresa de l’organització no estan definides, de manera que la direcció de les factures és in per defecte; catalog_missing, el directori d’empreses no està carregat; fx_rate_missing, alguns imports no tenen tipus de canvi (conversion.unconverted); fx_rate_stale, alguns tipus estan desfasats; enrichment_pending, alguns documents encara s’estan processant i no s’inclouen als totals. Mostreu un codi desconegut amb un missatge genèric.

400La sol·licitud no és vàlida: el valor d’un paràmetre o l’estat de l’objecte no permeten l’acció (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

Retry-After
Nombre de segons que cal esperar abans de reintentar la sol·licitud.
RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

503Un servei del qual depèn aquesta sol·licitud no està disponible temporalment. Torneu-ho a provar més tard.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Reintents segurs

Envieu una capçalera Idempotency-Key (per exemple, un UUID) amb cada POST i PATCH. Un reintent amb la mateixa clau en un termini de 24 hores retorna la resposta desada en lloc de tornar a executar la sol·licitud.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← finance · Referència de l’API

curl -X POST 'https://api.sursa.com/v1/finance/report' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"basis":"invoices","group_by":["category"],"measures":["invoiced"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Provar

Clau d’API

La clau es queda a la memòria d’aquesta pestanya i només s’envia a https://api.sursa.com.

Les sol·licituds actuen sobre les dades reals de la vostra organització.

X-View-As header

Idempotency-Key

Si és buit, es genera una clau nova per a cada sol·licitud.

Cos de la sol·licitud (JSON)