YOUK — Documentação da API

A API do YOUK permite que o sistema do parceiro (folha de pagamento, RH, ponto ou qualquer outro) envie documentos aos colaboradores de forma automática. Cada documento enviado é entregue ao colaborador diretamente no aplicativo YOUK, onde ele pode visualizar e, quando necessário, assinar digitalmente.

https://api.youk.com.br/v1

O que é um evento?

Na API do YOUK, evento é o nome dado a um documento enviado para um colaborador. Qualquer tipo de documento pode ser enviado, sempre em formato PDF: recibo de pagamento, recibo de férias, 13º salário, informe de rendimentos, espelho de folha de ponto, notificação de advertência ou qualquer outro documento do seu processo, usando o tipo CUSTOMIZADO.

Fluxo de integração

1. Enviar o documento — faça um POST /v1/eventos com o PDF em base64 e os dados do colaborador. A resposta retorna o uid do documento.
2. Acompanhar a entrega — consulte GET /v1/eventos/:id para saber o status de entrega e de assinatura do documento.
3. Baixar o documento assinado — quando o documento for assinável e o colaborador assinar, baixe o PDF assinado em GET /v1/eventos/:id/download_assinado.

Cadastro automático

Ao enviar um documento, o colaborador, o departamento, os grupos e o tipo do documento são cadastrados automaticamente caso ainda não existam. Colaborador, departamento e grupos são atualizados com o conteúdo do payload quando já existem; o tipo do documento, quando já existe, é reutilizado sem alterações. Não é necessário cadastrar o colaborador antes de enviar o primeiro documento.

Formato das requisições

A API aceita e retorna JSON com codificação UTF-8. Nas requisições POST, envie o cabeçalho Content-Type: application/json. Todos os campos do payload são textuais (string), exceto quando indicado como boolean, objeto ou lista.

Autenticação

Todas as requisições (exceto GET /v1/health) exigem um token de acesso enviado no cabeçalho Authorization, no formato Bearer.

O token é obtido pelo gestor da empresa na página administrativa do YOUK (manager.youk.com.br), na área de integrações.

curl --location 'https://api.youk.com.br/v1/eventos/kr7e9QlVOZsR6Qws0hmp' \
--header 'Authorization: Bearer SEU_TOKEN'

Erros de autenticação

Observação: no erro de token inválido, o campo code do corpo difere do status HTTP retornado. Utilize o status HTTP como referência para o tratamento de erros.

Erros

Erros são retornados com o status HTTP correspondente e um corpo JSON com o código, a mensagem e, quando disponível, detalhes adicionais.

Erros de validação

Quando o payload possui campos inválidos, a resposta traz status 400 e a lista completa de erros em details.erros. Cada item indica o campo em field, usando notação com ponto para campos aninhados (por exemplo, colaborador.nome) e prefixo com o número do item para listas (por exemplo, [1]grupos.descricao).

{
    "code": 400,
    "message": "Evento inválido",
    "details": {
        "valid": false,
        "erros": [
            {
                "code": 400,
                "message": "colaborador.nome - Precisa ter entre 2 e 120 caracteres",
                "field": "colaborador.nome"
            }
        ]
    }
}

Endereço não encontrado

Requisições para um caminho inexistente retornam 404:

{
    "code": 404,
    "message": "Endereço '/v1/caminho-invalido' não encontrado.",
    "details": {
        "metodo": "GET"
    }
}

Status da API

Verifica se a API está disponível. Não exige autenticação e pode ser usado em monitoramentos e testes de conectividade.

curl --location 'https://api.youk.com.br/v1/health'

{
    "status": "ok"
}

Enviar documento

Envia um documento em PDF para um colaborador. O documento é entregue no aplicativo YOUK e, quando marcado como assinável, o colaborador é solicitado a assiná-lo digitalmente.

Se o colaborador, o departamento ou os grupos ainda não existirem, eles são criados automaticamente com os dados do payload; se já existirem, são atualizados. O tipo do documento é criado automaticamente quando não existe; quando já existe (localizado pela descrição), é reutilizado sem alterações. A empresa deve estar cadastrada previamente no manager.youk.com.br.

Campos do payload

Tipo do documento (tipo)

Indica ao YOUK qual documento está sendo enviado. Use um dos tipos pré-definidos ou CUSTOMIZADO para qualquer outro documento.

Colaborador (colaborador)

Destinatário do documento. O colaborador é localizado pelo uid, depois pelo externo_id e por último pelo documento na empresa informada. Se não for encontrado, é criado automaticamente; se for encontrado, os dados são atualizados.

Empresa (colaborador.empresa)

Endereço (endereco)

Todos os campos do endereço são opcionais.

Departamento e grupos (departamento e grupos)

Estruturas idênticas usadas para organizar os colaboradores. São criados automaticamente quando não existem e atualizados quando já existem. O departamento é ignorado quando a descricao não é informada.

Exemplo de requisição

curl --location 'https://api.youk.com.br/v1/eventos' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "externo_id": "REC-2025-06-0001",
    "tipo": {
        "externo_id": "1",
        "tipo": "PAGAMENTO"
    },
    "data_referencia": "2025-06",
    "arquivo_base64": "JVBERi0xLjQK...",
    "colaborador": {
        "externo_id": "12345",
        "nome": "João da Silva",
        "documento": "111.444.777-35",
        "documento_tipo": "CPF",
        "data_admissao": "2024-01-15",
        "contato": {
            "telefone": "(21) 99999-0000"
        },
        "endereco": {
            "logradouro": "Rua das Flores",
            "numero": "12",
            "bairro": "Centro",
            "cidade": "Teresópolis",
            "estado_sigla": "RJ",
            "pais": "Brasil",
            "complemento": "Fundos",
            "cep": "25710-140"
        },
        "empresa": {
            "externo_id": "77",
            "nome_razao": "Empresa Exemplo LTDA",
            "documento": "11.222.333/0001-81",
            "documento_tipo": "CNPJ"
        },
        "departamento": {
            "externo_id": "10",
            "descricao": "Comercial"
        },
        "grupos": [
            {
                "externo_id": "5",
                "descricao": "Supervisores"
            }
        ]
    },
    "opcoes": {
        "assinavel": true,
        "retificar_anteriores": true
    }
}'

Resposta

{
    "uid": "kr7e9QlVOZsR6Qws0hmp"
}

Erros

Consultar documento

Consulta a situação de um documento enviado: se já foi entregue ao colaborador e, quando assinável, se já foi assinado. Substitua :id pelo uid retornado no envio do documento.

curl --location 'https://api.youk.com.br/v1/eventos/kr7e9QlVOZsR6Qws0hmp' \
--header 'Authorization: Bearer SEU_TOKEN'

{
    "id": "kr7e9QlVOZsR6Qws0hmp",
    "status_entrega": "ENTREGUE",
    "assinatura": {
        "assinavel": true,
        "status": "PENDENTE"
    }
}

Campos da resposta

Erros

Baixar documento assinado

Baixa o PDF assinado pelo colaborador. Disponível apenas para documentos enviados como assináveis (opcoes.assinavel = true) e que já foram assinados — acompanhe pelo campo assinatura.status da consulta. Substitua :id pelo uid retornado no envio do documento.

curl --location 'https://api.youk.com.br/v1/eventos/kr7e9QlVOZsR6Qws0hmp/download_assinado' \
--header 'Authorization: Bearer SEU_TOKEN'

{
    "arquivo": "JVBERi0xLjQK..."
}

O campo arquivo contém o PDF assinado codificado em base64.

Erros