--- title: "API Emissão de Notas" description: "API Emissão de Notas - Emita NFS-e direto do seu sistema" lang: en canonical: https://doc.apibrasil.io/apis/creditos/7d62c6f8-0074-40bd-a17e-ba49235b7233 markdown: https://doc.apibrasil.io/apis/creditos/7d62c6f8-0074-40bd-a17e-ba49235b7233.md source: apibrasil-documentation --- # API Emissão de Notas > API Emissão de Notas - Emita NFS-e direto do seu sistema - **Category:** Automação Empresarial - **Billing:** per query, with the Bearer Token only - **Price:** R$0.50 per query - **Limit:** 999,000 per month - **Registration:** requires a CNPJ - **Version:** v2 - **Published by:** APIBrasil - **OpenAPI specification:** https://doc.apibrasil.io/apis/creditos/7d62c6f8-0074-40bd-a17e-ba49235b7233/openapi.json ## How to call **Base address:** `https://gateway.apibrasil.io/api/v2` Authentication: the `Authorization: Bearer ` header. Nothing else. ## Endpoints (7 endpoints) **Contents** 1. `POST /consulta/emissao-notas/credits` 2. `POST /consulta/emissao-notas/credits` 3. `POST /consulta/emissao-notas/credits` 4. `POST /consulta/emissao-notas/credits` 5. `POST /consulta/emissao-notas/credits` 6. `POST /consulta/emissao-notas/credits` 7. `POST /consulta/emissao-notas/credits` ### 1. POST /consulta/emissao-notas/credits **tipo: emitentes-cadastro** · Cadastra a empresa que vai emitir as notas (o emitente), uma vez por CNPJ. Guarde o id devolvido em data.data.id: ele é o emitente_id de todas as outras operações. Em seguida, envie o certificado digital com o tipo certificado-upload. **Obrigatórios:** razao, cnpj (14 dígitos), cnae (7 dígitos), crt (1 Simples Nacional, 2 Simples Nacional com excesso de sublimite, 3 Regime Normal, 4 MEI), telefone (6 a 14 dígitos), rua, numero, bairro, municipio, cmun (código IBGE do município, 7 dígitos), uf, cep (8 dígitos) e documentos com nfse: true. **Opcionais:** nome (fantasia), im (inscrição municipal, exigida por muitas prefeituras), ie, email, complemento, webhook_url (até 200 caracteres; recebe um aviso a cada mudança de status das notas) e, para as prefeituras que pedem acesso ao portal, login_prefeitura, senha_prefeitura, client_id_prefeitura e client_secret_prefeitura. O cnae do cadastro não vai na nota: na NFS-e, o CNAE do serviço é enviado em servico.codigo_cnae. Cada CNPJ só pode ser cadastrado uma vez; para mudar dados, use emitentes-atualiza. Campo ausente ou fora do formato volta HTTP 422, com a lista em data.dados.errors, sem cobrança. - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 - **Price of this operation:** R$19.00 per query **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "emitentes-cadastro", "razao": "EMPRESA EXEMPLO LTDA", "nome": "EMPRESA EXEMPLO", "cnpj": "11222333000181", "cnae": "0000000", "crt": 1, "im": "1234567", "telefone": "11999999999", "email": "financeiro@empresaexemplo.com.br", "rua": "Rua Exemplo", "numero": "100", "bairro": "Centro", "municipio": "São Paulo", "cmun": "3550308", "uf": "SP", "cep": "01001000", "documentos": { "nfse": true }, "webhook_url": "https://seusistema.com.br/webhooks/notas" } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"emitentes-cadastro","razao":"EMPRESA EXEMPLO LTDA","nome":"EMPRESA EXEMPLO","cnpj":"11222333000181","cnae":"0000000","crt":1,"im":"1234567","telefone":"11999999999","email":"financeiro@empresaexemplo.com.br","rua":"Rua Exemplo","numero":"100","bairro":"Centro","municipio":"São Paulo","cmun":"3550308","uf":"SP","cep":"01001000","documentos":{"nfse":true},"webhook_url":"https://seusistema.com.br/webhooks/notas"}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "381,000", "balance_before": "400,000", "tax": "19,000", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 19,00.", "valor_consulta": 19, "api_limit_for": "credit", "homolog": false, "data": { "data": { "id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "user_id": 12345, "razao": "EMPRESA EXEMPLO LTDA", "nome": "EMPRESA EXEMPLO", "cnpj": "11222333000181", "cpf": null, "ie": null, "im": "1234567", "suframa": null, "cnae": "0000000", "crt": 1, "telefone": "11999999999", "email": "[omitido]", "rua": "Rua Exemplo", "numero": "100", "complemento": null, "bairro": "Centro", "municipio": "São Paulo", "cmun": "3550308", "uf": "SP", "cep": "01001000", "login_prefeitura": null, "senha_prefeitura": null, "client_id_prefeitura": null, "client_secret_prefeitura": null, "csc": null, "cscid": null, "documentos": { "nfe": false, "nfce": false, "nfse": true }, "status": "ativo", "provider_emitente_id": "48213", "webhook_url": "https://seusistema.com.br/webhooks/notas", "created_at": "2026-10-13T13:00:00.000000Z", "updated_at": "2026-10-13T13:00:00.000000Z" } } } ``` ### 2. POST /consulta/emissao-notas/credits **tipo: certificado-upload** · Envia o certificado digital A1 (arquivo .pfx ou .p12) do emitente. Sem ele a prefeitura não aceita as notas. Mande, dentro de dados, o emitente_id, a senha e o conteúdo do arquivo em Base64 no campo certificado. Reenvie sempre que o certificado for renovado. O arquivo pode ter até 5 MB. A resposta traz a validade e o titular do certificado (data.data.validade e data.data.proprietario) e o registro em data.certificado. Senha errada ou arquivo corrompido voltam erro (HTTP 502) com o motivo em message, sem cobrança. Senha com acento ou caractere especial costuma falhar: prefira letras e números. - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "certificado-upload", "dados": { "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "senha": "senha-do-certificado", "certificado": "MIIKZAIBAzCCCi4GCSqGSIb3DQEHAaCCCh8EggobMIIKFzCCBg..." } } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"certificado-upload","dados":{"emitente_id":"9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f","senha":"senha-do-certificado","certificado":"MIIKZAIBAzCCCi4GCSqGSIb3DQEHAaCCCh8EggobMIIKFzCCBg..."}}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,500", "balance_before": "400,000", "tax": "0,500", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,50.", "valor_consulta": 0.5, "api_limit_for": "credit", "homolog": false, "data": { "message": "Certificado enviado com sucesso.", "data": { "sucesso": true, "codigo": 200, "mensagem": "Certificado gravado com sucesso!", "validade": "2027-10-08 23:59:59", "proprietario": "11222333000181 - EMPRESA EXEMPLO LTDA:11222333000181" }, "certificado": { "id": "7a2d9e4f-1b3c-4d5e-9f8a-6b7c8d9e0f1a", "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "serial": "3A1F5C7E9B2D4F60", "valid_from": "2026-10-08T10:15:00-03:00", "valid_to": "2027-10-08T23:59:59-03:00", "subject": "C=BR, O=ICP-Brasil, ST=SP, L=Sao Paulo, CN=EMPRESA EXEMPLO LTDA:11222333000181", "provider": "other", "uploaded_at": "2026-10-13T10:20:00-03:00", "active": true } } } ``` ### 3. POST /consulta/emissao-notas/credits **tipo: nfse-envio** · Emite uma NFS-e. O envio não é cobrado: a nota custa R$ 0,50 e só é cobrada quando a prefeitura autoriza (rejeitada não paga). Mande o emitente_id e os dados da nota dentro de dados. A resposta traz o status (normalmente em_processamento) e a chave_nfe, que você usa para consultar e cancelar. O resultado final chega pelo nfse-consulta ou pelo webhook do emitente. **Antes do primeiro envio**, o emitente precisa estar cadastrado (emitentes-cadastro) e com o certificado enviado (certificado-upload). **Obrigatórios em dados:** - status "1" (situação normal), natureza_operacao "1" (tributação no município), data_emissao (ISO 8601 com fuso, como 2026-10-13T10:00:00-03:00) e codigo_aleatorio (8 dígitos aleatórios, novos a cada envio). - tomador: razao_social, cpf ou cnpj, e endereco com logradouro, codigo_municipio (IBGE, 7 dígitos) e uf. - servico: codigo (item da LC 116/2003), codigo_nbs (9 dígitos), discriminacao, valor_servicos, codigo_municipio (IBGE do local da prestação), tributos_municipais.iss_retido (true ou false) e itens com exatamente 1 item, repetindo codigo, codigo_nbs, discriminacao e valor_servicos. **Exigidos por muitas prefeituras** (sem eles a prefeitura rejeita a nota): - regime_tributacao: regime especial de tributação. Empresa do Simples Nacional costuma precisar dele; em vários municípios, 5 = MEI e 6 = ME ou EPP do Simples Nacional. - servico.codigo_nacional (código de tributação nacional, 6 dígitos), servico.codigo_cnae (7 dígitos) e servico.codigo_tributacao_municipio. - servico.tributos_municipais.aliquota_iss (em percentual: 2.5 = 2,5%) e valor_base_calculo_iss (em geral, igual ao valor do serviço). - servico.tributos_nacionais (cst e valor_base_calculo do PIS/COFINS); no Simples Nacional, também regime_apuracao e tributos_totais.percentual_tributos_simples_nacional. Os códigos fiscais e o regime são definidos pelo contador do emitente; os zeros do exemplo são só o formato. **Formato:** cpf, cnpj, códigos, numero e serie vão como texto (entre aspas); valores em reais e percentuais vão como número. numero e serie são opcionais: sem eles, a numeração segue a sequência do emitente. **Cobrança e retorno:** o envio não é cobrado. A nota custa R$ 0,50 e é cobrada quando a prefeitura a autoriza; nota rejeitada ou em falha não é cobrada. Para enviar é preciso ter pelo menos R$ 0,50 de saldo disponível; sem saldo, volta HTTP 422 sem chamar a prefeitura. Quando a prefeitura autoriza na hora, a resposta já traz status autorizado e a nota completa, no formato do nfse-consulta. Erro de formato volta HTTP 422 (lista em data.dados.errors) e campo exigido pelo layout da prefeitura volta HTTP 400 (detalhes em data.dados.errors.nfse_envio); nos dois casos não há cobrança. A rejeição da prefeitura chega no webhook do emitente, com nota.status rejeitado e o motivo em nota.last_error. - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 - **Price of this operation:** R$0.00 per query **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "nfse-envio", "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "dados": { "status": "1", "natureza_operacao": "1", "regime_tributacao": "0", "regime_apuracao": "1", "data_emissao": "2026-10-13T10:00:00-03:00", "data_competencia": "2026-10-13T10:00:00-03:00", "codigo_aleatorio": "48213977", "tomador": { "cnpj": "11444777000161", "razao_social": "CLIENTE EXEMPLO LTDA", "email": "financeiro@clienteexemplo.com.br", "endereco": { "logradouro": "Avenida Exemplo", "numero": "200", "bairro": "Centro", "codigo_municipio": "3550308", "uf": "SP", "cep": "01001000" } }, "servico": { "codigo": "000000", "codigo_nacional": "000000", "codigo_cnae": "0000000", "codigo_tributacao_municipio": "000000000", "codigo_nbs": "000000000", "discriminacao": "Descrição do serviço prestado", "valor_servicos": 1000, "codigo_municipio": "3550308", "tributos_municipais": { "iss_retido": false, "aliquota_iss": 2.5, "valor_base_calculo_iss": 1000 }, "tributos_nacionais": { "cst": "00", "valor_base_calculo": 1000 }, "tributos_totais": { "percentual_tributos_simples_nacional": 6 }, "itens": [ { "codigo": "000000", "codigo_nbs": "000000000", "discriminacao": "Descrição do serviço prestado", "valor_servicos": 1000 } ] } } } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"nfse-envio","emitente_id":"9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f","dados":{"status":"1","natureza_operacao":"1","regime_tributacao":"0","regime_apuracao":"1","data_emissao":"2026-10-13T10:00:00-03:00","data_competencia":"2026-10-13T10:00:00-03:00","codigo_aleatorio":"48213977","tomador":{"cnpj":"11444777000161","razao_social":"CLIENTE EXEMPLO LTDA","email":"financeiro@clienteexemplo.com.br","endereco":{"logradouro":"Avenida Exemplo","numero":"200","bairro":"Centro","codigo_municipio":"3550308","uf":"SP","cep":"01001000"}},"servico":{"codigo":"000000","codigo_nacional":"000000","codigo_cnae":"0000000","codigo_tributacao_municipio":"000000000","codigo_nbs":"000000000","discriminacao":"Descrição do serviço prestado","valor_servicos":1000,"codigo_municipio":"3550308","tributos_municipais":{"iss_retido":false,"aliquota_iss":2.5,"valor_base_calculo_iss":1000},"tributos_nacionais":{"cst":"00","valor_base_calculo":1000},"tributos_totais":{"percentual_tributos_simples_nacional":6},"itens":[{"codigo":"000000","codigo_nbs":"000000000","discriminacao":"Descrição do serviço prestado","valor_servicos":1000}]}}}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "400,000", "balance_before": "400,000", "tax": "0,000", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,00.", "valor_consulta": 0, "api_limit_for": "credit", "homolog": false, "data": { "data": { "id": "4c8e2a1b-7f3d-4b9a-8e6c-2d1f0a9b8c7e", "status": "em_processamento", "chave_nfe": "35261011222333000181900000000000000000000015", "consulta_identificador": "35261011222333000181900000000000000000000015" }, "message": "NFSe enviada e em processamento na prefeitura. Aguarde a resposta para obter o status final." } } ``` ### 4. POST /consulta/emissao-notas/credits **tipo: nfse-consulta** · Mostra uma NFS-e enviada: status, número, série, valores, tomador, item e o link do documento quando a prefeitura fornece. Mande o emitente_id e, em chave, a chave_nfe devolvida pelo nfse-envio. A nota vem em data.data. status pode ser criado, em_processamento, autorizado, rejeitado, falha ou cancelado. Depois da autorização, pdf_url traz o link de consulta do documento, quando a prefeitura disponibiliza; xml_url costuma vir vazio. O motivo de uma rejeição não aparece aqui: ele chega no webhook do emitente, em nota.last_error. Nota que não pertence ao emitente informado volta HTTP 404, sem cobrança. - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "nfse-consulta", "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "chave": "35261011222333000181900000000000000000000015" } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"nfse-consulta","emitente_id":"9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f","chave":"35261011222333000181900000000000000000000015"}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,500", "balance_before": "400,000", "tax": "0,500", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,50.", "valor_consulta": 0.5, "api_limit_for": "credit", "homolog": false, "data": { "data": { "id": "4c8e2a1b-7f3d-4b9a-8e6c-2d1f0a9b8c7e", "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "invoice_id": null, "recharge_id": null, "tipo": "nfse", "ambiente": "producao", "status": "autorizado", "provider_doc_id": null, "serie": "1", "numero": "15", "chave_nfe": "35261011222333000181900000000000000000000015", "xml_url": null, "pdf_url": "https://www.nfse.gov.br/ConsultaPublica/?tpc=1&chave=35503082211222333000181000000000000015102600000000", "totais": { "valor_servicos": 1000, "valor_liquido": 1000, "iss_retido": false, "codigo_municipio": "3550308" }, "destinatario": { "id": "2e6b8d0f-3a5c-4e7a-9b1d-3f5a7c9e1b2d", "documento_id": "4c8e2a1b-7f3d-4b9a-8e6c-2d1f0a9b8c7e", "tipo_pessoa": "pj", "cpf_cnpj": "11444777000161", "ie": null, "im": null, "nome": "CLIENTE EXEMPLO LTDA", "email": "[omitido]", "telefone": null, "logradouro": "Avenida Exemplo", "numero": "200", "complemento": null, "bairro": "Centro", "cep": "01001000", "municipio_id": null, "uf": "SP", "pais": null }, "itens": [ { "id": "5d7f9b1d-2c4e-4a6c-8e0a-4b6d8f0a2c4e", "documento_id": "4c8e2a1b-7f3d-4b9a-8e6c-2d1f0a9b8c7e", "ordem": 1, "codigo": "000000", "descricao": "Descrição do serviço prestado", "ncm": null, "cest": null, "cfop": null, "cnae": "0000000", "item_lista_servico": "000000", "unidade": null, "quantidade": "1.0000", "valor_unitario": "1000.0000", "valor_total": "1000.0000", "desconto": null, "frete": null, "seguro": null, "outras_despesas": null, "dados_adicionais": { "codigo_municipio": "3550308", "codigo_tributacao_municipio": "000000000", "codigo_nbs": "000000000", "iss_retido": false, "valor_aliquota": 2.5 }, "imposto": { "id": "8f0b2d4f-6a8c-4e1a-9c3e-5d7f9b1d3f5a", "item_id": "5d7f9b1d-2c4e-4a6c-8e0a-4b6d8f0a2c4e", "icms": null, "ipi": null, "pis": null, "cofins": null, "issqn": { "iss_retido": false, "codigo_tributacao_municipio": "000000000", "base_calculo": 1000, "aliquota": 2.5, "valor_iss": 25 }, "outros": null } } ], "created_at": "2026-10-13T13:00:00.000000Z", "updated_at": "2026-10-13T13:04:00.000000Z" } } } ``` ### 5. POST /consulta/emissao-notas/credits **tipo: nfse-cancelamento** · Pede o cancelamento de uma NFS-e autorizada. Mande o emitente_id, a chave (chave_nfe), o codigo_cancelamento e o motivo_cancelamento. O pedido é processado em segundo plano: confirme pelo nfse-consulta (status cancelado) ou pelo webhook do emitente. codigo_cancelamento: 1 (erro na emissão), 2 (serviço não prestado) ou 9 (outros). motivo_cancelamento: texto de 15 a 255 caracteres. O prazo e as regras de cancelamento são de cada prefeitura, e algumas não aceitam cancelamento pela API; nesses casos, o cancelamento é feito no portal da prefeitura. Se a prefeitura recusar o pedido, a nota fica com status falha e o motivo chega no webhook, em nota.last_error. Nota não encontrada volta HTTP 404 e campo inválido volta HTTP 422, sem cobrança. - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "nfse-cancelamento", "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "chave": "35261011222333000181900000000000000000000015", "codigo_cancelamento": "1", "motivo_cancelamento": "Nota emitida com valor incorreto" } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"nfse-cancelamento","emitente_id":"9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f","chave":"35261011222333000181900000000000000000000015","codigo_cancelamento":"1","motivo_cancelamento":"Nota emitida com valor incorreto"}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,500", "balance_before": "400,000", "tax": "0,500", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,50.", "valor_consulta": 0.5, "api_limit_for": "credit", "homolog": false, "data": { "message": "Solicitacao de cancelamento enviada com sucesso." } } ``` ### 6. POST /consulta/emissao-notas/credits **tipo: emitentes-atualiza** · Altera o cadastro de um emitente. Mande o emitente_id e só os campos que mudam; os demais ficam como estão. Campos e formatos são os mesmos do emitentes-cadastro. A resposta traz o cadastro completo em data.data. Também aceita status (ativo ou inativo) e serie_padrao (série usada quando a nota é enviada sem serie). Para trocar o endereço que recebe os avisos das notas, mande webhook_url. Se mandar documentos, pelo menos um tipo precisa estar true. - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "emitentes-atualiza", "emitente_id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "telefone": "11988887777", "email": "fiscal@empresaexemplo.com.br", "webhook_url": "https://seusistema.com.br/webhooks/notas" } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"emitentes-atualiza","emitente_id":"9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f","telefone":"11988887777","email":"fiscal@empresaexemplo.com.br","webhook_url":"https://seusistema.com.br/webhooks/notas"}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,500", "balance_before": "400,000", "tax": "0,500", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,50.", "valor_consulta": 0.5, "api_limit_for": "credit", "homolog": false, "data": { "data": { "id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "user_id": 12345, "razao": "EMPRESA EXEMPLO LTDA", "nome": "EMPRESA EXEMPLO", "cnpj": "11222333000181", "cpf": null, "ie": null, "im": "1234567", "suframa": null, "cnae": "0000000", "crt": 1, "telefone": "11988887777", "email": "[omitido]", "rua": "Rua Exemplo", "numero": "100", "complemento": null, "bairro": "Centro", "municipio": "São Paulo", "cmun": "3550308", "uf": "SP", "cep": "01001000", "login_prefeitura": null, "senha_prefeitura": null, "client_id_prefeitura": null, "client_secret_prefeitura": null, "csc": null, "cscid": null, "documentos": { "nfe": false, "nfce": false, "nfse": true }, "status": "ativo", "provider_emitente_id": "48213", "webhook_url": "https://seusistema.com.br/webhooks/notas", "created_at": "2026-10-13T13:00:00.000000Z", "updated_at": "2026-10-13T14:00:00.000000Z" } } } ``` ### 7. POST /consulta/emissao-notas/credits **tipo: emitentes-lista** · Lista os emitentes cadastrados na sua conta, em ordem de razão social, 15 por página. Use para recuperar um emitente_id. Filtros opcionais: cnpj, cpf e status (ativo ou inativo). A lista vem em data.emitentes e a paginação em data.pagination (total, per_page, current_page e last_page). - **Method:** `POST` - **Address:** `https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits` - **Route version:** v2 - **Price of this operation:** R$0.00 per query **Headers** | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Request body** ```json { "tipo": "emitentes-lista", "cnpj": "11222333000181" } ``` **In cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/emissao-notas/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"emitentes-lista","cnpj":"11222333000181"}' ``` **Sample response, from the catalog** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "400,000", "balance_before": "400,000", "tax": "0,000", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,00.", "valor_consulta": 0, "api_limit_for": "credit", "homolog": false, "data": { "emitentes": [ { "id": "9b1f3c2e-5d4a-4e8b-9c7d-1a2b3c4d5e6f", "user_id": 12345, "razao": "EMPRESA EXEMPLO LTDA", "nome": "EMPRESA EXEMPLO", "cnpj": "11222333000181", "cpf": null, "ie": null, "im": "1234567", "suframa": null, "cnae": "0000000", "crt": 1, "telefone": "11999999999", "email": "[omitido]", "rua": "Rua Exemplo", "numero": "100", "complemento": null, "bairro": "Centro", "municipio": "São Paulo", "cmun": "3550308", "uf": "SP", "cep": "01001000", "login_prefeitura": null, "senha_prefeitura": null, "client_id_prefeitura": null, "client_secret_prefeitura": null, "csc": null, "cscid": null, "documentos": { "nfe": false, "nfce": false, "nfse": true }, "status": "ativo", "provider_emitente_id": "48213", "webhook_url": "https://seusistema.com.br/webhooks/notas", "created_at": "2026-10-13T13:00:00.000000Z", "updated_at": "2026-10-13T13:00:00.000000Z" } ], "pagination": { "total": 1, "per_page": 15, "current_page": 1, "last_page": 1 } } } ``` In the sample responses, the fields of the account that generated the sample (`user.first_name`, `user.email`, `user.cellphone`) come out as `[omitido]`. The rest is what the catalog publishes. ## Pitfalls: what an integration gets wrong without warning Established from the responses the catalog itself publishes. In every one of them the code works on the happy path and fails silently everywhere else: 1. **The error arrives in the BODY, with HTTP 200.** The response carries a boolean `error` field and a `message`. Checking only `response.ok` or the HTTP status lets a failure through as a success. ALWAYS check `error === false` before reading `data`. 2. **`balance`, `tax` and `extra_charges.total` are STRINGS in Brazilian format — and the format varies between APIs.** Values seen in the catalog: `"154,380"`, `"497,84"`, `"0,000"` and `"0.19"`. Comma in some, dot in another; three decimal places in some, two in another. In JavaScript, `parseFloat("154,380")` returns `154` and drops the cents with no error at all, and `Number("154,380")` returns `NaN`. Write a converter that handles both separators, and never use these fields in a financial decision without converting them. 3. **Every call costs money.** Blind retries multiply the bill. Never automatically repeat a 4xx: a bad parameter repeated is still bad, and still charged. Retry only timeouts and 5xx, with exponential backoff and a small attempt ceiling. 4. **HTTP 402 means insufficient balance, and retrying does not fix it.** It is the one status that needs a human — a top-up. Treat it as a terminal error with its own message, and do not lump it in with generic 4xx. 5. **`extra_charges` bills on top of the lookup price.** When the body asks for add-on services, the response lists each one with its price plus a `total` that is NOT included in the base amount. If you show cost to an end user, add both. ## See also - OpenAPI specification: https://doc.apibrasil.io/apis/creditos/7d62c6f8-0074-40bd-a17e-ba49235b7233/openapi.json - API catalog: [API catalog](https://doc.apibrasil.io/apis.md) - Official SDKs: [Official SDKs](https://doc.apibrasil.io/sdks.md) - Documentation index: https://doc.apibrasil.io/llms.txt - HTML version of this page: https://doc.apibrasil.io/apis/creditos/7d62c6f8-0074-40bd-a17e-ba49235b7233