Retrieve documents from Nitrobox

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:

  1. After creating or archiving a document, Nitrobox sends a notification to a defined endpoint of the customer application (webhook).
  2. 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": "order",
    "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_client_id": 4477282,
    "timestamp": 5118603614630
}
Field NameExample ValueDescription
notification_typeinvoice.createdtype of the notification (e.g. created, archived)
business_client_id83id provided by Nitrobox
timestamp1549361280a UTC timestamp
invoice_identIdqP1tJ0c9qwpCjVinvoice number
reference_identorder-12345order number
debtor_ident5805u0178501debtor ident
customer_ident105h3439339customer address ident
typeinvoiceinvoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, order, depositinvoice or depositinvoicecancellation
statusinvoicedinvoiced or completed
next_status_timestamp154936800the timestamp at wich to send the next reminder
outstanding612.12the part of the value that is not assigned
invoice_total_inclusive_vat119.00invoice total gross amount
invoice_total_exclusive_vat100.00invoice total net amount
invoice_total_vat19.00invoice total vat amount
currencyEURinvoice currency
order_date1549361280the order date creation timestamp
invoice_date1549361280the incoive date creation timestamp
buisiness_segment_identTLK5dPagthe ident of the business segment

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": "order",
    "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_client_id": 4477282,
    "timestamp": 5118603614630
}
Field NameExample ValueDescription
notification_typeinvoice.updatedtype of the notification (e.g. created, archived)
business_client_id83id provided by Nitrobox
timestamp1549361280a UTC timestamp
invoice_identIdqP1tJ0c9qwpCjVinvoice number
reference_identorder-12345order number
debtor_ident5805u0178501debtor ident
customer_ident105h3439339customer address ident
typeinvoiceinvoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, order, depositinvoice or depositinvoicecancellation
statusinvoicedinvoiced, reminded1, reminded2, reminded3, reminded4 or completed
next_status_timestamp154936800the timestamp at wich to send the next reminder
outstanding612.12the part of the value that is not assigned
invoice_total_inclusive_vat119.00invoice total gross amount
invoice_total_exclusive_vat100.00invoice total net amount
invoice_total_vat19.00invoice total vat amount
currencyEURinvoice currency
order_date1549361280the order date creation timestamp
invoice_date1549361280the incoive date creation timestamp
buisiness_segment_identTLK5dPagthe ident of the business segment

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": "order",
    "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_client_id": 4572479,
    "timestamp": 5578911494372,
    "invoice_id": 4444
}
Field NameExample ValueDescription
notification_typeinvoice.archivedtype of the notification (e.g. created, archived)
business_client_id83id provided by Nitrobox
timestamp1549361280a UTC timestamp
invoice_identIdqP1tJ0c9qwpCjVinvoice number
invoice_id1000123generated invoice id
reference_identorder-12345order number
debtor_ident5805u0178501debtor ident
customer_ident105h3439339customer address ident
typeinvoiceinvoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, order, depositinvoice or depositinvoicecancellation
invoice_total_inclusive_vat119.00invoice total gross amount
invoice_total_exclusive_vat100.00invoice total net amount
invoice_total_vat19.00invoice total vat amount
currencyEURinvoice currency
order_date1549361280the order date creation timestamp
invoice_date1549361280the incoive date creation timestamp
buisiness_segment_identTLK5dPagthe ident of the business segment

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/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'