Portal do Cliente

O Portal do Cliente é a área da WebApiAlcance consumida pelo cliente final da Alcance Contabilidade (a empresa atendida), e não por operadores internos. Ele agrega dez grupos de rotas, todos sob o prefixo /portal:

  • Autenticação e gestão de acessos - login, sessão SSO, logout, perfil e autoatendimento do titular, troca de empresa ativa, recuperação de senha e o CRUD administrativo de acessos e vínculos com empresas.
  • Dados - lançamentos de lucro, sócios (QSA), resumo fiscal, simulação fiscal, competências sem movimento e resumo de ATA.
  • Plano de Saúde - operadoras vinculadas, dependentes e lançamentos de plano de saúde.
  • Certidões - certidões negativas da empresa (somente leitura).
  • Guias - guias de ISS e DCTFWeb/PGDAS, download do PDF e pagamento informado pelo cliente.
  • Situações fiscais - SITFIS da empresa (somente leitura).
  • Alvarás - alvarás de funcionamento e download do PDF.
  • TFF - guias de TFF de Salvador e download do PDF.
  • Chamados - abertura, thread de mensagens, anexos, encerramento e avaliação de chamados.
  • Financeiro - resumo, transações, CSV e consentimentos Open Finance (exige permissão de gestão no portal).
  • Notas fiscais - notas de serviço emitidas e recebidas pela empresa ativa e download do arquivo (somente leitura).

A marca registrada de todo o portal é o isolamento pela empresa ativa: o identificador da empresa vem sempre do token (id_cliente_ativo do contexto autenticado) e nunca do path/query/body. Assim o usuário do cliente A jamais enxerga (ou grava) dados do cliente B - o padrão anti-IDOR aplicado em cada rota. Recurso de outra empresa responde 404, nunca 403.

Autenticação própria do portal

O portal tem autenticação própria (token do portal, emitido no login do cliente); credenciais da API interna não autenticam rotas do portal.

Base path

/api/v1/portal

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/portal.

Autenticação

Como o portal não usa escopos recurso:acao, cada endpoint indica a Proteção aplicável. As proteções do token do portal são cumulativas (cada uma inclui a anterior):

ProteçãoRótulo nas rotasO que exige
PúblicopúblicoNada. Rotas de login, sessão SSO, logout, confirmação de e-mail, recuperação de senha e a foto do atendente. Todas sujeitas a limite de tentativas.
Token do portaltoken do portalBearer do portal válido, não revogado (por exemplo, no logout), usuário ativo, id_cliente do token pertencente aos vínculos ativos do acesso e token não anterior à última troca de senha. Falha = 401.
Token com senha definitivatoken com senha definitivaO anterior + a senha já não ser a provisória definida pelo escritório. Falha = 403 com message: { "codigo": "SENHA_PROVISORIA", "mensagem": "..." }.
Token com empresa ativatoken com empresa ativaO anterior + existir empresa ativa na sessão. Falha = 403 com message: { "codigo": "SEM_EMPRESA_VINCULADA", "mensagem": "..." }. É a proteção de todas as rotas de dados.
Permissão de gestãopermissão de gestão no portalO anterior + permissão de gestão no portal. Falha = 403. Só as rotas de Financeiro.
Uso internouso interno do escritório (restrito)Usuário do escritório com permissão adicional; sem ela, 403. Só as rotas de /portal/users.

O cliente faz login em POST /portal/auth/token (JSON com identifier + password) e recebe o JWT. O login também cria uma sessão SSO própria do portal, em um cookie de sessão, que POST /portal/auth/session troca por um access token novo.

Multi-empresa

Um acesso pode estar vinculado a várias empresas (vínculo N:N). O token carrega a empresa ativa da sessão, que é revalidada a cada request - revogar um vínculo tem efeito imediato. A empresa ativa é trocada por POST /portal/auth/switch-customer, que emite um token novo. Um acesso sem nenhum vínculo ativo consegue logar, ver /auth/me e sair, mas toda rota de dados responde 403 SEM_EMPRESA_VINCULADA.

Endpoints

As respostas com envelope seguem o formato de success_response: { "status": "success", "message": "...", "data": ... }. Algumas listagens antigas (lucro, sócios, plano de saúde) respondem error_response quando não há registros: { "status": "error", "message": "...", "details": [] }. Erros levantados pela rota (401, 403, 404, 409, 422, 429) seguem o formato padrão do FastAPI, { "detail": ... }.

Exceções ao envelope: o login (POST /auth/token) e a sessão SSO (POST /auth/session) devolvem o token cru; downloads de PDF, CSV e foto devolvem o binário; DELETE /lancamentos-lucro/sem-movimento responde 204 sem corpo.

Autenticação do Portal

Sessão, perfil e autoatendimento do titular do acesso.

POST /portal/auth/token

Login do cliente no portal. Aceita login OU e-mail no mesmo campo identifier + password, tudo em JSON (diferente do /auth/token interno, que é form-urlencoded/OAuth2). Cria a sessão SSO do portal (cookie de sessão) e grava a empresa ativa nela. Sujeito a limite de tentativas.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - as credenciais vão no corpo (PortalLoginRequest): identifier, password e, opcionalmente, remember.

Request

{
  "identifier": "empresa.acme",
  "password": "senha-do-portal",
  "remember": false
}

Response 200 OK

Retorna TokenOut - não usa o envelope padrão. customer é a empresa ativa (pode ser null no acesso sem vínculo ativo) e empresas lista todas as empresas vinculadas. Credenciais inválidas retornam 401 com message: "Credenciais inválidas"; senha provisória vencida retorna 401 com message: { "codigo": "SENHA_PROVISORIA_EXPIRADA", "mensagem": "..." }.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "portal_user": {
    "id": 3,
    "id_cliente": 1,
    "nome": "Financeiro Acme",
    "login": "empresa.acme",
    "email": "financeiro@acme.com.br",
    "perfil": "<perfil>",
    "ativo": true,
    "ultimo_login": "2026-07-03T09:12:00",
    "data_hora_criacao": "2026-01-10T14:00:00",
    "celular": "71988887777",
    "telefone": null,
    "email_novo_pendente": null,
    "senha_provisoria_em": null,
    "senha_provisoria": false,
    "senha_provisoria_expirada": false
  },
  "customer": {
    "id": 1,
    "razao_social": "ACME SERVICOS LTDA",
    "nome_fantasia": "ACME",
    "cpfecnpj": "12.345.678/0001-99",
    "cidade": "Salvador"
  },
  "empresas": [
    {
      "id": 1,
      "razao_social": "ACME SERVICOS LTDA",
      "nome_fantasia": "ACME",
      "cpfecnpj": "12.345.678/0001-99",
      "cidade": "Salvador",
      "ativa": true,
      "vinculada_em": "2026-01-10T14:00:00"
    }
  ]
}

Proteção: público - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/session

Retoma a sessão do portal (SSO): troca o cookie de sessão por um access token novo, rotacionando a sessão. A empresa ativa gravada na sessão sobrevive à renovação; se o vínculo dela foi revogado, cai na mesma regra de escolha do login. Responde com Cache-Control: no-store.

Parâmetros

Sem parâmetros e sem corpo - a credencial é o cookie de sessão. Sem cookie, sessão inválida ou usuário inativo retornam 401 com message: "session_expired".

Request

Sem corpo de requisição (o navegador envia o cookie).

Response 200 OK

Não usa o envelope padrão. expires_in é a validade do token em segundos e id_cliente é a empresa ativa da sessão renovada.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 28800,
  "id_cliente": 1
}

Proteção: público (cookie de sessão) - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/logout

Encerra a sessão do portal: revoga o token apresentado (se houver) e a sessão do cookie, e expira o cookie.

Parâmetros

Sem parâmetros. O Bearer é opcional (o logout funciona mesmo com o access token já expirado).

Request

Sem corpo de requisição.

Response 200 OK

revoked indica se algo foi revogado de fato.

{
  "status": "success",
  "message": "Logout efetuado.",
  "data": {
    "revoked": true
  }
}

Proteção: público (Bearer opcional).

GET /portal/auth/me

Retorna o usuário do portal autenticado, a empresa ativa (customer) e a lista de empresas vinculadas. Responde 200 mesmo para acesso sem vínculo ativo (customer: null, empresas: []) e mesmo com senha provisória - o front usa senha_provisoria para abrir o modal de troca.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo da resposta é o PortalMeOut ({ portal_user, customer, empresas }).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Usuário do portal recuperado",
  "data": {
    "portal_user": {
      "id": 3,
      "id_cliente": 1,
      "nome": "Financeiro Acme",
      "login": "empresa.acme",
      "email": "financeiro@acme.com.br",
      "perfil": "<perfil>",
      "ativo": true,
      "ultimo_login": "2026-07-03T09:12:00",
      "data_hora_criacao": "2026-01-10T14:00:00",
      "celular": "71988887777",
      "telefone": null,
      "email_novo_pendente": null,
      "senha_provisoria_em": null,
      "senha_provisoria": false,
      "senha_provisoria_expirada": false
    },
    "customer": {
      "id": 1,
      "razao_social": "ACME SERVICOS LTDA",
      "nome_fantasia": "ACME",
      "cpfecnpj": "12.345.678/0001-99",
      "cidade": "Salvador"
    },
    "empresas": [
      {
        "id": 1,
        "razao_social": "ACME SERVICOS LTDA",
        "nome_fantasia": "ACME",
        "cpfecnpj": "12.345.678/0001-99",
        "cidade": "Salvador",
        "ativa": true,
        "vinculada_em": "2026-01-10T14:00:00"
      }
    ]
  }
}

Proteção: token do portal.

PATCH /portal/auth/me

Autoatendimento de cadastro: o titular altera apenas nome, celular e telefone. Enviar qualquer outro campo (login, perfil, email, password, id_cliente, ativo) resulta em 422. Devolve o mesmo payload de GET /portal/auth/me.

Parâmetros

Sem parâmetros de rota ou query. O corpo é um PortalMeUpdate (PATCH parcial): campo ausente não altera nada; celular/telefone enviados como "" apagam o valor; máscara é aceita e removida (persistem só os dígitos).

Request

{
  "nome": "Financeiro Acme Matriz",
  "celular": "(71) 98888-7777",
  "telefone": ""
}

Response 200 OK

Mensagem "Dados atualizados com sucesso" e data no mesmo formato de GET /portal/auth/me (PortalMeOut).

Proteção: token com senha definitiva.

POST /portal/auth/change-password

Troca a senha pelo titular (inclusive para sair do estado de senha provisória). Exige a senha atual, encerra todas as sessões do titular em qualquer dispositivo e devolve um token novo, na mesma empresa ativa, além de recriar o cookie de sessão.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalChangePasswordRequest: senha_atual e nova_senha. Senha atual incorreta = 401; nova senha recusada pela política (mínimo de 12 caracteres e demais regras) = 422.

Request

{
  "senha_atual": "senha-provisoria",
  "nova_senha": "uma-senha-nova-bem-longa"
}

Response 200 OK

{
  "status": "success",
  "message": "Senha alterada com sucesso. As sessões anteriores foram encerradas.",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 28800
  }
}

Proteção: token do portal - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/switch-customer

Troca a empresa ativa da sessão (multi-empresa). Revalida o vínculo ativo com a empresa pedida, revoga o token anterior, grava a escolha na sessão e devolve um token novo já com a nova empresa. Empresa inexistente ou não vinculada retornam o mesmo 403 (indistinguíveis). Responde com Cache-Control: no-store.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalSwitchCustomerRequest: id_cliente (int >= 1).

Request

{
  "id_cliente": 11
}

Response 200 OK

{
  "status": "success",
  "message": "Empresa ativa alterada com sucesso.",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 28800,
    "customer": {
      "id": 11,
      "razao_social": "ACME FILIAL LTDA",
      "nome_fantasia": "ACME Filial",
      "cpfecnpj": "12.345.678/0002-70",
      "cidade": "Lauro de Freitas"
    },
    "empresas": [
      {
        "id": 1,
        "razao_social": "ACME SERVICOS LTDA",
        "nome_fantasia": "ACME",
        "cpfecnpj": "12.345.678/0001-99",
        "cidade": "Salvador",
        "ativa": false,
        "vinculada_em": "2026-01-10T14:00:00"
      },
      {
        "id": 11,
        "razao_social": "ACME FILIAL LTDA",
        "nome_fantasia": "ACME Filial",
        "cpfecnpj": "12.345.678/0002-70",
        "cidade": "Lauro de Freitas",
        "ativa": true,
        "vinculada_em": "2026-03-02T10:00:00"
      }
    ]
  }
}

Proteção: token com senha definitiva - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/email-change

Etapa 1 de 2 da troca de e-mail. Não troca o e-mail: registra a pendência, envia um link de confirmação ao endereço novo (válido por 2 horas) e um aviso ao endereço antigo. Até a confirmação, o e-mail atual continua valendo (o pendente aparece em email_novo_pendente).

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalEmailChangeRequest: novo_email e senha_atual. Senha atual incorreta = 401; endereço indisponível = 422; URL do portal não configurada no servidor = 503 (nada é gravado nem enviado).

Request

{
  "novo_email": "novo.financeiro@acme.com.br",
  "senha_atual": "minha-senha-atual"
}

Response 200 OK

A resposta não ecoa o token nem o endereço novo.

{
  "status": "success",
  "message": "Enviamos um link de confirmação para o novo e-mail. Ele vale por 2 horas. Até você confirmar, o e-mail atual continua valendo.",
  "data": {
    "aviso_ao_email_anterior_enviado": true,
    "aviso_ao_email_anterior_erro": null,
    "validade_horas": 2
  }
}

Proteção: token com senha definitiva - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/email-confirm

Etapa 2 de 2 da troca de e-mail. Pública - o token do link é a credencial (o cliente costuma clicar no celular, sem o portal logado). Token inexistente, expirado ou já usado retornam o mesmo 400 com a mesma mensagem.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalEmailConfirmRequest: token (1-512 caracteres). Endereço que ficou indisponível entre o pedido e o clique retorna 409.

Request

{
  "token": "Zt3n0qkV2b8c..."
}

Response 200 OK

Devolve só o e-mail agora vigente.

{
  "status": "success",
  "message": "E-mail confirmado e atualizado. Use-o no próximo acesso ao Portal.",
  "data": {
    "email": "novo.financeiro@acme.com.br"
  }
}

Proteção: público (token do link) - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/login-change

Troca o login do titular - imediata, sem etapa de confirmação, mas exigindo a senha atual e enviando aviso ao e-mail vigente com o login novo.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalLoginChangeRequest: novo_login (normalizado para minúsculas; 3 a 100 caracteres, letras minúsculas, números, ponto, hífen e sublinhado) e senha_atual. Status: 401 senha atual incorreta; 422 formato inválido ou igual ao atual; 409 login em uso por outro acesso.

Request

{
  "novo_login": "acme.financeiro",
  "senha_atual": "minha-senha-atual"
}

Response 200 OK

{
  "status": "success",
  "message": "Login alterado. Use-o no próximo acesso ao Portal.",
  "data": {
    "login": "acme.financeiro",
    "aviso_por_email_enviado": true,
    "aviso_por_email_erro": null
  }
}

Proteção: token com senha definitiva - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/password-recovery

Etapa 1 de 2 da recuperação de senha. Pública e responde sempre 202 com o mesmo corpo, exista ou não a conta (a rota não é enumeradora de clientes). Se a conta existir, envia um link de redefinição válido por 2 horas.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalRecoveryRequest: identificador (login ou e-mail, até 255 caracteres).

Request

{
  "identificador": "financeiro@acme.com.br"
}

Response 202 Accepted

{
  "status": "success",
  "message": "Se existir uma conta com esse login ou e-mail, enviamos um link para redefinir a senha. O link vale por 2 horas.",
  "data": {
    "enviado": true
  }
}

Proteção: público - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/auth/password-reset

Etapa 2 de 2 da recuperação de senha. Pública - o token do link é a credencial. Redefine a senha, mas não devolve sessão (nem token, nem cookie): o cliente precisa entrar pelo login com a senha nova. Token inválido (inexistente, expirado ou usado) = 400; senha recusada pela política = 422.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalResetRequest: token e nova_senha.

Request

{
  "token": "Zt3n0qkV2b8c...",
  "nova_senha": "uma-senha-nova-bem-longa"
}

Response 200 OK

{
  "status": "success",
  "message": "Senha redefinida. Todas as sessões anteriores foram encerradas — entre no Portal com a senha nova.",
  "data": {
    "redefinida": true
  }
}

Proteção: público (token do link) - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/empresa-ativa/escopo

Informa se a empresa ativa agrega filiais e quais empresas entram no escopo das telas por empresa (guias, alvarás, TFF, certidões, situações fiscais e notas fiscais). O front usa tem_filiais para decidir se mostra o seletor "Só esta empresa | Com filiais" (parâmetro incluir_filiais das listagens). Só a matriz agrega filiais, e só as filiais com vínculo ativo do acesso; filial e empresa sem filiais recebem tem_filiais: false e apenas a si mesmas. A empresa ativa vem sempre primeiro em empresas. Qualquer perfil do portal.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "tem_filiais": true,
    "empresas": [
      { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" },
      { "id": 13, "nome": "ACME SERVICOS LTDA FILIAL", "cnpj": "12345678000271" }
    ]
  }
}

cnpj traz só os dígitos; nome e cnpj podem ser null quando a empresa não tem cadastro completo.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Usuários e empresas

Gestão administrativa dos acessos ao portal e dos vínculos com empresas, operada pelo Hub interno. Todas exigem um usuário do escritório com permissão adicional - não um token do portal.

Uso interno do escritório (restrito)

As rotas do portal não usam escopos recurso:acao, então a permissão adicional exigida em cada rota de /portal/users é a autorização que elas têm. Sem ela, a resposta é 403.

POST /portal/users

Provisiona um novo acesso ao portal vinculado a um customer. O acesso nasce com senha provisória (senha_provisoria_em preenchido): a senha definida aqui não abre nenhuma rota de dados até o titular trocá-la. A senha é enviada ao e-mail do acesso; se o envio falhar, o acesso é criado mesmo assim e a resposta traz senha_provisoria para o operador repassar.

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo (PortalUserCreate): id_cliente, nome, login, email, password e, opcionalmente, perfil e ativo. Login/e-mail duplicado = 409; senha recusada pela política (mínimo real de 12 caracteres) = 422.

Request

{
  "id_cliente": 1,
  "nome": "Financeiro Acme",
  "login": "empresa.acme",
  "email": "financeiro@acme.com.br",
  "password": "senha-inicial-bem-forte",
  "perfil": "<perfil>",
  "ativo": true
}

Response 201 Created

Retorna PortalUserCreatedOut. Com email_enviado: false, a mensagem passa a ser "Acesso criado, mas o e-mail com a senha NÃO foi enviado - repasse a senha ao cliente por um canal seguro." e senha_provisoria vem preenchida.

{
  "status": "success",
  "message": "Acesso ao portal criado com sucesso",
  "data": {
    "portal_user": {
      "id": 3,
      "id_cliente": 1,
      "nome": "Financeiro Acme",
      "login": "empresa.acme",
      "email": "financeiro@acme.com.br",
      "perfil": "<perfil>",
      "ativo": true,
      "ultimo_login": null,
      "data_hora_criacao": "2026-07-03T09:15:00",
      "celular": null,
      "telefone": null,
      "email_novo_pendente": null,
      "senha_provisoria_em": "2026-07-03T09:15:00",
      "senha_provisoria": true,
      "senha_provisoria_expirada": false
    },
    "email_enviado": true,
    "email_erro": null,
    "senha_provisoria": null
  }
}

Proteção: uso interno do escritório (restrito).

GET /portal/users

Lista acessos do portal: de uma empresa (com id_cliente) ou de todas (sem filtro).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteint >= 1querynãoID do cliente cujos acessos serão listados. Omitido: todos os acessos, cada um com a lista empresas (vínculos ativos e revogados, no formato PortalVinculoOut).

Com id_cliente, o id_cliente de cada item é a empresa consultada. Sem filtro, é a empresa do acesso quando ele tem exatamente um vínculo ativo, senão null.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Acessos do portal recuperados",
  "data": [
    {
      "id": 3,
      "id_cliente": 1,
      "nome": "Financeiro Acme",
      "login": "empresa.acme",
      "email": "financeiro@acme.com.br",
      "perfil": "<perfil>",
      "ativo": true,
      "ultimo_login": "2026-07-03T09:12:00",
      "data_hora_criacao": "2026-01-10T14:00:00",
      "celular": null,
      "telefone": null,
      "email_novo_pendente": null,
      "senha_provisoria_em": null,
      "senha_provisoria": false,
      "senha_provisoria_expirada": false
    }
  ]
}

Proteção: uso interno do escritório (restrito).

GET /portal/users/{portal_user_id}

Retorna um acesso específico (para edição no Hub). id_cliente sai preenchido só quando o acesso tem exatamente um vínculo ativo; com dois ou mais (ou nenhum) sai null - a lista completa está em GET /portal/users/{portal_user_id}/empresas. Inexistente retorna 404.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
portal_user_idintpathsimID do acesso ao portal

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Acesso do portal recuperado" e data no formato PortalUserOut (mesmo objeto dos itens de GET /portal/users).

Proteção: uso interno do escritório (restrito).

PUT /portal/users/{portal_user_id}

Edita nome/e-mail/perfil, ativa-desativa ou reseta a senha de um acesso. id_cliente e login são imutáveis por aqui (os vínculos se editam pelas rotas /empresas). A senha passa pela mesma política da troca feita pelo titular (422 se recusada).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
portal_user_idintpathsimID do acesso ao portal

O corpo é um PortalUserUpdate com campos parciais: nome, email, perfil, ativo e password (reset).

Request (PortalUserUpdate - todos os campos opcionais)

{
  "nome": "Financeiro Acme Matriz",
  "email": "financeiro.matriz@acme.com.br",
  "ativo": false
}

Response 200 OK

Mensagem "Acesso ao portal atualizado com sucesso" e data no formato PortalUserOut, com id_cliente pela mesma regra de GET /portal/users/{portal_user_id}.

Proteção: uso interno do escritório (restrito).

DELETE /portal/users/{portal_user_id}

Remove um acesso ao portal.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
portal_user_idintpathsimID do acesso ao portal

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Acesso ao portal excluído com sucesso",
  "data": null
}

Proteção: uso interno do escritório (restrito).

GET /portal/users/{portal_user_id}/empresas

Lista os vínculos do acesso com empresas - ativos e revogados (é a tela de auditoria: quem concedeu, quem revogou e quando). Acesso inexistente retorna 404.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
portal_user_idintpathsimID do acesso ao portal

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Vínculos do acesso recuperados",
  "data": [
    {
      "id": 21,
      "portal_user_id": 3,
      "customer_id": 1,
      "ativo": true,
      "data_hora_criacao": "2026-01-10T14:00:00",
      "data_hora_revogacao": null,
      "ultimo_acesso_em": "2026-07-03T09:12:00",
      "id_usuario_created": 42,
      "id_usuario_revogacao": null,
      "razao_social": "ACME SERVICOS LTDA",
      "nome_fantasia": "ACME"
    }
  ]
}

Proteção: uso interno do escritório (restrito).

POST /portal/users/{portal_user_id}/empresas

Vincula mais uma empresa a um acesso existente. Idempotente: vincular o que já está vinculado devolve a linha como está, e revincular um vínculo revogado reativa a mesma linha. Responde 201 nos dois casos.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
portal_user_idintpathsimID do acesso ao portal

Corpo PortalVincularEmpresaRequest: customer_id (int >= 1).

Request

{
  "customer_id": 11
}

Response 201 Created

Mensagem "Empresa vinculada ao acesso" e data com um PortalVinculoOut (mesmo formato dos itens de GET /portal/users/{portal_user_id}/empresas).

Proteção: uso interno do escritório (restrito).

DELETE /portal/users/{portal_user_id}/empresas/{customer_id}

Revoga o acesso de um usuário do portal a uma empresa. Soft-delete: grava ativo=false, quem revogou e quando - a linha é a trilha de auditoria. O efeito é imediato: no próximo request, um token com essa empresa ativa recebe 401. Revogar o último vínculo é permitido (o acesso fica no estado "sem empresa vinculada").

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
portal_user_idintpathsimID do acesso ao portal
customer_idintpathsimID do cliente empresa a revogar

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Acesso à empresa revogado" e data com o PortalVinculoOut atualizado (ativo: false, data_hora_revogacao e id_usuario_revogacao preenchidos).

Proteção: uso interno do escritório (restrito).

Lançamentos

Lançamentos de lucro, sócios (QSA), resumo e simulação fiscal, competências sem movimento e resumo de ATA da empresa ativa. Toda rota filtra pelo id_cliente_ativo do token.

GET /portal/lancamentos-lucro

Lista os lançamentos de lucro apenas da empresa ativa, com a autoria resolvida (autor_nome, autor_realm). Sem registros, retorna error_response - { "status": "error", "message": "Nenhum lançamento de lucro encontrado.", "details": [] }.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
competenciastrquerynãoFiltro por competência MM/YYYY.
pageint >= 1querynãoPágina.
per_pageint 1..500querynãoItens por página.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos recuperados com sucesso!",
  "data": [
    {
      "id": 12,
      "id_cliente": 1,
      "id_qsa_cliente": 10,
      "competencia": "01/2026",
      "data_registro": "2026-01-15",
      "data_pagamento": "2026-01-20",
      "valor_liquido": "1234.56",
      "valor_bruto": null,
      "valor_ir_retido": "0",
      "id_ata": null,
      "valor_ata_utilizada": "0",
      "natureza_rendimento": "Lucros e dividendos",
      "status": "Em processamento",
      "observacao": "Distribuição referente ao 4º trimestre.",
      "tipo_evento_reinf": "R4010",
      "nome_socio": "João da Silva",
      "id_usuario_created": null,
      "id_portal_user_created": 7,
      "data_hora_criacao": "2026-07-03T09:15:00",
      "autor_nome": "Financeiro Acme",
      "autor_realm": "portal"
    }
  ]
}

Proteção: token com empresa ativa.

GET /portal/socios

Lista os sócios (quadro societário / QSA) apenas da empresa ativa. Usado, por exemplo, pelo dropdown de sócios do formulário de lançamento. Sem sócios, retorna error_response com details: [] e a mensagem "Nenhum sócio encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. Cada item da lista segue o schema PortalSocioOut.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Sócios recuperados com sucesso!",
  "data": [
    {
      "id": 10,
      "nome": "João da Silva",
      "cpfecnpj": "123.456.789-00",
      "qualificacao": "Sócio-Administrador"
    }
  ]
}

Proteção: token com empresa ativa.

GET /portal/lancamentos-lucro/resumo-fiscal

Resumo fiscal agregado por sócio x competência da empresa ativa. Usa a mesma regra de cálculo da rota interna (teto mensal de R$ 50.000, gross-up e isenção do sócio pessoa jurídica). Sem janela de data_registro (considera todo o histórico). Empresa sem lançamento devolve data: [] em success.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_qsa_clienteint > 0querynãoFiltro por sócio da própria empresa. Id alheio devolve agregação vazia.
competenciastrquerynãoFiltro por competência (MM/YYYY).
statusstrquerynãoFiltro por status do lançamento.
data_pagamento_iniciodatequerynãodata_pagamento >= (YYYY-MM-DD).
data_pagamento_fimdatequerynãodata_pagamento <= (YYYY-MM-DD).

Request

Sem corpo de requisição.

Response 200 OK

Lista de ResumoFiscalSocio.

{
  "status": "success",
  "message": "Resumo fiscal gerado com sucesso!",
  "data": [
    {
      "id_qsa_cliente": 10,
      "nome_socio": "João da Silva",
      "competencia": "01/2026",
      "total_liquido": "60000.00",
      "total_isencao_ata": "0.00",
      "base_tributavel": "60000.00",
      "incide_ir": true,
      "valor_bruto": "66666.67",
      "valor_ir": "6666.67",
      "motivo_isencao": null
    }
  ]
}

Proteção: token com empresa ativa.

GET /portal/lancamentos-lucro/sem-movimento

Lista todas as competências da empresa ativa marcadas como "sem movimento" (sem distribuição de lucros), sem paginação. origem diz quem marcou e pode_desfazer indica se a competência ainda está aberta na Receita. Empresa sem marcação devolve data: [] em success.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Competências sem movimento recuperadas!",
  "data": [
    {
      "competencia": "08/2026",
      "data_hora_criacao": "2026-08-31T10:15:00",
      "origem": "cliente",
      "pode_desfazer": true
    }
  ]
}

Proteção: token com empresa ativa.

POST /portal/lancamentos-lucro/sem-movimento

O cliente afirma que a competência não teve distribuição de lucros. É triagem, não ato fiscal (não gera R-4099). Idempotente: marcar de novo devolve 201 com a marcação existente. A autoria fica em id_portal_user_criacao.

Parâmetros

Sem parâmetros de rota ou query. Corpo SemMovimentoCompetencia: apenas competencia (MM/YYYY). Erros: 409 se já existe lançamento de lucro na competência; 409 se a competência não está aberta na Receita e ainda não há marcação; 422 se competencia não é MM/YYYY.

Request

{
  "competencia": "08/2026"
}

Response 201 Created

{
  "status": "success",
  "message": "Competência marcada como sem movimento.",
  "data": {
    "competencia": "08/2026",
    "data_hora_criacao": "2026-08-31T10:15:00",
    "origem": "cliente",
    "pode_desfazer": true
  }
}

Proteção: token com empresa ativa.

DELETE /portal/lancamentos-lucro/sem-movimento

Desfaz a marcação de "sem movimento" da empresa ativa numa competência. Quem marcou não restringe (o cliente desfaz inclusive marcações do escritório); o que restringe é o período estar aberto na Receita. Idempotente: competência sem marcação responde 204.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
competenciastrquerysimCompetência MM/YYYY.

Erros: 422 com message: "competencia deve estar no formato MM/YYYY."; 409 se existe marcação e a competência já foi encerrada na Receita (ou está indeterminada).

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo.

Proteção: token com empresa ativa.

GET /portal/ata/resumo

Agregado de ATA da empresa ativa: valor, utilizado e saldo (saldo = valor - utilizado, pode ser negativo). Os filtros de lançamento recortam só utilizado; id_qsa_cliente recorta as atas e afeta valor e utilizado. Empresa sem ata devolve zeros.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_qsa_clienteint > 0querynãoFiltro por sócio (customer_ata.id_customer_qsa).
competenciastrquerynãoCompetência (MM/YYYY) dos lançamentos.
statusstrquerynãoStatus do lançamento (não da ata).
data_pagamento_iniciodatequerynãolançamento.data_pagamento >=.
data_pagamento_fimdatequerynãolançamento.data_pagamento <=.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Resumo de ATA gerado com sucesso!",
  "data": {
    "valor": "100000.00",
    "utilizado": "40000.00",
    "saldo": "60000.00"
  }
}

Proteção: token com empresa ativa.

POST /portal/lancamentos-lucro

Cria um lançamento de lucro para a empresa ativa. O schema não aceita id_cliente (sempre o do token), status (fixado em "Em processamento") nem natureza_rendimento (fixada pelo backend no rótulo de lucros e dividendos - campo extra enviado é ignorado). A criação recalcula valor_bruto/valor_ir_retido dos lançamentos da mesma competência. A autoria fica em id_portal_user_created.

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo (PortalLancamentoLucroCreate). Se id_qsa_cliente não pertencer à empresa retorna 404; validação inválida retorna 422.

Request

{
  "competencia": "01/2026",
  "data_registro": "2026-01-15",
  "valor_liquido": "1234.56",
  "id_qsa_cliente": 10,
  "data_pagamento": "2026-01-20",
  "observacao": "Distribuição referente ao 4º trimestre."
}

Response 201 Created

Mensagem "Lançamento de lucro criado com sucesso!" e data com o lançamento gravado (LancamentoLucroRead: os mesmos campos do item de GET /portal/lancamentos-lucro, sem autor_nome/autor_realm).

Proteção: token com empresa ativa.

POST /portal/lancamentos-lucro/simular-fiscal

Prévia de valor_bruto/valor_ir_retido de um lançamento ainda não salvo. Não grava nada - é POST apenas para que valores não trafeguem na query string (e no access log). Usa a mesma regra de cálculo da rota interna, com valor_ata_utilizada fixo em 0 (o portal não escolhe ATA).

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalSimulacaoFiscalRequest: competencia (MM/YYYY ou YYYY-MM), valor_liquido (>= 0), id_qsa_cliente (opcional, posse validada) e excluir_id (opcional, id do lançamento em edição, posse validada). Erros: 404 sócio/lançamento inexistente ou de outra empresa; 422 competência malformada.

Request

{
  "competencia": "01/2026",
  "valor_liquido": "30000.00",
  "id_qsa_cliente": 10,
  "excluir_id": 7
}

Response 200 OK

data é um SimulacaoFiscalLucro: valor_bruto/valor_ir_retido do lançamento em edição e valor_bruto_mensal/valor_ir_mensal do mês inteiro do sócio, com valores monetários como string de 2 casas.

{
  "status": "success",
  "message": "Simulação fiscal gerada com sucesso!",
  "data": {
    "base_mensal_outros": "30000.00",
    "base_tributavel": "60000.00",
    "incide_ir": true,
    "motivo_isencao": null,
    "valor_bruto": "33333.33",
    "valor_ir_retido": "3333.33",
    "valor_bruto_mensal": "66666.67",
    "valor_ir_mensal": "6666.67"
  }
}

Proteção: token com empresa ativa.

PUT /portal/lancamentos-lucro/{lancamento_id}

Edita um lançamento de lucro da empresa ativa (campos parciais). status, id_cliente e natureza_rendimento nunca são aceitos; id_qsa_cliente pode ser reatribuído (validado contra a empresa). A edição segue as mesmas regras de negócio da rota interna.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID do lançamento

O corpo é um PortalLancamentoLucroUpdate (todos os campos opcionais). Regras: 404 se o lançamento não existe ou é de outra empresa (anti-IDOR); 409 Conflict se já saiu de "Em processamento"; 404 se o id_qsa_cliente informado não pertence à empresa.

Request (PortalLancamentoLucroUpdate - todos os campos opcionais)

{
  "valor_liquido": "1500.00",
  "observacao": "Valor ajustado após revisão."
}

Response 200 OK

Mensagem "Lançamento de lucro atualizado!" e data com o lançamento atualizado (LancamentoLucroRead).

Proteção: token com empresa ativa.

DELETE /portal/lancamentos-lucro/{lancamento_id}

Exclui (hard delete) um lançamento de lucro da empresa ativa, desde que ainda esteja "Em processamento". O servidor recalcula valor_bruto/valor_ir_retido dos lançamentos restantes da competência na mesma transação.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID do lançamento

Regras: 404 se o lançamento não existe ou é de outra empresa; 409 se já saiu de "Em processamento".

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamento de lucro removido!",
  "data": null
}

Proteção: token com empresa ativa.

Plano de Saúde

Operadoras vinculadas (read-only), dependentes e lançamentos de plano de saúde da empresa ativa.

GET /portal/operadoras-saude

Lista apenas as operadoras de saúde já vinculadas à empresa ativa (via customer_plano_saude). Sem operadoras vinculadas, retorna error_response com details: [] e a mensagem "Nenhuma operadora vinculada a esta empresa.".

Operadoras são READ-ONLY no portal

O portal não cria nem vincula operadoras; apenas lista as que já foram vinculadas no sistema interno. A base global de operadoras nunca é exposta (evita vazamento cross-tenant).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. Cada item da lista segue o schema PortalOperadoraOut.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operadoras recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "razao_social": "Operadora Exemplo",
      "registro_ans": "123456",
      "tipo_contratacao": "Coletivo empresarial",
      "tipo_cobertura": "Ambulatorial + Hospitalar",
      "abrangencia": "Nacional",
      "status": "ativo"
    }
  ]
}

Proteção: token com empresa ativa.

GET /portal/dependentes

Lista os dependentes apenas da empresa ativa. Sem registros, retorna error_response com details: [] e a mensagem "Nenhum dependente encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. Cada item da lista segue o schema PortalDependenteOut.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Dependentes recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "nome_completo": "Maria da Silva",
      "cpf": "123.456.789-00",
      "data_nascimento": "1990-05-20",
      "grau_parentesco": "Filho(a)",
      "id_customer_qsa": 10,
      "status": "ativo"
    }
  ]
}

Proteção: token com empresa ativa.

POST /portal/dependentes

Cria um dependente para a empresa ativa. id_cliente não aparece no body (fixado pelo token).

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo (PortalDependenteCreate). Se id_customer_qsa for informado, a rota valida que o sócio pertence à empresa (404 caso contrário).

Request

{
  "nome_completo": "Maria da Silva",
  "cpf": "123.456.789-00",
  "data_nascimento": "1990-05-20",
  "grau_parentesco": "Filho(a)",
  "id_customer_qsa": 10
}

Response 201 Created

{
  "status": "success",
  "message": "Dependente criado com sucesso!",
  "data": {
    "id": 1,
    "nome_completo": "Maria da Silva",
    "cpf": "123.456.789-00",
    "data_nascimento": "1990-05-20",
    "grau_parentesco": "Filho(a)",
    "id_customer_qsa": 10,
    "status": "ativo"
  }
}

Proteção: token com empresa ativa.

PUT /portal/dependentes/{dependente_id}

Edita um dependente da empresa ativa (campos parciais). id_cliente nunca é aceito.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
dependente_idintpathsimID do dependente

O corpo é um PortalDependenteUpdate (todos os campos opcionais). Regras: 404 se o dependente não existe ou é de outra empresa; 404 se id_customer_qsa informado não pertence à empresa.

Request (PortalDependenteUpdate - todos os campos opcionais)

{
  "grau_parentesco": "Cônjuge",
  "id_customer_qsa": 10
}

Response 200 OK

Mensagem "Dependente atualizado!" e data no formato PortalDependenteOut.

Proteção: token com empresa ativa.

GET /portal/lancamentos-plano-saude

Lista os lançamentos de plano de saúde apenas da empresa ativa. Sem registros, retorna error_response com details: [] e a mensagem "Nenhum lançamento de plano de saúde encontrado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
competenciastrquerynãoFiltro por competência MM/YYYY.
pageint >= 1querynãoPágina.
per_pageint 1..500querynãoItens por página.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos recuperados com sucesso!",
  "data": [
    {
      "id": 5,
      "id_cliente": 1,
      "competencia": "01/2026",
      "data_registro": "2026-01-15",
      "data_pagamento": "2026-01-20",
      "valor": "1234.56",
      "id_operadora_saude": 1,
      "id_qsa_cliente": 10,
      "id_dependente": 5,
      "natureza_rendimento": "Reembolso plano de saúde",
      "status": "pendente",
      "observacao": "Mensalidade titular + 1 dependente."
    }
  ]
}

Proteção: token com empresa ativa.

POST /portal/lancamentos-plano-saude

Cria um lançamento de plano de saúde para a empresa ativa. O schema não aceita id_cliente (sempre o do token) nem status (fixado em "pendente").

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo (PortalLancamentoPlanoSaudeCreate). Anti-IDOR: id_qsa_cliente, id_dependente (se houver) e id_operadora_saude são validados contra a empresa (404 se não pertencerem/estiverem vinculados); dependente que não pertence ao sócio titular informado retorna 422.

Request

{
  "competencia": "01/2026",
  "data_registro": "2026-01-15",
  "valor": "1234.56",
  "id_operadora_saude": 1,
  "id_qsa_cliente": 10,
  "id_dependente": 5,
  "data_pagamento": "2026-01-20",
  "natureza_rendimento": "Reembolso plano de saúde",
  "observacao": "Mensalidade titular + 1 dependente."
}

Response 201 Created

Mensagem "Lançamento de plano de saúde criado com sucesso!" e data no formato PortalLancamentoPlanoSaudeOut (mesmo objeto dos itens da listagem).

Proteção: token com empresa ativa.

PUT /portal/lancamentos-plano-saude/{lancamento_id}

Edita um lançamento de plano de saúde da empresa ativa (campos parciais). status e id_cliente nunca são aceitos; revalida id_qsa_cliente, id_dependente e id_operadora_saude informados contra a empresa.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID do lançamento

O corpo é um PortalLancamentoPlanoSaudeUpdate (todos os campos opcionais). Regras: 404 se o lançamento não existe ou é de outra empresa (anti-IDOR); 409 Conflict se já saiu de "pendente" ou se está vinculado a um evento EFD-Reinf ativo.

Request (PortalLancamentoPlanoSaudeUpdate - todos os campos opcionais)

{
  "valor": "1350.00",
  "observacao": "Reajuste da mensalidade."
}

Response 200 OK

Mensagem "Lançamento de plano de saúde atualizado!" e data no formato PortalLancamentoPlanoSaudeOut.

Proteção: token com empresa ativa.

Certidões

Certidões negativas da empresa ativa, somente leitura (quem emite é a automação). Só aparecem certidões com status Concluído ou Pendência Fiscal; não existe filtro de status nem de cliente.

GET /portal/certidoes-negativas

Lista as certidões negativas da empresa ativa (e das filiais, com incluir_filiais), sem o PDF. Cada item traz empresa (a dona da certidão). Lista vazia é estado válido (data: []).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
tipostrquerynãoFiltro por tipo de certidão.
limitint 1..500querynãoMáximo de itens. Default 100.
offsetint >= 0querynãoDeslocamento. Default 0.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Certidões recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 10,
      "tipo": "Receita Federal",
      "status": "Concluído",
      "observacao": null,
      "data_hora_emissao": "2026-01-15T10:30:00",
      "data_validade": "2026-04-15T00:00:00",
      "negativa": true,
      "motivo": null,
      "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/certidoes-negativas/{certidao_id}

Detalha uma certidão negativa da empresa ativa, com o PDF em pdf_base64. 404 se a certidão não existe, é de outra empresa ou tem status não visível no portal.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
certidao_idintpathsimID da certidão.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Certidão recuperada com sucesso!" e data no formato PortalCertidaoNegativaDetalheOut (os campos da listagem + pdf_base64).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Guias e pagamento

Guias de ISS e de DCTFWeb/PGDAS da empresa ativa. O portal não emite nem altera a guia; a única escrita é o pagamento informado pelo cliente, uma declaração sem conferência que não muda o status da guia. Só aparecem guias com status Concluído ou Paga. As duas origens têm rotas separadas (não há UNION): o front carrega cada recorte e ordena localmente.

GET /portal/guias/iss

Lista as guias de ISS da empresa ativa (e das filiais, com incluir_filiais), ordenadas por competência decrescente, sem o PDF (use tem_arquivo para habilitar o download). Lista vazia é estado válido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
competenciastrquerynãoCompetência (YYYY-MM).
start_datedatetimequerynãoEmissão >= start_date.
end_datedatetimequerynãoEmissão <= end_date.
limitint 1..500querynãoMáximo de guias. Default 500.
offsetint >= 0querynãoDeslocamento. Default 0.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Guias recuperadas com sucesso!",
  "data": [
    {
      "id": 9821,
      "tipo": "sem_aliquota",
      "competencia": "2026-07",
      "status": "Concluído",
      "data_hora_emissao": "2026-08-11T09:58:51",
      "arquivo_nome": "guia_iss_2026-07.pdf",
      "tem_arquivo": true,
      "pagamento_informado_em": null,
      "pagamento_origem": null,
      "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/guias/iss/{guia_id}/pdf

Baixa o PDF de uma guia de ISS da empresa ativa. 404 se a guia não existe, é de outra empresa, tem status não visível, não possui arquivo ou o arquivo não pôde ser lido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Request

Sem corpo de requisição.

Response 200 OK

Corpo binário com Content-Type: application/pdf e Content-Disposition: attachment (com filename ASCII e filename* UTF-8). Não usa envelope.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/guias/iss/{guia_id}/pagamento

Informa que o cliente pagou a guia de ISS. Sem corpo: a data é "agora" (horário de São Paulo) e o autor vem do token. Idempotente - guia já marcada devolve 200 com a mensagem "O pagamento desta guia já estava informado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Erros: 404 se a guia não existe, é de outra empresa ou não é visível; 409 com message: "Esta guia já consta como quitada pelo escritório." se o status já é Paga pela automação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Pagamento informado com sucesso!",
  "data": {
    "id": 9821,
    "tipo": "sem_aliquota",
    "competencia": "2026-07",
    "status": "Concluído",
    "data_hora_emissao": "2026-08-11T09:58:51",
    "arquivo_nome": "guia_iss_2026-07.pdf",
    "tem_arquivo": true,
    "pagamento_informado_em": "2026-10-06T14:32:10",
    "pagamento_origem": "cliente"
  }
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

DELETE /portal/guias/iss/{guia_id}/pagamento

Desfaz o pagamento informado de uma guia de ISS. Qualquer acesso da empresa pode desfazer. Idempotente - guia não marcada devolve 200 com a mensagem "O pagamento desta guia não estava informado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Erros 404/409 como no POST.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Pagamento informado desfeito com sucesso!" e data com a guia (PortalGuiaOut) já com pagamento_informado_em e pagamento_origem nulos.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/guias/dctfweb

Lista as guias de DCTFWeb/PGDAS da empresa ativa (e das filiais, com incluir_filiais), opcionalmente restritas a um setor. Mesmo formato de saída de GET /portal/guias/iss; aqui tipo traz DCTFWeb ou PGDAS.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
competenciastrquerynãoCompetência (YYYY-MM).
start_datedatetimequerynãoEmissão >= start_date.
end_datedatetimequerynãoEmissão <= end_date.
limitint 1..500querynãoMáximo de guias. Default 500.
offsetint >= 0querynãoDeslocamento. Default 0.
setorstrquerynãofiscal ou pessoal. Omitido = todos.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Guias recuperadas com sucesso!" e data como lista de PortalGuiaOut.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/guias/dctfweb/{guia_id}/pdf

Baixa o PDF de uma guia de DCTFWeb/PGDAS da empresa ativa. Mesmas regras de 404 de GET /portal/guias/iss/{guia_id}/pdf.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Request

Sem corpo de requisição.

Response 200 OK

Corpo binário com Content-Type: application/pdf e Content-Disposition: attachment. Não usa envelope.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/guias/dctfweb/{guia_id}/pagamento

Informa que o cliente pagou a guia de DCTFWeb/PGDAS. Sem corpo; mesmas regras de POST /portal/guias/iss/{guia_id}/pagamento (404, 409 se Paga pela automação, 200 idempotente).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Pagamento informado com sucesso!" e data com a guia (PortalGuiaOut) com pagamento_informado_em preenchido e pagamento_origem: "cliente".

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

DELETE /portal/guias/dctfweb/{guia_id}/pagamento

Desfaz o pagamento informado de uma guia de DCTFWeb/PGDAS. Mesmas regras de DELETE /portal/guias/iss/{guia_id}/pagamento.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Pagamento informado desfeito com sucesso!" (ou "O pagamento desta guia não estava informado.") e data com a guia (PortalGuiaOut).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/guias/guia-fiscal

Lista as guias fiscais da empresa ativa de tipos como FGTS, DAE, INSS, ICMS, PIS, COFINS, IRPJ e CSLL, ordenadas por competência decrescente. DAS, DARF e ISS não entram aqui: saem das outras duas origens. Estas guias não têm PDF nem status. Cada item traz empresa (a dona da guia). Lista vazia é estado válido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
competenciastrquerynãoCompetência (YYYY-MM). Formato inválido retorna 422.
start_datedatetimequerynãoRegistro >= start_date.
end_datedatetimequerynãoRegistro <= end_date.
limitint 1..500querynãoMáximo de guias. Default 500.
offsetint >= 0querynãoDeslocamento. Default 0.
setorstrquerynãofiscal (ICMS, PIS, COFINS, IRPJ, CSLL) ou pessoal (FGTS, DAE, INSS). Omitido = todos.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Guias recuperadas com sucesso!",
  "data": [
    {
      "id": 512,
      "tipo": "FGTS",
      "competencia": "2026-07",
      "vencimento": "2026-08-07",
      "valor_total": "1234.56",
      "data_hora_registro": "2026-08-01T09:30:00",
      "pagamento_informado_em": null,
      "pagamento_origem": null,
      "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
    }
  ]
}

pagamento_informado_em e pagamento_origem indicam o pagamento informado pelo cliente (pagamento_origem é cliente).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/guias/guia-fiscal/{guia_id}/pagamento

Informa que o cliente pagou a guia fiscal. Sem corpo: a data é "agora" (horário de São Paulo) e o autor vem do token. Idempotente - guia já marcada devolve 200 com a mensagem "O pagamento desta guia já estava informado.". Como estas guias não têm status, não existe o 409 de "quitada pelo escritório" das guias de ISS e DCTFWeb.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Erro: 404 ("Guia não encontrada.") se a guia não existe, é de empresa fora do escopo ou tem tipo não visível ao portal.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Pagamento informado com sucesso!",
  "data": {
    "id": 512,
    "tipo": "FGTS",
    "competencia": "2026-07",
    "vencimento": "2026-08-07",
    "valor_total": "1234.56",
    "data_hora_registro": "2026-08-01T09:30:00",
    "pagamento_informado_em": "2026-10-06T14:32:10",
    "pagamento_origem": "cliente",
    "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
  }
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

DELETE /portal/guias/guia-fiscal/{guia_id}/pagamento

Desfaz o pagamento informado de uma guia fiscal. Idempotente - guia não marcada devolve 200 com a mensagem "O pagamento desta guia não estava informado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
guia_idintpathsimID da guia.

Erro 404 como no POST.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Pagamento informado desfeito com sucesso!" e data com a guia já com pagamento_informado_em e pagamento_origem nulos.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Situações fiscais

Situações fiscais (SITFIS) da empresa ativa, somente leitura. Só aparecem emissões com status de processamento Concluido.

GET /portal/situacoes-fiscais

Lista as SITFIS da empresa ativa (e das filiais, com incluir_filiais), sem o PDF (use tem_pdf), com o detalhamento (diagnósticos) quando já extraído. Lista vazia é estado válido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
limitint 1..500querynãoMáximo de itens. Default 100.
offsetint >= 0querynãoDeslocamento. Default 0.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Situações fiscais recuperadas com sucesso!",
  "data": [
    {
      "id": 321,
      "id_cliente": 10,
      "protocolo": "PROT-2026-000321",
      "status": "Concluido",
      "data_hora_emissao": "2026-08-11T09:58:51",
      "observacao": null,
      "tem_pdf": true,
      "detalhamento": {
        "diagnostico_receita_federal": "Regular",
        "diagnostico_procuradoria_geral": "Regular",
        "status": "Regular",
        "observacao": null
      },
      "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/situacoes-fiscais/{situacao_id}

Detalha uma SITFIS da empresa ativa, com o PDF em pdf_base64 e o detalhamento. 404 se não existe, é de outra empresa ou não está Concluido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
situacao_idintpathsimID da situação fiscal.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Situação fiscal recuperada com sucesso!" e data no formato PortalSituacaoFiscalDetalheOut (os campos da listagem + pdf_base64).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Alvarás

Alvarás de funcionamento da empresa ativa. Só aparecem alvarás com status Concluído.

Recurso municipal - quem barra é o front

O Alvará de Funcionamento só existe em Salvador, mas as rotas não checam município: quem esconde o recurso é o front, pela cidade da empresa em GET /portal/auth/me. As rotas continuam recortadas pela empresa ativa, então quem furar a interface recebe apenas a própria lista (vazia). O mesmo vale para a TFF.

GET /portal/alvaras-funcionamento

Lista os alvarás da empresa ativa (e das filiais, com incluir_filiais), ordenados por ano_competencia decrescente, sem o PDF (use tem_arquivo). Lista vazia é estado válido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
ano_competenciaint 1900..2999querynãoExercício do alvará.
start_datedatetimequerynãoEmissão >= start_date.
end_datedatetimequerynãoEmissão <= end_date.
limitint 1..500querynãoMáximo de alvarás. Default 500.
offsetint >= 0querynãoDeslocamento. Default 0.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Alvarás recuperados com sucesso!",
  "data": [
    {
      "id": 318,
      "ano_competencia": 2026,
      "status": "Concluído",
      "data_hora_emissao": "2026-02-03T11:22:07",
      "arquivo_nome": "alvara_funcionamento_2026.pdf",
      "tem_arquivo": true,
      "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/alvaras-funcionamento/{alvara_id}/pdf

Baixa o PDF de um alvará da empresa ativa. 404 se não existe, é de outra empresa, tem status não visível, não possui arquivo ou o arquivo não pôde ser lido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
alvara_idintpathsimID do alvará.

Request

Sem corpo de requisição.

Response 200 OK

Corpo binário com Content-Type: application/pdf e Content-Disposition: attachment (com filename ASCII e filename* UTF-8). Não usa envelope.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

TFF

Guias de TFF (Taxa de Fiscalização de Funcionamento) de Salvador da empresa ativa. Só aparecem guias com status Concluído. Como no alvará, a restrição de município é do front.

GET /portal/tff-salvador

Lista as guias de TFF da empresa ativa (e das filiais, com incluir_filiais), ordenadas por ano_competencia decrescente e cota crescente, sem o PDF (use tem_arquivo). Lista vazia é estado válido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
ano_competenciaint 1900..2999querynãoExercício da guia.
cotastr (máx. 10)querynãoCota, valor cru (ex.: 1 ou 01).
start_datedatetimequerynãoEmissão >= start_date.
end_datedatetimequerynãoEmissão <= end_date.
limitint 1..500querynãoMáximo de guias. Default 500.
offsetint >= 0querynãoDeslocamento. Default 0.
incluir_filiaisboolquerynãoMatriz: inclui as filiais com vínculo ativo (veja GET /portal/empresa-ativa/escopo). Default false.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Guias de TFF recuperadas com sucesso!",
  "data": [
    {
      "id": 742,
      "ano_competencia": 2026,
      "cota": "1",
      "status": "Concluído",
      "data_hora_emissao": "2026-02-03T11:22:07",
      "arquivo_nome": "tff_salvador_2026_cota1.pdf",
      "tem_arquivo": true,
      "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" }
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/tff-salvador/{tff_id}/pdf

Baixa o PDF de uma guia de TFF da empresa ativa. 404 se não existe, é de outra empresa, tem status não visível, não possui arquivo ou o arquivo não pôde ser lido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
tff_idintpathsimID da guia de TFF.

Request

Sem corpo de requisição.

Response 200 OK

Corpo binário com Content-Type: application/pdf e Content-Disposition: attachment. Não usa envelope.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Chamados

Chamados de suporte da empresa ativa. Escopo é a empresa, não o acesso: todos os logins da empresa veem e respondem os mesmos chamados. A thread exposta contém só mensagens públicas, e a mensagem do cliente é sempre gravada como pública. Chamado de outra empresa responde 404.

O lado interno (atendimento pela contabilidade, notas internas, mudança de status) está documentado em Chamados.

POST /portal/chamados

Abre um chamado para a empresa ativa. id_cliente, status (nasce aberto) e autoria são definidos pela rota. Há um teto de 30 chamados não concluídos por empresa: acima dele, 429.

Parâmetros

Sem parâmetros de rota ou query. Corpo PortalChamadoCreate: titulo (1-200), detalhamento (1-20000) e tipo (opcional, default problema; problema, solicitacao, duvida ou sugestao).

Request

{
  "titulo": "Erro ao baixar guia",
  "detalhamento": "Ao clicar em baixar a guia de fevereiro, a tela fica carregando e nada baixa.",
  "tipo": "problema"
}

Response 201 Created

{
  "status": "success",
  "message": "Chamado aberto com sucesso!",
  "data": {
    "id": 128,
    "id_portal_user": 42,
    "titulo": "Erro ao baixar guia",
    "detalhamento": "Ao clicar em baixar a guia de fevereiro, a tela fica carregando e nada baixa.",
    "tipo": "problema",
    "status": "aberto",
    "data_hora_criacao": "2026-09-08T09:14:22",
    "data_hora_edicao": null,
    "data_hora_fechamento": null,
    "motivo_fechamento": null,
    "nao_lidas": 0,
    "ultima_mensagem_em": null
  }
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados

Lista os chamados da empresa ativa, com nao_lidas calculado para o acesso logado. Lista vazia é estado válido.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
statusstrquerynãoaberto, em_andamento ou concluido.
limitint 1..500querynãoMáximo de itens. Default 100.
offsetint >= 0querynãoDeslocamento. Default 0.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Chamados recuperados com sucesso!" e data como lista de PortalChamadoOut (mesmo formato do POST /portal/chamados).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados/resumo

Números do badge de Suporte e dos cards da tela de chamados. abertos conta os chamados não concluídos; por_status conta todos, com zero explícito para cada status (a soma é igual a total).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Resumo recuperado com sucesso!",
  "data": {
    "nao_lidas": 3,
    "chamados_com_novidade": 2,
    "abertos": 8,
    "total": 135,
    "por_status": {
      "aberto": 3,
      "em_andamento": 5,
      "concluido": 127
    }
  }
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados/{chamado_id}

Detalha um chamado da empresa ativa. 404 se não existe ou é de outra empresa.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Chamado recuperado com sucesso!" e data no formato PortalChamadoOut.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/chamados/{chamado_id}/leitura

Marca a thread como lida, para este acesso, até a última mensagem pública existente no momento (data definida pelo servidor). Sem corpo. Idempotente e monotônica.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Leitura registrada com sucesso!",
  "data": {
    "ultima_mensagem_lida_em": "2026-09-09T10:31:44"
  }
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados/{chamado_id}/mensagens

Lista a thread do chamado - só as mensagens públicas (filtro no SQL). Mensagens da contabilidade vêm com autor_nome (primeiro nome) e autor_foto_url quando disponíveis.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.
limitint 1..500querynãoMáximo de itens. Default 100.
offsetint >= 0querynãoDeslocamento. Default 0.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Mensagens recuperadas com sucesso!",
  "data": [
    {
      "id": 311,
      "id_chamado": 128,
      "autor_realm": "interno",
      "id_portal_user": null,
      "texto": "Identificamos o problema, já foi corrigido.",
      "data_hora_criacao": "2026-09-08T10:31:44",
      "autor_nome": "Marina",
      "autor_foto_url": "/api/v1/portal/atendentes/5c489b66504bd22cabc5e58697652de0/foto"
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/chamados/{chamado_id}/mensagens

Posta uma resposta do cliente na thread (sempre pública). Chamado concluído retorna 409 com message: "Este chamado já foi concluído e não aceita novas mensagens.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.

Corpo PortalChamadoMensagemCreate: apenas texto (1-20000).

Request

{
  "texto": "Continua acontecendo hoje de manhã."
}

Response 201 Created

Mensagem "Mensagem registrada com sucesso!" e data no formato PortalChamadoMensagemOut (com autor_realm: "portal").

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados/{chamado_id}/anexos

Lista os metadados dos anexos visíveis ao cliente (nunca os de mensagem interna), sem o conteúdo.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.
id_mensagemintquerynãoRestringe aos anexos de uma mensagem.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Anexos recuperados com sucesso!",
  "data": [
    {
      "id": 91,
      "id_chamado": 128,
      "id_mensagem": null,
      "nome_arquivo": "print-erro.png",
      "mime_type": "image/png",
      "tamanho_bytes": 184320,
      "data_hora_criacao": "2026-09-09T09:14:22"
    }
  ]
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/chamados/{chamado_id}/anexos

Anexa um arquivo (em base64) ao chamado - à abertura ou a uma mensagem pública dele. MIME aceitos: application/pdf, image/png e image/jpeg, até 5 MB, com conferência de magic bytes; recusa de validação retorna 400. Chamado/mensagem inexistente, de outra empresa, interna ou chamado concluído retornam 404.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.
id_mensagemintquerynãoPrende o anexo a uma mensagem; omitido = anexo da abertura.

Corpo PortalChamadoAnexoCreate: nome_arquivo, mime_type e conteudo_base64.

Request

{
  "nome_arquivo": "print-erro.png",
  "mime_type": "image/png",
  "conteudo_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Response 201 Created

Mensagem "Anexo enviado com sucesso!" e data com os metadados do anexo (PortalChamadoAnexoOut, sem o conteúdo).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados/anexos/{anexo_id}

Baixa um anexo com o conteúdo em base64, dentro do envelope JSON. A rota confere que o chamado pai é da empresa ativa e que o anexo não pertence a mensagem interna; as duas falhas respondem 404 com message: "Anexo não encontrado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
anexo_idintpathsimID do anexo.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Anexo recuperado com sucesso!" e data no formato PortalChamadoAnexoDownloadOut (os metadados de PortalChamadoAnexoOut + conteudo_base64). O Content-Type da resposta é application/json; o tipo do arquivo está em data.mime_type.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/chamados/{chamado_id}/encerrar

Encerra o chamado a pedido do cliente (status concluido). Definitivo - não existe reabertura pelo portal. Sem corpo. Chamado já concluído retorna 409.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.

Request

Sem corpo de requisição.

Response 200 OK

Mensagem "Chamado encerrado com sucesso!" e data com o chamado atualizado (PortalChamadoOut).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/chamados/{chamado_id}/avaliacao

Retorna a avaliação do atendimento do chamado. Ainda não avaliado é 200 com data: null, nunca 404 (o 404 fica para chamado inexistente ou de outra empresa).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Avaliacao recuperada com sucesso!",
  "data": {
    "nota": 4,
    "comentario": "Resolveram rápido, mas demorou a primeira resposta.",
    "data_hora_criacao": "2026-09-10T09:00:00",
    "data_hora_edicao": null
  }
}

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/chamados/{chamado_id}/avaliacao

Cria ou substitui (UPSERT) a avaliação do atendimento de um chamado concluído. O reenvio preenche data_hora_edicao. A avaliação é da empresa (qualquer acesso dela ajusta a mesma nota). Chamado não concluído retorna 409.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
chamado_idintpathsimID do chamado.

Corpo PortalChamadoAvaliacaoCreate: nota (inteiro de 1 a 5) e comentario (opcional, até 2000 caracteres; vazio vira null).

Request

{
  "nota": 4,
  "comentario": "Resolveram rápido, mas demorou a primeira resposta."
}

Response 200 OK

Mensagem "Avaliacao registrada com sucesso!" e data no formato PortalChamadoAvaliacaoOut (mesmo objeto do GET).

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/atendentes/{token}/foto

Miniatura da foto de perfil de um atendente interno, consumida diretamente por um img (que não envia Authorization). Pública: o token do path (HMAC opaco de 32 caracteres hexadecimais, não enumerável) faz o papel da credencial. É a URL que aparece em autor_foto_url nas mensagens.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
tokenstrpathsimToken opaco da foto (32 caracteres hex minúsculos).

Token fora do formato, pessoa sem foto e foto corrompida respondem o mesmo 404 (message: "Foto nao encontrada.").

Request

Sem corpo de requisição.

Response 200 OK

Corpo binário com Content-Type: image/jpeg (miniatura JPEG). Não usa envelope.

Proteção: público (token opaco no path) - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Notas fiscais

Notas fiscais de serviço (NFS-e) emitidas e recebidas pela empresa ativa, somente leitura, consolidadas a partir de mais de uma origem sem duplicar a mesma nota. Qualquer usuário do portal acessa. A empresa é sempre a ativa do token; incluir_filiais=true agrega as filiais com vínculo ativo do acesso quando a empresa ativa é a matriz (veja GET /portal/empresa-ativa/escopo). O período é de no máximo 366 dias e, sem inicio/fim, cobre os últimos 12 meses até hoje. Valores monetários saem como string decimal com 2 casas.

GET /portal/notas-fiscais

Lista paginada das notas do período. papel indica o lado da empresa na nota: prestador (emitida) ou tomador (recebida).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
iniciodatequerynãoEmissão a partir de (inclusivo). Padrão: 1º dia do mês de 11 meses atrás.
fimdatequerynãoEmissão até (inclusivo). Padrão: hoje (São Paulo).
situacaostrquerynãotodas (padrão), normal ou cancelada.
papelstrquerynãotodas (padrão), prestador ou tomador.
buscastrquerynãoTexto de busca, até 100 caracteres.
incluir_filiaisboolquerynãoInclui as filiais do escopo. Default false.
ordenarstrquerynãodata_emissao (padrão), numero ou valor_servico.
direcaostrquerynãodesc (padrão) ou asc.
paginaint >= 1querynãoPágina. Default 1.
por_paginaint 1..100querynãoItens por página. Default 20.

fim anterior a inicio ou período acima de 366 dias retorna 422.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "itens": [
      {
        "id": "repasse-1234",
        "papel": "prestador",
        "numero": "2026000123",
        "codigo_verificacao": "A1B2C3D4",
        "data_emissao": "2026-10-05T10:20:00",
        "competencia": "2026-10",
        "situacao": "normal",
        "empresa": { "id": 12, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000190" },
        "prestador": { "nome": "ACME SERVICOS LTDA", "documento": "12345678000190", "municipio": "Salvador" },
        "tomador": { "nome": "Cliente Exemplo LTDA", "documento": "98765432000110", "municipio": "Salvador" },
        "discriminacao": "Serviços prestados em outubro",
        "codigo_servico": "4.01",
        "valores": {
          "valor_servico": "1500.00",
          "aliquota": "5.00",
          "iss": "75.00",
          "iss_retido": false,
          "pis": null,
          "cofins": null,
          "csll": null,
          "irrf": null,
          "inss": null,
          "valor_liquido": "1500.00"
        },
        "tem_arquivo": true
      }
    ],
    "total": 1,
    "pagina": 1,
    "por_pagina": 20
  }
}

id é opaco para o front (<origem>-<número>) e é o que GET /portal/notas-fiscais/{nota_id}/arquivo recebe. tem_arquivo indica se o arquivo da nota pode ser baixado. empresa é a empresa do escopo dona da nota.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/notas-fiscais/resumo

Contagem e totais das notas do período, separados entre emitidas e recebidas. Usa o mesmo conjunto de notas da listagem, sem os filtros de papel e situacao e sem paginação.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
iniciodatequerynãoMesmo padrão da listagem.
fimdatequerynãoMesmo padrão da listagem.
buscastrquerynãoTexto de busca, até 100 caracteres.
incluir_filiaisboolquerynãoInclui as filiais do escopo. Default false.

Período inválido retorna 422, como na listagem.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "contagem": { "todas": 18, "prestador": 12, "tomador": 6 },
    "emitidas": { "valor_servico": "48200.00", "iss": "2410.00", "iss_retido": "0.00", "canceladas": 1 },
    "recebidas": { "valor_servico": "9300.00", "iss": "465.00", "iss_retido": "465.00", "canceladas": 0 },
    "tem_filiais": false,
    "atualizado_em": "2026-10-20T06:00:00"
  }
}

tem_filiais diz se a empresa ativa agrega filiais. atualizado_em é a data da atualização mais recente das notas, ou null se não há notas.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/notas-fiscais/{nota_id}/arquivo

Baixa o arquivo da nota. O mesmo 404 ("Arquivo da nota não encontrado.") cobre nota inexistente, de outra empresa, sem arquivo ou com nota_id fora do formato; a resposta não revela se a nota existe.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
nota_idstrpathsimid devolvido pela listagem. Só notas com tem_arquivo: true têm arquivo.

Request

Sem corpo de requisição.

Response 200 OK

Corpo binário com Content-Disposition: attachment e X-Content-Type-Options: nosniff. O Content-Type é o tipo do arquivo quando for PDF, XML, PNG ou JPEG; qualquer outro tipo sai como application/octet-stream. Não usa envelope.

Proteção: token com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Financeiro (Open Finance)

Dados bancários Open Finance (TecnoSpeed) da empresa ativa: consultas, cadastro de conta e geração de consentimento. Nenhuma rota aceita cliente_id: a empresa é sempre a ativa (a matriz agrega as filiais da mesma raiz; a filial vê só a si). Contas arquivadas nunca aparecem e conta_id fora do escopo responde 404 ("Conta não encontrada."). As respostas usam a mensagem padrão "Operação realizada com sucesso".

Exige permissão de gestão

Todas as rotas de /portal/financeiro (as seis de consulta e as duas de cadastro de conta e consentimento) exigem permissão de gestão no portal com empresa ativa. Sem ela, a resposta é 403. A permissão é do acesso, não do vínculo: quem a tem vê o financeiro de todas as empresas vinculadas a ele.

GET /portal/financeiro/resumo

Resumo financeiro do período: contas, saldos, entradas, saídas e resultado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
iniciodatequerynãoInício. Padrão: 1º dia do mês corrente (São Paulo).
fimdatequerynãoFim. Padrão: último dia do mês de inicio.

Período inválido retorna 422.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "contas": [
      {
        "id": 4,
        "cliente_id": 1,
        "empresa": "ACME SERVICOS LTDA",
        "bank_code": "341",
        "banco_nome": "Itaú",
        "agencia": "0001",
        "conta_mascarada": "****1234",
        "consentimento_status": "ativo",
        "ativo": true,
        "inativada_por": null,
        "removida_em": null,
        "saldo": "15230.45",
        "saldo_em": "2026-10-14T08:00:00"
      }
    ],
    "saldo_total": "15230.45",
    "saldo_total_em": "2026-10-14T08:00:00",
    "entradas": "48200.00",
    "saidas": "39110.20",
    "resultado": "9089.80",
    "ultima_captura": "2026-10-14T08:00:00",
    "inicio": "2026-10-01",
    "fim": "2026-10-31"
  }
}

Proteção: permissão de gestão no portal, com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/financeiro/transacoes

Transações paginadas do período. O documento da contraparte sai completo no portal (o titular é o dono do dado), no campo contraparte_documento_mascarado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
iniciodatequerynãoInício (mesmo padrão do resumo).
fimdatequerynãoFim (mesmo padrão do resumo).
conta_idintquerynãoRestringe a uma conta do escopo.
naturezastrquerynãoC (crédito) ou D (débito).
buscastrquerynãoTexto de busca, até 100 caracteres.
paginaint >= 1querynãoPágina. Default 1.
por_paginaint >= 1querynãoItens por página. Default 50.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "itens": [
      {
        "id": 99012,
        "conta_id": 4,
        "empresa": "ACME SERVICOS LTDA",
        "data": "2026-10-10",
        "descricao": "PIX RECEBIDO",
        "contraparte_nome": "Cliente Exemplo LTDA",
        "contraparte_documento_mascarado": "98.765.432/0001-10",
        "valor": "1500.00",
        "natureza": "C",
        "categoria": null
      }
    ],
    "total": 1,
    "pagina": 1,
    "por_pagina": 50
  }
}

Proteção: permissão de gestão no portal, com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/financeiro/transacoes.csv

Exporta as transações do período em CSV, com os mesmos filtros da listagem (sem paginação). Acima de 10.000 linhas retorna 422 pedindo um período menor.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
iniciodatequerynãoInício (mesmo padrão do resumo).
fimdatequerynãoFim (mesmo padrão do resumo).
conta_idintquerynãoRestringe a uma conta do escopo.
naturezastrquerynãoC ou D.
buscastrquerynãoTexto de busca, até 100 caracteres.

Request

Sem corpo de requisição.

Response 200 OK

Corpo com Content-Type: text/csv; charset=utf-8, separador ; e BOM UTF-8, e Content-Disposition: attachment; filename="transacoes_AAAAMMDD_AAAAMMDD.csv" (datas de início e fim). Não usa envelope.

Proteção: permissão de gestão no portal, com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/financeiro/consentimentos

Contas da empresa ativa que esperam autorização do titular no banco: ativas, não arquivadas, com consentimento pendente ou expirado e com link. O openfinance_link é sensível e sai só para quem tem permissão de gestão no portal.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": [
    {
      "conta_id": 4,
      "empresa": "ACME SERVICOS LTDA",
      "banco_nome": "Itaú",
      "conta_mascarada": "****1234",
      "consentimento_status": "expirado",
      "openfinance_link": "https://exemplo.openfinance/autorizar/abc123"
    }
  ]
}

Proteção: permissão de gestão no portal, com empresa ativa - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Contas Open Finance do portal

As rotas abaixo (bancos, contas e consentimento) também exigem permissão de gestão no portal com empresa ativa; sem ela, a resposta é 403. O número da conta nunca sai completo (só conta_mascarada) e o openfinance_link é sensível: só sai para quem tem permissão de gestão, só em https, e as respostas levam Cache-Control: no-store. Os erros destas rotas têm o formato { "status": "error", "message": "...", "code": "..." } (o code é opcional).

GET /portal/financeiro/bancos

Bancos aceitos no Open Finance para o tipo de pessoa da empresa ativa (CNPJ lista os bancos de pessoa jurídica, CPF os de pessoa física), ordenados por nome. Alimenta o formulário de cadastro de conta.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": [
    { "codigo": "341", "nome": "Itaú" },
    { "codigo": "237", "nome": "Bradesco" }
  ]
}

Erro: 404 ("Empresa não encontrada.") se a empresa ativa não existe.

Proteção: permissão de gestão no portal - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

GET /portal/financeiro/contas

Contas Open Finance não arquivadas da empresa ativa e, se ela for matriz, das filiais com vínculo ativo do acesso. O status_portal traduz a situação da conta para o cliente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": [
    {
      "id": 4,
      "banco_codigo": "341",
      "banco_nome": "Itaú",
      "agencia": "0001",
      "conta_mascarada": "****1234",
      "empresa": "ACME SERVICOS LTDA",
      "status_portal": "aguardando_autorizacao",
      "openfinance_link": "https://exemplo.openfinance/autorizar/abc123",
      "criado_em": "2026-10-01T09:00:00"
    }
  ]
}

status_portal:

ValorSignificado
pendente_liberacaoA contabilidade ainda não liberou o Open Finance da empresa dona da conta.
inativaConta desativada.
gerar_linkConta cadastrada, ainda sem link de consentimento: quem tem permissão de gestão pode gerá-lo.
ativaConsentimento ativo.
expiradaConsentimento expirado ou revogado: só a contabilidade renova.
aguardando_autorizacaoLink gerado, aguardando a autorização no banco. Único estado em que openfinance_link vem preenchido.

Proteção: permissão de gestão no portal - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/financeiro/contas

Cadastra uma conta Open Finance na empresa ativa. Se a contabilidade ainda não liberou o Open Finance da empresa, a conta é aceita e nasce pendente_liberacao; a contabilidade é avisada do cadastro. Há um limite de 20 contas por empresa.

Parâmetros

Sem parâmetros de rota ou query. Corpo ContaCreate (campos desconhecidos dão 422):

CampoTipoObrigatórioDescrição
bank_codestrsimCódigo do banco, conforme GET /portal/financeiro/bancos.
agenciastrsimSó dígitos, 1 a 10 caracteres.
agencia_digitostrnãoDígito da agência, até 2 caracteres.
numero_contastrsimSó dígitos, 1 a 12 caracteres.
numero_conta_digitostrnãoDígito da conta, até 2 caracteres.
account_typeintnãoSó vale para a Caixa (104).

Request

{
  "bank_code": "341",
  "agencia": "0001",
  "numero_conta": "12345",
  "numero_conta_digito": "6"
}

Response 201 Created

Envelope com a conta cadastrada (mesmo formato de um item de GET /portal/financeiro/contas).

Erros:

  • 404 empresa não encontrada.
  • 409 com code: conta_duplicada (a conta já está cadastrada), conta_arquivada (já cadastrada e desativada: falar com a contabilidade para reativar) ou limite_contas.
  • 422 com code: "banco_indisponivel" banco fora da lista aceita; 422 também para corpo inválido.
  • 429 limite de tentativas excedido; veja Retry-After.

Proteção: permissão de gestão no portal - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

POST /portal/financeiro/contas/{conta_id}/consentimento

Gera o link de consentimento de uma conta do escopo e o devolve. Usado para conta em gerar_link; em aguardando_autorizacao devolve o link já gerado. Conta pendente_liberacao e conta expirada respondem 409: o portal não renova consentimento, e no segundo caso a contabilidade é avisada para renovar.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
conta_idintpathsimID da conta.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "conta_id": 4,
    "openfinance_link": "https://exemplo.openfinance/autorizar/abc123"
  }
}

Erros:

  • 404 conta de outra empresa, arquivada ou inexistente ("Conta não encontrada.").
  • 409 com code: pendente_liberacao (Open Finance ainda não liberado pela contabilidade), link_expirado (o link expirou; a contabilidade foi avisada), link_indisponivel (o link precisa ser gerado de novo pela contabilidade) ou registro_recusado (o banco recusou os dados várias vezes). Outro conflito de estado responde 409 sem code.
  • 422 o banco não aceitou os dados da conta.
  • 429 limite de requisições excedido.
  • 502 não foi possível gerar o link agora.
  • 503 Open Finance indisponível, ou sem capacidade de atendimento no momento (a mensagem informa o horário para tentar de novo).

Proteção: permissão de gestão no portal - sujeito a limite de tentativas (excesso devolve 429 com Retry-After).

Schemas

PortalLoginRequest

CampoTipoObrigatórioObservações
identifierstrsimLogin ou e-mail do usuário do portal (3-120 caracteres).
passwordstrsimSenha em texto puro (1-128), verificada contra o hash.
rememberboolnãoDefault false. true = cookie de sessão com validade de 7 dias.

PortalUserCreate

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente ao qual o acesso é vinculado.
nomestrsimNome do acesso (1-200).
loginstrsimLogin do usuário (3-100).
emailEmailStrsimE-mail válido.
passwordstrsim8-128 no schema; mínimo real de 12 e demais regras da política do servidor.
perfilstrnãoPerfil de acesso do usuário (máx. 20). Default cliente.
ativoboolnãoDefault true.

PortalUserUpdate

Todos os campos são opcionais; id_cliente e login não aparecem (imutáveis por esta rota).

CampoTipoObservações
nomestrNovo nome (1-200).
emailEmailStrNovo e-mail.
perfilstrNovo perfil (máx. 20).
ativoboolAtiva/desativa o acesso.
passwordstrNova senha (reset). Mesma política de PortalUserCreate.

PortalUserOut

Saída pública do acesso - nunca expõe senha nem tokens de e-mail.

CampoTipoNotas
idintID do acesso ao portal.
id_clienteintEmpresa de contexto da resposta (ativa, consultada ou única). Pode ser null.
nomestrNome do acesso.
loginstrLogin.
emailstrE-mail vigente.
perfilstrPerfil de acesso do usuário.
ativoboolSituação do acesso.
ultimo_logindatetimeÚltimo login (pode ser null).
data_hora_criacaodatetimeTimestamp de criação.
celularstrSó dígitos (pode ser null).
telefonestrSó dígitos (pode ser null).
email_novo_pendentestrE-mail aguardando confirmação (pode ser null).
senha_provisoria_emdatetimePreenchido enquanto a senha for a definida pelo escritório.
senha_provisoriaboolCalculado: senha_provisoria_em não nulo.
senha_provisoria_expiradaboolCalculado: convite (nunca logado) com senha provisória há mais de 7 dias.

PortalUserCreatedOut

Resposta exclusiva de POST /portal/users.

CampoTipoNotas
portal_userPortalUserOutAcesso criado.
email_enviadobooltrue se a senha provisória foi entregue por e-mail.
email_errostrMotivo da falha de envio (nunca contém a senha).
senha_provisoriastrSenha em texto puro, só quando email_enviado é false.

CustomerResumo

Dados mínimos da empresa ativa, embutidos no login, no /me e no switch-customer.

CampoTipoNotas
idintID do customer.
razao_socialstrRazão social.
nome_fantasiastrNome fantasia (pode ser null).
cpfecnpjstrCNPJ/CPF (pode ser null).
cidadestrMunicípio do cadastro (pode ser null). Usado pelo front para recursos municipais.

PortalEmpresaVinculada

Item de empresas (só vínculos ativos).

CampoTipoNotas
idintID do cliente empresa vinculada.
razao_socialstrRazão social.
nome_fantasiastrPode ser null.
cpfecnpjstrPode ser null.
cidadestrPode ser null.
ativaboolÉ a empresa ativa da sessão atual.
vinculada_emdatetimeDesde quando o acesso alcança a empresa.

PortalVinculoOut

Vínculo acesso x empresa para a tela de gestão interna (inclui revogados).

CampoTipoNotas
idintID do vínculo.
portal_user_idintAcesso.
customer_idintEmpresa.
ativoboolfalse = revogado.
data_hora_criacaodatetimeConcessão.
data_hora_revogacaodatetimeRevogação (pode ser null).
ultimo_acesso_emdatetimeÚltima vez que a empresa foi a ativa.
id_usuario_createdintUsuário do escritório que concedeu.
id_usuario_revogacaointUsuário do escritório que revogou.
razao_socialstrResolvida do customer.
nome_fantasiastrResolvido do customer.

PortalSocioOut

CampoTipoNotas
idintcustomer_qsa.id.
nomestrNome do sócio.
cpfecnpjstrCPF/CNPJ do sócio (pode ser null).
qualificacaostrEx.: Sócio-Administrador (pode ser null).

PortalLancamentoLucroCreate

Não aceita id_cliente, status nem natureza_rendimento (fixados pelo backend; campos extras são ignorados).

CampoTipoObrigatórioObservações
competenciastrsimFormato MM/YYYY (7 caracteres).
data_registrodatesimData do registro.
valor_liquidoDecimalsimValor >= 0 (validador canônico).
id_qsa_clienteintnãoSócio titular (validado contra a empresa).
data_pagamentodatenãoData de pagamento.
observacaostrnãoObservação livre.

PortalLancamentoLucroUpdate

Todos os campos opcionais (patch): competencia, data_registro, data_pagamento, valor_liquido, observacao e id_qsa_cliente. status, id_cliente e natureza_rendimento nunca são aceitos.

PortalLancamentoLucroRead

Item de GET /portal/lancamentos-lucro (o LancamentoLucroRead canônico + autoria). Campos principais:

CampoTipoNotas
idintID do lançamento.
id_clienteintEmpresa.
id_qsa_clienteintSócio (pode ser null).
competenciastrMM/YYYY.
data_registrodate-
data_pagamentodatePode ser null.
valor_liquidoDecimalValor líquido distribuído.
valor_brutoDecimalBruto (REINF), pode ser null.
valor_ir_retidoDecimalIR retido. Default 0.
id_ataintAta usada como isenção (pode ser null).
valor_ata_utilizadaDecimalSempre 0 em lançamentos criados pelo portal.
natureza_rendimentostrNatureza do rendimento.
statusstrEm processamento, processado, cancelado, Via e-CAC, Transmitido ou Em retificação.
observacaostrPode ser null.
tipo_evento_reinfstrR4010, R4020 ou R4040 (derivado).
nome_sociostrNome do sócio (pode ser null).
id_usuario_createdintAutor interno (null se criado pelo portal).
id_portal_user_createdintAutor do portal (null se criado internamente).
data_hora_criacaodatetimeTimestamp de criação.
autor_nomestrPrimeiro nome (interno) ou nome completo (portal). Só na listagem.
autor_realmstrinterno ou portal. Só na listagem.

PortalSimulacaoFiscalRequest

CampoTipoObrigatórioObservações
competenciastrsimMM/YYYY ou YYYY-MM (normalizado para MM/YYYY).
valor_liquidoDecimalsim>= 0.
id_qsa_clienteintnão> 0. Sócio da própria empresa (posse validada).
excluir_idintnão> 0. Lançamento em edição (posse validada).

PortalSemMovimentoOut

CampoTipoNotas
competenciastrMM/YYYY.
data_hora_criacaodatetimePode ser null.
origemstrcliente (portal) ou escritorio (Hub). Derivado.
pode_desfazerboolCompetência ainda aberta na Receita (o DELETE é aceito).

PortalOperadoraOut

CampoTipoNotas
idintID da operadora.
razao_socialstrEx.: Operadora Exemplo.
registro_ansstrRegistro ANS (pode ser null).
tipo_contratacaostrPode ser null.
tipo_coberturastrPode ser null.
abrangenciastrPode ser null.
statusstrSituação da operadora (ex.: ativo).

PortalDependenteCreate

id_cliente não aparece (fixado pelo token). PortalDependenteUpdate tem os mesmos campos, todos opcionais.

CampoTipoObrigatórioObservações
nome_completostrsimNome do dependente (1-100).
cpfstrnãoCPF (máx. 14).
data_nascimentodatenãoData de nascimento.
grau_parentescostrnãoEx.: Filho(a) (máx. 50).
id_customer_qsaintnãoSócio titular (validado contra a empresa).

PortalDependenteOut

Campos id, nome_completo, cpf, data_nascimento, grau_parentesco, id_customer_qsa e status.

PortalLancamentoPlanoSaudeCreate

Não aceita id_cliente nem status. PortalLancamentoPlanoSaudeUpdate tem os mesmos campos, todos opcionais.

CampoTipoObrigatórioObservações
competenciastrsimFormato MM/YYYY.
data_registrodatesimData do registro.
valorDecimalsimValor (validador canônico do domínio).
id_operadora_saudeintsimOperadora vinculada à empresa (validada).
id_qsa_clienteintsimSócio titular (validado contra a empresa).
id_dependenteintnãoDependente coberto (validado contra a empresa).
data_pagamentodatenãoData de pagamento.
natureza_rendimentostrnãoMáx. 100.
observacaostrnãoMáx. 2000.

PortalLancamentoPlanoSaudeOut

Campos id, id_cliente, competencia, data_registro, data_pagamento, valor, id_operadora_saude, id_qsa_cliente, id_dependente, natureza_rendimento, status e observacao.

PortalCertidaoNegativaOut

CampoTipoNotas
idintID da certidão.
id_clienteintEmpresa.
tipostrEx.: Receita Federal.
statusstrConcluído ou Pendência Fiscal.
observacaostrPode ser null.
data_hora_emissaodatetimeEmissão.
data_validadedatetimePode ser null.
negativaboolPode ser null.
motivostrPode ser null.

PortalCertidaoNegativaDetalheOut acrescenta pdf_base64.

PortalGuiaOut

Serve ISS e DCTFWeb/PGDAS.

CampoTipoNotas
idintID da guia.
tipostrCru: com_aliquota/sem_aliquota (ISS) ou DCTFWeb/PGDAS.
competenciastrEx.: 2026-07 (pode ser null).
statusstrConcluído ou Paga.
data_hora_emissaodatetimePode ser null.
arquivo_nomestrPode ser null.
tem_arquivoboolHá PDF para baixar.
pagamento_informado_emdatetimeQuando o cliente informou o pagamento (null = não informado).
pagamento_origemstrcliente ou null.
empresaobjetoEmpresa dona da guia: id, nome e cnpj (só dígitos).

PortalSituacaoFiscalOut

CampoTipoNotas
idintID da SITFIS.
id_clienteintEmpresa.
protocolostrProtocolo da emissão.
statusstrStatus de processamento (Concluido).
data_hora_emissaodatetimePode ser null.
observacaostrPode ser null.
tem_pdfboolHá PDF disponível no detalhe.
detalhamentoobjetodiagnostico_receita_federal, diagnostico_procuradoria_geral, status e observacao; null se a extração ainda não rodou.
empresaobjetoEmpresa dona da SITFIS: id, nome e cnpj (só dígitos).

Os diagnósticos saem crus: Regular, Pendência, Exigibilidade Suspensa, Não Identificado ou nao_identificado. PortalSituacaoFiscalDetalheOut acrescenta pdf_base64.

PortalAlvaraFuncionamentoOut

Campos id, ano_competencia (exercício, int), status, data_hora_emissao, arquivo_nome e tem_arquivo.

PortalTFFSalvadorOut

Campos id, ano_competencia, cota (string crua), status, data_hora_emissao, arquivo_nome e tem_arquivo.

PortalChamadoOut

CampoTipoNotas
idintID do chamado.
id_portal_userintAcesso que abriu (pode ser null).
titulostrTítulo.
detalhamentostrDescrição.
tipostrproblema, solicitacao, duvida ou sugestao.
statusstraberto, em_andamento ou concluido.
data_hora_criacaodatetimeAbertura.
data_hora_edicaodatetimePode ser null.
data_hora_fechamentodatetimePode ser null.
motivo_fechamentostrPode ser null.
nao_lidasintRespostas da contabilidade ainda não vistas pelo acesso.
ultima_mensagem_emdatetimeÚltima mensagem pública (pode ser null).

PortalChamadoMensagemOut

Campos id, id_chamado, autor_realm (portal ou interno), id_portal_user, texto, data_hora_criacao, autor_nome e autor_foto_url (estes dois só para mensagens do realm interno).

PortalChamadoAnexoOut

Campos id, id_chamado, id_mensagem (null = anexo da abertura), nome_arquivo, mime_type, tamanho_bytes e data_hora_criacao. PortalChamadoAnexoDownloadOut acrescenta conteudo_base64.

PortalChamadoResumoOut

Campos nao_lidas, chamados_com_novidade, abertos (não concluídos), total e por_status (contagem por status, com zero explícito).

PortalChamadoAvaliacaoOut

Campos nota (1 a 5), comentario, data_hora_criacao e data_hora_edicao (null = nunca reenviada).

PortalConsentimentoFinanceiroOut

Campos conta_id, empresa, banco_nome, conta_mascarada, consentimento_status e openfinance_link.

Notas

A empresa vem SEMPRE do token

O cliente nunca informa id_cliente/customer_id no path, query ou body das rotas de dados. A empresa é a ativa do token, já verificada contra os vínculos ativos. Os schemas de escrita não têm id_cliente nem status (anti mass-assignment), e campos desconhecidos no corpo resultam em 422. Acessar um recurso de outra empresa retorna 404 - o portal não revela sequer a existência de dados de outro tenant. A única rota que recebe um id de empresa do corpo é POST /portal/auth/switch-customer, que reconsulta o vínculo no banco antes de emitir o token.

Lançamentos travam após processamento

Um lançamento só pode ser editado (ou, no caso do lucro, excluído) pelo portal enquanto está no status inicial: "Em processamento" (lucro) ou "pendente" (plano de saúde). Depois que a contabilidade processa/cancela o lançamento no sistema interno, a edição via portal retorna 409 Conflict.

Listagens vazias: dois comportamentos

As listagens de lançamentos de lucro, sócios, operadoras, dependentes e lançamentos de plano de saúde retornam error_response ({ status: "error", message, details: [] }) quando não há registros. As demais listagens (certidões, guias, situações fiscais, alvarás, TFF, chamados, sem movimento, resumo fiscal) retornam data: [] em success. Trate ambos os formatos no front.

  • Toda resposta de /api/v1/portal recebe Cache-Control: no-store.
  • As rotas de /portal/users são administrativas (uso interno do escritório, restrito) e não fazem parte do fluxo do cliente final - elas provisionam os acessos e os vínculos que depois autenticam no portal.
  • Senha provisória: enquanto senha_provisoria for true, só GET /auth/me, POST /auth/logout e POST /auth/change-password funcionam; as demais rotas autenticadas respondem 403 SENHA_PROVISORIA.
  • As rotas estão sujeitas a limite de tentativas; ao exceder, a API devolve 429 com Retry-After.