Centro assistenzaIntegrazioni

Per: Amministratori

Leggi le fatture con una chiave di gestione

Elenca le fatture pubblicate dal tuo hub e leggine una, con i relativi importi, pagamenti e rimborsi, per la tua contabilità o per la redazione di report.

In questo articolo4 sezioni

Prima di iniziare

Questa pagina riguarda la lettura delle fatture. I percorsi sono indicati sotto https://prd-api-manage.caseactive.com/v1/<hub id>. Il tool permette di visualizzare tutte le fatture pubblicate, per ogni caso, compresi i casi chiusi; però non è possibile creare, modificare, rimborsare o pagare delle fatture.

Chiamate

ChiamataCosa fa
GET /invoicesLe liste contengono gli estratti dei documenti fiscali, con i dati più recenti in primo piano.
GET /invoices/<case_id>/<invoice_id>Leggo un’fattura.
ParametroCosa faNecessarioPredefinito
statusSolo le fatture che presentano questo stato: open, paid, void, uncollectible o processing.No.Tutti
case_idSolo le fatture relative a un singolo caso.No.Ogni caso è diverso.
limitQuante fatture possono essere presentate su una singola pagina, fino a 1000.No.20
start_keyIl startKey della pagina precedenteNo.Prima pagina

Mentre ci sono ancora delle fatture da processare, chiamare nextLink, oppure inviare i dati tramite startKey e start_key. Questa lista non è filtrata per data, né per il momento in cui una fattura è stata ultimamente modificata. Per scoprire quali modifiche sono state apportate da quando hai effettuato l’ultima sincronizzazione, bisogna cercare nella tabella case_invoices utilizzando filter_by=updated_on:>, seguito dal tempo relativo all’ultima sincronizzazione in secondi Unix. Una modifica viene riconosciuta pochi secondi dopo la sua registrazione; quindi è necessario iniziare ogni ricerca poco prima della fine dell’ultima ricerca. Aggiungi filter_by=refund_status:=succeeded per individuare eventuali rimborso. Per ulteriori informazioni, vedi Ricerca casi e utenti con funzione di gestione.

Una fattura

Ogni importo rappresenta un numero intero espresso in centesimi, in dollari statunitensi: 96300 corrisponde a 963,00 dollari.

{
  "data": {
    "case_id": "cc-1a2b3c4d5e6f70",
    "invoice_id": "invoice::20260915143000_ab12cd34ef5678",
    "host_id": "ca-7e6d5c4b3a2f10",
    "name": "September legal services",
    "description": "Consultation and filing for Jane Sample's claim",
    "invoice_number": "INV-1042",
    "po_number": "PO-778",
    "terms": "Net 15",
    "host_ref_id": "acct-1042",
    "notes": "Thank you for your business.",
    "participants_ids": ["cu-4f1c2a9e8b7d60"],
    "user_id": "cu-9d8c7b6a5f4e30",
    "status": "paid",
    "due_date": "2026-09-30T17:00:00+00:00",
    "transactions": {
      "transactions": [
        {"transaction_type": "charge", "description": "Consultation (hours)", "value": 35000, "quantity": 2, "currency": "usd"},
        {"transaction_type": "charge", "description": "Court filing fee", "value": 30000, "quantity": 1, "currency": "usd"}
      ],
      "discount": 0.1,
      "tax": 0.07
    },
    "subtotal": 100000,
    "discount": 0.1,
    "discount_amount": 10000,
    "discounted_amount": 90000,
    "tax": 0.07,
    "tax_amount": 6300,
    "total": 96300,
    "payment_gateway": "stripe",
    "stripe_payment": {"user_id": "cu-4f1c2a9e8b7d60", "fees": 2863, "stripe_fee": 2823, "application_fee": 40, "net": 93437},
    "payment_attempts": [{"datetime": "2026-09-20T14:05:12+00:00", "success": true, "user_id": "cu-4f1c2a9e8b7d60"}],
    "completed_on": "2026-09-20T14:05:20+00:00",
    "published": 1,
    "created_on": "2026-09-15T14:30:00+00:00",
    "updated_on": "2026-09-20T14:05:20+00:00"
  }
}
CampoCosa contiene
invoice_id, case_idL’fattura, e il contenuto del caso a cui si riferisce l’fattura stessa. Bisogna leggere entrambe le fatture.
name, descriptionIl suo titolo e la sua descrizione
invoice_number, po_number, terms, notes, host_ref_idScritto sulla fattura. host_ref_id è il suo identificatore di riferimento.
participants_idsLe persone a cui viene inviato il messaggio…
user_idChi l’ha creato?
statusopen: in attesa di essere pagato. paid: già pagato online o indicato come pagato. void: annullato. uncollectible e processing: impostati dal proprio personale. paid e void sono valori definitivi.
due_dateQuando è il momento giusto…
transactionsLe sue linee rappresentano: un charge o un credit; inoltre, c’è un description, un value espresso in centesimi, e infine un quantity. Inoltre, vengono applicate delle tasse specifiche.
subtotalI crediti devono essere sottratti dai debiti; il valore totale non può mai essere inferiore a 0.
discount, discount_amount, discounted_amountIl tasso di sconto, espresso come frazione.0.1 È del 10% il sconto in centesimi; il totale dopo il sconto è…
tax, tax_amountLa aliquota fiscale, espressa come frazione0.07 È del 7%). Inoltre, il tributo, espresso in centesimi, si calcola sulla somma dopo la sconto.
totalQuanto è dovuto, in centesimi
payment_gatewayQuando il pagamento avviene online, stripe. Quando invece il personale incaricato conferma che il pagamento è stato effettuato, manual.
stripe_paymentPer un pagamento online: chi ha effettuato il pagamento, quali sono le spese e l’importo netto in centesimi.
payment_attemptsCiascuno cerca di pagare online: quando è riuscito a farlo, e perché no.
refundedUn rimborso, se presente: il valore è espresso in status (pending, succeeded, failed o canceled), amount in centesimi e reason. Lo stato dell’fattura rimane paid.
completed_onQuando il pagamento è stato effettuato o quando l’operazione è stata annullata.

Se una chiamata viene rifiutata

StatomessagePerché
404InvoiceDoesNotExistExceptionNessuna fattura presenta quel codice identificativo su quel caso, nel tuo hub.
400InvoiceNotPublishedExceptionL’fattura è una ricevuta per pagamento.
400SchemaFieldsExceptionstatus non è uno dei cinque.
400InvalidStartKeyExceptionstart_key non faceva parte di questa lista.

Per informazioni sul corpo dell’errore e sugli altri codici, si veda Comunicare gli errori dell’API e i codici di stato.

Articoli correlati

Gestire gli errori e i codici di stato delle APILeggi il corpo dell'errore, cosa significano i codici 400, 401, 403, 404, 500 e 503 e perché un elemento che la tua chiave non riesce a vedere risponde al codice 404.Integrazioni