Batch processing Fiscal documents

How to navigate between the endpoints

The four endpoints form one flow. Generation is asynchronous, so you never get the
documents back from the request that asks for them: you start a process, follow it, and
then read the documents it produced.

1- Create Fiscal Documents process which returns and id to be used on step 2.

1.2 - Webhook notification

2- Get Fiscal Document Process result status and results[].fiscal_document_ids to be used on step 3

3- Get a Fiscal Document

4- [Optional] Get the Fiscal Document transactions

Step by step

1. Generate. Call POST /documents/fiscal-documents with a period
   (start_date + end_date) or a list of transactions. The response is 201 with
   { "id": "..." }: the id of the process, not of a document. Send external_id if you
   want to look the process up later with your own reference.
2. Follow the process. Call GET /documents/fiscal-documents/{id} with that id until
   status is completed or failed. Each entry in results is one owner/counterpart pair
   with its own status (pending, success, failed, skipped), so a process can be
   completed and still contain failed pairs. Read error on those. A process with
   nothing to generate is created already completed with an empty results.
3. Read the documents. For every success result, take the ids in fiscal_document_ids
   and call GET /fiscal-documents/{id}. The response has a signed URL to download the
   file (signedUrl or files[].file_url, depending on the type). Signed URLs expire, so
   fetch the document again when you need a fresh link instead of storing the URL.
4. Drill into transactions (optional). Call GET /fiscal-documents/{id}/transactions
   with the document id to see which transactions it covers. It is paginated (page,
   limit, up to 100), so use it for documents with many transactions.

Moving between documents

A document can point to others. Take an id
from relatedDocuments[].id and call GET /fiscal-documents/{id} again to follow the
link. Each related document is a full document of its own, with its own file and status.

I have X, I want Y

The external_id you send when generating is stored on the process and on every document
it creates, which is why both "by external id" lookups return arrays: one reference can
match several processes or documents.