Method for sending documents (SendDocumentToAuthority)
This method allows you to issue documents directly to the Gosocket portal using the POST SendDocumentToAuthority service, where you can send the integration file and receive an immediate (synchronous) response from the tax authority.
Through this method, it is possible to send different types of integration structures (XML, JSON); its function is to transform them into the UBL representative of each country's tax authority, duly signed, and provide a response for its prior validation in just a few milliseconds.
For a more agile and scalable integration, it is recommended to use the platform's standard integration DTE, which helps ensure an almost immediate integration with our systems.
SendDocumentToAuthority method process
The SendDocumentToAuthority method process looks as follows depending on the country:
Countries with a synchronous process
Mexico, Guatemala, Peru, Panama:
- The client sends the request with the parameters seen previously.
- The Gosocket API converts the received DTE into a tax XML.
- The XML is signed according to the previously configured criteria.
- The signed XML is certified by the PAC/OSE/PT.
- The PAC/OSE/PT sends, through the API, an approval or rejection response along with the verified XML. This response is issued synchronously with the request.
- The API provides the synchronous response with the validation or rejection of the request to the client.
- The certified XML and its acceptance or rejection observations are sent to the tax authority.
Colombia, El Salvador:
- For Colombia and El Salvador, the process followed is the same as above, with two differences:
a. The signed XML is sent to the authority, and it returns an Acknowledgment of Receipt to the client through the API.
b. There is no figure such as the OSE/PAC/PT involved.
Countries with an asynchronous process
Costa Rica, Ecuador, Chile, Dominican Republic
- The user uses the same parameters already seen to make the request.
- Within the API, the document is transformed into an XML.
- The XML goes to signing.
- The API sends a synchronous response to the user containing the verified XML along with any observations for correction obtained. This is according to the parameters updated within the Gosocket API.
- The user receives the signed XML, as well as the observations returned by the API when issuing the response.
- In parallel, the API sends the signed XML to the tax authority for processing according to its regulations. The tax authority, in turn, sends the document's acknowledgment back to the API as a response.
- From the API, the user can manage PDF generation, document distribution, and report downloads.
- The server will periodically update the document's status in the API.
Synchronous / asynchronous process
Argentina
- The user uses the parameters to make the request, with the distinguishing features explained in the following section.
- Within the API, the document is transformed into an XML.
- If the request sent the value False in the async parameter, the API sends a response to the user containing the verified XML along with any observations for correction obtained. When the value of the async parameter in the request is True, the API will respond that the document was received and will wait in the queue until it reaches the sequential number to be sent to the Tax Authority. The server will periodically update the document's status in the API.
- From the API, the user can manage PDF generation, document distribution, and report downloads.
To connect to this functionality, you will need to enter the URL according to the environment being used:
PRODUCCIÓN
https://developers.gosocket.net/api/v1/Document/SendDocumentToAuthoritySANDBOX
https://developers-sbx.gosocket.net/api/v1/Document/SendDocumentToAuthorityHow does the SendDocumentToAuthority method work?
To make the request, the method has the following parameters in JSON format with the following structure:
| SendDocumentToAuthority (request) | |||
|---|---|---|---|
| Parameter | Type | Description | Allowed values |
| FileContent* | String | Parameter to include the file to be certified | XML file in JSON format or base 64. JSON file in JSON format or base 64. |
| Async* | Boolean | Type of API response | false (Synchronous) true (Asynchronous) false (synchronous) to consume the method this way, it is necessary to use the current sequential number for the document within the document's base 64 XML |
| Mapping* | String | Mapping code to use for the document transformation (generated by Gosocket) | Identifier provided by Gosocket |
| Sign* | Boolean | Parameter to indicate whether the generated XML must be signed. Parameter to indicate whether the document is transformed. | true (signs the document) false (does not sign the document) true (the document is transformed) |
| DefaultCertificate* | Boolean | Parameter to indicate whether the platform's default certificate will be used | true (Certificate configured on the platform false (Certificate configured on the company) |
*Required
Request example
- Select the method type. In this case, you must select POST.
- Enter the method's URL.
- Enter the parameters shown in the information table with their corresponding values.
- Press Send.
Note: Remember that before using the method, you must authenticate within the Authorization tab.
Response example
JSON response example for a synchronous process request
Note: To consume the method this way, it is necessary to use the current sequential number for the document within the document's base 64 XML when sending the request.
JSON response example for an asynchronous process request
Note: When the method is consumed this way, the sequential number used within the document's XML will be evaluated and will wait in the queue until it reaches the sequential number to be sent to the Tax Authority.
JSON Response example
{
"Success": true,
"GlobalDocumentId": "fc089d3b-ab79-13f3-65e6-8cd2275e1922",
"CountryDocumentId": "96A01B7C-22FC-4594-8857-E79FA1CB0845",
"OtherData":
{
"AuthorityTimeStamp": "2026-01-29T16:37:03",
"ReceivedStamp": "20263EB3DE66966946C8B33B896714456DF8CREY",
"Country": "sv",
"Certifier": "DGI"
},
"Messages": [],
"ResponseValue": "ew0KCSJ2ZXJzaW9uIjogMiwNCgkiYW1iaWVudGUiOiAiMDAiLA0KCSJ2ZXJzaW9uQXBwIjogMiwNCgkiZXN0YWRvIjogIlBST0NFU0FETyIsDQoJImNvZGlnb0dlbmVyYWNpb24iOiAiOTZBMDFCN0MtMjJGQy00NTk0LTg4NTctRTc5RkExQ0IwODQ1IiwNCgkic2VsbG9SZWNpYmlkbyI6ICIyMDI2M0VCM0RFNjY5NjY5NDZDOEIzM0I4OTY3MTQ0NTZERjhDUkVZIiwNCgkiZmhQcm9jZXNhbWllbnRvIjogIjI5LzAxLzIwMjYgMTY6Mzc6MDMiLA0KCSJjbGFzaWZpY2FNc2ciOiAiMTAiLA0KCSJjb2RpZ29Nc2ciOiAiMDAxIiwNCgkiZGVzY3JpcGNpb25Nc2ciOiAiUkVDSUJJRE8iLA0KCSJvYnNlcnZhY2lvbmVzIjogW10NCn0",
"Code": "001",
"Description": "RECIBIDO",
"ErrorException": null
}JSON Decoded ResponseValue example:
{
"version": 2,
"ambiente": "00",
"versionApp": 2,
"estado": "PROCESADO",
"codigoGeneracion": "96A01B7C-22FC-4594-8857-E79FA1CB0845",
"selloRecibido": "20263EB3DE66966946C8B33B896714456DF8CREY",
"fhProcesamiento": "29/01/2026 16:37:03",
"clasificaMsg": "10",
"codigoMsg": "001",
"descripcionMsg": "RECIBIDO",
"observaciones": []
}To correctly interpret its results, take the following into account:
| SendDocumentToAuthority (response) | |||
|---|---|---|---|
| Parameter | Type | Description | Example possible values |
| Success | Boolean | Parameter indicating whether the document was processed successfully. | MX CO GT PE PA true (document accepted by the tax authority) CL CR EC DOM* AR true (document processed successfully and sent to the tax authority) false (document had a problem during its process or was rejected by a tax authority) |
| GlobalDocumentId | String | Document identification in Gosocket. | 36-character alphanumeric UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| CountryDocumentId | String | Country-level fiscal identifier for the document, also known as CUFE, CLAVE, UUID, ID | See the Country Document ID Structure table |
| Other Data | String | Dynamic field for relating information about the document submission. It can vary by country as shown in the OtherData table. Not a mandatory field. | Being a dynamic field, it has the following structure: "OtherData": {"additionalProp1": "string", "additionalProp2": "string" }, This field can have from 0 to N properties. The xmlauthorization field shows the base 64 XML of the ARCA's authorization for the document. Within the Response Arca field, the Tax Authority's response is shown. |
| Messages | Array | If there are errors or observations from the tax authority, they will be shown in this section. | |
| ResponseValue | String | Response from the authority. Response from the DGI in base 64 | Certified XML (Certified document) Return of the sent XML (XML with error) CO Application response |
| Code | String | Response code of the process. | Example: 200 (OK), 503 (Time Out), 99, 7 (error) 001: Received |
| Description | String | Description of the request status or of the generated error. | Example: 200 "Invoice number XX has been accepted" 503 "Timeout sending to certifier" 200 "Processed Successfully." x"Validation contains errors in mandatory fields." 7 "Error in input Parameters(One or more errors occurred.)" 200 "Null" -> When the document was generated successfully. 001: Received |
| ErrorException | Array | Describes the exception information in case of an error due to an exception in the process. |
Note: This is a generic interpretation, meaning the interpretation could vary depending on the country.
In the OtherData parameter, for example, you can find the following properties:
| OtherData | |
|---|---|
| Country | OtherData properties |
| Argentina | Synchronous { "ResponseArca": "PEZFS…" "XmlAuthorization": "PQMDI…" } Asynchronous { "Country": "ar" "Certifier": "ARCA" "AuthorityTimeStamp": "21/02/2025 14:45:12" } |
| Chile | { "Country": "cl", "Certifier": "SII" } |
| Colombia | { "Country": "co", "Certifier": "DIAN", "AuthorityTimeStamp": "15/07/2022 15:42:06", "BarCodeText": "https...", "Folio": "990001015", "NumeroInterno": "01015", "Serie": "SETP" } |
| Costa Rica | { "Country": "cr", "Certifier": "MH" } |
| Ecuador | { "Country": "ec", "Certifier": "SRI" } |
| Guatemala | { "Country": "gt", "Certifier": "Megaprint", "AuthorityTimeStamp": "15/07/2022 15:00:15", "Number": "3558819305", "Series": "557AC19C", "BarCodeText": "https…" } |
| México | { "Country": "mx", "AuthorityTimeStamp": "15/07/2022 15:54:12", "Certifier": "GRUPO YACORD", "BarCodeText": "https…", "NoCertificado": "22345754", "RFCEmisor": "EKU9003173C1", "RFCReceptor": "CAVR781231UU2" } |
| Panamá | { "Country": "pa", "Certifier": "ebi", "AuthorityTimeStamp": "7/6/2022 11:00:56 PM", "BarCodeText": "https…" } |
| Perú | { "Country": "pe", "AuthorityTimeStamp": "15/07/2022 15:42:06", "BarCodeText": "20556695548 |
| El Salvador | { "AuthorityTimeStamp": "2026-01-29T16:37:03", "ReceivedStamp": "20263EB3DE66966946C8B33B896715556DF7CREY", "Country": "sv", "Certifier": "DGI" } |
Note: Being a dynamic field, it can have from 0 to N properties.
The OtherData field is populated depending on the country:
| OtherData | |||
|---|---|---|---|
| Country | Example | Field | Value |
| Argentina | Synchronous { "ResponseArca": "PEZFS…" "XmlAuthorization": "PQMDI…" } Asynchronous { "Country": "ar" "Certifier": "ARCA" "AuthorityTimeStamp": "21/02/2025 14:45:12" } | OtherData.ResponseArca | Response from the Tax Authority in base 64 |
| OtherData.XmlAtuhorization | Authorization from the Tax Authority in base 64 | ||
| TherData.Country | Country code | ||
| OtherData.Certifier | Tax authority and/or Certifying body for the document | ||
| OtherData.AuthorityTimeStamp | Date and Time the document was validated | ||
| Chile | { "Country": "cl", "Certifier": "SII" } | OtherData.Country | Country code |
| OtherData.Certifier | Tax authority and/or Certifying body for the document | ||
| Colombia | { "Country": "co", "Certifier": "DIAN", "AuthorityTimeStamp": "15/07/2022 15:42:06", "BarCodeText": "https...", "Folio": "990001015", "NumeroInterno": "01015", "Serie": "SETP" } | OtherData.Country | Country code |
| OtherData.Certifier | Tax authority and/or Certifying body for the document | ||
| OtherData.AuthorityTimeStamp | Date and Time the document was validated | ||
| OtherData.BarCodeText | QR code value | ||
| OtherData.Folio | Document's tax number | ||
| OtherData.NumeroInterno | Document's internal number | ||
| OtherData.Serie | Document series | ||
| Costa Rica | { "Country": "cr", "Certifier": "MH" } | OtherData.Country | Country code |
| OtherData.Certifier | Tax authority | ||
| Ecuador | { "Country": "ec", "Certifier": "SRI" } | OtherData.Country | Country code |
| OtherData.Certifier | Tax authority | ||
| Guatemala | { "Country": "gt", "Certifier": "Megaprint", "AuthorityTimeStamp": "15/07/2022 15:00:15", "Number": "3558819305", "Series": "557AC19C", "BarCodeText": "https…" } | OtherData.Country | Country code |
| OtherData.Certifier | Document certifier | ||
| OtherData.AuthorityTimeStamp | Date and Time the document was validated | ||
| OtherData.Number | Document's tax number | ||
| OtherData.Series | Document series | ||
| OtherData.BarCodeText | QR code value | ||
| México | { "Country": "mx", "AuthorityTimeStamp": "15/07/2022 15:54:12", "Certifier": "GRUPO YACORD", "BarCodeText": "https…", "NoCertificado": "22345754", "RFCEmisor": "EKU9003173C1", "RFCReceptor": "CAVR781231UU2" } | OtherData.Country | Country code |
| OtherData.AuthorityTimeStamp | Date and Time the document was validated | ||
| OtherData.Certifier | Document certifier | ||
| OtherData.BarCodeText | QR code value | ||
| OtherData.NoCertificado | Document's tax number | ||
| OtherData.RFCEmisor | Issuer's RFC | ||
| OtherData.RFCReceptor | Receiver's RFC | ||
| Panamá | { "Country": "pa", "Certifier": "ebi", "AuthorityTimeStamp": "7/6/2022 11:00:56 PM", "BarCodeText": "https…" } | OtherData.Country | Country code |
| OtherData.Certifier | Document certifier | ||
| OtherData.AuthorityTimeStamp | Date and Time the document was validated. | ||
| OtherData.BarCodeText | QR code value | ||
| Perú | { "Country": "pe", "AuthorityTimeStamp": "15/07/2022 15:42:06", "BarCodeText": "20556695548 | 01 | FAPI |
| OtherData.AuthorityTimeStamp | Submission Type: * Synchronous: Date and Time the document was validated. * Asynchronous: Date and Time the document was processed. Format: DD/MM/YY HH:MM:SS | ||
| OtherData.BarCodeText | QR code value | ||
| OtherData.OseIdentifier | Document Validator (SUNAT/OSE) | ||
| El Salvador | Synchronous { "AuthorityTimeStamp": "2026-01-29T16:37:03", "ReceivedStamp": "20263EB3DE66966946C8B33B896715556DF7CREY", "Country": "sv", "Certifier": "DGI" } | OtherData. AuthorityTimeStamp | Date and Time the document was validated |
| OtherData. ReceivedStamp | Receipt stamp for the accepted document | ||
| OtherData.Country | Country code | ||
| OtherData.Certifier | Tax authority and/or Certifying body for the document |
SendDocumentToAuthority method features
- To use the standard mapping the portal already has with the generic DTE, you can use the following mapping code: 11111111-1111-1111-1111-111111111111
- To use FileContent with a JSON-format file, you can use the same field structure of the generic DTE from the Documento node, since the API, upon detecting the JSON file format, converts it to XML format always adding the root node <DTE> and then transforms it into the tax XML through the generic mapping, for example:
JSON
{
"Documento": {
"Encabezado": {
"IdDoc": {
"Tipo": "01",
"...": "..."
},
"Emisor": {
"...": "..."
}
},
"Detalle": {
"...": "..."
}
}
}- If you want to work with a custom XML or JSON structure, you can use a custom mapping code. In the case of the JSON format, keep in mind that the root the API adds when converting JSON to XML is always
<DTE>. - Since the ResponseValue is the tax authority's response, this parameter only carries information for countries that issue the document synchronously.
- To generate credit or debit notes, all documents referenced within the same note must have been authorized by the same PAC.
Sending the Receiver Message
Another way to use the SendDocumentToAuthority service is to issue the receiver message through the Gosocket API.
This way, our clients can respond to their suppliers regarding acceptance or rejection of payment for their documents.
How the receiver message works
First, the client needs to generate the following receiver message structure:
<MensajeReceptor xmlns="https://cdn.comprobanteselectronicos.go.cr/xml-schemas/v4.3/mensajeReceptor" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Clave>50611072400310100815000100009010015294251116486634</Clave>
<NumeroCedulaEmisor>3101008150</NumeroCedulaEmisor>
<FechaEmisionDoc>2024-07-11T12:50:37</FechaEmisionDoc>
<Mensaje>1</Mensaje>
<DetalleMensaje>Aprobado comercialmente</DetalleMensaje>
<MontoTotalImpuesto>7099.59000</MontoTotalImpuesto>
<CodigoActividad>512201</CodigoActividad>
<MontoTotalImpuestoAcreditar>0.00000</MontoTotalImpuestoAcreditar>
<TotalFactura>252705.26000</TotalFactura>
<NumeroCedulaReceptor>3101595167</NumeroCedulaReceptor>
<NumeroConsecutivoReceptor>00100009050000000085</NumeroConsecutivoReceptor>
</MensajeReceptor>Taking into account the following criteria to structure your receiver message:
| SendDocumentToAuthority Receiver Message (XML message structure) | ||
|---|---|---|
| Field | Description | Allowed values |
| Clave* | Key of the document for which the acknowledgment is generated | 50 numeric characters |
| NumeroCedulaEmisor* | ID number of the related document | 12 numeric characters |
| FechaEmisionDoc* | Date and time when the acknowledgment is generated | yyyy-mm-ddThh:mm:ss |
| Mensaje* | Approval status 1. Accepted 2. Partially accepted 3. Rejected (this value is related to the status shown within "NumeroConsecutivoReceptor") | 1 numeric character |
| DetalleMensaje | Field for providing any additional detail to the message | 160 characters |
| MontoTotalImpuesto | Amount of the referenced document | Up to 15 whole numbers and up to 5 decimals |
| CodigoActividad | Activity code that comes within the referenced document | Up to 18 whole numbers and up to 5 decimals |
| MontoTotalImpuestoAcreditar | Total tax of the referenced document | Up to 18 whole numbers and up to 5 decimals |
| TotalFactura* | Total of the referenced document | Up to 18 whole numbers and up to 5 decimals |
| NumeroCedulaReceptor* | ID number of the receiver of the related document | 20 characters |
| NumeroConsecutivoReceptor | The receiver's consecutive number must be the concatenation of the following fields (the parameter for this data in the XSLT is consecutivo): Head Office - 001 (Default). Establishment or issuance point - 00001 (Default). Receiver message status - 05 (when the message is 1), 06 (when the message is 2), or 07 (when the message is 3). Folio - 0000000001 (Auto-incrementing number). |
*Required
Within the API, enter the following parameters:
- Select the method type. In this case, you must select POST.
- Enter the method's URL.
- Select the Body tab and click the selection circle for x-www-form-urlencoded to enter the parameters and generate the request.
- Enter the parameters shown in the table below with their corresponding values.
- Press Send.
The parameters are as follows:
| SendDocumentToAuthority Receiver Message (request) | |||
|---|---|---|---|
| Parameter | Type | Description | Allowed values |
| fileContent | Array | Content of the document (Receiver Message) | |
| Async | String | Since it is an asynchronous model, the value true is sent | true |
| Sign | String | The value true is sent so it is signed | true |
| defaultCertificate | String | Since each taxpayer must sign their documents with their own certificate, the parameter false is sent | false |
| mapping | Empty | This parameter must remain empty | Empty |
The API's response to this request will be the same as explained previously.
Once the message is registered in the documents received in Inbox, it is attached to the supplier's XML and sent to the Ministry of Finance for validation.
From the query screen, we can see the icon that indicates the receiver message is being validated, and the icon that shows there are attachments in the document, such as the receiver message.
To confirm that the acknowledgment was sent, go into the document and check the Attachments section as shown below:
In addition, the Ministry of Finance responds to the receiver message with a JSON containing the validation, which is shown as an attachment within the same section.
Clients with access to the Gosocket portal will be able to check the receiver message their client sent.
To review the receiver message, you will need to open the document to download it from the download button shown in the attachment record, as shown in the following image:
Invalidation
The invalidation process through the API in El Salvador works as shown below:
- The user sends the DTE to the API.
- The API processes the document to transform it into a JSON.
- It sends the signed JSON to the Tax Authority.
- The Tax Authority issues its acceptance or rejection of the invalidation.
- The API communicates the Tax Authority's acceptance or rejection to the user and returns the JSON.
Note: The invalidation Mapping is 193435a2-ab14-4d10-8f15-a85cf7a14426
Invalidation request
The parameters to send to the API are as follows:
| SendDocumentToAuthority (request) | |||
|---|---|---|---|
| Parameter | Type | Description | Allowed values |
| FileContent* | String | Parameter to include the invalidation file | XML file in JSON format or base 64 |
| Async* | Boolean | Type of API response | true (Synchronous) |
| Mapping* | String | Mapping code to use for the invalidation transformation. | **Mapping:**f6deb258-6dd1-4d2a-89d1-dccd2495904d |
| Sign* | Boolean | Parameter to indicate whether the JSON must be signed | true (signs the JSON) false (does not sign the JSON) |
| DefaultCertificate* | Boolean | Parameter to indicate whether the certificate configured on the platform by the company will be used. | false (Certificate configured by the company) |
*Required
API response to the invalidation
The API's response will be shown with all the parameters mentioned here, with the following data in the OtherData parameter:
"OtherData": {
"Country": "sv",
"Certifier": "DGI",
"AuthorityTimeStamp": "16/01/2023 11:24:33"
}Folio Assignment for issuance via API in Chile
We currently manage two Folio Managers in Chile:
- Folio Manager 1.0
- Folio Manager 3.0
The API in the SendDocumentToAuthority method is able to decide which of the 2 manager versions to use, based on:
- Manager 1.0 uses an agent that is sent in the request's DTE in the custom fields section.
- Manager 3.0 uses a biller that is sent as a parameter (BillerId) in the request of the SendDocumentToAuthority issuance method.
And the following conditions:
- The "BillerId" parameter always takes priority, meaning that if it has a value, Folio Manager 3.0 will be used; the system looks for the biller in Folio Manager V3.0 to assign the folio.
- When the "BillerId" parameter is not sent or arrives empty, and the company has the Folio Assignment configuration (Feature: AsignarFolio - Methods: MakeDocumentAndSend and AssignNumber), the folio is assigned automatically without needing an agent.
- When the "BillerId" parameter is not sent or arrives empty, and the "CategoryID" custom field has a value, the folio is assigned using Folio Manager 1.0.
- When the "BillerId" parameter has a value, and additionally the "CategoryID" custom field also has a value, the "BillerId" request parameter takes priority; the system looks in Folio Manager 3.0 and, if it cannot find the biller to assign the folio, it returns the corresponding error message.
- When the "BillerId" parameter is not sent or arrives empty, and the "CategoryID" custom field also has no value, and the company also does not have the Folio Assignment configuration (Feature: AsignarFolio - Methods: MakeDocumentAndSend and AssignNumber) to automatically assign the folio without needing an agent, the method continues with its normal flow without assigning a folio.
- When the BillerId parameter is included in the API, the system understands it must go to GF3.0 to assign the folio; however, if the ValidateNumber parameter is included as true, the system will not request a folio assignment, but will instead validate the folio already filled in on the DTE.
- If the new ValidateNumber parameter is not sent, or is sent with a value of false (given that the BillerId parameter was also sent), the system will request GF3.0 to assign the folio.
- Folio validation only applies to folios with a rejected or error status.
- If a request is made to validate an unassigned folio, a message will be returned indicating that it has not been assigned, and the document will not be generated, because folio gaps cannot be generated in GF3.0.
- Folio [20692] is within this subrange: DocType [33] - NumberFrom [20687] - NumberTo [20696]; however, the folio has not been previously delivered.
- If a request is made to validate an approved folio, a message will be returned indicating that it has already been issued
- Folio [20690] is already in use by a document issued for document type [33]