GetDocument

Consulta el estado y metadata de un documento registrado en la plataforma Gosocket para Brasil.

Endpoint

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

PRODUCCIÓNhttps://developers.gosocket.net/api/v1/Document/GetDocument

Método: POST

Límites del rango de fechas

• El período máximo entre DateFrom y DateTo es de 1 mes.
• No se pueden combinar años distintos en el mismo rango (ej.: de diciembre a enero no es válido).

Parámetros de entrada

AtributoTipoDescripción

CountrystringCódigo del país. Siempre "br" para Brasil. Requerido.

SenderCodestringCNPJ del emisor del documento. Requerido.

GlobalDocumentIdstringIdentificador global único del documento en Gosocket. Opcional — si se envía, los filtros de fecha no son necesarios. Si no se usa, enviar cadena vacía o no incluirlo.

DateFromstringFecha de emisión desde. Requerido cuando no se especifica GlobalDocumentId. Formatos aceptados: "yyyy-MM-dd" o "yyyy-MM-ddTHH:mm:ss".

DateTostringFecha de emisión hasta. Requerido cuando no se especifica GlobalDocumentId. Mismos formatos que DateFrom.

ReceiverCodestringCNPJ del receptor. Opcional — filtro adicional para acotar resultados.

DocumentTypeIdstringCódigo fiscal SEFAZ del tipo de documento como string. Opcional. Ejemplo: "55" (NF-e), "57" (CT-e), "58" (MDF-e). Nota: es el código fiscal, distinto del código interno Gosocket (entero 1, 2, 3…) que aparece en otros contextos de la API.

ResultMaxItemCountnumberNúmero máximo de documentos a retornar. Opcional. Valor por defecto: 10. Máximo: 100.

ContinuationTokenstringToken de paginación obtenido de la respuesta anterior. Opcional. Incluir para obtener la siguiente página de resultados.

CountryDocumentIdstringChave de acesso del documento. Opcional — permite filtrar por el identificador fiscal exacto.

ExternalIdstringProtocolSefaz del documento. Opcional — útil para localizar un documento por su protocolo SEFAZ.

DocumentTagValuesobjectFiltra documentos por valor de etiqueta. Opcional. Ejemplo: {"AuthorityStatus": "2"} para obtener solo documentos autorizados; {"AuthorityStatus": "3"} para solo rechazados.

Parámetros de respuesta

La respuesta contiene tres campos raíz: Documents (array de documentos encontrados), ContinuationToken (token de paginación opaco — pasar tal cual en la siguiente petición; null si no hay más resultados) y Description (ej. "Cantidad de documentos encontrados 5").

Cada objeto en Documents contiene:

AtributoTipoDescripción

UrlPdfstringURL de descarga del PDF del documento. Solo aparece cuando la funcionalidad está habilitada para el TaxID (no es default — debe solicitarse al equipo de Integraciones). Solo presente cuando AuthorityStatus es "2".

UrlXmlstringURL de descarga del XML tributario del documento. Mismas condiciones que UrlPdf.

GlobalDocumentIdstringIdentificador global único del documento en la plataforma Gosocket.

CountryDocumentIdstringChave de acesso del documento (44 dígitos para NF-e/CT-e/MDF-e; hash SHA-256 para NFS-e).

ExternalIdstringIdentificador de la autoridad fiscal: ProtocolSefaz para NF-e/CT-e/MDF-e; número de NFS-e asignado por la Prefeitura para NFS-e. Poblado cuando el documento fue autorizado; cadena vacía cuando fue rechazado.

CountryIdstringCódigo del país. Siempre "br" para Brasil.

DatestringFecha de emisión del documento. Formato ISO 8601: "yyyy-MM-ddTHH:mm:ss".

DocumentTypeIdnumberCódigo numérico del tipo de documento. Ejemplo: 55 (NF-e), 57 (CT-e), 58 (MDF-e), 551 (NFS-e).

DocumentTypeNamestringNombre descriptivo del tipo de documento. Ejemplo: "Nota Fiscal Eletrônica".

TotalAmountnumberValor total del documento en la moneda indicada por CurrencyType.

CurrencyTypestringMoneda del documento. Siempre "BRL" para Brasil.

SeriesNumberstringConcatenación de serie y número. Ejemplo: "170318" (serie 1, número 70318).

SeriesstringSerie del documento.

NumbernumberNúmero (folio) del documento.

DocumentSenderCodestringCNPJ del emisor del documento.

DocumentSenderNamestringRazón social del emisor.

DocumentReceiverCodestringCNPJ del receptor. Puede ser cadena vacía en documentos de exportación.

DocumentReceiverNamestringRazón social del receptor.

DocumentTimeStampstringTimestamp del procesamiento en Gosocket. Formato ISO 8601 UTC (con Z).

AuthorityTimeStampstringTimestamp de la respuesta de la autoridad fiscal. Formato ISO 8601 sin timezone (hora local Brasil, UTC-3). Puede ser `null` cuando el estado no fue determinado por la autoridad (ej.: documentos subidos vía Upload con estado 6).

SyncPointstringGUID del punto de sincronización — corresponde al ID de la cuenta API que realizó el envío.

DocumentTagsarrayEtiquetas de estado y trazabilidad. Cada elemento tiene Code, TimeStamp y Value. La etiqueta con Code "AuthorityStatus" contiene el estado fiscal (ver tabla abajo). Otras etiquetas frecuentes (la lista puede variar): "tpEmis", "DocumentOrigin", "DistributionSender", "DistributionReceiver", entre otras.

NotesarrayHistorial de procesamiento. El número de entradas varía según el flujo. Cada elemento tiene: Mandatory (boolean — true indica error bloqueante), Code (cStat SEFAZ cuando Source es "NDD"; puede ser un GUID u otro identificador para otros Source), Note (descripción del evento), Source ("NDD" para flujo vía API, "Gosocket" para flujo de upload directo con códigos como "Upload" y "NoRetries", "Distribution Process" / "Servidor de Correo Distribución" para eventos de distribución), TimeStamp y Detail.

FieldsarrayCampos adicionales del documento. El array puede contener cero o más elementos. Para Brasil vía NDD suele incluir un elemento con Code "AdditionalDataNDD" cuyo Value es un JSON serializado. Para NF-e/CT-e/MDF-e contiene: MunicipalCode, EmissionType, protocolSefaz, documentKey, emissionCode y version (puede ser vacío en CT-e/MDF-e). El campo `protocol` (GUID NDD) solo está presente cuando el documento fue procesado vía SendDocumentToAuthority; está ausente en documentos subidos por Upload. Para NFS-e contiene: MunicipalCode, protocol, protocolSefaz (número de NFS-e) y documentKey (puede estar vacío según el municipio).

Valores de AuthorityStatus

Código	Estado	Notes.Code de NDD correspondiente
0	Por enviar	—
1	Enviado	—
2	Autorizado	NF-e/CT-e/MDF-e: "100" (en plazo) o "150" (fora de prazo) — NFS-e: "45"
3	Rechazado	"225", "228", "745", "999" u otro cStat SEFAZ
4	Anulado	—
5	Error	—
6	Sin resolución	—
7	Inutilizado	—
8	Denegado	—

Ejemplo

GetDocument

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

Notas

AuthorityStatus en DocumentTags

El estado fiscal no viene en un campo de primer nivel — vive dentro del array DocumentTags como el objeto cuyo Code es "AuthorityStatus". El campo Value contiene el código numérico (dígito simple: "2", "3", etc.).

El estado "2" (Autorizado) puede originarse de un Notes.Code: "100" (autorizado en plazo) o "150" (autorizado fora de prazo) — ambos producen el mismo AuthorityStatus.

El estado "6" (Sin resolución) indica que el sistema no pudo determinar el estado tras agotar los reintentos de consulta. Ocurre principalmente en documentos subidos vía Upload. Las Notes mostrarán Source: "Gosocket" con Code: "NoRetries" en estos casos.

Descarga de XML y PDF

Los campos UrlPdf y UrlXml aparecen en la respuesta cuando la funcionalidad está habilitada para el TaxID (no es el comportamiento por defecto — debe solicitarse al equipo de Integraciones). Solo están disponibles cuando el documento tiene AuthorityStatus: "2".

Como alternativa siempre disponible (sin necesidad de activación), los archivos se pueden descargar con los endpoints:

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

Notes: leer el resultado final

Para determinar el resultado de una transacción NDD, itera el array Notes y localiza la última entrada con Source: "NDD" que sea el resultado de la consulta a la entidad fiscal. Si tiene Mandatory: true, es un error bloqueante (rechazo); si el Code es "100" o "150", el documento fue autorizado. Las entradas intermedias con Code: "200" y Source: "NDD" son pasos internos de procesamiento (aceptación y envío a SEFAZ), no el resultado final. Las entradas con otros Source ("Distribution Process", "Servidor de Correo Distribución", etc.) registran eventos de distribución posteriores y pueden aparecer o no dependiendo de la configuración del TaxID.