Colombia events

Report mercantile events

Through this method, you can report each of the mercantile statuses or RADIAN statuses of a document (Acknowledgement, Receipt, Claim, Acceptance, etc.).

To make the request in the API, you must enter the following parameters:

Parameter	Type	Description	Allowed values
ChangeDocumentStatus (request)
globalDocumentId*	String	Document identification in Gosocket.	36-character alphanumeric UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
countryDocumentId	String	Country-level tax identifier of the document, also known as CUFE, CLAVE, UUID, ID	See table Country Document ID Structure
countryId	String	Code of the document's country of issuance	ar, bo, br, cl, co, cr, ec, gt, mx, pa, pe, py, do, sv, uy
status*	Integer	Code of the mercantile status or RADIAN status to report.	Example: 30, 31, 32
description*	String	Description of the status to report.	Example: Authorized
code*	String	Document type code (invoice, credit note, etc.)	1, 2, 3, …

*Required

Mercantile events are identified as follows:

Code	Event
030	Acknowledgement of receipt
031	Claim
032	Receipt of the good and/or provision of the service
033	Express acceptance
034	Tacit acceptance

RADIAN events are identified as follows:

Code	Event
035	Guarantee (Aval)
036	Registration in RADIAN of the sales electronic invoice as a negotiable instrument circulating in the national territory
037	Endorsement in ownership
038	Endorsement in guarantee
039	Endorsement in procuration
040	Cancellation of the electronic endorsement
041	Circulation limitation of the sales electronic invoice as a negotiable instrument
042	Termination of the circulation limitation of the sales electronic invoice as a negotiable instrument
043	Mandate
044	Termination of the mandate
045	Payment of the sales electronic invoice as a negotiable instrument
046	Payment report
047	Endorsement with ordinary assignment effects
048	Protest
049	Transfer of economic rights
050	Notification to the debtor about the transfer of economic rights
051	Payment of the transfer of economic rights

---

Request example

POST https://developers.gosocket.net/sandbox/api/v1/Document/ChangeDocumentStatus
  ?globalDocumentId=00000000-0000-0000-0000-000000000000
  &countryId=co
  &status=30
  &description=acuse de recibo factura
  &code=1

Fictitious data

The identifiers in the examples on this page are fictitious.

Note: Remember that before using the method, you must authenticate on the Authorization tab.

For this method, we use Postman's Params tab.

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

---

Response example

{
"Success": true,
"GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
"CountryDocumentId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"OtherData": {
"Country": "co",
"Certifier": "DIAN",
"AuthorityTimeStamp": "06/09/2023 16:38:47"
},
"Messages": [
"Regla: 0, Notificación: La Application response 0000000000, ha sido autorizada."
],
"ResponseValue": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZ...",
"Code": "00",
"Description": "La Application response 0000000000, ha sido autorizada.",
"ErrorException": null
}

Note: the ResponseValue value is shown truncated; it corresponds to the authority's response encoded in base 64.

To correctly interpret the API's response, take into account the following criteria:

Parameter	Type	Description	Allowed values
ChangeDocumentStatus (response)
Success	Boolean	Indicates whether the request was executed correctly.	true: The request was executed correctly. false: The request was executed with some inconsistency.
GlobalDocumentId	String	Document identification in Gosocket.	00000000-0000-0000-0000-000000000000
CountryDocumentId	String	Country-level tax identifier of the document, also known as CUFE, CLAVE, UUID, ID	See table Country Document ID Structure
OtherData	String	Additional properties according to the country.	Example Chile: {"Folio": "17529"}
Messages	String	Rules validated for the document according to the mercantile code or RADIAN code	Example Colombia: "Regla: 0, Notificación: La Application response 6473921416, ha sido autorizada."
ResponseValue	String	Authority's response encoded in base 64.
Code	String	Process response code	Examples: 500: Some inconsistency occurred 0 or 00: It worked correctly 99: some rule did not pass validation 400: Document not found
Description	String	Description of the response of the executed process	Example Chile: "Respuesta del SII para el documento folio 17451: Accion Completada OK."
ErrorException	String	Description of the exception when an error occurs.

---

Characteristics of the ChangeDocumentStatus method

• The method allows reporting the mercantile acknowledgement statuses or RADIAN status one by one.
• When the CountryDocumentId parameter and the countryId parameter are sent in the request, it is not mandatory to also send the GlobalDocumentId parameter
• When the value of CountryDocumentId is not known, the GlobalDocumentId parameter must be sent
• The OtherData parameter can contain the following properties:

{
"Country": "co",
"Certifier": "DIAN",
"AuthorityTimeStamp": "25/07/2022 19:20:31"
}

• Some examples of rules validated in the process for the messages parameter are:

  • "Evento no puede ser registrado ya que el documento presenta un evento previo de acuse de recibo de la factura electronica de venta."
  • "La Application response 6473921416, ha sido autorizada."
  • "Solo se pueda transmitir el evento (034) Aceptación Tácita de la factura, pasados 3 días hábiles, después de la transmisión del evento (032) recibo del bien o aceptación de la prestación del servicio"
  • "No se puede recibir un reclamo si previamente no se han recibido los eventos Acuse de recibo de la factura electrónica y un recibo de bien y prestación de servicio"
  • "Esta UUID no existe en la base de datos de la DIAN"

• When the document Id (globalDocumentId) does not exist, the system responds:

{
"Success": false,
"GlobalDocumentId": "00000000-0000-0000-0000-000000000000",
"CountryDocumentId": null,
"OtherData": null,
"Messages": null,
"ResponseValue": null,
"Code": "400",
"Description": "Document Not Found",
"ErrorException": null
}

Let's look at the different scenarios in which we can use this method.