GetDocument

Queries the status and metadata of a document registered on the Gosocket platform for Brazil.

Endpoint

QAhttps://developers-sbx.gosocket.net/api/v1/Document/GetDocument

PRODUCTIONhttps://developers.gosocket.net/api/v1/Document/GetDocument

Method: POST

Date range limits

• The maximum period between DateFrom and DateTo is 1 month.
• Year ranges that span different years are not allowed (e.g. December to January is not valid).

Input parameters

AtributoTipoDescripción

CountrystringCountry code. Always "br" for Brazil. Required.

SenderCodestringCNPJ of the document issuer. Required.

GlobalDocumentIdstringUnique global identifier of the document on Gosocket. Optional — if provided, date filters are not required. If not used, send an empty string or omit it.

DateFromstringIssue date from. Required when GlobalDocumentId is not specified. Accepted formats: "yyyy-MM-dd" or "yyyy-MM-ddTHH:mm:ss".

DateTostringIssue date to. Required when GlobalDocumentId is not specified. Same formats as DateFrom.

ReceiverCodestringCNPJ of the receiver. Optional — additional filter to narrow results.

DocumentTypeIdstringSEFAZ fiscal document type code as string. Optional. Example: "55" (NF-e), "57" (CT-e), "58" (MDF-e). Note: this is the fiscal code, different from the Gosocket internal integer code (1, 2, 3…) used in other API contexts.

ResultMaxItemCountnumberMaximum number of documents to return. Optional. Default: 10. Maximum: 100.

ContinuationTokenstringPagination token from the previous response. Optional. Include to retrieve the next page of results.

CountryDocumentIdstringChave de acesso of the document. Optional — filter by exact fiscal identifier.

ExternalIdstringProtocolSefaz of the document. Optional — useful to locate a document by its SEFAZ protocol.

DocumentTagValuesobjectFilter documents by tag value. Optional. Example: {"AuthorityStatus": "2"} to get only authorized documents; {"AuthorityStatus": "3"} for only rejected ones.

Response parameters

The response contains three root fields: Documents (array of found documents), ContinuationToken (opaque pagination token — pass as-is in the next request; null if there are no more results) and Description (e.g. "Cantidad de documentos encontrados 5").

Each object in Documents contains:

AtributoTipoDescripción

UrlPdfstringPDF download URL. Only present when the functionality is enabled for the TaxID (not default — must be requested from the Integrations team). Only present when AuthorityStatus is "2".

UrlXmlstringFiscal XML download URL. Same conditions as UrlPdf.

GlobalDocumentIdstringUnique global identifier of the document on the Gosocket platform.

CountryDocumentIdstringChave de acesso (44 digits for NF-e/CT-e/MDF-e; SHA-256 hash for NFS-e).

ExternalIdstringTax authority identifier: ProtocolSefaz for NF-e/CT-e/MDF-e; NFS-e number assigned by the Prefeitura for NFS-e. Populated when the document was authorized; empty string when rejected.

CountryIdstringCountry code. Always "br" for Brazil.

DatestringDocument issue date. ISO 8601 format: "yyyy-MM-ddTHH:mm:ss".

DocumentTypeIdnumberNumeric document type code. Example: 55 (NF-e), 57 (CT-e), 58 (MDF-e), 551 (NFS-e).

DocumentTypeNamestringDescriptive name of the document type. Example: "Nota Fiscal Eletrônica".

TotalAmountnumberTotal value of the document in the currency indicated by CurrencyType.

CurrencyTypestringDocument currency. Always "BRL" for Brazil.

SeriesNumberstringConcatenation of series and number. Example: "170318" (series 1, number 70318).

SeriesstringDocument series.

NumbernumberDocument number (folio).

DocumentSenderCodestringCNPJ of the document issuer.

DocumentSenderNamestringLegal name of the issuer.

DocumentReceiverCodestringCNPJ of the receiver. May be empty for export documents.

DocumentReceiverNamestringLegal name of the receiver.

DocumentTimeStampstringProcessing timestamp in Gosocket. ISO 8601 UTC format (with Z).

AuthorityTimeStampstringTax authority response timestamp. ISO 8601 without timezone (Brazil local time, UTC-3). May be `null` when the status was not determined by the authority (e.g. uploaded documents with status 6).

SyncPointstringSync point GUID — corresponds to the ID of the API account that sent the document.

DocumentTagsarrayStatus and traceability tags. Each element has Code, TimeStamp and Value. The tag with Code "AuthorityStatus" contains the fiscal status (see table below). Other frequent tags (list may vary): "tpEmis", "DocumentOrigin", "DistributionSender", "DistributionReceiver", among others.

NotesarrayProcessing history. The number of entries varies by flow. Each element has: Mandatory (boolean — true indicates a blocking error), Code (SEFAZ cStat when Source is "NDD"; may be a GUID or other identifier for other Sources), Note (event description), Source ("NDD" for API flow, "Gosocket" for direct upload flow with codes like "Upload" and "NoRetries", "Distribution Process" / "Servidor de Correo Distribución" for distribution events), TimeStamp and Detail.

FieldsarrayAdditional document fields. The array may contain zero or more elements. For Brazil via NDD it typically includes an element with Code "AdditionalDataNDD" whose Value is a serialized JSON. For NF-e/CT-e/MDF-e it contains: MunicipalCode, EmissionType, protocolSefaz, documentKey, emissionCode and version (may be empty for CT-e/MDF-e). The `protocol` field (NDD GUID) is only present when the document was processed via SendDocumentToAuthority; absent for uploaded documents. For NFS-e it contains: MunicipalCode, protocol, protocolSefaz (NFS-e number) and documentKey (may be empty depending on the municipality).

AuthorityStatus values

Code	Status	Corresponding NDD Notes.Code
0	To be sent	—
1	Sent	—
2	Authorized	NF-e/CT-e/MDF-e: "100" (on time) or "150" (fora de prazo) — NFS-e: "45"
3	Rejected	"225", "228", "745", "999" or other SEFAZ cStat
4	Voided	—
5	Error	—
6	Unresolved	—
7	Voided (Inutilizado)	—
8	Denied	—

Examples

GetDocument

{
"Country": "br",
"SenderCode": "00000000000100",
"DateFrom": "2026-06-01",
"DateTo": "2026-06-30",
"DocumentTypeId": "55",
"ResultMaxItemCount": 10,
"GlobalDocumentId": ""
}

Notes

AuthorityStatus in DocumentTags

The fiscal status is not a top-level field — it lives inside the DocumentTags array as the object whose Code is "AuthorityStatus". The Value field contains the numeric code (single digit: "2", "3", etc.).

Status "2" (Authorized) can originate from Notes.Code: "100" (on time) or "150" (fora de prazo) — both produce the same AuthorityStatus.

Status "6" (Unresolved) means the system could not determine the status after exhausting query retries. It mainly occurs in documents uploaded via Upload. Notes will show Source: "Gosocket" with Code: "NoRetries" in these cases.

XML and PDF download

The UrlPdf and UrlXml fields appear in the response when the functionality is enabled for the TaxID (not the default behaviour — must be requested from the Integrations team). Only available when the document has AuthorityStatus: "2".

As an always-available alternative (no activation required), files can be downloaded with the endpoints:

• GET /api/v1/File/DownloadDocumentXml?GlobalDocumentId=<id> — approved XML
• GET /api/v1/File/DownloadDocumentPdf?GlobalDocumentId=<id>&Type=default — PDF

Notes: reading the final result

To determine the result of an NDD transaction, iterate the Notes array and locate the last entry with Source: "NDD" that represents the result of the tax authority query. If it has Mandatory: true, it is a blocking error (rejection); if the Code is "100" or "150", the document was authorized. Intermediate entries with Code: "200" and Source: "NDD" are internal NDD processing steps, not the final result. Entries with other Source values record subsequent distribution events and may or may not appear depending on the TaxID configuration.