Elencare e cercare le fatture ricevute
- Nella sandbox
Dalla 0.35.0. Gli stessi parametri e la stessa risposta di GET /invoices, solo per le fatture ricevute; state è
received, validated o validation_failed. Una chiave cliente vede quelle del proprio cliente; l’operatore quelle di ogni cliente, oppure
quelle di un cliente con client.
apiKeyAuthorizationBearer <token>Inviare la chiave come token bearer: Authorization: Bearer <your-api-key>. Lo stato del servizio è l’unica chiamata che non richiede una chiave.
q?stringlength <= 100route?array<>state?array<>client?string^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$received_from?stringdatereceived_to?stringdatesort?string"newest""newest""oldest"page?integer1 <= value1page_size?integer252550100200Una pagina di risultati.
application/json- response
data*array<>total*integerpage*integerpage_size*integercounts_by_state*curl -X GET "https://example.com/received" \ -H "Authorization: Bearer <your-api-key>"{ "data": [ { "id": "string", "invoice_ref": "string", "invoice_number": "string", "route": "PEPPOL", "client": "string", "environment": "sandbox", "state": "received", "direction": "in", "rail_id": "string", "document_sha256": "string", "duplicate_of": "string", "links": { "self": "string", "events": "string" }, "errors": [ { "code": "string" } ], "documents": [ { "kind": "received-xml", "sha256": "string", "href": "string" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "total": 0, "page": 0, "page_size": 0, "counts_by_state": { "property1": 0, "property2": 0 }}Elencare gli eventi di stato di una fattura ricevuta GET
Dalla 0.35.0. Gli stessi eventi che consegna il webhook, in ordine di sequenza, ciascuno con direction in.
Consegnare una fattura che il cliente ha ricevuto tramite un canale POST
Dalla 0.35.0 (17 ott. 2026). Il corpo è l’XML esattamente come l’ha consegnato il canale (UBL, CII o FA(3)); nulla viene modificato e nulla viene inviato. Il file viene prima conservato, sigillato con la chiave dati del cliente, perché per legge è già ricevuto; poi i validatori del canale lo controllano, come per un invio pass-through, e il risultato arriva come evento di stato (received, poi validated o validation_failed, con direction: in) sul webhook del cliente e su GET /received/{id}/events. Un file che non supera le regole viene conservato e risulta validation_failed con gli errori; non viene mai scartato. Un file che non è una fattura da conservare viene rifiutato con 422 e non viene memorizzato nulla, come su POST /invoices/xml: un DOCTYPE (EI-XML-DTD, mai analizzato), un XML non ben formato (EI-XML-SYNTAX) oppure un documento che non è una fattura nota al canale (EI-XML-TYPE). Un controllo che non ha potuto essere eseguito (un validatore non raggiungibile) viene ritentato e, dopo l’ultimo tentativo, la fattura passa nell’elenco della Gestione degli scarti e resta received. Un cliente consegna al massimo 120 documenti al minuto e 2.000 al giorno, con qualsiasi chiave (429, non conservato sotto l’Idempotency-Key). Il file viene restituito come download (Content-Disposition: attachment). Un documento del canale è una fattura ricevuta del cliente: per rail_id quando è indicato, per lo SHA-256 del file quando non lo è. Lo stesso documento di nuovo risponde 202 con duplicate_of; lo stesso rail_id con byte diversi risponde 409 received-id-conflict e non viene memorizzato nulla. Le fatture ricevute sono tenute separate dalle fatture che il cliente invia: non compaiono in GET /invoices, nella serie, nelle metriche né nel rapporto mensile, e non bloccano mai un invio dello stesso file. Una fattura ricevuta viene eliminata con la conservazione dei dati del cliente quando non c’è più nulla di aperto su di essa (il suo controllo è terminato, oppure una persona ha gestito la sua riga della Gestione degli scarti), ed è nell’export del cliente sotto received/. Ambito submit; una chiave cliente agisce solo per il proprio cliente.