The Spanish version is the authoritative reference. View in Spanish

How does the Docupath integration work?

Gosocket uses Docupath as its Intelligent Document Processing (IDP) engine: it sends tax PDFs to the Finn vertical pipeline, Docupath interprets them with AI without templates, extracts the structured data, and returns it to Gosocket in native XML format ready for the tax pipeline.

General architecture

The integration consists of three mechanisms: two flows that operate over different APIs with different authentication (① and ②), and a third one (③) that reuses the same API and authentication as Flow ① to poll for the result. Flow ③ is the integration's automatic process; Flow ② is simply a manual contingency for when someone approves the document by hand in the Docupath portal. Gosocket generates external_id and batch_id when sending the PDF (Flow ①); Docupath stores them and returns them unchanged as externalId + batchId in the response ZIP (Flow ②) — or Gosocket retrieves them directly by querying the status (Flow ③), closing the traceability loop through either path.

The flows

Flow ① always happens: Gosocket sends the document. To get the result there are two paths: Flow ② is a manual contingency — it depends on someone approving the document in the Docupath portal — and Flow ③ is the automatic process, where Gosocket obtains the result on its own without depending on that approval.

Not all of them share authentication or endpoint

Flow ① uses OAuth 2.0 against the Docupath API. Flow ② uses Basic Auth against the Gosocket API. Flow ③ reuses the API and the access_token from flow ① — it isn't a new integration, it's a different way of consuming the same API.

Flow ① — Gosocket → Docupath

Gosocket acts as a client of the Docupath API. It sends the tax PDF and its metadata; Docupath processes it with AI and delivers the result back via flow ② (UploadZipDocument).

1. Authentication

Gosocket obtains an access_token via OAuth 2.0 Client Credentials (POST /v1/oauth/token). The token expires in ~1 hour and can be renewed with the refresh_token.

2. Sending the document

POST /v1/documents — multipart/form-data with the PDF (file) and the metadata (external_id + organization client_id). Gosocket generates the external_id for traceability.

3. AI processing

Docupath extracts data with the Finn (finance) vertical: duplicates, price variance, business rules. The status moves from uploaded → processing → approved / rejected.

4. Delivery

Docupath packages the resulting XML + the original PDF and delivers them to Gosocket via UploadZipDocument (flow ②). Documents with errors are managed from the Docupath private portal.

Step 1 — AuthenticationPOSTObtains the OAuth 2.0 access_token. Credentials from the Docupath portal.Step 2 — Send documentPOSTPOST /v1/documents with the PDF, external_id and batch_id.Step 3 — Processing and deliveryProcessDocupath processes with AI and delivers the result to Gosocket via flow ②.

Flow ② — Docupath → Gosocket (manual contingency)

Gosocket receives the processed document through the UploadZipDocument endpoint. Once the AI engine completes processing and someone approves it manually in the Docupath portal, Docupath packages the result (XML + original PDF) into a .zip and delivers it to Gosocket. Because it depends on that manual approval, this flow is only a contingency, not the integration's automatic mechanism — that role belongs to Flow ③, described next.

1. Authentication

Basic Auth with credentials assigned by Gosocket to Docupath (a Username + Password pair, one per environment). There is no token-issuing flow; the credentials go on every request.

2. Preparing the ZIP

The .zip must contain exactly one XML and one PDF with the same base name. The XML must be in Gosocket native format. The content is Base64-encoded to send as a string in the JSON body.

3. Sending to Gosocket

POST /api/v1/UploadZipDocument — JSON body with country, externalId, batchId, fileBase64 (Base64 ZIP), fileExt="zip" and fileName. Gosocket registers the document and returns the status.

4. Correlation

Gosocket generates externalId and batchId in Flow ① and Docupath returns them unchanged. They must stay the same across retries so as not to break end-to-end traceability.

Step 1 — AuthenticationBasic AuthCredentials assigned by Gosocket to Docupath, one per environment.Step 2 — Prepare the ZIPProcessPackage XML + PDF with the same base name, encode in Base64.Step 3 — Send the documentPOSTPOST /api/v1/UploadZipDocument with the Base64 ZIP, externalId and batchId.

Flow ③ — Periodic polling — automatic process

Gosocket queries the document's status directly against the Docupath API, instead of waiting for Flow ② to deliver it. It exists because the transition to approved requires that manual review — autoreview doesn't behave reliably (Docupath Help Center) — and testing showed that the XML and PDF are already available from the pending_review state, before any manual approval, which lets polling resolve the document without human intervention.

1. Authentication

Reuses the OAuth 2.0 access_token obtained in Flow ①. No additional credentials or endpoint required.

2. Polling

GET /v1/documents/search?external_id={id} every 5 minutes, up to 10 retries (~50 minutes) per document.

3. Evaluation

If current_status is pending_review or approved and processed_info carries the XML, it is considered resolved. If it is uploaded or processing, it retries. If it is rejected/expired, or retries run out, an error is flagged in the monitoring table.

4. Retrieval

processed_info delivers the processed XML directly in the response. file_url delivers a signed URL (with expiration) to download the original PDF.

Step 1 — AuthenticationOAuth 2.0Reuses the Flow ① access_token.Step 2 — Poll periodicallyGETGET /v1/documents/search every 5 minutes, max. 10 retries.Step 3 — Obtain XML and PDFProcessExtract processed_info and download file_url.

Document lifecycle

Where to go next

Gosocket → DocupathFlowStep-by-step process: OAuth 2.0 authentication, sending the PDF and delivery of the result.Docupath → GosocketFlowManual contingency: preparing the ZIP and delivering the processed document when someone approves it by hand in the portal.Periodic pollingFlowAutomatic process: reuses the access_token, polls every 5 minutes and extracts the XML and PDF without manual intervention.APIsReferenceFull technical reference of the four methods: authentication, parameters, examples and errors.