Obter a rastreabilidade de um processo

GET/document/roadmapchave públicapuk_

Este serviço retorna a rastreabilidade completa de um processo de assinatura: quem o criou, quem participa dele e o que aconteceu em cada momento. É o serviço que você usa para auditar um processo, reconstruir seu histórico diante de uma reclamação ou alimentar um painel de acompanhamento.

A resposta contém os dados do processo, a lista de participantes e um registro de atividades ordenado em ordem cronológica crescente, do evento mais antigo ao mais recente. Não há paginação nem filtros: o processo inteiro é retornado em uma única chamada.

O que esta página cobre

Esta página documenta a rastreabilidade do processo: eventos de notificação, lembrete, leitura, assinatura, aprovação, rejeição, cancelamento e reativação. Para consultar o status atual do processo e de cada participante, use GET /document; para ler as mensagens individuais de uma conversa do WhatsApp, use GET /whatsapp/records.

Autenticação

Inclua sua chave pública no cabeçalho Authorization.

Authorization: puk_xxx...

Parâmetros de consulta

Nome	Tipo	Descrição
`code`	String obrigatório	Código do processo cuja rastreabilidade você deseja obter. Com 9 ou 10 caracteres.

code aceita o código de um contrato (9 caracteres) ou de um documento (10 caracteres); é o mesmo valor que GET /document retorna no campo code.

O processo deve pertencer à sua organização

A consulta é limitada à organização proprietária da chave pública. Um código que não existe e um código que pertence a outra organização retornam o mesmo erro, DOCUMENT_NOT_FOUND.

🧪 Exemplos de uso

dica

Você pode copiar qualquer um dos exemplos de acordo com a sua linguagem preferida.

🔹 Obter a rastreabilidade de um processo

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/roadmap?code=CODEDOCUM' \
  --header 'Authorization: puk_yourPublicKey'

import requests

response = requests.get(
  "https://api.auco.ai/v1.5/ext/document/roadmap",
  headers={"Authorization": "puk_yourPublicKey"},
  params={"code": "CODEDOCUM"}
)
print(response.json())

const axios = require('axios');

axios
  .get('https://api.auco.ai/v1.5/ext/document/roadmap', {
    headers: { Authorization: 'puk_yourPublicKey' },
    params: { code: 'CODEDOCUM' },
  })
  .then((response) => console.log(response.data));

📥 Exemplos de resposta

🔹 Processo assinado pelo WhatsApp

{
  "name": "Contrato de serviços",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-06-26T21:48:42.755Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "phone": "+573001234567"
    }
  ],
  "activityLog": [
    {
      "action": "NOTIFICATION_SIGN",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:48:44.307Z",
      "by": "+573001234567"
    },
    {
      "action": "PARTICIPANT_READ",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:49:47.523Z",
      "by": "+573001234567"
    },
    {
      "action": "PARTICIPANT_SIGN",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:50:10.940Z",
      "by": "+573001234567"
    }
  ]
}

🔸 Processo com vários participantes, uma rejeição e um cancelamento

{
  "name": "Contrato de serviços",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-02-10T14:02:11.418Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "email": "john@example.com",
      "phone": "+573001234567",
      "location": {
        "lat": 4.6533326179999995,
        "lng": -74.05834928765297,
        "street": "Calle 98 15-17, 110221 Bogotá, Colombia"
      },
      "ipAddress": "190.24.10.55 Bogotá, Bogota D.C., Colombia"
    },
    {
      "id": "02",
      "name": "Emily Clark",
      "role": "APPROVER",
      "email": "emily@example.com"
    },
    {
      "name": "Auditoria interna",
      "role": "READER",
      "email": "audit@example.com"
    }
  ],
  "activityLog": [
    {
      "action": "NOTIFICATION_SIGN",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T14:02:13.902Z",
      "by": "john@example.com"
    },
    {
      "action": "PARTICIPANT_READ",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T15:31:08.114Z",
      "by": "john@example.com",
      "ip": "190.24.10.55"
    },
    {
      "action": "PARTICIPANT_SIGN",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T15:33:44.660Z",
      "by": "john@example.com",
      "ip": "190.24.10.55"
    },
    {
      "action": "NOTIFICATION_APPROVER",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-10T15:33:47.201Z",
      "by": "emily@example.com"
    },
    {
      "action": "REMINDER_APPROVE",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-11T15:33:47.318Z",
      "by": "emily@example.com"
    },
    {
      "action": "PARTICIPANT_REJECT",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-11T16:10:29.775Z",
      "by": "emily@example.com",
      "message": "O anexo 2 não corresponde ao serviço contratado."
    },
    {
      "action": "CANCEL_SIGN",
      "platform": "ARCHIVE",
      "participant": "ARCHIVE",
      "timestamp": "2026-02-11T16:44:02.031Z",
      "by": "example@auco.ai"
    }
  ]
}

🔸 Processo criado sem notificar

Um processo criado com notification: false existe e tem participantes, mas ainda não gerou nenhum evento: activityLog retorna vazio.

{
  "name": "Contrato de serviços",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-02-10T14:02:11.418Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "email": "john@example.com"
    }
  ],
  "activityLog": []
}

📋 Campos da resposta

Campo	Tipo	Descrição
`name`	String	Nome do processo, conforme definido na criação do processo.
`documentCode`	String	Código do processo consultado. Corresponde ao `code` que você enviou.
`createdAt`	String	Data e hora de criação do processo, no formato ISO 8601 e em UTC.
`author`	Object	Opcional. Usuário da sua organização que criou o processo. Não aparece se o criador não existir mais como usuário.
`author.name`	String	Nome do criador do processo.
`author.email`	String	Opcional. Endereço de e-mail do criador do processo.
`participants`	Array<Object>	Pessoas envolvidas no processo: signatários, aprovadores e leitores. Retorna vazio (`[]`) se o processo não tiver participantes.
`participants[].id`	String	Opcional. Identificador do participante dentro do processo. É o valor para o qual `activityLog[].participant` aponta. Os leitores não o incluem, nem os participantes sem atividade registrada até o momento.
`participants[].name`	String	Opcional. Nome do participante.
`participants[].role`	String	Papel do participante no processo. Veja Papéis.
`participants[].email`	String	Opcional. Endereço de e-mail do participante.
`participants[].phone`	String	Opcional. Número de telefone do participante em formato internacional, com código do país e o sinal `+`.
`participants[].location`	Object	Opcional. Localização registrada para o participante durante o processo. Só aparece se a Auco a capturou.
`participants[].location.lat`	Number	Latitude, em graus decimais.
`participants[].location.lng`	Number	Longitude, em graus decimais.
`participants[].location.street`	String	Endereço aproximado derivado das coordenadas.
`participants[].ipAddress`	String	Opcional. Texto livre com o endereço IP registrado para o participante. Pode chegar em vários formatos: apenas o IP, ou o IP seguido da localização aproximada derivada dele. Não o trate como um endereço IP puro.
`activityLog`	Array<Object>	Eventos do processo, ordenados em ordem cronológica crescente: o primeiro elemento é o mais antigo. Retorna vazio (`[]`) se não houver atividade.
`activityLog[].action`	String	Evento ocorrido. Veja Ações.
`activityLog[].platform`	String	Canal pelo qual o evento ocorreu. Veja Plataformas.
`activityLog[].participant`	String	`id` do participante ao qual o evento pertence, ou o valor especial `ARCHIVE` quando o evento pertence ao processo e não a uma pessoa.
`activityLog[].timestamp`	String	Data e hora do evento, no formato ISO 8601 e em UTC.
`activityLog[].by`	String	Opcional. Identificador com o qual a ação foi realizada ou para o qual foi entregue: o endereço de e-mail quando `platform` é `EMAIL` e o número de telefone quando é `WHATSAPP`.
`activityLog[].ip`	String	Opcional. Endereço IP a partir do qual o evento foi registrado. Só aparece quando a Auco o recebeu.
`activityLog[].message`	String	Opcional. Texto associado ao evento, por exemplo o motivo escrito pelo participante ao rejeitar.

Os campos opcionais só chegam quando há dados

author, id, name, email, phone, location, ipAddress, by, ip, and message são omitidos da resposta quando não há valor: eles não chegam como null nem como string vazia. Sua integração deve verificar se a chave existe antes de lê-la, em vez de supor que o objeto sempre tem o mesmo formato.

participant nem sempre é uma pessoa

activityLog[].participant costuma ser o id de um elemento de participants[], mas os eventos que afetam todo o processo chegam com participant: "ARCHIVE". Esse valor não corresponde a nenhum participants[].id: se você tentar resolvê-lo na lista de participantes, não encontrará correspondência. Veja Eventos no nível do processo.

📖 Dicionário de rastreabilidade

As três colunas que você interpreta em cada evento são action (o que aconteceu), platform (por qual canal) e participant (para quem). Estas tabelas listam os valores que a Auco emite hoje.

O catálogo não é fechado

Podem aparecer valores de action, platform e role que não estão nestas tabelas: o catálogo cresce junto com o produto. Não construa sua integração supondo que a lista é fechada. Trate um valor desconhecido como um evento que você ainda não consegue classificar — exiba-o como está, registre-o em log — em vez de descartá-lo ou deixar seu processamento falhar.

Ações (`activityLog[].action`)

Notificações enviadas pela Auco

`action`	Significado
`NOTIFICATION_SIGN`	Convite para assinar enviado
`NOTIFICATION_APPROVER`	Convite para aprovar enviado
`NOTIFICATION_FINISH`	Notificação de conclusão enviada
`NOTIFICATION_FAILED_SIGN`	Falha no convite para assinar

Lembretes

`action`	Significado
`REMINDER_SIGN`	Lembrete de assinatura enviado
`REMINDER_APPROVE`	Lembrete de aprovação enviado
`REMINDER_UPLOAD`	Lembrete de envio de arquivo
`REMINDER_PAYMENT`	Lembrete de pagamento

Os lembretes podem vir do agendamento automático do processo ou de um envio manual com POST /document/reminder.

Ações dos participantes

`action`	Significado
`PARTICIPANT_READ`	Documento visualizado
`PARTICIPANT_SIGN`	Documento assinado
`PARTICIPANT_APPROVE`	Documento aprovado
`PARTICIPANT_REJECT`	Documento rejeitado
`READ_PARTICIPANT`	Documento visualizado

READ_PARTICIPANT equivale a PARTICIPANT_READ

Alguns processos registram o evento de leitura como READ_PARTICIPANT. Ele significa exatamente o mesmo que PARTICIPANT_READ: o participante abriu o documento. Se você classifica os eventos pelo valor de action, trate os dois como o mesmo evento.

Alterações no processo

`action`	Significado
`UPDATE_SIGNER`	Participante atualizado
`UPDATE_SIGN`	Assinatura atualizada
`CANCEL_SIGN`	Processo cancelado
`REACTIVATION_SIGN`	Processo reativado

Papéis (`participants[].role`)

Valor	Significado	Descrição
`SIGNER`	Signatário	Deve assinar o documento. É o papel padrão.
`APPROVER`	Aprovador	Deve aprovar ou rejeitar o documento, sem assiná-lo.
`READER`	Leitor	Recebe o documento para revisá-lo; não assina nem aprova.

O papel é definido na criação do processo e retornado como está, portanto você também pode encontrar valores específicos da sua integração.

Plataformas (`activityLog[].platform`)

Valor	Descrição
`EMAIL`	O evento ocorreu por e-mail.
`WHATSAPP`	O evento ocorreu pelo WhatsApp.
`ARCHIVE`	O evento foi realizado a partir do arquivo web da Auco, e não de um canal para um participante.

Quando platform é WHATSAPP, você pode obter o detalhe da conversa — as mensagens e seus status de entrega — com GET /whatsapp/records.

Eventos no nível do processo (`participant: "ARCHIVE"`)

Alguns eventos não pertencem a um participante, mas ao processo como um todo: um cancelamento realizado a partir do arquivo web da Auco, por exemplo. Esses eventos chegam com participant: "ARCHIVE", e o campo by identifica o usuário da sua organização que realizou a ação, não um signatário.

Trate-os como eventos no nível do processo: não tente resolver ARCHIVE com participants[].id, pois nunca haverá correspondência.

⚠️ Respostas de erro

Código	Descrição
400	Erro de validação no parâmetro `code` (ausente, ou com comprimento fora do intervalo de 9 a 10 caracteres), ou processo não encontrado (`DOCUMENT_NOT_FOUND`).
401	Autenticação inválida ou ausente

DOCUMENT_NOT_FOUND é retornado quando o processo não existe ou não pertence à organização da chave pública com a qual você está consultando.

Autenticação​

Parâmetros de consulta​

🧪 Exemplos de uso​

🔹 Obter a rastreabilidade de um processo​

📥 Exemplos de resposta​

🔹 Processo assinado pelo WhatsApp​

🔸 Processo com vários participantes, uma rejeição e um cancelamento​

🔸 Processo criado sem notificar​

📋 Campos da resposta​

📖 Dicionário de rastreabilidade​

Ações (activityLog[].action)​

Papéis (participants[].role)​

Plataformas (activityLog[].platform)​

Eventos no nível do processo (participant: "ARCHIVE")​

⚠️ Respostas de erro​