Quickstart: primeira emissão pela API no sandbox

Atualizado em 11/11/2026

Nesta página

Antes de começar
1. Crie uma chave de teste
2. Cadastre um tomador
3. Emita a nota
4. Acompanhe o status
5. Vá para produção
Próximos passos

Em quatro chamadas você emite uma NFS-e no sandbox da Emitra: sem certificado, sem Sefin e sem consumir cota. Depois é só trocar a chave para produção.

Antes de começar#

Uma conta na Emitra com o papel owner ou admin (só eles criam chaves).
curl, Python 3.10+, Node.js 18+ ou PHP 8.1+.

1. Crie uma chave de teste#

No painel, abra Notas › Automação › Integrações › Chaves de API.
Clique em Nova chave, escolha o ambiente Teste e marque os escopos customers:write, nfse:emit e nfse:read.
Copie a chave. Ela aparece uma única vez e começa com emt_test_.

Guarde a chave numa variável de ambiente:

Terminal

export EMITRA_API_KEY="emt_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Cadastre um tomador#

cURL

curl https://emitra.com.br/api/v1/integracao/tomadores \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_pessoa": "PJ",
    "documento": "11444777000161",
    "nome": "Padaria Silva Ltda",
    "email": "financeiro@padariasilva.com.br",
    "endereco": {
      "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
      "cep": "01001000", "municipio_ibge": "3550308", "uf": "SP"
    }
  }'

Python

import os, requests

API = "https://emitra.com.br/api/v1/integracao"
H = {"Authorization": f"Bearer {os.environ['EMITRA_API_KEY']}"}

r = requests.post(f"{API}/tomadores", headers=H, json={
    "tipo_pessoa": "PJ",
    "documento": "11444777000161",
    "nome": "Padaria Silva Ltda",
    "email": "financeiro@padariasilva.com.br",
    "endereco": {"logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
                 "cep": "01001000", "municipio_ibge": "3550308", "uf": "SP"},
})
tomador_id = r.json()["data"]["id"]

JavaScript

const API = "https://emitra.com.br/api/v1/integracao";
const headers = {
  Authorization: `Bearer ${process.env.EMITRA_API_KEY}`,
  "Content-Type": "application/json",
};

const r = await fetch(`${API}/tomadores`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    tipo_pessoa: "PJ",
    documento: "11444777000161",
    nome: "Padaria Silva Ltda",
    email: "financeiro@padariasilva.com.br",
    endereco: { logradouro: "Rua das Flores", numero: "100", bairro: "Centro",
                cep: "01001000", municipio_ibge: "3550308", uf: "SP" },
  }),
});
const { data: tomador } = await r.json();

PHP

<?php
$api = "https://emitra.com.br/api/v1/integracao";
$headers = [
    "Authorization: Bearer " . getenv("EMITRA_API_KEY"),
    "Content-Type: application/json",
];

$ch = curl_init("$api/tomadores");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        "tipo_pessoa" => "PJ",
        "documento" => "11444777000161",
        "nome" => "Padaria Silva Ltda",
        "email" => "financeiro@padariasilva.com.br",
        "endereco" => ["logradouro" => "Rua das Flores", "numero" => "100", "bairro" => "Centro",
                       "cep" => "01001000", "municipio_ibge" => "3550308", "uf" => "SP"],
    ]),
]);
$tomador = json_decode(curl_exec($ch), true)["data"];

A resposta traz o id do tomador: 5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10.

3. Emita a nota#

A emissão exige o header Idempotency-Key. Se a conexão cair e você reenviar a mesma requisição com a mesma chave, a Emitra devolve a resposta original em vez de criar outra nota.

cURL

curl https://emitra.com.br/api/v1/integracao/nfse \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2026-11-0001" \
  -d '{
    "tomador_id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
    "competencia": "2026-11-10",
    "servico": {
      "codigo_tributacao_nacional": "010601",
      "descricao": "Consultoria em tecnologia da informação - novembro/2026",
      "valor": "1500.00"
    },
    "external_ref": "pedido-2026-11-0001"
  }'

Python

r = requests.post(f"{API}/nfse", headers={**H, "Idempotency-Key": "pedido-2026-11-0001"}, json={
    "tomador_id": tomador_id,
    "competencia": "2026-11-10",
    "servico": {
        "codigo_tributacao_nacional": "010601",
        "descricao": "Consultoria em tecnologia da informação - novembro/2026",
        "valor": "1500.00",
    },
    "external_ref": "pedido-2026-11-0001",
})
nfse_id = r.json()["data"]["id"]  # 202 Accepted

JavaScript

const e = await fetch(`${API}/nfse`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "pedido-2026-11-0001" },
  body: JSON.stringify({
    tomador_id: tomador.id,
    competencia: "2026-11-10",
    servico: {
      codigo_tributacao_nacional: "010601",
      descricao: "Consultoria em tecnologia da informação - novembro/2026",
      valor: "1500.00",
    },
    external_ref: "pedido-2026-11-0001",
  }),
});
const { data: nfse } = await e.json(); // 202 Accepted

PHP

$ch = curl_init("$api/nfse");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => array_merge($headers, ["Idempotency-Key: pedido-2026-11-0001"]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        "tomador_id" => $tomador["id"],
        "competencia" => "2026-11-10",
        "servico" => [
            "codigo_tributacao_nacional" => "010601",
            "descricao" => "Consultoria em tecnologia da informação - novembro/2026",
            "valor" => "1500.00",
        ],
        "external_ref" => "pedido-2026-11-0001",
    ]),
]);
$nfse = json_decode(curl_exec($ch), true)["data"]; // 202 Accepted

Resposta 202

{
  "status": "success",
  "message": "DPS recebida e enfileirada",
  "data": {
    "id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "queued",
    "external_ref": "pedido-2026-11-0001",
    "is_test": true,
    "created_at": "2026-11-11T10:15:30-03:00"
  }
}

Note que o valor vai como string decimal ("1500.00"), nunca como número de ponto flutuante.

4. Acompanhe o status#

A emissão é assíncrona. Consulte a nota até o status sair de queued/signed/sent:

cURL

curl https://emitra.com.br/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84 \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Resposta 200 (trecho)

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "authorized",
    "numero_nfse": "42",
    "chave_acesso": "35503082211222333000181000000000004226114829130573",
    "ambiente": "sandbox",
    "is_test": true
  }
}

Quer ver uma rejeição? No sandbox, emita com um valor terminado em .13 (ex.: "1500.13"). A tabela completa está em Sandbox e números mágicos.

5. Vá para produção#

Envie o certificado A1 e ajuste a configuração fiscal.
Crie uma chave Produção (emt_live_) com os mesmos escopos.
Troque a variável EMITRA_API_KEY. A URL base é a mesma.

Próximos passos#

Esta página foi útil?