Saltar al contenido principal

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:

  • API en ambiente de Sandbox

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

  • API en ambiente de Producción

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

¿Cómo funciona el método GetAccount?​

Antes de explicar su funcionamiento es importante señalar que este método debe ser habilitado por Gosocket para poder hacer uso del mismo.

Si quiere hacer uso del método Acérquese 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ámetroTipoDescripciónValores permitidos
AccountCode*****StringID 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*****StringTipo de documento de identificación del cliente consultar: * 1: NIT * 2: CUI1 o 2
receiverCode*****StringNúmero de identificación del cliente a consultarConsultar tabla Estructura ID Fiscal
countryId*StringCódigo del país de la empresa que realiza la consultagt

* Todos los parámetros son requeridos

Ejemplo de petición​

image-20250731-214849.png

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.

Ejemplo de respuesta​

Respuesta no satisfactoria: Empresa No Habilitada

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

Respuesta satisfactoria: Cliente NIT Encontrado

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

Respuesta no satisfactoria: Cliente NIT No Encontrado

{
    "ErrorMessage": [
        "003:No se ha encontrado el registro"
    ],
    "IsValid": false,
    "StatusCode": "1",
    "StatusDescription": "Error",
    "StatusMessage": "Código de respuesta 1 - Error",
    "XmlBase64Bytes": "PD94bWwgdmVyc2lv...50ZVJlc3BvbnNlPg==",
    "XmlBytes": null,
    "XmlDocumentKey": null,
    "XmlFileName": null,
    "ResponseType": "Sync",
    "OtherData": null,
    "GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
    "Timestamp": "2025-07-31T20:44:52.6478585Z",
    "Response": null,
    "TaxDocument": null,
    "PrinterXml": null
}

Respuesta satisfactoria: Cliente CUI Encontrado

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

Respuesta no satisfactoria: Cliente CUI Inválido

{
    "ErrorMessage": [
        "003:CUI Inválido."
    ],
    "IsValid": false,
    "StatusCode": "1",
    "StatusDescription": "Error",
    "StatusMessage": "Código de respuesta 1 - Error",
    "XmlBase64Bytes": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/PjxSZXRvcm5hRGF0b3NDbGllbnRlUmVzcG9uc2VDVUk+PGxpc3RhZG9fZXJyb3Jlcz48ZXJyb3I+PGNvZF9lcnJvcj4wMDM8L2NvZF9lcnJvcj48ZGVzY19lcnJvcj5DVUkgSW52w6FsaWRvLjwvZGVzY19lcnJvcj48L2Vycm9yPjwvbGlzdGFkb19lcnJvcmVzPjx0aXBvX3Jlc3B1ZXN0YT4xPC90aXBvX3Jlc3B1ZXN0YT48L1JldG9ybmFEYXRvc0NsaWVudGVSZXNwb25zZUNVST4=",
    "XmlBytes": null,
    "XmlDocumentKey": null,
    "XmlFileName": null,
    "ResponseType": "Sync",
    "OtherData": null,
    "GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
    "Timestamp": "2025-07-31T20:51:41.9368821Z",
    "Response": null,
    "TaxDocument": null,
    "PrinterXml": null
}

Respuesta no satisfactoria: Cliente CUI No Encontrado

{
    "ErrorMessage": [
        "003:No se ha encontrado el registro"
    ],
    "IsValid": false,
    "StatusCode": "1",
    "StatusDescription": "Error",
    "StatusMessage": "Código de respuesta 1 - Error",
    "XmlBase64Bytes": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/PjxSZXRvcm5hRGF0b3NDbGllbnRlUmVzcG9uc2VDVUk+PGxpc3RhZG9fZXJyb3Jlcz48ZXJyb3I+PGNvZF9lcnJvcj4wMDM8L2NvZF9lcnJvcj48ZGVzY19lcnJvcj5ObyBzZSBoYSBlbmNvbnRyYWRvIGVsIHJlZ2lzdHJvPC9kZXNjX2Vycm9yPjwvZXJyb3I+PC9saXN0YWRvX2Vycm9yZXM+PHRpcG9fcmVzcHVlc3RhPjE8L3RpcG9fcmVzcHVlc3RhPjwvUmV0b3JuYURhdG9zQ2xpZW50ZVJlc3BvbnNlQ1VJPg==",
    "XmlBytes": null,
    "XmlDocumentKey": null,
    "XmlFileName": null,
    "ResponseType": "Sync",
    "OtherData": null,
    "GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
    "Timestamp": "2025-07-31T20:51:59.206107Z",
    "Response": null,
    "TaxDocument": null,
    "PrinterXml": null
}

Respuesta no satisfactoria: Error en los parametros de consulta

{
    "ErrorMessage": null,
    "IsValid": false,
    "StatusCode": "500",
    "StatusDescription": "El tipo de identificación debe ser 1 o 2.",
    "StatusMessage": "El tipo de identificación debe ser 1 o 2.",
    "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ámetroTipoDescripciónValores permitidos
errorMessage*Stringcodedescription según corresponda mensajes de error retornados
isValidBoleanRsultado de la petición: * true cuando el cliente existe * false cuando no existe el clienteTrue False
statusCodeStringCódigo de respuesta0: 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.
statusDescriptionStringDescripción del código
StatusMessageStringDescripción de la respuestaCódigo de respuesta 0 - Cliente encontrado. Código de respuesta 1 - Error El tipo de identificación debe ser 1 o 2
xmlBase64BytesStringXML en base 64 de la respuesta retornada por el catálogo de la SAT cuando existe el cliente.* null * XML en base 64
xmlBytesStringnull
XmlDocumentKeyStringnull
XmlFileNameStringnull
ResponseTypeStringTipo de respuesta del servicio consultado: síncronaSync
OtherDataStringSolo 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 " }
CUIStringNIT o CUI del cliente consultadoValor del NIT Valor del CUI
nombreStringNombre del cliente consultadoejemplo "GOSOCKET GUATEMALA, SOCIEDAD ANONIMA"
direccion*StringDirección del cliente NIT consultadoejemplo “CUCHILLA 10 EL CARMEN, GUATEMALA”
GlobalDocumentIdString00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000
TimestampStringFecha-hora de consulta2025-05-02T21:50:31.7268377Z
ResponseStringnull
TaxDocumentStringnull
PrinterXmlStringnull