Solicitacoes de negocio
Solicitacoes de negocio sao o mecanismo que a plataforma usa para executar fluxos de trabalho que envolvem varias etapas. Em vez de fazer uma chamada de API que faz tudo de uma vez, você cria uma solicitação e o sistema cuida do resto.
O que e uma solicitação de negocio?
Pense como um envelope de tarefa. Dentro do envelope você coloca o que quer fazer (criar um contrato, emitir notas, encerrar um contrato), e o sistema executa passo a passo, atualizando o status conforme avanca.
A solicitação fica no banco de dados com um status que muda ao longo do tempo. Isso permite que:
- você saiba em que etapa o processo esta
- O sistema possa retomar se algo der errado
- Outros sistemas (como o n8n) sejam notificados quando cada etapa termina
Os 4 tipos de solicitação
Existem quatro tipos de solicitação, cada uma para um proposito diferente:
Novo Contrato
Inicia um contrato digital preenchivel. O sistema cria um rascunho de contrato que o cliente assina depois.
Novo Contrato (PDF)
Registra um PDF de contrato assinado fora da plataforma (por exemplo, assinado fisicamente). O sistema ja considera o contrato como aprovado.
Emissão de Notas em Lote
Emite um lote de notas fiscais de uma vez. você informa varios profissionais e clientes, e o sistema gera todas as notas em sequencia.
Encerrar Contrato
Solicita o encerramento de um contrato que ja foi aprovado. O sistema registra a solicitação, notifica as partes, e opcionalmente anexa o PDF do distrato assinado. Se o distrato ja estiver disponivel, o contrato vai direto para encerrado e a solicitação direto para concluida, sem passar pelo estado intermedio.
Como funciona o fluxo?
Passo 1: Criar a solicitação
você envia uma chamada para a API informando o tipo e os dados. O sistema cria a solicitação com status inicial Rascunho e imediatamente muda para Aberto.
Passo 2: O sistema processa
Dependendo do tipo, o sistema faz coisas diferentes:
- Novo Contrato: cria um contrato em rascunho, pronto para ser preenchido
- Novo Contrato (PDF): registra o PDF e marca o contrato como aprovado
- Emissão de Notas em Lote: busca as entidades fiscais, normaliza os dados, e cria as notas fiscais uma por uma
- Encerrar Contrato: valida que o contrato esta aprovado, registra a solicitação de encerramento, e opcionalmente anexa o PDF do distrato (se ja tiver o PDF, vai direto para encerrado)
Passo 3: Acompanhar o status
você pode consultar o status a qualquer momento. Quando algo muda (uma nota e emitida, um PDF e gerado), o sistema atualiza o status da solicitação.
Passo 4: Receber notificacao
Em vez de ficar perguntando, você pode pedir para ser avisado quando algo acontece. A plataforma manda uma mensagem para o seu sistema toda vez que o status muda.
Os status possiveis
Cada solicitação passa por varios status até chegar ao final:
O cancelamento pode acontecer a qualquer momento:
Outros status que podem aparecer:
- Aguardando: o sistema esta esperando algo (por exemplo, uma resposta do governo)
- Com Erro: algo deu errado. O sistema vai tentar de novo.
- Cancelamento Solicitado: o cancelamento foi pedido mas ainda não foi confirmado
Exemplo pratico: emitir notas de varios profissionais
Imagine que você e um escritorio de contabilidade e precisa emitir as notas fiscais de 10 profissionais ao mesmo tempo. Em vez de fazer 10 chamadas separadas, você faz uma unica solicitação:
- você informa o mes fiscal (ex: abril/2026)
- você lista os 10 profissionais com seus clientes e valores
- O sistema cria 10 notas fiscais em sequencia
- Cada nota passa pelo seu proprio fluxo (emitida, cancelada, etc.)
- Quando todas as 10 notas terminam, a solicitação e marcada como concluida
Se algo der errado em uma das notas, as outras continuam normalmente. A solicitação só e marcada com erro se o sistema não conseguir processa-la.
Efeitos em cascata
Quando uma solicitação muda de status, o sistema atualiza automaticamente os recursos ligados:
Contrato
Quando a solicitação de criar contrato e concluida, o contrato muda de preenchendo para aprovado ou aguardando assinatura.
Nota fiscal
Quando a solicitação de emitir notas e concluida, cada nota individual muda para emitida ou cancelada.
Encerramento
Quando a solicitação de encerrar e concluida, o contrato muda para encerrado. Se o PDF do distrato foi enviado junto com a solicitação, o contrato vai direto para encerrado sem passar por aguardando encerramento. O PDF do distrato fica gravado no contrato para consulta futura.
Isso significa que você não precisa atualizar cada recurso manualmente. Basta criar a solicitação e o sistema cuida dos detalhes.
Dicas praticas
Sempre use o tipo certo
Se você quer emitir notas para um novo cliente, use new_contract (Novo Contrato) primeiro para criar o contrato, e depois use profesional_invoice_emission (emissão de Notas em Lote) para emitir as notas. Nao tente fazer tudo em uma unica solicitação.
Nao modifique depois que comecou
Depois que a solicitação sai do status Aberto, os dados não podem mais ser alterados. Se você errou algo, cancele a solicitação e crie uma nova.
Use IDs de string
O profesional_id e sempre uma string, mesmo que pareca um número. Envie como string para evitar problemas.
Configure o retorno antes de criar
Se você quer ser avisado quando a solicitação terminar, configure o retorno automatico antes de criar. Assim você não precisa ficar perguntando ao sistema se terminou.
Anexe o distrato no momento certo
Se você ja tem o PDF do distrato assinado, envie junto com a solicitação de encerramento (data.pdf_url) — o sistema vai direto para o estado final sem passar pelo intermediario. Se ainda não tem, envie depois, quando a solicitação for marcada como concluida (campo termination_pdf_url no payload de status). As duas formas sao validas — use a que for mais conveniente para o seu fluxo. O documento só pode ser definido uma vez: depois de gravado, ele e bloqueado.
Problemas comuns
"Entidade fiscal não encontrada"
O sistema não conseguiu encontrar a entidade fiscal para um dos profissionais. Verifique se todos os profissionais tem entidade fiscal cadastrada antes de criar a solicitação.
"Contrato em status invalido"
você tentou encerrar um contrato que não esta aprovado. O sistema só permite encerramento de contratos aprovados.
"Dados imutaveis"
você tentou modificar os dados de uma solicitação que ja saiu do status Aberto. Crie uma nova solicitação com os dados corrigidos.
"Evento desconhecido"
O sistema de retorno automatico recebeu um tipo de evento que não reconhece. Apenas update_status e suportado pelo sistema automatico.