Overall process to retrieve a document created by the Nitrobox

(such as an invoice)

The goal is to retrieve a document that was created by the Nitrobox:

After creating or archiving a document, Nitrobox sends a notification to a defined endpoint of the customer application (webhook).
The customer application can use the information given in the notification to call the Nitrobox API back again and retrieve the document created.

Notification

The customer application needs to provide an endpoint that can receive notifications from Nitrobox. In the following you can find JSON examples of notifications, Nitrobox will send.

For created:

The invoice object is created in Nitrobox.

{
    "notification_type": "invoice.created",
    "invoice_ident": "oZsPY5tWUHDKYRvR",
    "reference_ident": "q3qhVB9HB4JYXD7J",
    "debtor_ident": "62HllWVs5aCMEgEW",
    "customer_ident": "z5fMvwQLoOr5fTgC",
    "type": "invoice",
    "status": "completed",
    "next_status_timestamp": 5557209325763,
    "outstanding": 119,
    "invoice_total_exclusive_vat": 100,
    "invoice_total_vat": 19,
    "invoice_total_inclusive_vat": 119,
    "currency": "EUR",
    "order_date": 5620102107748,
    "invoice_date": 5620102107748,
    "business_segment_ident": "TLK5dPag",
    "business_segment_idents": ["TLK5dPag"],
    "business_client_id": 4477282,
    "timestamp": 5118603614630,
    "invoice_origin_references": [
        {"reference_type": "ORDER", "reference_ident": "q3qhVB9HB4JYXD7J"}
    ],
    "document_reason": "CORRECTION",
    "related_invoice_ident": "1234"
}

Field Name	Example Value	Description
notification_type	invoice.created	type of the notification (e.g. created, archived)
business_client_id	83	id provided by Nitrobox
timestamp	1549361280	a UTC timestamp
invoice_ident	IdqP1tJ0c9qwpCjV	invoice number
reference_ident	order-1	[Optional] order/contract ident, when only one order is involved. Is empty, when multiple orders are involved. Rather use invoice_origin_references instead
debtor_ident	5805u0178501	debtor ident
customer_ident	105h3439339	customer address ident
type	invoice	invoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, depositinvoice or depositinvoicecancellation
status	invoiced	invoiced or completed
next_status_timestamp	154936800	the timestamp at which to send the next reminder
outstanding	119	the part of the value that is not assigned
invoice_total_inclusive_vat	119.00	invoice total gross amount
invoice_total_exclusive_vat	100.00	invoice total net amount
invoice_total_vat	19.00	invoice total vat amount
currency	EUR	invoice currency
order_date	1549361280	the order date creation timestamp
invoice_date	1549361280	the incoive date creation timestamp
business_segment_ident	segment-1	the ident of the business segment. Is empty, when multiple business segments are involved.
business_segment_idents	[segment-1, segment-2]	possibly multiple business segment idents
invoice_origin_references	[{"reference_type": "ORDER", reference_ident: "IdqP1tJ0c9qwpCjV"}]	possibly multiple invoice origins references, that list the idents of ORDERs or CONTRACTs, that are on this invoice together with a type of the source
document_reason	CORRECTION	empty, CORRECTION, CANCELLATION
related_invoice_ident	1234	invoice number of parent document. Not set if document is a root document (e.g. regular invoice)

For updated:

Changes of invoice lifecycle, for example in the case of dunning or when the document is paid in full.

{
    "notification_type": "invoice.updated",
    "invoice_ident": "oZsPY5tWUHDKYRvR",
    "reference_ident": "q3qhVB9HB4JYXD7J",
    "debtor_ident": "62HllWVs5aCMEgEW",
    "customer_ident": "z5fMvwQLoOr5fTgC",
    "type": "invoice",
    "status": "completed",
    "next_status_timestamp": 5557209325763,
    "outstanding": 6888654.16,
    "invoice_total_exclusive_vat": 100,
    "invoice_total_vat": 19,
    "invoice_total_inclusive_vat": 119,
    "currency": "EUR",
    "order_date": 5620102107748,
    "invoice_date": 5620102107748,
    "business_segment_ident": "TLK5dPag",
    "business_segment_idents": ["TLK5dPag"],
    "business_client_id": 4477282,
    "timestamp": 5118603614630,
    "invoice_origin_references": [
        {"reference_type": "ORDER", "reference_ident": "q3qhVB9HB4JYXD7J"}
    ]
}

Field Name	Example Value	Description
notification_type	invoice.updated	type of the notification (e.g. created, archived)
business_client_id	83	id provided by Nitrobox
timestamp	1549361280	a UTC timestamp
invoice_ident	IdqP1tJ0c9qwpCjV	invoice number
reference_ident	order-1	[Optional] order/contract ident, when only one order is involved. Is empty, when multiple orders are involved. Rather use invoice_origin_references instead
debtor_ident	5805u0178501	debtor ident
customer_ident	105h3439339	customer address ident
type	invoice	invoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, depositinvoice or depositinvoicecancellation
status	invoiced	invoiced, reminded1, reminded2, reminded3, reminded4 or completed
next_status_timestamp	154936800	the timestamp at which to send the next reminder
outstanding	612.12	the part of the value that is not assigned
invoice_total_inclusive_vat	119.00	invoice total gross amount
invoice_total_exclusive_vat	100.00	invoice total net amount
invoice_total_vat	19.00	invoice total vat amount
currency	EUR	invoice currency
order_date	1549361280	the order date creation timestamp
invoice_date	1549361280	the incoive date creation timestamp
business_segment_ident	segment-1	the ident of the business segment. Is empty, when multiple business segments are involved.
business_segment_idents	[segment-1, segment-2]	possibly multiple business segment idents
invoice_origin_references	[{"reference_type": "ORDER", reference_ident: "IdqP1tJ0c9qwpCjV"}]	possibly multiple invoice origins references, that list the idents of ORDERs or CONTRACTs, that are on this invoice together with a type of the source

For archived:

A PDF is created out of the invoice object and is stored at Nitrobox Archive System. In the future, we might differ between pdf created and archived.

{
    "notification_type": "invoice.archived",
    "invoice_ident": "nmSnRG0Rcyh19gTK",
    "reference_ident": "IdqP1tJ0c9qwpCjV",
    "debtor_ident": "2FcR8i6CuUnBIm0g",
    "customer_ident": "qzqEPFvpRFQcy4Us",
    "type": "invoice",
    "invoice_total_exclusive_vat": 100,
    "invoice_total_vat": 19,
    "invoice_total_inclusive_vat": 119,
    "currency": "USD",
    "order_date": 5620102107748,
    "invoice_date": 5620102107748,
    "business_segment_ident": "TLK5dPag",
    "business_segment_idents": ["TLK5dPag"],
    "business_client_id": 4572479,
    "timestamp": 5578911494372,
    "invoice_id": 4444,
    "invoice_origin_references": [
        {"reference_type": "ORDER", "reference_ident": "IdqP1tJ0c9qwpCjV"}
    ]
}

Field Name	Example Value	Description
notification_type	invoice.archived	type of the notification (e.g. created, archived)
business_client_id	83	id provided by Nitrobox
timestamp	1549361280	a UTC timestamp
invoice_ident	IdqP1tJ0c9qwpCjV	invoice number
invoice_id	1000123	generated invoice id
reference_ident	order-1	[Optional] order/contract ident, when only one order or contract is involved. Is empty, when multiple orders or contracts are involved. Rather use invoice_origin_references instead
debtor_ident	5805u0178501	debtor ident
customer_ident	105h3439339	customer address ident
type	invoice	invoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, depositinvoice or depositinvoicecancellation
invoice_total_inclusive_vat	119.00	invoice total gross amount
invoice_total_exclusive_vat	100.00	invoice total net amount
invoice_total_vat	19.00	invoice total vat amount
currency	EUR	invoice currency
order_date	1549361280	the order date creation timestamp
invoice_date	1549361280	the incoive date creation timestamp
business_segment_ident	segment-1	the ident of the business segment. Is empty, when multiple business segments are involved.
business_segment_idents	[segment-1, segment-2]	possibly multiple business segment idents
invoice_origin_references	[{"reference_type": "ORDER", reference_ident: "IdqP1tJ0c9qwpCjV"}]	possibly multiple invoice origins references, that list the idents of ORDERs or CONTRACTs, that are on this invoice together with a type of the source

Call Nitrobox File-Endpoint to retrieve document

After receiving the notification the customer application can use the invoice_ident and business_client_id to receive the file.
Example call:

curl --request GET \
  --url 'https://stage-api.nitrobox.eu/v2/files/1000000003?83=' \
  --header 'Accept: */*' \
  --header 'Authorization: Bearer qYUppwXtlPGVjRL2WVexO3g1HxsiogRw' \
  --header 'Cache-Control: no-cache' \
  --header 'Connection: keep-alive' \
  --header 'Host: stage-api.nitrobox.eu' \
  --header 'accept-encoding: gzip, deflate' \
  --header 'cache-control: no-cache'