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/portalA 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ção | Rótulo nas rotas | O que exige |
|---|---|---|
| Público | público | Nada. 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 portal | token do portal | Bearer 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 definitiva | token com senha definitiva | O 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 ativa | token com empresa ativa | O 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ão | permissão de gestão no portal | O anterior + permissão de gestão no portal. Falha = 403. Só as rotas de Financeiro. |
| Uso interno | uso 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int >= 1 | query | não | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
portal_user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
portal_user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
portal_user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
portal_user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
portal_user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
portal_user_id | int | path | sim | ID do acesso ao portal |
customer_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | não | Filtro por competência MM/YYYY. |
page | int >= 1 | query | não | Página. |
per_page | int 1..500 | query | não | Itens 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_qsa_cliente | int > 0 | query | não | Filtro por sócio da própria empresa. Id alheio devolve agregação vazia. |
competencia | str | query | não | Filtro por competência (MM/YYYY). |
status | str | query | não | Filtro por status do lançamento. |
data_pagamento_inicio | date | query | não | data_pagamento >= (YYYY-MM-DD). |
data_pagamento_fim | date | query | não | data_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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | sim | Competê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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_qsa_cliente | int > 0 | query | não | Filtro por sócio (customer_ata.id_customer_qsa). |
competencia | str | query | não | Competência (MM/YYYY) dos lançamentos. |
status | str | query | não | Status do lançamento (não da ata). |
data_pagamento_inicio | date | query | não | lançamento.data_pagamento >=. |
data_pagamento_fim | date | query | não | lanç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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
dependente_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | não | Filtro por competência MM/YYYY. |
page | int >= 1 | query | não | Página. |
per_page | int 1..500 | query | não | Itens 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
tipo | str | query | não | Filtro por tipo de certidão. |
limit | int 1..500 | query | não | Máximo de itens. Default 100. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
certidao_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | não | Competência (YYYY-MM). |
start_date | datetime | query | não | Emissão >= start_date. |
end_date | datetime | query | não | Emissão <= end_date. |
limit | int 1..500 | query | não | Máximo de guias. Default 500. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | não | Competência (YYYY-MM). |
start_date | datetime | query | não | Emissão >= start_date. |
end_date | datetime | query | não | Emissão <= end_date. |
limit | int 1..500 | query | não | Máximo de guias. Default 500. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
setor | str | query | não | fiscal ou pessoal. Omitido = todos. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | não | Competência (YYYY-MM). Formato inválido retorna 422. |
start_date | datetime | query | não | Registro >= start_date. |
end_date | datetime | query | não | Registro <= end_date. |
limit | int 1..500 | query | não | Máximo de guias. Default 500. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
setor | str | query | não | fiscal (ICMS, PIS, COFINS, IRPJ, CSLL) ou pessoal (FGTS, DAE, INSS). Omitido = todos. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
guia_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
limit | int 1..500 | query | não | Máximo de itens. Default 100. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
situacao_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ano_competencia | int 1900..2999 | query | não | Exercício do alvará. |
start_date | datetime | query | não | Emissão >= start_date. |
end_date | datetime | query | não | Emissão <= end_date. |
limit | int 1..500 | query | não | Máximo de alvarás. Default 500. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
alvara_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ano_competencia | int 1900..2999 | query | não | Exercício da guia. |
cota | str (máx. 10) | query | não | Cota, valor cru (ex.: 1 ou 01). |
start_date | datetime | query | não | Emissão >= start_date. |
end_date | datetime | query | não | Emissão <= end_date. |
limit | int 1..500 | query | não | Máximo de guias. Default 500. |
offset | int >= 0 | query | não | Deslocamento. Default 0. |
incluir_filiais | bool | query | não | Matriz: 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
tff_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
status | str | query | não | aberto, em_andamento ou concluido. |
limit | int 1..500 | query | não | Máximo de itens. Default 100. |
offset | int >= 0 | query | não | Deslocamento. 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID do chamado. |
limit | int 1..500 | query | não | Máximo de itens. Default 100. |
offset | int >= 0 | query | não | Deslocamento. 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID do chamado. |
id_mensagem | int | query | não | Restringe 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID do chamado. |
id_mensagem | int | query | não | Prende 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
anexo_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
chamado_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
token | str | path | sim | Token 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
inicio | date | query | não | Emissão a partir de (inclusivo). Padrão: 1º dia do mês de 11 meses atrás. |
fim | date | query | não | Emissão até (inclusivo). Padrão: hoje (São Paulo). |
situacao | str | query | não | todas (padrão), normal ou cancelada. |
papel | str | query | não | todas (padrão), prestador ou tomador. |
busca | str | query | não | Texto de busca, até 100 caracteres. |
incluir_filiais | bool | query | não | Inclui as filiais do escopo. Default false. |
ordenar | str | query | não | data_emissao (padrão), numero ou valor_servico. |
direcao | str | query | não | desc (padrão) ou asc. |
pagina | int >= 1 | query | não | Página. Default 1. |
por_pagina | int 1..100 | query | não | Itens 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
inicio | date | query | não | Mesmo padrão da listagem. |
fim | date | query | não | Mesmo padrão da listagem. |
busca | str | query | não | Texto de busca, até 100 caracteres. |
incluir_filiais | bool | query | não | Inclui 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | str | path | sim | id 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
inicio | date | query | não | Início. Padrão: 1º dia do mês corrente (São Paulo). |
fim | date | query | não | Fim. 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
inicio | date | query | não | Início (mesmo padrão do resumo). |
fim | date | query | não | Fim (mesmo padrão do resumo). |
conta_id | int | query | não | Restringe a uma conta do escopo. |
natureza | str | query | não | C (crédito) ou D (débito). |
busca | str | query | não | Texto de busca, até 100 caracteres. |
pagina | int >= 1 | query | não | Página. Default 1. |
por_pagina | int >= 1 | query | não | Itens 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
inicio | date | query | não | Início (mesmo padrão do resumo). |
fim | date | query | não | Fim (mesmo padrão do resumo). |
conta_id | int | query | não | Restringe a uma conta do escopo. |
natureza | str | query | não | C ou D. |
busca | str | query | não | Texto 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:
| Valor | Significado |
|---|---|
pendente_liberacao | A contabilidade ainda não liberou o Open Finance da empresa dona da conta. |
inativa | Conta desativada. |
gerar_link | Conta cadastrada, ainda sem link de consentimento: quem tem permissão de gestão pode gerá-lo. |
ativa | Consentimento ativo. |
expirada | Consentimento expirado ou revogado: só a contabilidade renova. |
aguardando_autorizacao | Link 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):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
bank_code | str | sim | Código do banco, conforme GET /portal/financeiro/bancos. |
agencia | str | sim | Só dígitos, 1 a 10 caracteres. |
agencia_digito | str | não | Dígito da agência, até 2 caracteres. |
numero_conta | str | sim | Só dígitos, 1 a 12 caracteres. |
numero_conta_digito | str | não | Dígito da conta, até 2 caracteres. |
account_type | int | não | Só 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:
404empresa não encontrada.409comcode:conta_duplicada(a conta já está cadastrada),conta_arquivada(já cadastrada e desativada: falar com a contabilidade para reativar) oulimite_contas.422comcode: "banco_indisponivel"banco fora da lista aceita;422também para corpo inválido.429limite de tentativas excedido; vejaRetry-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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
conta_id | int | path | sim | ID 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:
404conta de outra empresa, arquivada ou inexistente ("Conta não encontrada.").409comcode: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) ouregistro_recusado(o banco recusou os dados várias vezes). Outro conflito de estado responde409semcode.422o banco não aceitou os dados da conta.429limite de requisições excedido.502não foi possível gerar o link agora.503Open 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
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
identifier | str | sim | Login ou e-mail do usuário do portal (3-120 caracteres). |
password | str | sim | Senha em texto puro (1-128), verificada contra o hash. |
remember | bool | não | Default false. true = cookie de sessão com validade de 7 dias. |
PortalUserCreate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | ID do cliente ao qual o acesso é vinculado. |
nome | str | sim | Nome do acesso (1-200). |
login | str | sim | Login do usuário (3-100). |
email | EmailStr | sim | E-mail válido. |
password | str | sim | 8-128 no schema; mínimo real de 12 e demais regras da política do servidor. |
perfil | str | não | Perfil de acesso do usuário (máx. 20). Default cliente. |
ativo | bool | não | Default true. |
PortalUserUpdate
Todos os campos são opcionais; id_cliente e login não aparecem (imutáveis por esta rota).
| Campo | Tipo | Observações |
|---|---|---|
nome | str | Novo nome (1-200). |
email | EmailStr | Novo e-mail. |
perfil | str | Novo perfil (máx. 20). |
ativo | bool | Ativa/desativa o acesso. |
password | str | Nova senha (reset). Mesma política de PortalUserCreate. |
PortalUserOut
Saída pública do acesso - nunca expõe senha nem tokens de e-mail.
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do acesso ao portal. |
id_cliente | int | Empresa de contexto da resposta (ativa, consultada ou única). Pode ser null. |
nome | str | Nome do acesso. |
login | str | Login. |
email | str | E-mail vigente. |
perfil | str | Perfil de acesso do usuário. |
ativo | bool | Situação do acesso. |
ultimo_login | datetime | Último login (pode ser null). |
data_hora_criacao | datetime | Timestamp de criação. |
celular | str | Só dígitos (pode ser null). |
telefone | str | Só dígitos (pode ser null). |
email_novo_pendente | str | E-mail aguardando confirmação (pode ser null). |
senha_provisoria_em | datetime | Preenchido enquanto a senha for a definida pelo escritório. |
senha_provisoria | bool | Calculado: senha_provisoria_em não nulo. |
senha_provisoria_expirada | bool | Calculado: convite (nunca logado) com senha provisória há mais de 7 dias. |
PortalUserCreatedOut
Resposta exclusiva de POST /portal/users.
| Campo | Tipo | Notas |
|---|---|---|
portal_user | PortalUserOut | Acesso criado. |
email_enviado | bool | true se a senha provisória foi entregue por e-mail. |
email_erro | str | Motivo da falha de envio (nunca contém a senha). |
senha_provisoria | str | Senha em texto puro, só quando email_enviado é false. |
CustomerResumo
Dados mínimos da empresa ativa, embutidos no login, no /me e no switch-customer.
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do customer. |
razao_social | str | Razão social. |
nome_fantasia | str | Nome fantasia (pode ser null). |
cpfecnpj | str | CNPJ/CPF (pode ser null). |
cidade | str | Município do cadastro (pode ser null). Usado pelo front para recursos municipais. |
PortalEmpresaVinculada
Item de empresas (só vínculos ativos).
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do cliente empresa vinculada. |
razao_social | str | Razão social. |
nome_fantasia | str | Pode ser null. |
cpfecnpj | str | Pode ser null. |
cidade | str | Pode ser null. |
ativa | bool | É a empresa ativa da sessão atual. |
vinculada_em | datetime | Desde quando o acesso alcança a empresa. |
PortalVinculoOut
Vínculo acesso x empresa para a tela de gestão interna (inclui revogados).
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do vínculo. |
portal_user_id | int | Acesso. |
customer_id | int | Empresa. |
ativo | bool | false = revogado. |
data_hora_criacao | datetime | Concessão. |
data_hora_revogacao | datetime | Revogação (pode ser null). |
ultimo_acesso_em | datetime | Última vez que a empresa foi a ativa. |
id_usuario_created | int | Usuário do escritório que concedeu. |
id_usuario_revogacao | int | Usuário do escritório que revogou. |
razao_social | str | Resolvida do customer. |
nome_fantasia | str | Resolvido do customer. |
PortalSocioOut
| Campo | Tipo | Notas |
|---|---|---|
id | int | customer_qsa.id. |
nome | str | Nome do sócio. |
cpfecnpj | str | CPF/CNPJ do sócio (pode ser null). |
qualificacao | str | Ex.: Sócio-Administrador (pode ser null). |
PortalLancamentoLucroCreate
Não aceita id_cliente, status nem natureza_rendimento (fixados pelo backend; campos extras são ignorados).
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
competencia | str | sim | Formato MM/YYYY (7 caracteres). |
data_registro | date | sim | Data do registro. |
valor_liquido | Decimal | sim | Valor >= 0 (validador canônico). |
id_qsa_cliente | int | não | Sócio titular (validado contra a empresa). |
data_pagamento | date | não | Data de pagamento. |
observacao | str | não | Observaçã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:
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do lançamento. |
id_cliente | int | Empresa. |
id_qsa_cliente | int | Sócio (pode ser null). |
competencia | str | MM/YYYY. |
data_registro | date | - |
data_pagamento | date | Pode ser null. |
valor_liquido | Decimal | Valor líquido distribuído. |
valor_bruto | Decimal | Bruto (REINF), pode ser null. |
valor_ir_retido | Decimal | IR retido. Default 0. |
id_ata | int | Ata usada como isenção (pode ser null). |
valor_ata_utilizada | Decimal | Sempre 0 em lançamentos criados pelo portal. |
natureza_rendimento | str | Natureza do rendimento. |
status | str | Em processamento, processado, cancelado, Via e-CAC, Transmitido ou Em retificação. |
observacao | str | Pode ser null. |
tipo_evento_reinf | str | R4010, R4020 ou R4040 (derivado). |
nome_socio | str | Nome do sócio (pode ser null). |
id_usuario_created | int | Autor interno (null se criado pelo portal). |
id_portal_user_created | int | Autor do portal (null se criado internamente). |
data_hora_criacao | datetime | Timestamp de criação. |
autor_nome | str | Primeiro nome (interno) ou nome completo (portal). Só na listagem. |
autor_realm | str | interno ou portal. Só na listagem. |
PortalSimulacaoFiscalRequest
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
competencia | str | sim | MM/YYYY ou YYYY-MM (normalizado para MM/YYYY). |
valor_liquido | Decimal | sim | >= 0. |
id_qsa_cliente | int | não | > 0. Sócio da própria empresa (posse validada). |
excluir_id | int | não | > 0. Lançamento em edição (posse validada). |
PortalSemMovimentoOut
| Campo | Tipo | Notas |
|---|---|---|
competencia | str | MM/YYYY. |
data_hora_criacao | datetime | Pode ser null. |
origem | str | cliente (portal) ou escritorio (Hub). Derivado. |
pode_desfazer | bool | Competência ainda aberta na Receita (o DELETE é aceito). |
PortalOperadoraOut
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID da operadora. |
razao_social | str | Ex.: Operadora Exemplo. |
registro_ans | str | Registro ANS (pode ser null). |
tipo_contratacao | str | Pode ser null. |
tipo_cobertura | str | Pode ser null. |
abrangencia | str | Pode ser null. |
status | str | Situação da operadora (ex.: ativo). |
PortalDependenteCreate
id_cliente não aparece (fixado pelo token). PortalDependenteUpdate tem os mesmos campos, todos opcionais.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome_completo | str | sim | Nome do dependente (1-100). |
cpf | str | não | CPF (máx. 14). |
data_nascimento | date | não | Data de nascimento. |
grau_parentesco | str | não | Ex.: Filho(a) (máx. 50). |
id_customer_qsa | int | não | Só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.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
competencia | str | sim | Formato MM/YYYY. |
data_registro | date | sim | Data do registro. |
valor | Decimal | sim | Valor (validador canônico do domínio). |
id_operadora_saude | int | sim | Operadora vinculada à empresa (validada). |
id_qsa_cliente | int | sim | Sócio titular (validado contra a empresa). |
id_dependente | int | não | Dependente coberto (validado contra a empresa). |
data_pagamento | date | não | Data de pagamento. |
natureza_rendimento | str | não | Máx. 100. |
observacao | str | não | Má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
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID da certidão. |
id_cliente | int | Empresa. |
tipo | str | Ex.: Receita Federal. |
status | str | Concluído ou Pendência Fiscal. |
observacao | str | Pode ser null. |
data_hora_emissao | datetime | Emissão. |
data_validade | datetime | Pode ser null. |
negativa | bool | Pode ser null. |
motivo | str | Pode ser null. |
PortalCertidaoNegativaDetalheOut acrescenta pdf_base64.
PortalGuiaOut
Serve ISS e DCTFWeb/PGDAS.
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID da guia. |
tipo | str | Cru: com_aliquota/sem_aliquota (ISS) ou DCTFWeb/PGDAS. |
competencia | str | Ex.: 2026-07 (pode ser null). |
status | str | Concluído ou Paga. |
data_hora_emissao | datetime | Pode ser null. |
arquivo_nome | str | Pode ser null. |
tem_arquivo | bool | Há PDF para baixar. |
pagamento_informado_em | datetime | Quando o cliente informou o pagamento (null = não informado). |
pagamento_origem | str | cliente ou null. |
empresa | objeto | Empresa dona da guia: id, nome e cnpj (só dígitos). |
PortalSituacaoFiscalOut
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID da SITFIS. |
id_cliente | int | Empresa. |
protocolo | str | Protocolo da emissão. |
status | str | Status de processamento (Concluido). |
data_hora_emissao | datetime | Pode ser null. |
observacao | str | Pode ser null. |
tem_pdf | bool | Há PDF disponível no detalhe. |
detalhamento | objeto | diagnostico_receita_federal, diagnostico_procuradoria_geral, status e observacao; null se a extração ainda não rodou. |
empresa | objeto | Empresa 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
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do chamado. |
id_portal_user | int | Acesso que abriu (pode ser null). |
titulo | str | Título. |
detalhamento | str | Descrição. |
tipo | str | problema, solicitacao, duvida ou sugestao. |
status | str | aberto, em_andamento ou concluido. |
data_hora_criacao | datetime | Abertura. |
data_hora_edicao | datetime | Pode ser null. |
data_hora_fechamento | datetime | Pode ser null. |
motivo_fechamento | str | Pode ser null. |
nao_lidas | int | Respostas da contabilidade ainda não vistas pelo acesso. |
ultima_mensagem_em | datetime | Ú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/portalrecebeCache-Control: no-store. - As rotas de
/portal/userssã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_provisoriafortrue, sóGET /auth/me,POST /auth/logoutePOST /auth/change-passwordfuncionam; as demais rotas autenticadas respondem403 SENHA_PROVISORIA. - As rotas estão sujeitas a limite de tentativas; ao exceder, a API devolve
429comRetry-After.