Catálogo

Quais documentos a minha empresa tem acesso? É o que estas três consultas respondem: os tipos habilitados para ela, as declarações cadastradas e os tipos de documento customizados.

Os documentos são liberados empresa por empresa. O catálogo da Dynadok tem centenas de tipos, e a sua empresa enxerga só o subconjunto que foi habilitado para ela — não há como adivinhar quais são. Estas três consultas respondem isso e devolvem os ids que você usa no resto da integração.

Procurando document-types?

É aqui. A rota que lista os tipos de documento habilitados para a sua chave se chama GET /v1/api/catalog/documents — não existe /document-types nem /companies/me/document-types.

Também não use a lista de valores de type do contrato OpenAPI para isso: ela é o catálogo da plataforma, com centenas de tipos, e não o que a sua empresa tem acesso. Enviar um tipo não habilitado responde 400:

O tipo de documento "X" não está liberado para a sua empresa.
O catálogo liberado está em GET /v1/api/catalog/documents.

Rotas

método e rota	o que faz
`GET /v1/api/catalog/documents`	`List the document types released to the company`
`GET /v1/api/catalog/declarations`	`List the declarations of the company`
`GET /v1/api/catalog/custom-document-types`	`List the custom document types of the company`

O item do catálogo

As três rotas devolvem o mesmo formato de item:

campo	o que é
`documentId`	id do documento no catálogo
`declarationId`	id da declaração, ou `null`
`customDocumentTypeId`	id do tipo customizado, ou `null`
`type`	tipo do documento (ex.: `RG`, `CNH`)
`title`	nome exibido

declarationId e customDocumentTypeId vêm sempre, com null quando não se aplicam, e têm os mesmos nomes que aparecem em acceptedDocuments na consulta de documentos solicitados. É por essas chaves que você casa um item do catálogo com um documento solicitado, sem traduzir nome de campo no meio do caminho.

O caminho inverso não é garantido

O catálogo lista o que a empresa pode pedir hoje. Um documento solicitado guarda o que foi configurado quando foi configurado — então um declarationId ou customDocumentTypeId que aparece em acceptedDocuments pode não estar nestas listas, se depois disso a declaração foi arquivada ou removida, ou o tipo customizado voltou a rascunho.

Isso não quebra nada do que já existe: o documento solicitado continua aparecendo, o envio continua sendo aceito, e os arquivos já enviados continuam sendo lidos e baixados normalmente. O envio é identificado pelo competencyDocumentId do slot, não pelo catálogo.

Na prática: use o catálogo para descobrir o que pedir, e acceptedDocuments para saber o que um participante já tem pedido. Não trate "não está no catálogo" como "este slot é inválido".

A natureza do item vem do type, com a mesma regra nas duas consultas — não existe um campo de categoria para isso:

`type`	natureza
`DECLARACAO_DO_CLIENTE`	declaração
`TIPO_DOCUMENTO_CUSTOMIZADO`	tipo customizado
qualquer outro	documento comum

Os ids dizem qual: declarationId aponta a declaração cadastrada, customDocumentTypeId o tipo customizado. Se você juntar as três listas, é por type que separa de novo.

Em declaração e em tipo customizado, o documentId repete entre os itens: um único documento do catálogo representa toda a categoria, e quem identifica o item é declarationId ou customDocumentTypeId.

Documentos liberados

curl 'https://api.dynadok.com/v1/api/catalog/documents?page=1&perPage=20' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": [
    {
      "documentId": "6500a1b2c3d4e5f600000011",
      "declarationId": null,
      "customDocumentTypeId": null,
      "type": "CNH",
      "title": "CNH"
    },
    {
      "documentId": "6500a1b2c3d4e5f600000012",
      "declarationId": null,
      "customDocumentTypeId": null,
      "type": "HOLERITE",
      "title": "Contracheque"
    }
  ],
  "meta": { "page": 1, "perPage": 20, "total": 261, "lastPage": 14 }
}

Só aparece o que está habilitado para a sua empresa. Um tipo que existe no catálogo da Dynadok mas não foi liberado para você não vem nesta lista — e não pode ser pedido numa competência. Para liberar, fale com o suporte.

Aceita também juridicNature (PF ou PJ) para restringir aos documentos daquela natureza jurídica.

Declarações

curl 'https://api.dynadok.com/v1/api/catalog/declarations' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": [
    {
      "documentId": "6500a1b2c3d4e5f600000020",
      "declarationId": "6500a1b2c3d4e5f600000021",
      "customDocumentTypeId": null,
      "type": "DECLARACAO_DO_CLIENTE",
      "title": "Declaração de residência"
    }
  ],
  "meta": { "page": 1, "perPage": 10, "total": 1, "lastPage": 1 }
}

Declaração arquivada não aparece: arquivar é o desligamento da declaração, equivalente a um documento não liberado. Os documentos solicitados que já apontavam para ela seguem valendo — ver a ressalva acima.

Tipos de documento customizados

curl 'https://api.dynadok.com/v1/api/catalog/custom-document-types' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": [
    {
      "documentId": "6500a1b2c3d4e5f600000030",
      "declarationId": null,
      "customDocumentTypeId": "6500a1b2c3d4e5f600000031",
      "type": "TIPO_DOCUMENTO_CUSTOMIZADO",
      "title": "Ficha de matrícula"
    }
  ],
  "meta": { "page": 1, "perPage": 10, "total": 1, "lastPage": 1 }
}

Vêm só os tipos publicados — rascunho em edição no painel não entra, nem tipo publicado que recebeu edição ainda não publicada. Os documentos solicitados que já apontavam para ele seguem valendo — ver a ressalva acima. Todos compartilham o mesmo type, TIPO_DOCUMENTO_CUSTOMIZADO, e o mesmo documentId; quem distingue é o customDocumentTypeId.

Se a sua empresa não tem a funcionalidade de documentos customizados habilitada, esta rota responde 403. As outras duas seguem funcionando.

Paginação e busca

As três aceitam page (padrão 1), perPage (padrão 10), query para busca textual pelo nome, e orderByColumn/orderByDirection. A resposta usa o envelope padrão com meta de paginação.

O catálogo de documentos pode passar de 250 itens numa empresa — pagine, não assuma que a primeira página traz tudo.

Do catálogo até o envio

O catálogo diz o que a empresa pode pedir. Ele não diz o que foi pedido a um participante: isso está em GET /v1/api/participants/{participantId}/document-requests, que traz cada documento solicitado com o competencyDocumentId usado no envio.

E atenção: type não identifica um documento solicitado — a mesma competência pode pedir dois documentos do mesmo tipo. No upload, mande sempre o competencyDocumentId.

Erros típicos

Ver Envelope e erros. Chave inválida ou revogada responde 401; empresa sem a funcionalidade de documentos customizados responde 403 na rota correspondente.

Catálogo

Rotas​

O item do catálogo​

Documentos liberados​

Declarações​

Tipos de documento customizados​

Paginação e busca​

Erros típicos​