Overview

HTTP verbs

B2BWrite tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

B2BWrite tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The requested resource requires authentication

403 Forbidden

You have no permission on requested resource

404 Not Found

The requested resource did not exist

500 Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request

502 Bad Gateway

The server, while acting as a gateway or proxy, received an invalid response from the upstream server

Headers

Every request should have the following headers:

Name Description

Accept-Language

Advertises which languages the client is able to understand, and which locale variant is preferred

Authorization

TS Digital access token (e.g. Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.Et9HFtf9R3GEMA0IICOfFMVXY7kkTX1wr4qCyhIf58U)

User-Agent

User agent string (e.g. Lynfa/5.0 (Windows NT x.y; rv:10.0) Paghe/1.0)

X-App-Namet

Caller application name (e.g. TS000)

X-App-Version

Caller application version (e.g. 1.0.2)

Optional headers:

Name Description

X-Correlation-ID

Multiple x-request-id correlation identifier (e.g 6a83ff97-ac20-47c8-bbe3-1f3319cf9aa6)

X-Item-ID

TS Digital item identifier that made the request

X-Manager-ID

TS Digital item identifier that manages the one provided in x-item-id

X-Request-ID

Unique request identifier (e.g. cjqqbbezk139w08878awoj1p0)

X-User-ID

Identifier of local TS Digital user making the request

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

status

String

Http Status description

code

String

Http Status code

timestamp

String

Response time as ISO date string

message

String

Error description

For example, a request that attempts to apply a non-existent tag to a note will produce a 400 Bad Request response:

{
    "status": "BAD_REQUEST",
    "code": "400",
    "timestamp": "02-12-2019 21:00:25",
    "message": "E' necessario filtrare per ownerId",
    "subErrors": null
}

Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

Invoices v2

Elenco delle API di scrittura per l’invio e l’aggiornamento delle fatture. Le API v1 sono deprecate e verranno dismesse.

Upload fattura

Upload fattura. A differenza delle API v1 l’upload di un xml non valido rispetto allo schema xsd avrà come riposta un errore 400 (la fattura non viene quindi salvata su TSDigital). Per i flussi SDIPA, SDIPR e SELFINV verranno effettuati anche i controlli SdI e il mancato superamento impedirà l’upload con un errore 400. E' quindi importante gestire correttamente gli errori in risposta poichè in futuro questi controlli potrebbero essere estesi. Per le fatture SELFSEND è possibile aggiungere al payload gli xml delle notifiche SdI.

Request Fields

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/upload/request-fields.adoc[]

Response Fields

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/upload/response-fields.adoc[]

Sample Request

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/upload/http-request.adoc[]

Sample Response

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/upload/http-response.adoc[]

CURL sample

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/upload/curl-request.adoc[]

Aggiunta notifiche ad una fattura

L’aggiunta notifiche ad una fattura è utilizzabile solo per fatture con flusso SELFSEND. Vengono effettuati controlli sulla coerenza del nome file specificato al momento dell’upload della fattura su TSDigital, sul nome file delle notifiche e sul loro contenuto. Il mancato superamento dei controlli avrà come risposta un errore 400.

Request Fields

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/addNotification/request-fields.adoc[]

Sample Request

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/addNotification/http-request.adoc[]

Sample Response

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/addNotification/http-response.adoc[]

CURL sample

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/addNotification/curl-request.adoc[]

Conferma download

Conferma download (Solo per i flussi abilitati).

Sample Request

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/confirmDownload/http-request.adoc[]

Sample Response

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/confirmDownload/http-response.adoc[]

CURL sample

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/confirmDownload/curl-request.adoc[]

Accetazione fattura

Accetazione fattura SDIPA passiva (è necessario prima aver effettuato la conferma di download).

Sample Request

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/acceptInvoice/http-request.adoc[]

Sample Response

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/acceptInvoice/http-response.adoc[]

CURL sample

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/acceptInvoice/curl-request.adoc[]

Rifiuto fattura

Rifiuto fattura SDIPA passiva (è necessario prima aver effettuato la conferma di download).

Request Fields

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/rejectInvoice/request-fields.adoc[]

Sample Request

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/rejectInvoice/http-request.adoc[]

Sample Response

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/rejectInvoice/http-response.adoc[]

CURL sample

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/rejectInvoice/curl-request.adoc[]

Invio fattura a F@W

Invio fattura a F@W. Utilizzabile solo per fatture SDIPR attive che rispettano le specifiche definite da F@W.

Sample Request

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/sendInvoiceToFaw/http-request.adoc[]

Sample Response

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/sendInvoiceToFaw/http-response.adoc[]

CURL sample

Unresolved directive in invoices.adoc - include::/app/target/generated-snippets/invoices/sendInvoiceToFaw/curl-request.adoc[]

Orders v1

Elenco delle API di scrittura per l’invio e l’aggiornamento degli ordini.

Upload ordine

Upload ordine. L’upload di un xml non valido rispetto allo schema xsd avrà come riposta un errore 400 (l’ordine non viene quindi salvato su TSDigital). E' quindi importante gestire correttamente gli errori in risposta.

Request Fields

Unresolved directive in orders.adoc - include::/app/target/generated-snippets/orders/upload/request-fields.adoc[]

Response Fields

Unresolved directive in orders.adoc - include::/app/target/generated-snippets/orders/upload/response-fields.adoc[]

Sample Request

Unresolved directive in orders.adoc - include::/app/target/generated-snippets/orders/upload/http-request.adoc[]

Sample Response

Unresolved directive in orders.adoc - include::/app/target/generated-snippets/orders/upload/http-response.adoc[]

CURL sample

Unresolved directive in orders.adoc - include::/app/target/generated-snippets/orders/upload/curl-request.adoc[]

EReceipts v1

Elenco delle API di scrittura per l’invio di corrispettivi.

Upload corrispettivi

Upload corrispettivi. L’upload di un xml non valido rispetto allo schema xsd avrà come riposta un errore 400 (l’ordine non viene quindi salvato su TSDigital). E' quindi importante gestire correttamente gli errori in risposta.

Request Fields

Unresolved directive in ereceipts.adoc - include::/app/target/generated-snippets/ereceipts/upload/request-fields.adoc[]

Response Fields

Unresolved directive in ereceipts.adoc - include::/app/target/generated-snippets/ereceipts/upload/response-fields.adoc[]

Sample Request

Unresolved directive in ereceipts.adoc - include::/app/target/generated-snippets/ereceipts/upload/http-request.adoc[]

Sample Response

Unresolved directive in ereceipts.adoc - include::/app/target/generated-snippets/ereceipts/upload/http-response.adoc[]

CURL sample

Unresolved directive in ereceipts.adoc - include::/app/target/generated-snippets/ereceipts/upload/curl-request.adoc[]