Ações em nome do participante

Ações que o participante faz no portal e que a integração pode fazer por ele, com as mesmas regras do portal: consultar e concluir o envio, justificar um documento, pedir revisão de um documento recusado e excluir um dependente. A ação fica registrada como feita pela integração.

Rotas

método e rota	o que faz	permissão (chave escopada)
`GET /v1/api/competencies/{competencyId}/participants/{participantId}/submission/status`	estado do botão "Concluir envio"	`perm:participant:read`
`POST /v1/api/competencies/{competencyId}/participants/{participantId}/submission/conclude`	conclui o envio	`perm:participant:submission:conclude`
`POST /v1/api/competencies/{competencyId}/participants/{participantId}/documents/justification`	justifica um documento	`perm:participant-document:upload`
`POST /v1/api/competencies/{competencyId}/participants/{participantId}/participant-documents/{participantDocumentId}/request-review`	pede revisão de documento recusado	`perm:participant-document:review:request`
`DELETE /v1/api/competencies/{competencyId}/participants/{participantId}/dependents/{dependentId}`	exclui um dependente e os envios dele	`perm:participant:update`

As permissões novas aparecem no painel como Concluir envio em nome do participante (perm:participant:submission:conclude) e Pedir revisão em nome do participante (perm:participant-document:review:request). As demais estão em Chaves escopadas.

Em todas, participantId é o participante na competência da rota. Se ele não existe, é de outra competência ou de outra empresa, a resposta é 404.

Consultar o estado da conclusão

curl 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/submission/status' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "enabled": true,
    "submissionCompleted": false,
    "submissionCompletedAt": null,
    "canConclude": false,
    "pendingRequiredCount": 1,
    "pendingRequiredDocumentIds": ["6500a1b2c3d4e5f60000000a"],
    "issues": []
  }
}

campo	significado
`enabled`	a competência tem o botão "Concluir envio" habilitado
`submissionCompleted` / `submissionCompletedAt`	se e quando o envio foi concluído
`canConclude`	todos os documentos obrigatórios já foram enviados
`pendingRequiredCount` / `pendingRequiredDocumentIds`	obrigatórios que faltam, pelo `competencyDocumentId` de `document-requests`
`issues`	pendências apontadas na última tentativa de conclusão

Concluir o envio

curl --request POST 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/submission/conclude' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "status": "BLOCKED",
    "submissionCompleted": false,
    "submissionCompletedAt": null,
    "issues": [
      {
        "message": "O comprovante de residência está em nome de outra pessoa.",
        "participantDocumentId": "6500a1b2c3d4e5f60000000e"
      }
    ]
  }
}

status diz o que aconteceu:

`status`	significado
`COMPLETED`	o envio foi concluído nesta chamada
`ALREADY_COMPLETED`	já estava concluído; nada muda e a chamada pode ser repetida
`BLOCKED`	a validação da competência apontou pendências em `issues`; o envio não foi concluído

BLOCKED vem com 200, não com erro: leia sempre data.status. Cada pendência traz message e, quando se refere a um documento, o participantDocumentId.

Erros:

400 se a competência não tem a conclusão de envio habilitada.
400 se ainda há documento obrigatório pendente de envio ou em processamento. Consulte antes o estado da conclusão.

Justificar um documento

A justificativa vai em multipart/form-data, com arquivo obrigatório, como no portal. O documento precisa ser de um item que aceite justificativa (acceptJustification: true em document-requests).

curl --request POST 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/documents/justification' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE' \
  --form 'participantDocumentId=6500a1b2c3d4e5f60000000e' \
  --form 'justification=Documento em emissão no órgão responsável.' \
  --form 'files=@protocolo.pdf'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": { "_id": "6500a1b2c3d4e5f60000000e" }
}

participantDocumentId, justification e files são obrigatórios.
O documento passa a JUSTIFIED, e o arquivo fica como anexo da justificativa.
422 se o item não aceita justificativa.
404 se o documento não é do participante.

Pedir revisão de documento recusado

É o mesmo pedido de revisão que o participante faz no portal: só existe depois que o revisor automático recusou um reenvio idêntico do documento. O documento volta a processar com uma análise mais rigorosa; se for recusado de novo, segue para conferência humana.

curl --request POST 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/participant-documents/6500a1b2c3d4e5f60000000e/request-review' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{ "reason": "O documento está legível e dentro da validade." }'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "_id": "6500a1b2c3d4e5f60000000e",
    "status": "PROCESSING",
    "documentStatus": "PROCESSING",
    "selfReviewAttempts": 1,
    "canAutoReprocess": false
  }
}

reason é obrigatório, de 10 a 500 caracteres. O documento vai no caminho, não no corpo.
O resultado chega como qualquer processamento: por webhook ou consulta do documento.
422, com o motivo na message, quando o pedido não cabe: tipo de documento sem revisão, documento que não está recusado, recusa por validação automática, ou revisão pedida antes da reanálise do reenvio.
404 se o documento não é do participante.

Excluir um dependente

Exclusão em cascata

Todos os documentos enviados para o dependente são excluídos junto com ele.

curl --request DELETE 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/dependents/6500a1b2c3d4e5f600000008' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "dependentId": "6500a1b2c3d4e5f600000008",
    "deletedDocumentsCount": 2
  }
}

deletedDocumentsCount é quantos envios do dependente foram excluídos.
Repetir a chamada para um dependente já excluído responde 200 com deletedDocumentsCount: 0.
Dependente que nunca existiu no participante responde 404.

Cadastro de dependentes: o que muda

POST /v1/api/participants/{participantId}/dependents aceita chave escopada, com perm:participant:create. Um item cujo CPF (ou CNPJ) já pertence a um dependente do mesmo grupo (competencyDocumentGroupId) atualiza esse dependente em vez de criar outro; com chave escopada, isso exige também perm:participant:update, senão a resposta é 403.

Para qualquer chave, campo personalizado que não existe no projeto para dependentes responde 422, e nada é gravado:

{
  "success": false,
  "status": 422,
  "message": "Custom field is not defined for this entity in the project.",
  "errors": [],
  "context": "UNKNOWN_CUSTOM_FIELD",
  "extraData": {}
}

Os nomes aceitos em customFields são os campos personalizados de dependente configurados no projeto.

Com chave escopada, um dependente com dados inválidos recusa o lote inteiro com 422 e context: "INVALID_DEPENDENT"; a message traz o nome do dependente. Com chave legada, o comportamento anterior continua: itens inválidos são ignorados e os demais são gravados.

Participante inexistente nessa rota responde 404.

Ações em nome do participante

Rotas​

Consultar o estado da conclusão​

Concluir o envio​

Justificar um documento​

Pedir revisão de documento recusado​

Excluir um dependente​

Cadastro de dependentes: o que muda​