emissaoja · NFS-e

Diz se o emissaoja está no ar e como está o motor fiscal. Sem chave.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Confere formato e dígitos verificadores de um CNPJ, sem consultar nada. Sem chave.

{
  "type": "object",
  "properties": {
    "cnpj": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "description": "CNPJ com ou sem pontuação"
    }
  },
  "required": [
    "cnpj"
  ],
  "additionalProperties": false
}

Dados cadastrais de um CNPJ na Receita Federal (razão social, situação, CNAEs, endereço, Simples/MEI, sócios com CPF mascarado). Não cria tomador; para emitir para esse CNPJ use criar_tomador.

{
  "type": "object",
  "properties": {
    "cnpj": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "description": "CNPJ com ou sem pontuação"
    }
  },
  "required": [
    "cnpj"
  ],
  "additionalProperties": false
}

A empresa da conta: CNPJ, nome, estado da credencial do Emissor Nacional (ausente, verificando, ativa, congelada), estado do onboarding (configurando, perguntas, pronto…), importação e avisos. Comece por aqui: se a credencial está ausente, a pessoa precisa conectar a empresa (configurar_credencial); se há perguntas, responda-as com responder_perguntas_fiscais.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Conecta a empresa da conta ao Emissor Nacional com o CNPJ e a senha do portal (não é a conta gov.br). A senha é conferida no portal, nunca guardada nem devolvida. Depois o emissaoja lê o cadastro fiscal e traz as notas dos últimos 90 dias. Só use quando a pessoa pedir e informar a senha ela mesma; são no máximo 3 tentativas erradas por dia (regra do portal, para não bloquear a conta da empresa). Responde na hora com a tentativa; acompanhe com situacao_credencial até proximo_passo sair de "aguardar".

{
  "type": "object",
  "properties": {
    "cnpj": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "description": "CNPJ da empresa"
    },
    "senha": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Senha do Emissor Nacional (nfse.gov.br), informada pela pessoa"
    },
    "ciente_ultima_tentativa": {
      "type": "boolean",
      "default": false,
      "description": "true quando a pessoa confirma que é a última tentativa do dia (situacao_credencial avisa)"
    }
  },
  "required": [
    "cnpj",
    "senha"
  ],
  "additionalProperties": false
}

Estado da credencial e da última tentativa de conexão: estado (verificando, aceita, senha_recusada, portal_indisponivel, bloqueada…) e proximo_passo (aguardar, configurando, pronto, corrigir_senha, tentar_mais_tarde, redefinir_no_portal, suporte). Consulte a cada poucos segundos enquanto for "aguardar".

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Estágios do onboarding, perguntas que o cadastro fiscal não responde sozinho (alíquota do Simples, regime de apuração) e bloqueios. Responda com responder_perguntas_fiscais.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Grava a alíquota do Simples Nacional (percentual da última apuração, 0 < x ≤ 33) e/ou o regime de apuração (1 = competência, 2 = caixa, 3 = outro). Só com valores que a pessoa informou; nunca invente.

{
  "type": "object",
  "properties": {
    "aliquota_simples": {
      "type": "number",
      "description": "Percentual, ex.: 6 ou 4.5"
    },
    "reg_ap_trib_sn": {
      "type": "integer",
      "enum": [
        1,
        2,
        3
      ]
    }
  },
  "additionalProperties": false
}

Lista os tomadores (clientes) da empresa, com busca por nome ou documento. Cada um tem tipo (pj/pf), id, nome e documento; o par tipo + id é o que emitir_nota usa.

{
  "type": "object",
  "properties": {
    "busca": {
      "type": "string",
      "maxLength": 100,
      "description": "Parte do nome ou do documento"
    },
    "pagina": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "default": 1
    }
  },
  "additionalProperties": false
}

Cadastra um cliente pelo CNPJ (nome e endereço vêm da Receita) ou pelo CPF com o nome completo. Se já existir, devolve o existente (ja_existia). Devolve tipo + id para emitir_nota.

{
  "type": "object",
  "properties": {
    "documento": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "description": "CNPJ ou CPF, com ou sem pontuação"
    },
    "nome": {
      "type": "string",
      "maxLength": 150,
      "description": "Nome completo (obrigatório para CPF)"
    }
  },
  "required": [
    "documento"
  ],
  "additionalProperties": false
}

Serviços cadastrados da empresa (descrição, código nacional de tributação, ISS, principal). emitir_nota usa o principal quando servico_id não é informado.

{
  "type": "object",
  "properties": {
    "ativos": {
      "type": "string",
      "enum": [
        "1",
        "0",
        "todos"
      ],
      "default": "1"
    }
  },
  "additionalProperties": false
}

Emite uma nota fiscal de serviço no Emissor Nacional para um tomador já cadastrado (use listar_tomadores ou criar_tomador antes). Faz a prévia e, sem bloqueio, pede a emissão: responde com o pedido (acompanhe com acompanhar_pedido até autorizada, recusada ou incerta). Com bloqueio, devolve o que falta (bloqueios com code, mensagem e acao) em vez de emitir. Passe sempre uma referencia única por nota que a pessoa quer emitir (ex.: "pedido-123"): repetir a mesma referencia devolve o mesmo pedido e nunca emite duas vezes. Confirme com a pessoa tomador, valor e descrição antes de chamar; a nota tem efeito fiscal real.

{
  "type": "object",
  "properties": {
    "tomador_tipo": {
      "type": "string",
      "enum": [
        "pj",
        "pf"
      ],
      "description": "pj (CNPJ) ou pf (CPF)"
    },
    "tomador_id": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "UUID"
    },
    "valor": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Valor do serviço em reais, até 2 casas"
    },
    "descricao": {
      "type": "string",
      "maxLength": 2000,
      "description": "Discriminação do serviço na nota (omitida: a do serviço)"
    },
    "servico_id": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "UUID do serviço (omitido: o principal)"
    },
    "competencia": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "AAAA-MM-DD (omitida: hoje)"
    },
    "referencia": {
      "type": "string",
      "minLength": 8,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$",
      "description": "Identificador único desta nota no seu lado (Idempotency-Key)"
    },
    "permitir_repetida_de": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "Quando a resposta anterior foi possivel_duplicada e a pessoa confirmou que é outra nota: o pedido_id informado"
    },
    "confirmo_repeticao": {
      "type": "boolean",
      "default": false,
      "description": "Quando a resposta anterior foi emissao_repetida_recente e a pessoa confirmou"
    }
  },
  "required": [
    "tomador_tipo",
    "tomador_id",
    "valor"
  ],
  "additionalProperties": false
}

Estado de um pedido de emissão: na_fila, emitindo, confirmando, autorizada (com numero e chave_acesso), recusada (com motivo) ou incerta. Consulte de novo depois de proxima_consulta_ms enquanto não for terminal.

{
  "type": "object",
  "properties": {
    "pedido_id": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "UUID"
    }
  },
  "required": [
    "pedido_id"
  ],
  "additionalProperties": false
}

Notas emitidas (locais e importadas do portal) com número, situação, data, tomador, valor e o par origem + id que cancelar_nota usa. Filtros por período (mes_atual, mes_anterior, ano_atual, 12_meses), situação (todas, emitidas, canceladas) e busca.

{
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "enum": [
        "mes_atual",
        "mes_anterior",
        "ano_atual",
        "12_meses"
      ],
      "default": "12_meses"
    },
    "busca": {
      "type": "string",
      "maxLength": 100,
      "description": "Número da nota ou nome/documento do tomador"
    },
    "situacao": {
      "type": "string",
      "enum": [
        "todas",
        "emitidas",
        "canceladas"
      ],
      "default": "todas"
    },
    "limite": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}

Cancela uma nota emitida, dentro do prazo do Emissor Nacional. Irreversível: confirme com a pessoa a nota (número, tomador, valor) e o motivo antes. Responde com a operação; acompanhe com acompanhar_operacao (processando → concluida ou falhou).

{
  "type": "object",
  "properties": {
    "origem": {
      "type": "string",
      "enum": [
        "local",
        "importada"
      ]
    },
    "nota_id": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "UUID"
    },
    "motivo": {
      "type": "string",
      "enum": [
        "1",
        "2"
      ],
      "description": "1 = erro na emissão, 2 = serviço não prestado"
    },
    "justificativa": {
      "type": "string",
      "minLength": 15,
      "maxLength": 255
    }
  },
  "required": [
    "origem",
    "nota_id",
    "motivo"
  ],
  "additionalProperties": false
}

Estado de uma operação (cancelamento): processando, concluida ou falhou (com o erro).

{
  "type": "object",
  "properties": {
    "operacao_id": {
      "type": "string",
      "minLength": 10,
      "maxLength": 40
    }
  },
  "required": [
    "operacao_id"
  ],
  "additionalProperties": false
}