Guatemala: Método para consultar datos del cliente por NIT o CUI (GetAccount)

Este método permite consultar los datos de “Nombre ” y “Dirección” de un cliente, en el catálogo dispuesto por la SAT, especificando tipo y número documento por medio del método GET GetAccount.

Para conectarse a esta funcionalidad será necesario que ingrese la URL de acuerdo con el ambiente a consumir:

PRODUCCIÓNhttps://developers.gosocket.net/api/v1/Account/GetAccount

SANDBOXhttps://developers-sbx.gosocket.net/api/v1/Account/GetAccount

---

¿Cómo funciona el método GetAccount?

ANTES DE INICIAR

Es importante señalar que este método debe ser habilitado por Gosocket para poder hacer uso del mismo.

Solicita el acceso con el equipo comercial de Gosocket.

Para realizar la petición, el método tiene los siguientes parámetros con la siguiente estructura:

GetAccount (request)

Parámetro	Tipo	Descripción	Valores permitidos
AccountCode*	String	ID Fiscal de la empresa que realiza la consulta. Requerido para verificar que la empresa pueda hacer uso del servicio.	Consultar tabla Estructura ID Fiscal
identificationType*	String	Tipo de documento de identificación del cliente consultar: - 1: NIT - 2: CUI	1 o 2
receiverCode*	String	Número de identificación del cliente a consultar	Consultar tabla Estructura ID Fiscal
countryId*	String	Código del país de la empresa que realiza la consulta	gt

* Todos los parámetros son requeridos

---

Ejemplo de petición

Nota

Recuerde que antes de utilizar el método, debe realizar su autenticación dentro de la pestaña Authorization.

Para este método utilizamos la pestaña Params de Postman.

1. Seleccione el tipo de método. En este caso, se debe seleccionar GET.
2. Ingrese la URL del método.
3. Ingrese los parámetros que se muestran en la tabla anterior con sus valores correspondientes.
4. Presione Send.

---

Ejemplos de respuesta

Cliente NIT

{
   "ErrorMessage": null,
  "IsValid": true,
  "StatusCode": "0",
  "StatusDescription": "Cliente encontrado",
  "StatusMessage": "Código de respuesta 0 - Cliente encontrado",
  "XmlBase64Bytes": "PD94bWwgdmVyc2lvbj0iMS4w...VSZXNwb25zZT4=",
  "XmlBytes": null,
  "XmlDocumentKey": null,
  "XmlFileName": null,
  "ResponseType": "Sync",
  "OtherData": {
      "CUI": "104525746",
      "nombre": "GOSOCKET GUATEMALA, SOCIEDAD ANONIMA",
      "direccion": "CUCHILLA 10 EL CARMEN, MANZ. M LT. 26 RES. VISTA AZUL KM 13 CUCHILLA EL CARMEN ZONA 10 DEL CARMEN SANTA CATARINA PINULA, ZONA 10, RESIDENCIAL VISTA AZUL, GUATEMALA, GUATEMALA"
  },
  "GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
  "Timestamp": "2025-07-31T20:42:56.6783531Z",
  "Response": null,
  "TaxDocument": null,
  "PrinterXml": null
}

Cliente CUI

{
   "ErrorMessage": null,
  "IsValid": true,
  "StatusCode": "0",
  "StatusDescription": "Cliente encontrado",
  "StatusMessage": "Código de respuesta 0 - Cliente encontrado",
  "XmlBase64Bytes": "PD94bWwgdmVyc2lvbj0iMS4...50ZVJlc3BvbnNlQ1VJPg==",
  "XmlBytes": null,
  "XmlDocumentKey": null,
  "XmlFileName": null,
  "ResponseType": "Sync",
  "OtherData": {
      "CUI": "3021547620101",
      "nombre": "EMANUEL FRANCISCO ,CATALÁN REYNA "
  },
  "GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
  "Timestamp": "2025-07-31T20:50:28.6140412Z",
  "Response": null,
  "TaxDocument": null,
  "PrinterXml": null
}

Errores generales

{
  "ErrorMessage": null,
  "IsValid": false,
  "StatusCode": "500",
  "StatusDescription": "Empresa no activa para utilizar el evento GetAccount",
  "StatusMessage": "Empresa no activa para utilizar el evento GetAccount",
  "XmlBase64Bytes": null,
  "XmlBytes": null,
  "XmlDocumentKey": null,
  "XmlFileName": null,
  "ResponseType": null,
  "OtherData": null,
  "GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
  "Timestamp": null,
  "Response": null,
  "TaxDocument": null,
  "PrinterXml": null
}

Para interpretar adecuadamente esta respuesta, tome en cuenta los siguientes parámetros:

GetAccount (response)

Parámetro	Tipo	Descripción	Valores permitidos
errorMessage*	String	code: description según corresponda mensajes de error retornados	- null - [ "003:No se ha encontrado el registro" ] - [ "003:CUI Inválido." ]
isValid	Bolean	Resultado de la petición: - true cuando el cliente existe - false cuando no existe el cliente	- True - False
statusCode	String	Código de respuesta	- 0 - 1 - 500
statusDescription	String	Descripción del código	- 0: Cliente encontrado - 1: Error - 500: Empresa no activa para utilizar el evento GetAccount - 500: El tipo de identificación debe ser 1 o 2. - 500: El número de NIT no puede ser nulo o vacío. - 500: El número de CUI no puede ser nulo o vacío.
StatusMessage	String	Descripción de la respuesta	- Código de respuesta 0 - Cliente encontrado. - Código de respuesta 1 - Error El tipo de identificación debe ser 1 o 2
xmlBase64Bytes	String	XML en base 64 de la respuesta retornada por el catálogo de la SAT cuando existe el cliente.	- null - XML en base 64
xmlBytes	String	null
XmlDocumentKey	String	null
XmlFileName	String	null
ResponseType	String	Tipo de respuesta del servicio consultado: síncrona	Sync
OtherData	String	Solo en caso de que haya concluido con éxito la consulta, y el cliente haya sido encontrado, se retorna con los parámetros que siguen: - CUI - nombre - direccion* (solo aplica para consulta de NIT)	- null - "OtherData": { "CUI": "104536746", "nombre": "GOSOCKET GUATEMALA, SOCIEDAD ANONIMA", "direccion": "CUCHILLA 10 EL CARMEN, GUATEMALA" } - "OtherData": { "CUI": "3021658720101", "nombre": "EMANUEL FRANCISCO ,CATALÁN REYNA " }
CUI	String	NIT o CUI del cliente consultado	- Valor del NIT - Valor del CUI
nombre	String	Nombre del cliente consultado	Ejemplo: "GOSOCKET GUATEMALA, SOCIEDAD ANONIMA"
direccion*	String	Dirección del cliente NIT consultado	Ejemplo: “CUCHILLA 10 EL CARMEN, GUATEMALA”
GlobalDocumentId	String	00000000-0000-0000-0000-000000000000	00000000-0000-0000-0000-000000000000
Timestamp	String	Fecha-hora de consulta	2025-05-02T21:50:31.7268377Z
Response	String	null
TaxDocument	String	null
PrinterXml	String	null