Vai al contenuto
Sursa Developers

POST/v1/finance/report

Ottenere un report finanziario di sintesi

finance_report

Restituisce i totali delle fatture o dei pagamenti dell’organizzazione, raggruppati per un massimo di tre dimensioni (categoria, gruppo, settore di attività del fornitore, fornitore, acquirente, controparte, direzione, valuta, mese, trimestre, anno), con le misure invoiced, paid, unpaid e tax. I totali includono solo i documenti visibili all’utente (le raccolte e le categorie del suo profilo dati e l’impostazione “rispondere solo in base alle schede verificate”); i filtri della richiesta restringono questo perimetro ma non lo ampliano mai.

In modalità reporting (predefinita) gli importi vengono convertiti nella valuta di rendicontazione dell’organizzazione al tasso della data del documento, e gli importi senza tasso sono elencati in conversion.unconverted. In modalità original gli importi in valute diverse non vengono sommati e la valuta diventa una dimensione della riga. Se le righe sono più di limit, truncated è true e totals copre comunque tutte le righe. Richiede un profilo dati con accesso ai dati finanziari (finance.forbidden).

Il report, gli elenchi di fatture e pagamenti e le loro esportazioni sono operazioni di lettura anche se usano POST: sono disponibili in modalità “View as” e per le chiavi API con l’ambito read (e, come prima, per le chiavi con l’ambito write).

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di intestazione

  • X-View-Asstring

    Solo per le chiavi API con il ruolo admin. Esegue la richiesta come il profilo dati <profile>[:viewer|verifier|editor], ad esempio employee:viewer. La chiave di installazione non può usare questa intestazione (403).

Parametri cookie

  • kb_view_asstring

    Cookie della modalità “View as” per una sessione. POST /auth/view-as lo imposta e DELETE /auth/view-as lo cancella.

Corpo della richiesta

application/json

Oggetto: FinanceReportRequest

  • basisstring

    invoices: fatture, note di credito e ricevute. payments: il registro dei pagamenti (flusso di cassa). Con payments l’unica misura è paid, e la dimensione direction e il totale mostrano il movimento del denaro, in o out, mentre un trasferimento tra le tue persone giuridiche è internal.

    Valori ammessi: invoicespayments

    Predefinito: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Per impostazione predefinita invoiced (paid per payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Quale data determina il periodo e il filtro from/to: la data del documento o la data del pagamento.

    Valori ammessi: documentpayment

    Predefinito: "document"

  • filtersFinanceFilter
  • order_bystring

    Misura o dimensione per l’ordinamento. Per impostazione predefinita, la prima misura in ordine decrescente.

  • order_descboolean

    Predefinito: true

  • limitinteger

    Predefinito: 1000≥ 1, ≤ 10000

  • languagestring

    Lingua delle etichette di categorie e gruppi, en|ru. Per impostazione predefinita en.

Risposte

200Il report

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: FinanceReport

  • currency_modeFinanceCurrencyModeobbligatorio
  • currencystring

    Valuta di rendicontazione (modalità reporting).

  • rowsarray of FinanceReportRowobbligatorio
  • totalsarray of FinanceReportTotalobbligatorio

    Totali su tutte le righe prima del troncamento, un elemento per valuta (in un report suddiviso per direzione, per valuta e direzione, FinanceReportTotal.direction).

  • truncatedbooleanobbligatorio
  • limitintegerobbligatorio
  • total_rowsintegerobbligatorio

    Numero di righe raggruppate prima del troncamento.

  • conversionFinanceConversion
  • warningsarray of string

    Codici di avviso: profile_missing, i dati aziendali dell’organizzazione non sono impostati, quindi la direzione delle fatture è in per impostazione predefinita; catalog_missing, l’anagrafica delle aziende non è caricata; fx_rate_missing, alcuni importi non hanno un tasso di cambio (conversion.unconverted); fx_rate_stale, alcuni tassi non sono aggiornati; enrichment_pending, alcuni documenti sono ancora in elaborazione e non sono inclusi nei totali. Mostra un codice sconosciuto con un messaggio generico.

400La richiesta non è valida: il valore di un parametro o lo stato dell’oggetto non consente l’azione (`detail` è un messaggio).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

  • Retry-After

    Numero di secondi da attendere prima di ripetere la richiesta.

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

503Un servizio da cui dipende questa richiesta non è temporaneamente disponibile. Riprova più tardi.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Nuovi tentativi sicuri

Invia un’intestazione Idempotency-Key (per esempio un UUID) con ogni POST e PATCH. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la risposta salvata invece di eseguire di nuovo la richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← finance · Riferimento API