Guia de integração

Documentação da API Emitfy

A API REST da Emitfy permite emitir notas (NFS-e, NF-e, NFC-e, CT-e), gerenciar o catálogo (clientes, produtos e vendas — o mesmo da Dashboard), empresas da assinatura e receber eventos via webhook. Conta = billing; Assinatura = keys, webhooks e ops; Empresa = CNPJ no path. Ideal para SaaS e ERPs com múltiplos CNPJs em uma única credencial.

Emitir NFS-e Ver catálogo (vendas) Configurar autenticação

Qual fluxo escolher?

Atalho (NF-e / NFS-e)

Um POST com tomador/destinatário e valor. A Emitfy cria venda, cliente e produto por baixo. Ideal para emissão pontual.

Ir para NFS-e

Catálogo (Dashboard)

Cadastre clientes e produtos; nas vendas use customer: "<uuid>" e SKU. Ideal para SaaS recorrente e dados já corrigidos na Emitfy.

Ir para vendas

Começar

Autenticação

Credencial da assinatura/conta, empresa no path e rate limit.

Empresas

Cadastro de empresas (CNPJ) da assinatura e upload de certificado A1.

Sandbox

Ambiente de homologação e testes.

Emissão

NF-e

Nota fiscal eletrônica de produtos (modelo 55).

NFS-e

Nota fiscal de serviço — emissão, consulta e cancelamento.

API

NFC-e

Cupom fiscal ao consumidor final. Requer ativação na conta.

API

CT-e

Conhecimento de transporte e CT-e OS. Requer ativação na conta.

Catálogo

Clientes

Cadastro fiscal reutilizável — ideal para recorrência.

Produtos

Produtos e serviços do catálogo (SKU, NCM, etc.).

Vendas

Cria venda, emite e cancela nota — espelho da Dashboard.

Destinatário

Notas recebidas

Captura DistDFe e manifestação do destinatário.

Integração

Webhooks

Eventos na assinatura (/v1/webhooks); payload com companyId e taxId.

Idempotência

Evite emissão duplicada em retentativas.

Erros

Formato padrão e códigos de negócio.

Para IAs

llms.txt, Markdown por página e OpenAPI para agentes.

SDKs

SDKs oficiais em breve; use CodeTabs e OpenAPI enquanto isso.

Primeiros passos

Gerar credenciais

Crie sua chave em Painel → API & Webhooks.

Configurar autenticação

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

Emitir a primeira nota

Use o atalho /v1/companies/:companyId/nfse ou o catálogo /v1/companies/:companyId/sales e acompanhe via webhook.

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",
    "serviceCode": "01.01",
    "amount": 1500.00,
    "borrower": {
      "taxId": "123.456.789-00",
      "name": "João Silva",
      "email": "[email protected]"
    }
  }'

Formato de resposta

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

200Resposta de sucesso

{
  "ok": true,
  "data": {
    "id": "018f6e3b-...",
    "status": "processing",
    "type": "nfse",
    "amount": 1500.00
  }
}

401Resposta de erro

{
  "ok": false,
  "code": "INVALID_API_CREDENTIALS",
  "message": "Credenciais de API inválidas.",
  "statusCode": 401
}

Suporte técnico

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

E-mail técnico

[email protected]

Tratamento de erros

Códigos e formato padrão