Documentação

API de emitentes

Basehttps://api.apisimples.com/v1

Visão geral

Cadastre e atualize emitentes pela API com a chave geral da conta. Dá para habilitar documentos, enviar o certificado A1 e configurar o download de NF-e/NFC-e de saída com os XMLs semente por série.

GET/emitentesLista os emitentes da conta.
POST/emitentesCadastra um emitente.
GET/emitentes/{id}Consulta um emitente.
POST/emitentes/{id}Atualiza um emitente.
POST/emitentes/{id}/excluirExclui um emitente.

Com o download de saída ativo, as notas emitidas (saída) são capturadas e o XML fica disponível nestas rotas — com a chave do emitente:

GET/saida/notasLista as notas de saída capturadas.
GET/saida/notas/{id}Consulta uma nota de saída.
GET/saida/notas/{id}/xmlBaixa o XML da nota de saída (base64).
POST/saida/sincronizarDispara a captura das notas mais recentes.

A cobertura por estado do download de saída está em /cobertura. Detalhes em Listar notas e Baixar XML.

Testar

Use a chave geral da conta (aps_…), não a chave do emitente.

GEThttps://api.apisimples.com/v1/emitentes

Autenticação

Cadastro de emitentes: chave geral da conta (aps_…), no painel em Empresa.

Authorization: Bearer aps_sua_chave_da_conta
Content-Type: application/json
Accept: application/json

Notas e XML de saída (/saida/…): chave do emitente (apse_…), a mesma da emissão.

Authorization: Bearer apse_sua_chave_do_emitente
Accept: application/json

Listar

GEThttps://api.apisimples.com/v1/emitentes

Criar

POSThttps://api.apisimples.com/v1/emitentes

HTTP 201 devolve o emitente com a chave apse_… para as demais APIs.

{
    "nome": "Loja Centro",
    "razao": "Loja Centro LTDA",
    "cnpj": "12345678000199",
    "crt": "1",
    "telefone": "11999990000",
    "email": "fiscal@loja.com.br",
    "rua": "Rua das Flores",
    "numero": "100",
    "bairro": "Centro",
    "cmun": "3550308",
    "municipio": "São Paulo",
    "uf": "SP",
    "cep": "01001000",
    "documentos": {
        "nfe": true,
        "nfce": true
    },
    "nfe_ambiente": "2",
    "csc": "seu-csc",
    "cscid": "1",
    "certificado": "base64-do-pfx",
    "certificado_senha": "senha-do-pfx",
    "download_saida": {
        "nfe": true,
        "nfce": true
    },
    "xmls_saida": [
        {
            "modelo": "55",
            "xml": "base64-ou-conteudo-do-xml-nfe"
        },
        {
            "modelo": "65",
            "xml": "base64-ou-conteudo-do-xml-nfce"
        }
    ]
}

Consultar

GEThttps://api.apisimples.com/v1/emitentes/{id}

Inclui certificado (metadados), documentos, download de saída e a lista de XMLs semente.

Atualizar

POSThttps://api.apisimples.com/v1/emitentes/{id}

Atualização parcial: campos omitidos mantêm o valor atual. Se enviar documentos ou download_saida, o objeto substitui o conjunto atual. Novos itens em xmls_saida entram por série; use remover_xmls_saida com os ids para apagar.

Excluir

POSThttps://api.apisimples.com/v1/emitentes/{id}/excluir

Payload

Campos do payload

CampoDescrição
nome
stringobrigatório

Nome fantasia, 2 a 60 caracteres.

razao
stringobrigatório

Razão social, 2 a 60 caracteres.

apelido
stringopcional

Apelido interno, até 60 caracteres.

cnpj
stringcondicional

CNPJ com 14 dígitos. Obrigatório se não houver CPF.

cpf
stringcondicional

CPF com 11 dígitos.

crt
stringobrigatório

Regime tributário: 1, 2, 3 ou 4.

ie / im / suframa / cnae
stringopcional

Inscrições e CNAE quando aplicável.

telefone
stringobrigatório

Somente dígitos.

email
stringopcional

E-mail de contato.

rua / numero / complemento / bairro / cmun / municipio / uf / cep
stringsim*

Endereço. Complemento opcional.

documentos
objectopcional

Flags booleanas: nfe, nfce, nfse, pix, boleto, etc.

nfe_ambiente
stringcondicional

1 produção ou 2 homologação, se NF-e/NFC-e estiver ligada.

csc / cscid
stringcondicional

Obrigatórios se NFC-e estiver ligada.

nfse_sistema / nfse_ambiente
stringcondicional

Sistema e ambiente da NFS-e, se habilitada.

webhook
stringopcional

URL de webhook do emitente.

logo
stringopcional

Imagem JPG/PNG em base64, até 1 MB.

remover_logo
boolopcional

true remove a logo na atualização.

certificado
stringcondicional

PFX/P12 em base64. Exigido para NF-e/NFC-e e download de saída.

certificado_senha
stringcondicional

Senha do PFX.

remover_certificado
boolopcional

true remove o certificado na atualização.

download_saida
objectopcional

nfe e/ou nfce em true para baixar notas emitidas.

xmls_saida
arrayopcional

Lista de XMLs semente. Veja a seção abaixo.

remover_xmls_saida
arrayopcional

Ids dos XMLs a remover na atualização.

Download de saída

Com download_saida.nfe ou download_saida.nfce em true, o emitente passa a capturar as notas emitidas (saída). Exige certificado A1 e os XMLs semente por série. A disponibilidade por UF está em Cobertura.

As notas capturadas ficam disponíveis nas rotas /saida/notas, autenticadas com a chave do emitente (apse_…).

{
    "download_saida": {
        "nfe": true,
        "nfce": true
    }
}

XMLs por série

Um XML por série dos últimos 60 dias, usado para cadastrar a série na captura. Aceita o XML em texto ou em base64. Validamos o modelo (55 ou 65) e o CNPJ do emitente no XML.

Na NFC-e, SP, AM e GO não exigem XML semente (sistemas próprios).

Campos do payload

CampoDescrição
xmls_saida[].modelo
stringobrigatório

55 para NF-e ou 65 para NFC-e.

xmls_saida[].xml
stringobrigatório

Conteúdo do XML ou base64.

{
    "xmls_saida": [
        {
            "modelo": "55",
            "xml": "<?xml version=\"1.0\"?><nfeProc>...</nfeProc>"
        },
        {
            "modelo": "65",
            "xml": "conteudo-ou-base64"
        }
    ]
}

Listar notas de saída

Com o download de saída habilitado no emitente, as notas capturadas entram nesta lista. Use a chave do emitente (apse_…).

GEThttps://api.apisimples.com/v1/saida/notas

Campos do payload

CampoDescrição
modelo
stringopcional

55 (NF-e) ou 65 (NFC-e).

inicio / fim
stringopcional

Filtro por emissão — AAAA-MM-DD.

page
intopcional

Página, padrão 1.

limite
intopcional

Itens por página, padrão 20, máx. 50.

curl "https://api.apisimples.com/v1/saida/notas?modelo=55&inicio=2026-11-01&fim=2026-11-30&page=1&limite=20" \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Accept: application/json"

Consulta de uma nota:

GEThttps://api.apisimples.com/v1/saida/notas/{id}

Para forçar a captura das notas mais recentes deste emitente:

POSThttps://api.apisimples.com/v1/saida/sincronizar
curl -X POST "https://api.apisimples.com/v1/saida/sincronizar" \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Accept: application/json"

Baixar XML de saída

Devolve o XML autorizado da nota de saída em base64. O id é o da lista /saida/notas. Só funciona com has_xml: true.

GEThttps://api.apisimples.com/v1/saida/notas/{id}/xml
curl "https://api.apisimples.com/v1/saida/notas/{id}/xml" \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Accept: application/json"

HTTP 404 com xml_indisponivel se o XML ainda não tiver sido capturado. Chame POST /saida/sincronizar e tente de novo.

Erros

HTTPCódigoQuando
401autenticacao_ausenteO header Authorization não veio.
401autenticacao_invalidaChave inválida (aps_… no cadastro ou apse_… em /saida).
403conta_inativaA conta está inativa.
403download_saida_desabilitadoO emitente não tem download de saída ligado.
404emitente_nao_encontradoO id não existe nesta conta.
404nota_nao_encontradaA nota de saída não é deste emitente.
404xml_indisponivelO XML da nota ainda não foi capturado.
422validacaoCampos inválidos; veja a lista erros.