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": "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 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-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_ident5805u0178501debtor ident
customer_ident105h3439339customer address ident
typeinvoiceinvoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, depositinvoice or depositinvoicecancellation
statusinvoicedinvoiced or completed
next_status_timestamp154936800the timestamp at which to send the next reminder
outstanding119the 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
business_segment_identsegment-1the 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_reasonCORRECTIONempty, CORRECTION, CANCELLATION
related_invoice_ident1234invoice 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 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-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_ident5805u0178501debtor ident
customer_ident105h3439339customer address ident
typeinvoiceinvoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, depositinvoice or depositinvoicecancellation
statusinvoicedinvoiced, reminded1, reminded2, reminded3, reminded4 or completed
next_status_timestamp154936800the timestamp at which 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
business_segment_identsegment-1the 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 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-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_ident5805u0178501debtor ident
customer_ident105h3439339customer address ident
typeinvoiceinvoice, creditmemo, creditmemo_goodwill, creditmemo_warranty, 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
business_segment_identsegment-1the 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/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'