← Todos os guias
Guia geral

Conceitos da plataforma

Os principais objetos que existem na plataforma, o que cada um representa, e como eles se conectam.

01

Profissionais

Um profissional é a pessoa ou empresa que presta serviços. Cada profissional tem um cadastro com nome, e-mail, CPF ou CNPJ, e outras informações pessoais.

Quando um profissional se cadastra na plataforma, a API cria automaticamente uma entidade fiscal para ele. A entidade fiscal é o "lado oficial" do profissional — o que o governo enxerga.

02

Entidades fiscais

As entidades fiscais representam o cadastro da empresa ou do profissional perante o governo. Existem dois tipos:

Entidade fiscal vendedora

Quem emite a nota fiscal. É a empresa ou o MEI que prestou o serviço. Contém o CNPJ, endereço, regime tributário, e dados do certificado digital.

Entidade fiscal compradora

Quem recebe a nota fiscal. É o cliente que contratou o serviço. Pode ser uma pessoa física (CPF) ou jurídica (CNPJ).

Entidade fiscal de negócio

Representa o negócio (a empresa que usa a plataforma) no cadastro fiscal. Distinta das entidades dos profissionais.

03

MEI (Microempreendedor Individual)

O MEI é um tipo especial de entidade fiscal — o Microempreendedor Individual, com regime tributário simplificado e limite de faturamento de R$ 81 mil por ano. A plataforma trata o MEI como um caso especial porque:

  • Tem obrigações próprias (DAS mensal, DASN anual)
  • Pode passar pelo Diagnóstico MEI, que avalia a saúde fiscal
  • Tem regras simplificadas para emissão de notas

Para um profissional MEI, a plataforma mantém dados específicos como os pagamentos do DAS, declarações anuais, e situação do CNPJ.

04

Notas fiscais

A nota fiscal é o documento eletrônico que comprova a prestação de um serviço. A plataforma emite NFS-e (Nota Fiscal de Serviços eletrônica) diretamente nos sistemas das prefeituras, sem precisar acessar cada site manualmente.

Cada nota fiscal tem:

  • Um vendedor (a entidade fiscal vendedora — quem prestou)
  • Um comprador (a entidade fiscal compradora — quem contratou)
  • Um valor, descrição do serviço, e competência (mês/ano)
  • Um status: pendente, solicitada, emitida, cancelada, ou com erro
05

Contratos

Um contrato representa um acordo entre o cliente e o profissional. Os contratos vinculam as notas fiscais a um compromisso maior — por exemplo, "esse cliente contratou 12 sessões de massagem ao longo do ano".

Quando você cria um contrato, a plataforma pode usá-lo para emitir notas fiscais automaticamente, no valor e na frequência definidos.

06

Credenciais e autenticação

Para emitir notas fiscais, a plataforma precisa de algumas credenciais armazenadas:

pass-gov

Senha do portal do governo (gov.br / prefeitura). Usada para buscar o DAS e outras informações fiscais.

pass-invoices

Credenciais de acesso ao portal de notas fiscais da prefeitura. Pode ser só uma senha, um token, ou usuário e senha.

Certificado digital (.pfx)

Arquivo que assina as notas fiscais eletronicamente. É opcional, mas recomendado para produção.

Essas credenciais são armazenadas de forma criptografada e usadas automaticamente quando você solicita uma emissão de nota.

07

Como tudo se conecta

Em um fluxo típico de uso da plataforma:

  1. ☐ Você cadastra um profissional (a API cria automaticamente a entidade fiscal dele)
  2. ☐ Você armazena as credenciais (pass-gov, pass-invoices, certificado)
  3. ☐ Você executa o setup de emissão para preparar a entidade fiscal para emitir notas
  4. ☐ Para cada serviço prestado, você cria uma nota fiscal (ou várias, se for em lote)
  5. ☐ Para cada cliente, você cria um contrato que pode gerar notas automaticamente
  6. ☐ Para MEIs, você pode executar o Diagnóstico a qualquer momento para ver a saúde fiscal