Guatemala: Method to query client data by NIT or CUI (GetAccount)

This method allows you to query the "Name" and "Address" data of a client, in the catalog provided by SAT, specifying the document type and number through the GET GetAccount method.

To connect to this functionality, you will need to enter the URL according to the environment you want to use:

PRODUCTIONhttps://developers.gosocket.net/api/v1/Account/GetAccount

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

---

How does the GetAccount method work?

BEFORE YOU START

It is important to note that this method must be enabled by Gosocket in order to use it.

Request access from the Gosocket sales team.

To make the request, the method has the following parameters with the following structure:

GetAccount (request)

Parameter	Type	Description	Allowed values
AccountCode*	String	Tax ID of the company making the query. Required to verify that the company can use the service.	See the Tax ID Structure table
identificationType*	String	Type of identification document of the client to query: - 1: NIT - 2: CUI	1 or 2
receiverCode*	String	Identification number of the client to query	See the Tax ID Structure table
countryId*	String	Country code of the company making the query	gt

* All parameters are required

---

Request example

Note

Remember that before using the method, you must authenticate within the Authorization tab.

For this method, we use the Postman Params tab.

1. Select the method type. In this case, you must select GET.
2. Enter the method's URL.
3. Enter the parameters shown in the table above with their corresponding values.
4. Press Send.

---

Response examples

NIT client

{
   "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
}

CUI client

{
   "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
}

General errors

{
  "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
}

To properly interpret this response, take into account the following parameters:

GetAccount (response)

Parameter	Type	Description	Allowed values
errorMessage*	String	code: description as applicable, returned error messages	- null - [ "003:No se ha encontrado el registro" ] - [ "003:CUI Inválido." ]
isValid	Boolean	Request result: - true when the client exists - false when the client does not exist	- True - False
statusCode	String	Response code	- 0 - 1 - 500
statusDescription	String	Description of the code	- 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	Description of the response	- 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	Base64-encoded XML of the response returned by the SAT catalog when the client exists.	- null - Base64-encoded XML
xmlBytes	String	null
XmlDocumentKey	String	null
XmlFileName	String	null
ResponseType	String	Response type of the queried service: synchronous	Sync
OtherData	String	Only when the query has completed successfully and the client has been found is it returned with the parameters below: - CUI - nombre - direccion* (only applies for NIT queries)	- 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 or CUI of the queried client	- NIT value - CUI value
nombre	String	Name of the queried client	Example: "GOSOCKET GUATEMALA, SOCIEDAD ANONIMA"
direccion*	String	Address of the queried NIT client	Example: "CUCHILLA 10 EL CARMEN, GUATEMALA"
GlobalDocumentId	String	00000000-0000-0000-0000-000000000000	00000000-0000-0000-0000-000000000000
Timestamp	String	Query date-time	2025-05-02T21:50:31.7268377Z
Response	String	null
TaxDocument	String	null
PrinterXml	String	null