Using externalCode and externalStatus

Latest update: April 15th, 2021

Optionally, you can use two attributes that will allow you to make a customized follow-up on the signing process requested to Viafirma based on the internal data of your business:

• externalCode
• externalStatus

You can specify them in your calls as follows:

{
    "externalCode" : "string",
    "externalStatus" : "string"
}

For example:

{
  "groupCode" : "{{groupCode}}",
  "externalCode" : "Ejemplo_mi_expediente_00AA999",
  "externalStatus" : "mi_estado_de_tramitacion_interna",
  "workflow" : {
    "type" : "WEB"
  },
  "notification" : {
    "text" : "TEST Firma web",
    "detail" : "notificado vía email",
    "sharedLink" : {
      "email" : "{{SIGNER_01_MAIL}}",
      "subject" : "TEST firma remota"
    }
  },
  "document" : {
    "templateCode" : "{{templateCode}}"
  }
}

Once you have included the values that have meaning for your business, you can exploit them as follows:

• obtain all signing processes with externalCode equal to the specified one.
• obtain all signing processes with externalStatus equal to the one specified.

In addition, you can change the externalStatus whenever you need it.

In the postman collection which you can download to test Viafirma's API you have a set of use cases with examples of the three available services.

List of processes from an externalCode

GET /messages/external/{{externalCode}}

Returns list of signing processes that have the requested externalCode.

### List of processes from an externalStatus

GET /messages/external/status/{{externalStatus}}

Returns list of signing processes that have the requested externalStatus.

For both cases the response will be as follows:

Response application/JSON:

[
    {
        "messageCode": "string",
        "status": "string",
        "userCode": "string",
        "groupCode": "string",
        "templateCode": "string",
        "creationDate": 0,
        "externalCode": "string",
        "externalStatus": "string"
    }
]

Where:

• status: an ENUM with the following possible values:

(DELETED, EXPIRED, ERROR, REJECTED, TRANSFERRED, RESPONSED, SERVER_SIGN, 
SENT, SIGNED, WAITING, COMMITTED, RECEIVED, TEMPORAL_STORED, STAND_BY, 
WAITING_CHECK, APPROVED, FINISHED, WAITING_OCR, WAITING_CLIENT_SIGNATURE, 
MAX_ERROR_REACHED, ATTACHMENT_VERIFICATION, TRANSFER_CANCELED, SAVED, INVALID, 
WAITING_EXTERNAL_APPROVAL, WORKFLOW_PROCESS)

• creationDate: int (epoch timestamp in milliseconds)

Response example:

[
    {
        "messageCode": "LSC11603886068032R559",
        "status": "RESPONSED",
        "userCode": "john",
        "groupCode": "myGroup01",
        "templateCode": "template901",
        "creationDate": 1603886068000,
        "externalCode": "test000",
        "externalStatus": "testStatusA"
    }
]

Update externalStatus

PUT /messages/external/{{messageCode}}/status/{{externalStatus}}

Allows you to update the externalStatus of a process.

Update externalCode

PUT /v3/messages/external/{messageCode}/code/{code}

Allows you to update the externalCode of a process.