Uso de externalCode y externalStatus

Última revisión: 15 Abril 2021

De forma opcional puedes ayudarte con el uso de dos atributos que te permitirán hacer un seguimiento a medida de los procesos de firma solicitados a Viafirma a partir de datos internos de tu negocio:

• externalCode
• externalStatus

Podrás indicarlos en tus llamadas de la siguiente forma:

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

Por ejemplo:

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

Una vez incluido estos valores que tienen significado para tu negocio podrás explotarlo de la siguiente forma:

• obtener todos los procesos de firma cuyo externalCode sea igual al indicado.
• obtener todos los procesos de firma cuyo externalStatus sea igual al idicado.

Además tú mismo podrás ir cambiando el externalStatus cuando lo vayas necesitado.

En la colección postman que puedes descargar para probar el API de Viafirma tienes un un set de casos de uso con ejemplos de los tres servicios disponibles.

Lista de procesos a partir de un externalCode

GET /messages/external/{{externalCode}}

Devuelve lista de procesos de firma que tengan el externalCode solicitado.

Lista de procesos a partir de un externalStatus

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

Devuelve lista de procesos de firma que tengan el externalStatus solicitado.

Para ambos casos la respuesta será la siguiente:

Response application/JSON:

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

Donde:

• status: es un ENUM con los siguientes valores posibles:

(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)

Ejemplo de respuesta:

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

Actualizar Estado Externo

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

Te permite actualizar el externalStatus de un proceso ya iniciado.

Actualizar Código Externo

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

Te permite actualizar el externalCode de un proceso ya iniciado.