NotaMCP

Prepara uma NFS-e e devolve a PRÉVIA + confirmacao_token. NÃO emite nada. Mostre a prévia ao usuário e chame confirmar_emissao só depois do OK explícito dele. Tomador: informe tomador_id (salvo) OU tomador_doc + tomador_razao.

{
  "type": "object",
  "properties": {
    "tomador_id": {
      "type": "string",
      "description": "Id de um tomador salvo (listar_tomadores)."
    },
    "configuracao_id": {
      "type": "string",
      "description": "Id de uma combinação devolvida por listar_configuracoes."
    },
    "tomador_doc": {
      "type": "string",
      "description": "CNPJ (14 dígitos) ou CPF (11) do tomador."
    },
    "tomador_razao": {
      "type": "string",
      "description": "Razão social ou nome do tomador."
    },
    "tomador_tipo": {
      "type": "string",
      "enum": [
        "",
        "exterior"
      ],
      "description": "Use \"exterior\" para tomador estrangeiro."
    },
    "tomador_pais": {
      "type": "string",
      "description": "País ISO2 do tomador estrangeiro (ex.: \"SG\")."
    },
    "valor": {
      "type": "string",
      "description": "Valor do serviço em reais, ex.: \"1250,00\"."
    },
    "competencia": {
      "type": "string",
      "description": "Mês de referência YYYY-MM. Vazio = mês atual."
    },
    "discriminacao": {
      "type": "string",
      "description": "Descrição do serviço, como sai impressa na nota."
    },
    "configuracao": {
      "type": "object",
      "description": "Configuração fiscal só desta nota. Campos omitidos herdam o cadastro/configuracao_id. Nunca invente códigos fiscais.",
      "properties": {
        "codigo_servico": {
          "type": "string",
          "description": "Item da LC 116, ex.: 17.06 ou 17.06.01. Não é CNAE."
        },
        "codigo_cnae": {
          "type": "string",
          "description": "CNAE do serviço, com 7 dígitos."
        },
        "codigo_nbs": {
          "type": "string",
          "description": "NBS, se aplicável."
        },
        "ctrib_mun": {
          "type": "string",
          "description": "Código de tributação definido pela prefeitura; vazio quando não houver."
        },
        "aliquota_simples": {
          "type": "string",
          "description": "Percentual efetivo do Simples."
        },
        "calcular_iss": {
          "type": "boolean"
        },
        "aliquota_iss": {
          "type": "string",
          "description": "Percentual do ISS quando destacado."
        },
        "trib_federal": {
          "type": "string",
          "description": "Tributos federais aproximados (%)."
        },
        "trib_municipal": {
          "type": "string",
          "description": "Tributos municipais aproximados (%)."
        }
      }
    }
  },
  "required": [
    "valor",
    "discriminacao"
  ]
}

Últimas combinações realmente usadas de serviço, CNAE, NBS e tributação. Use configuracao_id em emitir_nota. Se houver ambiguidade, pergunte ao usuário — não escolha nem invente código fiscal.

{
  "type": "object",
  "properties": {
    "limite": {
      "type": "integer",
      "description": "Máximo de combinações (1–20, padrão 8)."
    }
  }
}

Emite DE VERDADE a nota da prévia. Chame apenas depois que o usuário aprovou a prévia nesta conversa. Idempotente: o mesmo token nunca emite duas vezes. Autorizada, devolve danfse_url (PDF) e xml_url — links para o usuário abrir, que você não consegue baixar.

{
  "type": "object",
  "properties": {
    "confirmacao_token": {
      "type": "string",
      "description": "Token devolvido por emitir_nota."
    }
  },
  "required": [
    "confirmacao_token"
  ]
}

Situação de uma nota desta conta (status, número, chave de acesso, erro).

{
  "type": "object",
  "properties": {
    "nota_id": {
      "type": "integer",
      "description": "Id da nota (veio da emissão ou de listar_notas)."
    }
  },
  "required": [
    "nota_id"
  ]
}

Histórico de notas da conta, com filtros opcionais.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "emitida",
        "rejeitada",
        "pendente",
        "cancelada",
        "erro"
      ],
      "description": "Filtro por status."
    },
    "competencia": {
      "type": "string",
      "description": "Filtro YYYY-MM."
    },
    "limite": {
      "type": "integer",
      "description": "Máx. de notas (1–100, padrão 20)."
    }
  }
}

Cancela uma NFS-e autorizada na SEFIN. Exige confirmar=true — peça confirmação explícita ao usuário antes. O crédito da emissão NÃO volta (a nota existiu); o cancelamento é grátis.

{
  "type": "object",
  "properties": {
    "nota_id": {
      "type": "integer"
    },
    "motivo": {
      "type": "string",
      "description": "Motivo em texto (vai para a SEFIN)."
    },
    "codigo_motivo": {
      "type": "integer",
      "enum": [
        1,
        2,
        4
      ],
      "description": "1=erro na emissão · 2=serviço não prestado · 4=duplicidade."
    },
    "confirmar": {
      "type": "boolean",
      "description": "Precisa ser true — confirmação do usuário nesta conversa."
    }
  },
  "required": [
    "nota_id",
    "motivo",
    "confirmar"
  ]
}

Tomadores salvos desta conta (use o id em emitir_nota). Passe `busca` com o NOME que o usuário falou para achar o tomador sem precisar do CNPJ — ignora acento, caixa e pontuação. Se voltar mais de um, pergunte qual antes de emitir.

{
  "type": "object",
  "properties": {
    "busca": {
      "type": "string",
      "description": "Nome (ou parte) da empresa, ou o documento. Ex.: \"acai\" acha \"Açaí & Cia Ltda\"."
    }
  }
}

Salva/atualiza um tomador frequente (ex.: "salva a Shopee como tomador").

{
  "type": "object",
  "properties": {
    "doc": {
      "type": "string",
      "description": "CNPJ ou CPF (só números ou formatado)."
    },
    "razao": {
      "type": "string",
      "description": "Razão social ou nome."
    },
    "tipo": {
      "type": "string",
      "enum": [
        "",
        "exterior"
      ]
    },
    "pais": {
      "type": "string",
      "description": "ISO2, só para exterior."
    }
  },
  "required": [
    "razao"
  ]
}

Quantidade de notas disponíveis, preço por nota, ambiente e teto diário. O nome técnico saldo é mantido por compatibilidade.

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

Gera um link de pagamento (Pix/cartão) para adicionar créditos de notas. Entregue o link ao usuário — o pagamento acontece no navegador dele e as notas entram após a confirmação.

{
  "type": "object",
  "properties": {
    "valor_centavos": {
      "type": "integer",
      "enum": [
        1000,
        2500,
        5000,
        10000
      ],
      "description": "Valor da recarga em centavos: 1000 (R$10), 2500 (R$25), 5000 (R$50) ou 10000 (R$100)."
    }
  },
  "required": [
    "valor_centavos"
  ]
}