Guia de integração

Documentação da API Emitfy

A API REST da Emitfy é a superfície completa do produto: emite NFS-e, NF-e, NFC-e e CT-e (NFC-e e CT-e são exclusivos de API), gerencia catálogo (clientes, produtos), empresas da assinatura e envia eventos via webhook. Ideal para SaaS, ERPs, gateways e parceiros com múltiplos CNPJs em uma única credencial. Notas emitidas pela API aparecem normalmente na dashboard (exceto NFC-e e CT-e, que não têm telas).

Como a emissão funciona?

Emissão por tipo de nota

Cada documento tem seu endpoint: POST .../nfse, .../nfe, .../nfce e .../cte. Um POST com os dados da nota e a Emitfy cuida do resto.

Ir para NFS-e

Dashboard × API

A dashboard é simples e focada no mercado digital (NF-e e NFS-e). A API expõe todos os campos e também NFC-e e CT-e, exclusivos de API — pensada para SaaS, ERPs, gateways e parceiros.

Ver NFC-e

Primeiros passos

2

Configurar autenticação

Envie X-Api-Key e X-Api-Secret em todas as chamadas.

4

Emitir a primeira nota

Use POST /v1/companies/:companyId/nfse (ou o endpoint do tipo desejado) e acompanhe via webhook. Para testar, use o sandbox.

Base URL e autenticação

Use a URL base https://api.emitfy.com. Todas as requisições privadas validam os headers X-Api-Key e X-Api-Secret da assinatura/conta. Emissão e catálogo usam /v1/companies/:companyId/...; webhooks ficam em /v1/webhooks.

Headers obrigatórios
X-Api-Key: <api-key>
X-Api-Secret: <api-secret>
Content-Type: application/json
Exemplo: emitir NFS-e (curl)
curl -X POST https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfse \
  -H "X-Api-Key: <api-key>" \
  -H "X-Api-Secret: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceDescription": "Consultoria em tecnologia",
    "cityServiceCode": "02800",
    "federalServiceCode": "01.05",
    "iss": { "rate": 2.9, "isWithheld": false },
    "amount": 1500.00,
    "borrower": {
      "taxId": "123.456.789-00",
      "name": "João Silva",
      "email": "[email protected]"
    }
  }'

Onde encontro o companyId?

O companyId é o identificador (UUID) da empresa na Emitfy — não é o CNPJ. A credencial é da conta e vale para todas as empresas; o companyId na URL diz em qual CNPJ emitir. Há dois jeitos de obter:

  1. No painel, em API & Webhooks: o bloco Company ID mostra o ID (com seletor quando há mais de uma empresa) e um exemplo de requisição já preenchido.
  2. Pela API: GET /v1/companies lista as empresas da conta. Use o id do CNPJ desejado. Com uma única empresa, é o primeiro item.
Listar empresas
curl https://api.emitfy.com/v1/companies \
  -H "X-Api-Key: <api-key>" \
  -H "X-Api-Secret: <api-secret>"
200Resposta
{
  "success": true,
  "data": [
    {
      "id": "01a17883-2c36-7263-9ea4-93f5c44573f0",
      "taxId": "11.222.333/0001-81",
      "tradeName": "Empresa Exemplo",
      "legalName": "EMPRESA EXEMPLO LTDA",
      "isOwner": true
    }
  ]
}

Sandbox (homologação)

Para testar sem emitir notas com valor fiscal, use o sandbox. É um ambiente separado da produção: crie uma conta em app-sandbox.emitfy.com, cadastre a empresa, envie o certificado A1 e gere as chaves lá.

  • Base URL: https://api-sandbox.emitfy.com (MCP: https://mcp-sandbox.emitfy.com/mcp).
  • Emissão sempre em homologação (SEFAZ/prefeitura), sem plano nem cobrança.
  • Contas, chaves, empresas e companyId do sandbox não valem em produção, e vice-versa — o mesmo e-mail vira duas contas independentes.

Formato de resposta

As respostas seguem um envelope JSON. Em sucesso, success é true com data; em erro, success é false com error.code e error.message.

200Resposta de sucesso
{
  "success": true,
  "data": {
    "id": "018f6e3b-...",
    "status": "processing",
    "type": "nfse",
    "amount": 1500.00
  }
}
401Resposta de erro
{
  "success": false,
  "error": {
    "code": "INVALID_API_CREDENTIALS",
    "message": "Credenciais de API inválidas.",
    "details": null
  }
}

Suporte técnico

Em caso de dúvidas na integração, o time técnico ajuda com onboarding, debugging e validação de payloads.