SDKs

Clientes oficiais para chamar a API Emitfy sem montar HTTP na mão. Em todas as linguagens a tipagem acompanha o OpenAPI público. O contrato narrado continua na referência.

Como usar o SDK

Autentique com as chaves da assinatura/conta (apiKey + apiSecret).
Operações de conta: emitfy.webhooks e emitfy.companies.
Operações da empresa: const company = emitfy.company(companyId) e então company.nfse, company.nfe, company.customers, etc.

Em todas as linguagens a forma é a mesma: recurso → método HTTP (list / create / get / update / delete). Payloads JSON iguais aos da referência.

Mapa rápido — conta

SDK	HTTP	Docs
`emitfy.webhooks.list()`	`GET /v1/webhooks`	Webhooks
`emitfy.webhooks.create(body)`	`POST /v1/webhooks`	Webhooks
`emitfy.webhooks.update(id, body)`	`PUT /v1/webhooks/:id`	Webhooks
`emitfy.webhooks.setActive(id, active)`	`PATCH /v1/webhooks/:id/active`	Webhooks
`emitfy.webhooks.delete(id)`	`DELETE /v1/webhooks/:id`	Webhooks
`emitfy.companies.list()`	`GET /v1/companies`	Empresas
`emitfy.companies.create(body)`	`POST /v1/companies`	Empresas

Mapa rápido — empresa

Prefixo: company = emitfy.company(companyId). Cada recurso abaixo aceita list, create, get(id), update(id, body) e delete(id) (quando o endpoint existir na API).

SDK	Base HTTP	Docs
`company.nfse`	`/v1/companies/:companyId/nfse`	NFS-e
`company.nfe`	`/v1/companies/:companyId/nfe`	NF-e
`company.nfce`	`/v1/companies/:companyId/nfce`	NFC-e
`company.cte`	`/v1/companies/:companyId/cte`	CT-e
`company.createCteOs(body)`	`POST …/cte-os`	CT-e
`company.customers`	`/v1/companies/:companyId/customers`	Clientes
`company.products`	`/v1/companies/:companyId/products`	Produtos
`company.sales`	`/v1/companies/:companyId/sales`	Vendas
`company.invoices`	`/v1/companies/:companyId/invoices`	—
`company.receivedNfes`	`/v1/companies/:companyId/received-nfes`	Notas recebidas

Ações extras (cancelar, sync, manifesto, PDF/XML) usam resource.post('…/ação', body?) — veja o path exato na página de referência do recurso.

Receitas

1. Emitir NFS-e

Campos do body: referência NFS-e. Use Idempotency-Key no segundo argumento de create.

JavaScript

import { Emitfy } from '@emitfy/sdk'

const emitfy = new Emitfy({
  apiKey: process.env.EMITFY_API_KEY,
  apiSecret: process.env.EMITFY_API_SECRET
})

const company = emitfy.company(process.env.EMITFY_COMPANY_ID)

const nfse = await company.nfse.create(
  {
    serviceDescription: 'Desenvolvimento de software sob demanda',
    serviceCode: '01.05',
    amount: 2500,
    borrower: {
      taxId: '12.345.678/0001-90',
      name: 'Empresa Cliente LTDA',
      email: '[email protected]'
    }
  },
  'pedido-001' // Idempotency-Key
)

2. Cadastrar webhook da conta

Eventos e assinatura HMAC: webhooks.

JavaScript

await emitfy.webhooks.create({
  url: 'https://seu-sistema.com/webhooks/emitfy',
  events: {
    invoice: ['nfse.authorized', 'nfse.canceled'],
    cte: []
  }
})

3. Cliente + venda (SaaS recorrente)

Ideal quando o cadastro já está corrigido na Emitfy. Detalhes em clientes e vendas.

JavaScript

const customer = await company.customers.create({
  name: 'Cliente SaaS',
  taxId: '123.456.789-09',
  email: '[email protected]'
})

const sale = await company.sales.create({
  customer: customer.id,
  items: [{ productSku: 'PLANO-PRO', quantity: 1, amount: 99.9 }]
})

Instalação

Node.js — npm i @emitfy/sdk
PHP — composer require emitfy/sdk
Python — pip install emitfy
C# / .NET — dotnet add package Emitfy
Java — com.emitfy:emitfy (Maven Central)

Quickstart por linguagem

Node.js / TypeScript

Pacote @emitfy/sdk: facade tipada + tipos (WebhookCreate, NfseCreateData, …) alinhados ao OpenAPI.

JavaScript

import { Emitfy } from '@emitfy/sdk'

const emitfy = new Emitfy({
  apiKey: process.env.EMITFY_API_KEY,
  apiSecret: process.env.EMITFY_API_SECRET
})

const company = emitfy.company(process.env.EMITFY_COMPANY_ID)
await company.nfse.create({ serviceDescription: 'Serviço', amount: 100 })

PHP

Facade + camada tipada Emitfy\Generated\*. Use $emitfy->webhooksApi() para models tipados.

PHP

<?php
use Emitfy\Emitfy;

$emitfy = new Emitfy([
  'apiKey' => getenv('EMITFY_API_KEY'),
  'apiSecret' => getenv('EMITFY_API_SECRET'),
]);

$company = $emitfy->company(getenv('EMITFY_COMPANY_ID'));
$company->nfse->create([
  'serviceDescription' => 'Serviço de software',
  'amount' => 100,
]);

Python

Facade + emitfy.generated (Pydantic). Atalhos: emitfy.webhooks_api(), WebhookCreate.

JavaScript

from emitfy import Emitfy
import os

emitfy = Emitfy(os.environ["EMITFY_API_KEY"], os.environ["EMITFY_API_SECRET"])
company = emitfy.company(os.environ["EMITFY_COMPANY_ID"])
company.nfse.create({"serviceDescription": "Serviço", "amount": 100})

C# / .NET

Facade + Emitfy.Generated.*. Atalho: emitfy.WebhooksApi().

JavaScript

using Emitfy;

var emitfy = new EmitfyClient(
  Environment.GetEnvironmentVariable("EMITFY_API_KEY")!,
  Environment.GetEnvironmentVariable("EMITFY_API_SECRET")!
);

var company = emitfy.Company(Environment.GetEnvironmentVariable("EMITFY_COMPANY_ID")!);
await company.Nfse.CreateAsync(new { serviceDescription = "Serviço", amount = 100 });

Java

Facade + com.emitfy.generated.*. Atalho: emitfy.webhooksApi().

Shell

<!-- Maven Central: com.emitfy:emitfy -->
<dependency>
  <groupId>com.emitfy</groupId>
  <artifactId>emitfy</artifactId>
  <version>0.2.2</version>
</dependency>

JavaScript

import com.emitfy.Emitfy;
import java.util.Map;

Emitfy emitfy = new Emitfy(System.getenv("EMITFY_API_KEY"), System.getenv("EMITFY_API_SECRET"));
Emitfy.CompanyContext company = emitfy.company(System.getenv("EMITFY_COMPANY_ID"));
company.nfse.create(Map.of("serviceDescription", "Serviço", "amount", 100));

Referência completa

Páginas de referência — body, query, erros e exemplos curl.
OpenAPI — contrato público.
llms-full.txt — contexto para agentes (guia).