# SelfNotas API — guia de integração para agentes de código

Este arquivo é para agentes como Claude Code, Codex e Cursor. Ele descreve como integrar a API SelfNotas (emissão de NFS-e e NFC-e no Brasil) em outro sistema.

Para usar num projeto: salve este arquivo como `AGENTS.md` (Codex), `CLAUDE.md` (Claude Code) ou referencie o link no prompt.

- Documentação completa, com exemplos de resposta: https://documenter.getpostman.com/view/1137906/2sBYPv2Xqd
- Base URL: `https://api.selfnotas.com.br`
- Formato: JSON (`Content-Type: application/json`)
- Servidor MCP: [`selfnotas-mcp`](https://www.npmjs.com/package/selfnotas-mcp) (`npx -y selfnotas-mcp`), para consultar notas e municípios direto na conversa. Este guia é para quando você vai escrever código que chama a API.

## Antes de escrever código: regras para o agente

1. **Não existe ambiente de testes.** Toda chamada bem-sucedida a `POST /v1/nfse/emitir` gera uma nota fiscal válida, com efeito fiscal. Cancelar também é definitivo.
2. **Nunca chame `/v1/nfse/emitir` nem `/v1/nfse/cancelar/:id` em testes automatizados, scripts de exemplo ou para "ver se funciona".** Use mocks ou um servidor falso. Peça confirmação explícita ao usuário antes de qualquer chamada real.
3. Para conferir se credenciais e configuração estão certas sem emitir nada, use `GET /v1/empresas`, `GET /v1/nfse/series` ou `GET /v1/nfse/municipio/:ibge/requisitos`.
4. Leia token e empresa de variáveis de ambiente (`SELFNOTAS_TOKEN`, `SELFNOTAS_COMPANY_ID`, opcional `SELFNOTAS_BASE_URL`). Nunca grave em código, log ou teste.
5. Sempre confira o campo `success` da resposta. Erros de validação e de negócio voltam com HTTP `200`.
6. NFC-e está em **beta**: o contrato pode mudar. Para produção, integre NFS-e.

## Autenticação

Todas as rotas, exceto as consultas públicas, exigem os dois headers:

```
Authorization: Bearer <SELFNOTAS_TOKEN>
x-company-id: <SELFNOTAS_COMPANY_ID>
```

O token precisa ter acesso à empresa informada. As credenciais são fornecidas pela SelfNotas. Sem os headers, ou com credenciais inválidas, a resposta é HTTP `401` com corpo em texto (`Unauthorized`), não JSON.

Rotas públicas (sem headers): `GET /v1/nfse/consultar/:id`, `GET /v1/nfse/consultar/pdf/:id` e `GET /v1/nfse/consultar/xml/:id`.

## Formato das respostas

| Situação | HTTP | Corpo |
|----------|------|-------|
| Sucesso | 200 | `{ "success": true, "data": { ... } }` |
| Erro de validação ou de negócio | 200 | `{ "success": false, "message": "...", "detalhes": ... }` |
| Credenciais ausentes ou inválidas | 401 | texto `Unauthorized` |
| Limite de consultas (60/min por IP nas rotas `/consultar`) | 429 | `{ "success": false, "error": "Muitas requisições. Tente novamente em instantes.", "code": 429 }` + header `Retry-After` (segundos) |
| Erro interno | 500 | `{ "success": false, "error": "Internal server error", "code": 500 }` |

## Fluxo de integração

1. Cadastrar a empresa e o certificado A1: `POST /v1/empresas` (normalmente uma vez, feito pelo usuário).
2. Se a empresa vier de outro emissor, alinhar a numeração: `POST /v1/nfse/series`.
3. Opcional: ver os campos exigidos pelo município: `GET /v1/nfse/municipio/:ibge/requisitos`.
4. Emitir: `POST /v1/nfse/emitir`.
5. Guardar `id`, `numero`, `serie`, `chave`, `pdf_nfse` e `xml_nfse` de cada nota.
6. Consultar, baixar PDF/XML ou cancelar pelo `id`.

## Emitir NFS-e

`POST /v1/nfse/emitir`

A emissão é síncrona: a nota volta aprovada, ou com o motivo da rejeição, na própria resposta.

```json
{
  "rps": [
    {
      "id": "8f6c2b1e-4d3a-4c9b-a1e2-3f4d5c6b7a89",
      "tomador": {
        "cpf_cnpj": "98765432000110",
        "razao_social": "Cliente Exemplo Comercio Ltda",
        "email": "contas@clienteexemplo.com.br",
        "endereco": "Rua Exemplo",
        "numero": "456",
        "bairro": "Itaim Bibi",
        "cidade": "São Paulo",
        "uf": "SP",
        "codigo_municipio": "3550308",
        "cep": "04538133"
      },
      "servico": {
        "valor_servicos": 180.00,
        "aliquota": 5,
        "iss_retido": false,
        "item_lista_servico": "11.01",
        "codigo_servico": "110101",
        "codigo_nbs": "106043000",
        "discriminacao": "Mensalidade de estacionamento - novembro/2026",
        "codigo_municipio": "3550308",
        "data_competencia": "2026-11-20"
      }
    }
  ]
}
```

### `rps[]` (obrigatório, array não vazio)

Cada item vira uma nota. Itens são processados em sequência.

| Campo | Obrigatório | Descrição |
|-------|-------------|-----------|
| `id` | sim | UUID gerado pelo seu sistema. **É a chave de idempotência**: reenviar o mesmo `id` devolve a nota já emitida em vez de criar outra. Gere um por venda/serviço e salve antes de chamar a API. |
| `tomador` | não | Cliente. Pode ser omitido para consumidor não identificado. |
| `servico` | sim | Serviço prestado. |

### `tomador`

Se `cpf_cnpj` for informado, também é obrigatório `razao_social` (ou `nome` / `nome_completo`).

Campos: `cpf_cnpj` (só dígitos), `razao_social`, `nome_completo`, `email`, `endereco`, `numero`, `complemento`, `bairro`, `cidade`, `uf`, `codigo_municipio` (IBGE, 7 dígitos), `cep` (só dígitos).

### `servico`

| Campo | Obrigatório | Descrição |
|-------|-------------|-----------|
| `valor_servicos` | sim | Valor bruto, número maior que zero. |
| `discriminacao` | sim | Descrição do serviço. |
| `item_lista_servico` ou `codigo_servico` | um dos dois | Item da LC 116 (ex.: `"11.01"`) ou código de tributação nacional (ex.: `"110101"`). |
| `aliquota` | recomendado | Alíquota do ISS em %. Exigida no Padrão Nacional. |
| `iss_retido` | não | `true` se o ISS é retido pelo tomador. |
| `valor_deducoes` | não | Deduções da base de cálculo. |
| `codigo_municipio` | não | IBGE do local da prestação. Padrão: município da empresa. |
| `codigo_nbs` | não | Código NBS. |
| `data_competencia` | não | `YYYY-MM-DD`. Padrão: data da emissão. |
| `valor_pis`, `valor_cofins`, `valor_inss`, `valor_ir`, `valor_csll` | não | Retenções federais. |
| `pTotTribFed`, `pTotTribEst`, `pTotTribMun` | não | Percentuais aproximados de tributos (Lei 12.741/2012). |

### Resposta

```json
{
  "success": true,
  "message": "1 nota(s) emitida(s) com sucesso",
  "data": {
    "notas": [
      {
        "id": "019a8f2e-6c1d-7b3a-9f10-2d4e5a6b7c8d",
        "numero": 412,
        "numero_dps": 412,
        "serie": "1",
        "data_emissao": "2026-11-20T14:32:10-03:00",
        "chave": "35503082212345678000195000000000041226110000000001",
        "status": "aprovado",
        "rpsId": "8f6c2b1e-4d3a-4c9b-a1e2-3f4d5c6b7a89",
        "pdf_nfse": "https://api.selfnotas.com.br/v1/nfse/consultar/pdf/019a8f2e-6c1d-7b3a-9f10-2d4e5a6b7c8d",
        "xml_nfse": "https://api.selfnotas.com.br/v1/nfse/consultar/xml/019a8f2e-6c1d-7b3a-9f10-2d4e5a6b7c8d",
        "alertas": []
      }
    ],
    "erros": [],
    "total": 1,
    "ids": ["8f6c2b1e-4d3a-4c9b-a1e2-3f4d5c6b7a89"],
    "sucesso": 1,
    "falhas": 0
  }
}
```

**Lote com falha parcial:** se algum RPS falhar, `success` vem `false`, mas `data.notas` ainda traz as notas que foram emitidas. Processe os dois arrays. Cada item de `data.erros` tem `rpsId`, `index` e `erro` (texto para mostrar ao usuário). Reenvie só os RPS que falharam, com o mesmo `id`.

**Dados inválidos** (nada é emitido):

```json
{
  "success": false,
  "message": "Dados de emissão inválidos",
  "detalhes": ["RPS[0]: Valor do serviço deve ser maior que zero"]
}
```

Outros erros comuns em `erro`/`message`: certificado vencido (a mensagem traz a data), município que não aderiu ao emissor nacional, série inválida e rejeições da SEFIN com o código original.

### Repetição segura

- Timeout ou erro de rede: reenvie com **o mesmo** `rps[].id`. Não gere um id novo, ou a nota pode sair em dobro.
- HTTP 500: o mesmo vale; reenvie com o mesmo id depois de alguns segundos.
- `success: false` com mensagem de validação: corrija os dados antes de reenviar.

## Outras rotas

| Método | Rota | Auth | Descrição |
|--------|------|------|-----------|
| GET | `/v1/nfse/consultar/:id` | pública | Dados da nota pelo `id` da SelfNotas. |
| GET | `/v1/nfse/consultar/pdf/:id` | pública | DANFSe em PDF (`application/pdf`). Pode ser enviado ao cliente. |
| GET | `/v1/nfse/consultar/xml/:id` | pública | XML assinado (`application/xml`). |
| POST | `/v1/nfse/cancelar/:id` | sim | Cancela. Body: `{ "motivo": "..." }` com pelo menos 10 caracteres. **Irreversível.** |
| GET | `/v1/nfse/municipio/:ibge/requisitos?padraoNacional=true` | sim | Campos obrigatórios e valores sugeridos para o município. Não emite nada. |
| POST | `/v1/nfse/series` | sim | Define o último número emitido: `{ "serie_rps": "1", "numero": 411 }`. |
| GET | `/v1/nfse/series` | sim | Série e último número atuais. |
| GET | `/v1/nfse/series/sincronizar` | sim | Calcula o próximo número pela última nota aprovada. Não altera nada. |
| GET | `/v1/empresas` | sim | Dados cadastrais (sem certificado nem senha). |
| POST | `/v1/empresas` | sim | Cadastra ou atualiza a empresa. Envie só o que mudar. Certificado A1 (`.pfx`) em base64 no campo `certificado` e senha em `certificado_senha`. |
| POST | `/v1/nfce/emitir` | sim | NFC-e (beta). |
| POST / GET | `/v1/nfce/serie` | sim | Série e número da NFC-e. |
| GET | `/health` | pública | HTTP 200 sem corpo. |

O `id` usado nas rotas de consulta e cancelamento é o `id` devolvido em `data.notas[]` (UUID v7 da SelfNotas), não o `rps[].id` do seu sistema.

## Checklist de implementação

- [ ] Cliente HTTP com base URL, os dois headers e timeout de pelo menos 60 s (a emissão espera a resposta da SEFIN).
- [ ] Tabela/coluna para guardar `rps_id` antes da chamada e `nota_id`, `numero`, `serie`, `chave`, `pdf_nfse`, `xml_nfse`, `status` depois.
- [ ] Repetição com o mesmo `rps_id` em timeout e 5xx.
- [ ] Tratamento de `success: false`, incluindo lote parcial (`data.notas` + `data.erros`).
- [ ] Mensagem de erro legível para o usuário a partir de `message` / `erros[].erro`.
- [ ] Testes com mock do endpoint de emissão. Nenhum teste chama a API real.
- [ ] Credenciais só em variáveis de ambiente.

## Exemplo mínimo (TypeScript)

```ts
const BASE = process.env.SELFNOTAS_BASE_URL ?? "https://api.selfnotas.com.br";

async function emitirNfse(rps: { id: string; tomador?: object; servico: object }) {
  const res = await fetch(`${BASE}/v1/nfse/emitir`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SELFNOTAS_TOKEN}`,
      "x-company-id": process.env.SELFNOTAS_COMPANY_ID!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ rps: [rps] }),
    signal: AbortSignal.timeout(90_000),
  });

  if (res.status === 401) throw new Error("Credenciais SelfNotas inválidas");
  const body = await res.json();

  const nota = body.data?.notas?.[0];
  if (nota) return nota; // id, numero, serie, chave, pdf_nfse, xml_nfse

  const erro = body.data?.erros?.[0]?.erro ?? body.detalhes?.join("; ") ?? body.message;
  throw new Error(`NFS-e não emitida: ${erro}`);
}
```
